docs: document object viewers and asset proxy

README.md

@@ -7,10 +7,11 @@ analyze their contents. A lightweight, client-only pnpm monorepo.
 
 | Package             | Role                                                   | Runtime    |
 | ------------------- | ------------------------------------------------------ | ---------- |
-| `apps/web`          | React frontend: search + mod pages                     | Browser    |
-| `apps/proxy`        | Hono HTTP server: Workshop search + save fetch         | Node       |
+| `apps/web`          | React frontend: search + mod pages + 3D object viewers | Browser    |
+| `apps/proxy`        | Hono HTTP server: Workshop search, save fetch, tracing | Node       |
 | `packages/tts`      | Fetch save from Steam, BSON-parse to `TTSMod`          | Node       |
 | `packages/extract`  | Analyze a `TTSMod`: objects, asset refs, downloads     | Isomorphic |
+| `packages/mesh`     | 2D shapes + extrusion into 3D mesh geometry            | Isomorphic |
 | `packages/shared`   | Shared types + zod schemas                             | Isomorphic |
 
 See [`docs/architecture.md`](docs/architecture.md) for the architecture and
@@ -28,7 +29,7 @@ Get a Steam Web API key at https://steamcommunity.com/dev/apikey (free).
 
 To run the frontend alongside the proxy, open a second terminal and run
 `pnpm --filter @tts/web dev` (serves at http://localhost:5173 and proxies
-`/search`, `/items`, and `/health` to the backend).
+`/search`, `/items`, `/health`, `/asset`, and `/trace` to the backend).
 
 ## API
 
@@ -38,6 +39,7 @@ To run the frontend alongside the proxy, open a second terminal and run
 | GET    | `/search?q=&page=`| Search the Workshop (scrapes browse page)    |
 | GET    | `/items/:id`      | Full parsed `TTSMod` (BSON save)             |
 | GET    | `/items/:id/file` | Raw save bytes, filename from header         |
+| GET    | `/asset?url=`      | CORS-safe proxy for external assets (textures, models) |
 | GET    | `/trace?url=&mode=&format=&offset=` | Trace an image into a vector shape (BSON); `offset` insets/outsets in pixels |
 
 ## Commands
@@ -51,6 +53,24 @@ pnpm test         # run the unit tests (vitest)
 pnpm lint         # lint all packages
 ```
 
+## Object viewers
+
+The mod page renders each selected object in 3D. Tiles, tokens, cards, and
+custom models each have a viewer built on `@react-three/fiber`, `@react-three/drei`,
+and `@react-three/postprocessing`, registered per object class and lazy-loaded
+so the three.js stack is code-split out of the main bundle.
+
+- **Tiles / tokens** — extruded from a 2D shape; tokens trace the image's alpha
+  channel via `/trace` to match the artwork's silhouette.
+- **Cards** — a thin rounded rect. Deck images are sheets divided into a
+  `NumWidth` x `NumHeight` grid; the face/back sprite is selected by `CardID`
+  from the containing deck's config.
+- **Custom models** — GLTF/OBJ/FBX loaded from `CustomMesh.MeshURL`.
+
+The camera fits the object's bounds on load, and back faces are flipped so
+they aren't mirrored. See [`docs/decisions.md`](docs/decisions.md) for the
+rationale behind these choices.
+
 ## How search works
 
 Steam has no official search API. The proxy fetches the Workshop browse page