tts-workshop/docs/full-setup-view.md

# Full Setup View — Plan

> **Scope:** A new page that renders every loadable object in a save into a
> single shared 3D scene, sharing materials and geometry where possible. This
> complements the existing per-object inspection on the mod page.

## Motivation

The mod page (`apps/web/src/pages/ModPage.tsx`) inspects one object at a time
inside a shared `Scene`. A "full setup" view renders the whole save at once —
every tile, token, card, and custom model laid out on a virtual table — so a
user can see the entire scene at a glance.

## Current architecture (relevant pieces)

- Each viewer owns its own `<Scene>` wrapper (`components/viewers/Scene.tsx`),
  which provides the camera, lights, orbit controls, contact shadows, and
  post-processing. The mesh content lives inside each viewer:
  - `TileViewer` → `<TileMesh>` (extruded tile, textured top face)
  - `TokenViewer` → `<TokenMesh>` (alpha-traced extruded token)
  - `CardViewer` → `<CardMesh>` (rounded-rect card, sprite UVs)
  - `CustomModelViewer` → `<Model>` (GLTF/OBJ/FBX via `FlexibleModelLoader`)
- `@tts/extract` provides `flattenObjects(mod)` / `traverseMod` to enumerate
  every object in a save.
- `@tts/mesh` provides the shape + extrusion helpers used by the viewers.
- Every object in a save carries a `Transform` (position/rotation/scale in TTS
  world units), which the proxy passes through in the raw BSON. The shared
  type now models it as `TTSObjectTransform`.

## Plan

### 1. Refactor viewers to expose their mesh content (no `Scene`)

Each viewer currently wraps its mesh in `<Scene>`. To compose everything into
one scene, extract and export the inner mesh components, keeping the existing
viewers as thin wrappers:

- `TileViewer` → export `TileObjectMesh` (accepts a `TTSObject`)
- `TokenViewer` → export `TokenObjectMesh`
- `CardViewer` → export `CardObjectMesh`
- `CustomModelViewer` → export `CustomModelMesh` (the `<Model>` + fallback box)

Each viewer now renders `<Scene><XxxObjectMesh object={…} /></Scene>`, so the
object-facing wrapper is the single source of truth for both the per-object
view and the full-setup view.

### 2. New page `FullSetupPage.tsx` at `/mod/:id/setup`

- Reuse `useModStore` (same load path as `ModPage`).
- `flattenObjects(mod)` → filter to renderable classes (those registered in
  `components/viewers/register.ts`: `Tile`, `Custom_Tile`, `Custom_Token`,
  `Card`, `CardCustom`, `Deck`, `DeckCustom`, `Custom_Deck`, `Custom_Model*`).
- Render **one** `<Scene>` containing all renderable objects as
  `<group position={…}>` entries, dispatching to the right `*Mesh` by `Name`.
- Show a summary header (total objects, rendered count, skipped count) and
  loading/error states matching `ModPage`.

### 3. Layout

- Place each object at its real position from the save's `Transform` instead of
  a generated grid.
- `components/viewers/transform.ts` converts a TTS transform to three.js:
  TTS is left-handed (Y up, +Z toward the player), three.js is right-handed,
  so Z is reflected in position and rotation. Each class also gets a base-size
  correction (our viewer meshes are authored for inspection, in arbitrary
  units) and a "lay flat" rotation for the extruded tile/token/card meshes.
- `Scene`'s `Bounds fit` auto-fits the camera to the full layout, so no camera
  work is needed.
- Non-renderable objects (bags, dice, boards without assets) are skipped and
  counted, not dropped silently.

### 4. Share materials & geometry

- **Geometry cache (module-level `Map<string, BufferGeometry>`):** key by a
  canonical string — `card:{w}:{h}:{t}`, `tile:{type}:{aspect}:{t}`,
  `token:{url}:{t}`, `model:{meshUrl}`. All cards of the same size, or tiles
  of the same type/size, reuse one geometry instead of rebuilding per object.
  Token geometry is keyed by the source image URL (the trace is cached per
  URL, so the silhouette is deterministic).
- **Material cache (module-level `Map<string, Material>`):** key by
  `textureUrl + color + roughness`. drei already caches textures by URL
  globally, so sharing the material on top avoids per-object material
  allocation for tiles/tokens with the same image.
- **Cards are the exception:** each card clones its texture for sprite UVs, so
  its face material cannot be shared — but its geometry still can (same card
  size).
- Dispose shared resources on page unmount, or accept a module-level cache for
  the session (see Open decisions).

### 5. Routing & navigation

- Add `<Route path="/mod/:id/setup" element={<FullSetupPage />} />` in
  `apps/web/src/App.tsx`.
- Add a "Full setup" link/button on `ModPage` next to the download button.

### 6. Edge cases

- Objects with no asset (no `ImageURL`/`MeshURL`) render as neutral-colored
  placeholders (matching the current viewers' fallback behavior).
- Token tracing suspends per URL (already cached in `TokenViewer`); the shared
  `Scene` Suspense boundary handles it.
- Large saves: the grid + shared geometry keeps it performant, but cap or warn
  on very large object counts if needed.

## Files touched

- `apps/web/src/components/viewers/{Tile,Token,Card,CustomModel}Viewer.tsx` —
  export object-facing mesh wrappers
- `apps/web/src/components/viewers/sharedResources.ts` — new geometry/material
  caches
- `apps/web/src/components/viewers/transform.ts` — new TTS→three.js placement
  conversion
- `packages/shared/src/types.ts` — add `TTSObjectTransform`
- `apps/web/src/pages/FullSetupPage.tsx` — new
- `apps/web/src/App.tsx` — route
- `apps/web/src/pages/ModPage.tsx` — nav link
- Possibly a small `geometryCache`/`materialCache` helper under
  `components/viewers/`

## Open decisions (defaults in bold)

- **Layout style** — **real `Transform` placement** (was a grouped grid before
  the transform data was wired in).
- **Geometry/material cache lifetime** — **session-level module cache**
  (simplest, consistent with drei's global texture cache) vs dispose-on-unmount.