docs: document image tracing endpoint

docs/implementation-plan.md

@@ -63,6 +63,8 @@ tts-workshop/
 │   │   │   ├── search.ts   # GET /search?q=...&page=1
 │   │   │   ├── items.ts    # GET /items/:id, /items/:id/file
 │   │   │   ├── asset.ts    # GET /asset?url=... (CORS-safe asset proxy)
+│   │   │   ├── trace.ts    # GET /trace?url=... (image → vector shape)
+│   │   │   ├── svgShape.ts # parse vtracer SVG into { outline, holes }
 │   │   │   └── health.ts   # GET /health
 │   │   └── env.ts          # zod env validation
 │   └── web/
@@ -202,6 +204,17 @@ Hono server exposing search + fetch.
     it back with a `Content-Type` header. Workshop hosts often omit CORS
     headers, which would block three.js loaders in the browser; routing through
     the proxy makes those assets loadable. Only `http(s)` URLs are allowed.
+- `routes/trace.ts`
+  - `GET /trace?url=...&mode=alpha&threshold=128&format=shape` — fetch an
+    image, trace it into a vector shape, and return the result BSON-encoded.
+    `mode` is `alpha` (default), `bw`, or `color`; `format` is `shape`
+    (default) or `svg`. `shape` returns a parsed `{ outline, holes }` polygon
+    matching `@tts/mesh`'s `Shape` interface, ready to extrude.
+- `routes/svgShape.ts`
+  - `parseSvgShape(svg)` — parse a vtracer SVG into a `TracedShape`
+    (`{ outline, holes }`): flatten beziers to polylines, split subpaths into
+    rings, classify by winding (CCW outline / CW hole), and assign holes to
+    their containing outline.
 - `routes/health.ts`
   - `GET /health` — liveness.
 - `env.ts` — zod validation of `STEAM_API_KEY`, `PORT`.
@@ -259,6 +272,7 @@ proxy API and `packages/extract` directly for analysis.
 | GET    | `/items/:id`        | Full parsed `TTSMod` (`?fileUrl=` skips key) | key* |
 | GET    | `/items/:id/file`   | Raw save bytes, filename from header         | key* |
 | GET    | `/asset?url=`       | CORS-safe proxy for external assets          | —    |
+| GET    | `/trace?url=&mode=&format=` | Trace an image into a vector shape (BSON) | —    |
 
 \* `STEAM_API_KEY` is optional; `/items/*` works without it when a `fileUrl`
 query param is supplied.
@@ -275,12 +289,17 @@ query param is supplied.
                       download BSON → parse → TTSMod
         ↓
 packages/extract    →  flatten objects / extract refs / download assets
+        ↓
+/trace?url=...      →  sharp decode → vtracer → parse SVG → BSON shape
 ```
 
 ## Dependencies
 
 - `hono`, `@hono/node-server`, `@hono/cors` — server.
-- `bson` — BSON deserialization.
+- `bson` — BSON deserialization (save files + trace results).
+- `@visioncortex/vtracer` — raster-to-SVG vectorization (wasm).
+- `sharp` — image decoding to RGBA for tracing.
+- `svgpath` — SVG path parsing for traced shapes.
 - `cheerio` — Workshop browse page scraping (backend only).
 - `zod` — validation.
 - `react`, `react-dom`, `react-router-dom`, `zustand` — frontend.