docs: record CAD import and image-reference planning notes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

task_plan.md

@@ -4,7 +4,7 @@
 Persist Brand Kits by authenticated user, bind one optional Brand Kit to each project/canvas, expose a canvas-header selector, and make every Agent Chat turn and newly created thread use the selected kit as authoritative creative context.
 
 ## Current Phase
-Phase 12
+Phases 21-22
 
 ## Phases
 
@@ -91,6 +91,54 @@ Phase 12
 - [ ] Provide the working preview URL and concise implementation notes
 - **Status:** pending
 
+### Phase 15: CAD Import Discovery and Design
+- [x] Trace the canvas asset import, upload, persistence, rendering, and export paths
+- [x] Define the supported DWG/DXF conversion boundary and failure states
+- **Status:** complete
+
+### Phase 16: CAD Import Implementation
+- [x] Confirm no backend API change is required for browser-side conversion
+- [x] Add DWG/DXF selection, conversion, SVG/canvas rendering, and user feedback
+- [x] Add focused tests and documentation
+- **Status:** complete
+
+### Phase 17: CAD Import Verification and Delivery
+- [x] Run relevant frontend tests/builds
+- [x] Inspect CAD import and canvas behavior in a browser with the exact R12 file
+- [x] Review scope and deliver concise support/limitation notes
+- **Status:** complete
+
+### Phase 18: General CAD Compatibility Follow-up
+- [x] Reproduce the block-heavy DWG timeout and isolate its dominant output path
+- [x] Replace recursive INSERT/DIMENSION expansion with reusable SVG block definitions and full insert transforms
+- [x] Cover nested blocks, repeated inserts, MINSERT arrays, malformed references, and recursion cycles
+- **Status:** complete
+
+### Phase 19: Vector Image Toolbar Follow-up
+- [x] Recognize uploaded SVG and CAD-derived SVG nodes as vector images
+- [x] Hide the raster image toolbar and show the compact vector/download toolbar for vector nodes
+- [x] Preserve original SVG download behavior
+- **Status:** complete
+
+### Phase 20: Follow-up Verification and Delivery
+- [x] Verify both user-provided CAD files plus representative DWG/DXF regression fixtures
+- [x] Run focused tests, typecheck, and production builds
+- [x] Verify vector toolbar, rendering, download, and persistence in a real browser
+- **Status:** complete
+
+### Phase 21: Vector Reference Message Rendering
+- [x] Reproduce CAD-derived SVG references falling back to raw prompt directives
+- [x] Parse SVG/CAD reference names with nested parentheses into the existing message capsule
+- [x] Verify SVG directives enter the existing thumbnail/hover/copy component path; run tests and production build
+- **Status:** complete
+
+### Phase 22: Model-Compatible SVG References
+- [x] Identify every canvas frontend submission path that can pass an SVG image reference to image generation
+- [x] Rasterize SVG references to transparent WebP only at the model submission boundary
+- [x] Cache and replace submitted reference URLs without mutating SVG canvas nodes or display names
+- [x] Add focused regression coverage and verify prepared model content receives a WebP asset URL
+- **Status:** complete
+
 ## Invariants
 - Brand Kits are owned and queried only through the authenticated user ID from request context.
 - A project may reference zero or one Brand Kit owned by the same user.
@@ -107,6 +155,11 @@ Phase 12
 - Device timestamps cross the API boundary as RFC3339 UTC instants and are localized only in the browser's timezone.
 - Visual annotation actions never mutate the source image node; their copied result node is the only generation target.
 - Desktop and mobile web-session limits come from server configuration; the API returns the effective values and the UI never hard-codes them.
+- Imported CAD files are read without mutation; only a sanitized derived SVG is uploaded and rendered, with explicit size, timeout, empty-drawing, and conversion errors.
+- Repeated and nested CAD block references are represented once and instanced with SVG references; conversion cost must scale with unique block geometry, not insert count.
+- SVG-backed image nodes use vector-only actions and download their source SVG rather than exposing raster editing actions.
+- User-message image directives render through one attachment capsule/preview path regardless of raster or SVG source format.
+- SVG remains the persisted canvas source; transparent WebP derivatives exist only for model-compatible image inputs.
 
 ## Errors Encountered
 | Error | Attempt | Resolution |
@@ -127,3 +180,20 @@ Phase 12
 | Escaping the `psql \d` meta-command through Docker produced an invalid command | 1 | Query `information_schema.columns` and `pg_indexes` with regular SQL instead. |
 | Desktop limit regression test observed two valid desktop sessions when the configured limit was 1 | 1 | Confirmed the limit was presentation-only; enforce it atomically during session creation and reconcile pre-fix sessions during device listing. |
 | Launching `mcp-zero` from `server/` used a repository-root relative path | 1 | Relaunch with `../.tools/bin/mcp-zero` while keeping generation output rooted in `server/`. |
+| NPM lookup for a nonexistent `@loaders.gl/dxf` package returned 404 and stopped the chained lookup | 1 | Use independent package searches and validate the chosen converter package before installation. |
+| Package inspection commands raced the tar extraction and looked under the wrong transient path | 1 | Inspect the extracted tree first, then run dependent file reads sequentially against the discovered path. |
+| `npm install` inherited a parent workspace containing an unsupported `workspace:*` URL | 1 | Inspect local package-manager metadata and run installation with workspace discovery disabled or use the repository's actual package manager. |
+| TypeScript rejected `.length` on the CAD library's entity collection | 1 | Use the collection's declared count/iteration API instead of assuming it is an array. |
+| Next 16 Turbopack emitted the module worker as raw `.ts` instead of executable bundled JavaScript | 1 | Run Next dev/build through its supported webpack mode, which handles `new Worker(new URL(...))`; retain Vite's native worker bundling. |
+| Used nonexistent Playwright CLI command `network` | 1 | Use the CLI's documented `requests` and `response-body` commands for network inspection. |
+| First Vite DXF upload triggered dependency pre-bundling and a development-page reload | 1 | Retry after Vite finishes one-time dependency optimization; production worker output is already bundled. |
+| Real upstream DXF fixture parsed to an empty model space in `@node-projects/acad-ts` | 1 | Validate the library's document assembly in Node, then replace the DXF path or reader entirely if real fixtures remain empty. |
+| Directory-wide listing of the WeChat file folder stalled on container-managed storage | 1 | Use the exact user-provided path directly; metadata access confirms the file is readable. |
+| The exact R12 DXF crashed while serializing the first inherited-color POINT | 1 | Resolve non-renderable ByLayer/ByBlock colors through the entity and layer before calling the third-party SVG writer; lock the case with a minimal R12 regression test. |
+| Next production minification reduced valid DXF geometry to zero-valued entities | 1 | Restore `acad-ts` constructor names from stable export keys before its name-based metadata lookup; keep the normal minified build and cover the mangled-name path in the regression test. |
+| Reusing one entity writer and slicing its cumulative string exhausted the Node heap on the exact R12 drawing | 1 | Give each entity a short-lived fragment writer so output assembly stays linear in total geometry size. |
+| Node's strip-only TypeScript test runner rejected constructor parameter properties | 1 | Use explicit class fields and constructor assignments, which preserve the project test runner's supported syntax subset. |
+| Vector reference regression suite failed on nested English and Chinese CAD filenames | 1 | Expected red phase confirmed: the directive regex stops before the final filename parenthesis; update it to bind the closing delimiter adjacent to the URL separator. |
+| First post-fix parser assertion still expected no `index` property | 1 | The production parser correctly emits `index: undefined`; align the regression fixture with the stable result shape. |
+| In-app browser discovery returned no available browser backend | 1 | Followed the browser skill troubleshooting flow and confirmed an empty backend list; retain automated tests/builds and report the interactive verification gap. |
+| Combined final planning patch targeted progress lines as task-plan context | 1 | Split the update by file and apply each change against its exact current section. |