From c7f4bd03fddf2b665111c0105eb949e352c57b4b Mon Sep 17 00:00:00 2001
From: hypercross <helios.tnak@gmail.com>
Date: Sat, 8 Aug 2026 15:12:15 +0800
Subject: [PATCH] docs: document mesh package and traced token viewer

---
 docs/architecture.md        |  4 ++++
 docs/implementation-plan.md | 39 ++++++++++++++++++++++++++++++++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/docs/architecture.md b/docs/architecture.md
index 40ba457..a123325 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -31,6 +31,7 @@ shared types/validation package.
 | `apps/proxy`       | Hono HTTP server: search + fetch endpoints  | Node         |
 | `packages/tts`     | Fetch save from Steam, BSON-parse to `TTSMod` | Node       |
 | `packages/extract` | Analyze a `TTSMod`: objects, refs, assets   | Isomorphic   |
+| `packages/mesh`    | 2D shapes + extrusion into 3D mesh geometry | Isomorphic   |
 | `packages/shared`  | Shared types + zod schemas                  | Isomorphic   |
 
 ## Dependency graph
@@ -40,6 +41,7 @@ apps/web ──► apps/proxy ──► packages/tts ──► packages/shared
       │            │            │
       │            │            └──► (fetchMod → TTSMod)
       │            ▼
+      ├──► packages/mesh ──► packages/shared (types)
       └──► packages/extract ──► packages/shared (types)
 ```
 
@@ -50,6 +52,8 @@ apps/web ──► apps/proxy ──► packages/tts ──► packages/shared
   (image → vector shape) over HTTP.
 - **`apps/web` → `packages/extract`** — uses `buildTree` / `collectRefs`
   to analyze a loaded `TTSMod` in the browser (tree sidebar + asset refs).
+- **`apps/web` → `packages/mesh`** — extrudes 2D shapes into 3D geometry for
+  the tile and token viewers.
 - **`apps/proxy` → `packages/tts`** — calls `fetchMod` / `getFileName` to serve
   item requests.
 - **`apps/proxy` → `packages/shared`** — uses shared types and zod schemas for
diff --git a/docs/implementation-plan.md b/docs/implementation-plan.md
index 0fd9ccd..cd1b835 100644
--- a/docs/implementation-plan.md
+++ b/docs/implementation-plan.md
@@ -30,6 +30,7 @@ apps/web ──► apps/proxy ──► packages/tts ──► packages/shared
       │            │            │
       │            │            └──► (fetchMod → TTSMod)
       │            ▼
+      ├──► packages/mesh ──► packages/shared (types)
       └──► packages/extract ──► packages/shared (types)
            (isomorphic, used by the frontend)
 ```
@@ -40,6 +41,8 @@ apps/web ──► apps/proxy ──► packages/tts ──► packages/shared
   derivation. Returns raw parsed `TTSMod`.
 - **`packages/extract`** — analysis: flatten/filter objects, extract asset refs,
   download assets. Isomorphic (browser + Node).
+- **`packages/mesh`** — 2D shapes + extrusion into 3D geometry for the
+  frontend viewers. Isomorphic (browser + Node).
 - **`packages/shared`** — shared types + zod schemas.
 
 ## Repository layout
@@ -107,6 +110,14 @@ tts-workshop/
     │   └── src/
     │       ├── index.ts        # fetchMod, getFileName
     │       └── errors.ts
+    ├── mesh/
+    │   └── src/
+    │       ├── index.ts        # public API barrel
+    │       ├── types.ts        # FaceGeometry, ExtrudedGeometry, UVBounds
+    │       ├── shapes.ts       # Shape + shape generators (rect, circle, ...)
+    │       ├── tessellate.ts   # triangulate + cap faces
+    │       ├── walls.ts        # side walls
+    │       └── extrude.ts      # extrudeShape / extrudeShapeParts
     └── extract/
         ├── package.json
         ├── tsconfig.json
@@ -183,6 +194,31 @@ Isomorphic analysis of a parsed `TTSMod`. No Node-specific APIs.
   - No Node-only packages (`cheerio` stays in the backend search only).
   - Pure, deterministic functions where possible.
 
+### `packages/mesh`
+
+2D shape + extrusion library used by the frontend viewers to build 3D geometry.
+
+- `shapes.ts`
+  - `Shape` — `{ outline, holes }`, the minimal interface the tessellator and
+    wall generator need. Shape generators: `rectShape`, `polygonShape`,
+    `hexShape`, `circleShape`, `roundedRectShape`, `frameShape`, plus
+    `scaleShape` and `signedArea`.
+- `tessellate.ts`
+  - `triangulate(shape)` — earcut triangulation (same as three.js).
+  - `capFaces(shape, height, uvScale, uvBounds)` — top/bottom faces. UVs map
+    the shape's bounding box (or `uvBounds` framing) to the unit square; the
+    bottom face uses the same planar xy mapping as the top (no mirror).
+- `walls.ts`
+  - `wallFaces(shape, height, uvScale, uvBounds)` — side walls with outward
+    normals and planar xy UVs (z-independent).
+- `extrude.ts`
+  - `extrudeShape(shape, options)` — merged caps + walls as one geometry.
+  - `extrudeShapeParts(shape, options)` — caps and walls as separate
+    geometries (for distinct materials).
+  - `ExtrudeOptions` — `height`, `capUvScale`, `wallUvScale`, `uvBounds`.
+- `types.ts`
+  - `FaceGeometry`, `ExtrudedGeometry`, `UVBounds`.
+
 ### `apps/proxy`
 
 Hono server exposing search + fetch.
@@ -242,7 +278,8 @@ proxy API and `packages/extract` directly for analysis.
 - `components/viewers/` — 3D viewers built on `@react-three/fiber`,
   `@react-three/drei`, and `@react-three/postprocessing`. `register.ts`
   registers lazy-loaded viewers for `Tile`/`Custom_Tile` (flat box),
-  `Custom_Token` (cylinder), `Card`/`Deck`/`Custom_Deck` (thin box with
+  `Custom_Token` (shape traced from the image's alpha channel via `/trace`,
+  extruded with `@tts/mesh`), `Card`/`Deck`/`Custom_Deck` (thin box with
   face/back textures), and `Custom_Model`/`Custom_Model_Bag`/
   `Custom_Model_Infinite_Bag` (GLTF/OBJ/FBX from `CustomMesh.MeshURL`).
   `Scene.tsx` is a shared canvas with lighting, orbit controls, contact