@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/docs/idea/03-ir.md

@@ -0,0 +1,97 @@
+# 03 — The IR
+
+**One intermediate representation crosses every stage: an indexed triangle `Mesh`.** Primitives emit it, kinds compose it, QA, the rasteriser and the GLB writer consume it. Nothing else crosses a module boundary. Source: `src/core/mesh.ts`, `src/core/asset.ts`.
+
+## Conventions
+
+| Convention | Value | Why |
+|---|---|---|
+| Units | Metres | Real dimensions from reference sheets drop straight in ([ADR 004](../decisions/004-z-up-metres.md)) |
+| Up | +Z | Architecture, vehicles and CAD think in plan (XY) + height |
+| Front | +X | One rule for every asset; the leading end of a loco, the gun of a tank |
+| Left / right | +Y / −Y | Follows from Z-up, X-front, right-handed |
+| Ground | z = 0 | Primitives put their base at `at`; things stand on the ground |
+| glTF output | Y-up, front +Z | Root rotation `[-0.5, -0.5, -0.5, 0.5]`: authoring +X front → glTF +Z, +Z up → +Y, +Y left → +X ([ADR 009](../decisions/009-gltf-front-axis.md)). Part numbers stay Z-up and readable |
+| Rotation | Parts: yaw about local Z. Meshes: any rotation via `place` / `applyAffine` | Part yaw covers turrets, doors, street layout; mesh-level `place` covers sloped plates, angled rods |
+| Colour | Linear RGB per vertex | glTF `COLOR_0` space; `hex()` converts from sRGB |
+
+## `Mesh`
+
+| Field | Type | Per |
+|---|---|---|
+| `positions` | `Float32Array` | vertex × 3 |
+| `normals` | `Float32Array` | vertex × 3 |
+| `uvs` | `Float32Array` | vertex × 2, into the shared trim sheet ([04](04-materials.md)) |
+| `colors` | `Float32Array` | vertex × 3, linear RGB |
+| `indices` | `Uint32Array` | triangle × 3, counter-clockwise from outside |
+
+Helpers: `MeshBuilder` (`vertex`, `tri`, `quad`, `build`), `merge`, `translate`, `boundsOf`, `triangleCount`. Transforms (`src/core/transform.ts`): `place(mesh, { at, yaw, pitch, roll, scale })`, `affine`, `frame`, `applyAffine`. Rotation order Z (yaw) · Y (pitch) · X (roll); normals are rotated and renormalised, so use uniform scale.
+
+## Parts
+
+A compiled asset is a flat, ordered list of parts; the hierarchy is in `parent` pointers.
+
+| Field | Meaning |
+|---|---|
+| `name` | Unique, snake_case. A pivot's name becomes its glTF node and mesh name; static parts merge into their pivot on export ([batching](#batching-parts--pivots)) |
+| `mesh` | `Mesh` or `null` (a group / pivot) |
+| `at` | Translation in the parent's space = the pivot |
+| `parent` | Part name or `null` (child of the root node) |
+| `yaw` | Rotation about local Z |
+| `motion` | `spin` / `slide` / `sway` / `null`; baked to a looping clip named `run` only with `animations: true` |
+| `emitter` | Particle source config, exported as `extras.ts23d.emitter` on an empty node |
+| `socket` | Attachment point config, exported as `extras.ts23d.socket` on an empty node |
+| `surface` | `opaque` · `cutout` · `glass` · `translucent`; picks one of ≤ 4 shared materials |
+
+**Pivots go where the part hinges.** A turret group sits on the ring; the gun group sits at the trunnion; the barrel is offset forward from it. Rotate `gun` in the engine and the barrel elevates correctly. The `t34` recipe shows exactly this.
+
+`worldTransforms(parts)` chains translation + yaw down the hierarchy; `toWorld(t, p)` maps a local point. QA and the renderer read world space from there.
+
+## LODs
+
+| LOD | Use | What a recipe typically does |
+|---|---|---|
+| 0 | Hero / close | Full detail, high segment counts |
+| 1 | Mid distance | Fewer segments, small parts kept |
+| 2 | Far | Masses only: drop hatches, windows, rivets; 6-segment cylinders |
+
+**LODs are re-runs, not decimation.** `compile(asset, { lod })` calls `build` again with `ctx.lod` set. The far LOD keeps named parts, pivots and silhouette because the author chose what to drop. Each LOD has its own triangle budget.
+
+## Batching: parts → pivots
+
+**`toGlb` merges every static part into its nearest pivot ancestor by default (`mergeToPivots`, `src/export/merge-pivots.ts`).** A pivot is anything with no mesh (a `ctx.group`, `ctx.emitter`, `ctx.socket`) or a part with `motion`. Groups, emitters and sockets always survive batching as named nodes. Batching also splits by surface: opaque geometry merges into the pivot's own mesh; each other surface in use becomes one child `<pivot>_<surface>` (e.g. `body_glass`), one draw call each. Static top-level geometry becomes one `body` node.
+
+| Asset | Draw calls after merge |
+|---|---|
+| A static prop or building | 1 (`body`) |
+| A shampoo bottle: opaque cap, translucent body | 2 |
+| A tank | `body` + `turret` + `gun` + one per road wheel (each spins independently) |
+
+So: **draw calls = movable pieces with geometry.** Names the engine binds to (`turret`, `gun`, `road_wheel_l_0`) survive; static detail names (`turret_hatch`) don't. QA and `real.measures` run on the unmerged compile, so they still see every part. Pass `toGlb(asset, { keepParts: true })` to keep one node per part (debugging, editors).
+
+Planned (M3): bake motion into vertex attributes (pivot + spin axis per vertex) so a shader animates all wheels in one draw call.
+
+## GLB layout
+
+Validity: every exported shape is checked by the Khronos glTF-Validator in the test suite (`src/export/validator.test.ts`): 0 errors. Production rules and remaining gaps: [glb-production.md](../architecture/glb-production.md).
+
+| glTF element | Content |
+|---|---|
+| `scene[0]` | One root node named after the asset, rotated Z-up/+X-front → Y-up/+Z-front |
+| `nodes` | One per **pivot**, `translation` = `at`, `rotation` = yaw quaternion, plus `body` for static top-level geometry. `{ keepParts: true }` keeps one node per part |
+| `meshes` | One per pivot (and surface) with geometry, static parts merged in. `POSITION`, `NORMAL`, `TEXCOORD_0` (float32); `COLOR_0` normalised u16 RGBA; indices u16 when ≤ 65,535 vertices, else u32 |
+| `materials` | At most 4, one per surface in use, all over the same trim sheet: `opaque` (`ts23d_trim`), `cutout` (alpha-test, double-sided), `glass` and `translucent` (`KHR_materials_transmission` + `_volume` + `_ior`; alpha-blend fallback) |
+| `animations` | Two clips: `rest` first (static, so viewers that autoplay the first clip open paused), then `run`: 4 s, every motion rounded to whole cycles (`cyclesOf`) so the loop is seamless, spins ≥ 12 keys per turn, linear, time accessors shared. `toGlb()` exports it only with `{ animations: true }` (glTF has no autoplay flag; games drive pivots from code). `t3d build` bakes it by default so viewers show play controls; `--no-animations` skips it |
+| `extras` | Root: `{ kind, lod, units: 'metres', up }`. Nodes: `ts23d.emitter`, `ts23d.socket` |
+
+Textures: the painted trim sheet, bound to every surface material (`--sheet external` by default: shared PNGs next to the GLBs). With `--sheet none` vertex colour alone carries the look.
+
+Shipped since: the painted trim sheet (albedo, normal, ORM), embedded or as shared external PNGs, `TANGENT` only when a sheet is bound ([04](04-materials.md)).
+
+Planned for the GLB, M2:
+
+| Addition | Effect |
+|---|---|
+| `optimize(mesh)` pass: vertex weld + vertex-cache reorder, reports ACMR | Fewer vertices, better GPU post-transform cache use |
+| Opt-in `web` profile: `KHR_mesh_quantization` + `EXT_meshopt_compression` | Smaller files for three.js / Babylon / glTFast. Not default: Godot refuses required extensions, so the default stays core glTF |
+| LOD switch-distance hints in node extras | Engines pick LODs without guessing |

package/docs/idea/04-materials.md

@@ -0,0 +1,114 @@
+# 04 — Materials
+
+**Every asset shares one texture set: a 1024² trim sheet, tinted by vertex colour, under at most four surface materials (opaque, cutout, glass, translucent).** One texture set for everything (with static geometry batched per pivot, draw calls = the parts the engine moves), equal texel density across assets, and a palette swap is a recipe edit, never a new texture. Source: `src/material/`. Decisions: [ADR 003](../decisions/003-shared-trim-sheet.md), superseded by [ADR 008](../decisions/008-surface-materials.md) (surfaces).
+
+## Status (2026-10-25)
+
+| Piece | Status |
+|---|---|
+| Trim-sheet layout: 8 strips, 6 decal cells, 11 foliage cells | Shipped |
+| UVs authored against the layout by every primitive | Shipped |
+| Palettes + `hex()` sRGB → linear | Shipped |
+| `grime` pass (vertex-colour wear) | Shipped |
+| ≤ 4 shared materials per GLB (opaque, cutout, glass, translucent) over one sheet | Shipped |
+| `paintTrimSheet`: procedural albedo / normal / ORM | Shipped |
+| Sheet in the GLB: embedded, or shared external PNGs | Shipped |
+| `threeMaterialSource` (TSL) and `godotShaderSource` (.gdshader): wind, window glow, wear | Shipped |
+| KTX2 (`KHR_texture_basisu`) | Planned |
+| `kubeezImages`: image source for decals / texture sources | Planned, M5 |
+
+## The trim sheet
+
+| Region | Contents | Mapping |
+|---|---|---|
+| Strips: 8 rows, each 1/16 of V, full U | `plain` `brick` `stone` `slate` `iron` `wood` `glass` `concrete` | Tile along U; one strip rect = 2 m of surface |
+| Cells: 1/8 × 1/8 squares from V = 0.5 | `window_sash` `door_panel` `clock` `smokebox` `sign` `porthole` | Fixed decals; one cell = 1 m |
+
+`stripRect(id)` / `cellRect(id)` return `{ u0, v0, u1, v1, metres }`. `metres` is the point: a primitive maps UVs by world size, so a 6 m wall and a 0.4 m crate show bricks at the same size.
+
+A primitive takes `strip?: StripId` (default `plain`). Cells are used by the planned `cell()` primitive (M1).
+
+## Colour: palettes and vertex colour
+
+The sheet is greyscale detail (mortar lines, grain, rivets); hue comes from `COLOR_0`, multiplied over it.
+
+```ts
+import { definePalette, palettes } from '@developerz.ai/ts23d';
+
+const livery = { ...palettes.victorianRail, paint: palettes.victorianRail.red };   // repaint = spread
+const custom = definePalette({ hull: '#203040', deck: '#8a6f4e' });            // sRGB hex in, linear out
+```
+
+| Palette | Keys |
+|---|---|
+| `victorianRail` | `paint` `trim` `iron` `brass` `red` |
+| `artDeco` | `limestone` `steel` `glass` `bronze` |
+| `modernGlass` | `glass` `aluminium` `concrete` |
+| `harbour` | `hull` `deck` `white` `red` |
+
+Era/region palettes are data. Add one in `src/material/palette.ts` with the era in the key name.
+
+## Wear: passes
+
+`/passes` post-processes a finished mesh, so recipes stay about shape. Shipped: `grime(mesh, { ground?, groundStrength?, zones? })` darkens vertex colour below `ground` metres of the mesh's own z, not world z (mud, dust) and inside spherical `zones` (`{ at, radius, strength }`: soot round a chimney, oil under an engine).
+
+```ts
+ctx.part('hull', grime(box({ size: [6, 3, 1.5], color: green, strip: 'iron' }), { ground: 0.6 }));
+```
+
+## Shader sources
+
+Per-asset effects that keep the shared material. Generated per engine from the same hints:
+
+| Function | Output | Hints |
+|---|---|---|
+| `threeMaterialSource(hints)` | three.js TSL node-material source | `wind: { strength }`, `windowGlow: { color, ratio }`, wear |
+| `godotShaderSource(hints)` | Godot `.gdshader` source | same |
+
+Wind is crown `sway` motion in the GLB today; per-vertex wind weights are planned.
+
+## Procedural material generator
+
+`paintTrimSheet(recipe = DEFAULT_SHEET): PaintedSheet` paints the whole sheet from code at a fixed seed, so textures are as deterministic as meshes.
+
+| Output | Format |
+|---|---|
+| `albedo` | RGBA8, sRGB. Greyscale detail, tinted by vertex colour; foliage cells are the exception (coloured albedo, alpha = leaf mask) |
+| `normal` | RGBA8, tangent space |
+| `orm` | RGBA8: R occlusion · G roughness · B metalness |
+
+| Size | Paint time (measured) |
+|---|---|
+| 512² | ≈ 0.22 s |
+| 1024² (default) | ≈ 0.8 s |
+| 2048² | ≈ 2.95 s |
+
+Strip kinds (`StripRecipe.kind`): `bond` · `planks` · `plates` · `noise` · `flat` · `slate` · `concrete` · `glass`, with `scaleMetres`, `roughness`, `metalness` and per-kind params. Cells: 6 decal cells (window sash, door panel, clock, smokebox, sign, porthole) and 11 foliage cells.
+
+### Getting it into the GLB
+
+| Library | CLI | Result |
+|---|---|---|
+| `toGlb(a, { sheet })` | `--sheet embed` | Textures inside each GLB |
+| `toGlb(a, { sheet: { external: true, prefix } })` | `--sheet external` (default) | `out/trim_sheet_{albedo,normal,orm}.png` written once; every GLB references `../trim_sheet_*.png` |
+| no `sheet` | `--sheet none` | Vertex colour only |
+
+`--sheet-size 512|1024|2048`. `TANGENT` is emitted only when a sheet is bound. The `material_swatches` recipe shows every strip and cell.
+
+### Known limits
+
+- Strips are 64 texels tall at 1024²; a strip is 2 m of surface.
+- `box` stretches V over the whole face, so tall faces stretch the strip vertically.
+- Mips blend neighbouring strips from mip level 3.
+- No KTX2 yet; PNG only.
+
+### Image sources
+
+Code paints the base; images add what code paints badly: signage, logos, weathering photos, concept-art colour.
+
+- Cells accept `{ image: Uint8Array }` instead of a recipe: stamp a decal.
+- Recommended source: **[kubeez.com](https://kubeez.com)** (a partner) for reference/concept images, decals and texture source images. Planned adapter: `kubeezImages({ apiKey })` in `/neural` ([08](08-neural-adapters.md)). The key is passed by the caller, never read from the environment.
+- Any function returning PNG bytes fits the `ImageSource` interface.
+- Generated images are cached by (source, prompt, seed) like generated meshes, so rebuilds need no network.
+
+Images are inputs, never the only path. The sheet must paint without them.

package/docs/idea/05-agent-loop.md

@@ -0,0 +1,141 @@
+# 05 — The agent loop
+
+**The agent writes, builds, looks, and fixes the single worst thing, until two looks in a row find nothing.** ts23d's job is to make each turn of that loop cheap: a build in well under a second, one QA verdict, one image that shows everything.
+
+## The loop
+
+```
+research refs ─► write recipe ─► t3d build ──QA FAIL──► fix finding ─┐
+                      ▲              │                               │
+                      │           QA PASS ◄──────────────────────────┘
+                      │              ▼
+                 detail pass ◄─ read PNG ◄─ t3d shot
+```
+
+| Step | Command / action | Done when |
+|---|---|---|
+| 1. Research | Find real dimensions, a side elevation, photos. Put the URLs in `sources`, overall L × W × H in `real`, and every key size (driver diameter, gauge, wheelbase, turret width) in `real.measures` | The spec is in the recipe, in metres, each number with a source |
+| 2. Masses | Write the big volumes only: hull, body, tiers. Real dimensions | Silhouette roughly right |
+| 3. Build | `bunx t3d build recipes/x/x.ts` | Prints `QA PASS`, exit 0. Fix every finding first; each prints a `fix:`. A `measures` or `proportions` finding means rebuild the part, never edit the spec |
+| 4. Shot | `bunx t3d build` already wrote `out/x/sheet.png`; `bunx t3d shot recipes/x/x.ts` for a sheet without GLBs | `out/x/sheet.png` + `manifest.json` written |
+| 5. Read | Open the PNG (vision). Compare against the reference | One concrete error named, e.g. "turret 30% too tall in SIDE -Y" |
+| 6. Fix | Edit the recipe for that one error | → step 3 |
+| 6b. Photo match *(planned, M2)* | `photoMatch(asset, { photo, camera })` → one PNG: photo · model · overlay, plus silhouette IoU | IoU stops rising; the overlay shows no misplaced mass |
+| 7. Detail pass | Once masses read right: hatches, rivets, windows, handrails. Gate each on `ctx.lod` | Detail shows at LOD0, dropped by LOD2, budget holds |
+| Stop | Two consecutive shots with nothing worth fixing | |
+
+Fix one thing per iteration. Proportions before details: a wrong mass makes every detail on it wrong.
+
+## Fidelity from real-world sizes
+
+**The spec goes in first; the model is rebuilt until the gate agrees with it.** Real-world sizes are the cheapest fidelity there is: a 4-4-0 with the right driver diameter, wheelbase and boiler height reads as *that* locomotive before any texture exists.
+
+| Gate | Holds | Tolerance |
+|---|---|---|
+| `proportions` | Overall L × W × H vs `real` | ±5% |
+| `measures` | Each named dimension vs `real.measures` | ±2% each |
+| `clashes` | Moving parts clear everything through their whole motion | 1 cm |
+| `floating-parts` | Every part in surface contact with something grounded | 2 cm |
+
+An agent that "fixes" a finding by editing `value` or `tolerance` has defeated the gate. Review rule: a diff touching `real` needs a source for the new number.
+
+## The contact sheet
+
+One PNG, 1200 × 840 px. Every view orthographic, on the same scale, over a ground grid in metres. Rendered on the CPU ([ADR 007](../decisions/007-cpu-contact-sheets.md)).
+
+**Header line:** `NAME  <X>X<Y>X<Z>M  GRID <step>M  LOD0`: bounding box in metres, grid step, LOD.
+
+| Cell | Label | Camera | Check |
+|---|---|---|---|
+| Row 1, left | `3/4 FRONT` | From front-right (+X, −Y), above | Overall read; does it look like the thing? |
+| Row 1, middle | `FRONT +X` | Looking at the +X face | Width, symmetry, track/gauge |
+| Row 1, right | `SIDE -Y` | From −Y, front (+X) on the right | Length, height, profile vs a side elevation |
+| Row 2, left | `TOP` | From above, +X up | Plan, footprint, alignment |
+| Row 2, middle | `3/4 REAR` | From rear-left (−X, +Y), above | The back nobody modelled |
+| Row 2, right | `FAR LOD2` | 3/4 front, LOD2 compile | Does the far LOD keep the silhouette? |
+
+Grid step is picked so the asset spans ≤ 24 cells: 0.1, 0.5, 1, 5, 10, 50 or 100 m. Shading is flat Lambert over vertex colour; texture is not shown.
+
+### Reading it
+
+| Symptom in the sheet | Likely cause |
+|---|---|
+| A part hangs in the air in `SIDE -Y` / `FRONT +X` | Wrong `at` z, or `at` given in world space instead of parent space |
+| Asset faces left in `SIDE -Y` | Front built along −X; flip it, +X is front |
+| Header dims don't match the reference | Units (cm vs m), or a stray part stretching the bounds |
+| `FAR LOD2` loses a defining shape | Dropped a mass instead of a detail at LOD2 |
+| Mirror-image parts asymmetric in `TOP` | Sign error on one side's y |
+
+## Photo match (planned, M2)
+
+**The step after the contact sheet: compare against reality, not against memory.** `photoMatch(asset, { photo, camera: { eye, target, fovDeg } })` renders the model from the camera that took the reference photo and stacks three panels in ONE PNG:
+
+| Panel | Shows |
+|---|---|
+| Top | The reference photo |
+| Middle | The model from the same camera, scaled to the photo |
+| Bottom | 50% overlay of the two |
+
+It also returns silhouette IoU (0–1), the number the planned `silhouetteIoU` gate and the M6 reverse direction optimise. Camera solving from ≥ 4 marked correspondences comes later (M6); until then the agent passes the camera.
+
+The bar: [`loco-photo-match.png`](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/reference/loco-photo-match.png), from the in-house predecessor, not from this library.
+
+## Debugging with `inspect`
+
+When a finding is unclear, write a scratch script instead of guessing. `inspect(compiled)` answers geometric questions by part glob:
+
+```ts
+import { compile, inspect } from '@developerz.ai/ts23d';
+import { t34 } from './recipes/t34/t34.ts';
+
+const q = inspect(compile(t34, { lod: 0 }));
+q.parts('road_wheel_l_*');                  // names
+q.bounds('turret*');                        // world AABB
+q.distance('track_l_top', 'hull_upper');    // surface gap, metres (0 = touching/intersecting)
+q.penetration('track_l_top', 'hull_upper'); // { depth, samples }: how deep A sits inside B's solid
+```
+
+| Method | Returns |
+|---|---|
+| `parts(glob)` | Matching part names |
+| `mesh(glob)` | Merged world-space mesh, or `null` |
+| `bounds(glob)` | World AABB, or `null` |
+| `distance(a, b, max?)` | Smallest surface-to-surface distance, capped at `max` |
+| `penetration(a, b)` | `{ depth, samples }`: deepest point of A inside B's closed solid |
+
+Also exported: `glob(pattern) → RegExp`, `insideSolid`. Once you know the intent, encode it as a `checks` entry so the gate holds it from then on.
+
+## Output an agent reads
+
+`out/<asset>/manifest.json` answers most questions without opening a GLB: triangles and draw calls per LOD, pivots (the names engine code binds to), emitters, sockets, surfaces, `real` and each measure with its **measured** value, sources, QA findings. `out/index.json` lists every asset in the run with its verdict.
+
+## Machine-readable output
+
+`--json` on any command:
+
+```json
+{"ok":true,"data":[{"asset":"<name>","findings":[],"triangles":[<lod0>,<lod1>,<lod2>]}]}
+{"ok":false,"error":{"code":"T3D_PART_UNKNOWN","message":"…","fix":"add the parent (ctx.group or ctx.part) before its children"}}
+```
+
+Current numbers for the gallery recipes: `bun run bench` (README benchmarks block).
+
+Exit codes: `0` pass · `1` QA finding or `T3D_*` error · `2` usage.
+
+## Prompt snippet
+
+```text
+Using @developerz.ai/ts23d, write recipes/<name>.ts: a <thing>, real dimensions in metres,
+Z up, +X front. Look up reference dimensions first. Block out the masses, then details.
+Name every part that moves (axle_*, door_*, rotor_*) and pivot it where it hinges.
+Loop: bunx t3d build → fix until QA PASS → read out/<name>/sheet.png →
+fix the single biggest error → repeat. Stop when two shots in a row show nothing worth fixing.
+Never use Math.random; use ctx.rng.
+```
+
+The package ships `CLAUDE.md` (the repo's `AGENTS.md` links to it) and `llms.txt` for agents that read them.
+
+## Planned (as of 2026-10)
+
+- **Reverse direction:** a VLM proposes recipe params from photos; the loop scores them by silhouette IoU and keeps the best (M6).
+- **MCP server:** `build`, `shot`, `list` as tools, PNG returned inline (M6).

package/docs/idea/06-qa.md

@@ -0,0 +1,101 @@
+# 06 — QA gates
+
+**A gate finding is a build failure, not a warning.** `t3d build` runs every default gate on every LOD and exits 1 on any finding. The agent iterates until it prints `QA PASS`. Source: `src/qa/`.
+
+## Shipped (as of 2026-10)
+
+`DEFAULT_GATES`, run per LOD by `runQa(compiled)`:
+
+| Gate | Runs at | Fails when | Fix line it prints |
+|---|---|---|---|
+| `triangle-budget` | Every LOD | Total triangles at LOD *n* > `budget.triangles[n]` | Drop detail at this LOD (read `ctx.lod`) or raise the budget with a reason |
+| `floating-parts` | Every LOD | A part's **surface** doesn't come within 2 cm of the ground (z ≈ 0) or of a grounded part's surface, transitively | Move it onto what holds it (check `at`, parent, LOD-gated detail around it). Bounding boxes touching is not enough |
+| `clashes` | Every LOD | Another part penetrates more than 1 cm into the volume a moving part sweeps through its whole motion | Move or trim either part for running clearance; if they interlock by design, `clearOf: ['<part>']` on the moving part |
+| `part-names` | Every LOD | A part name isn't `[a-z][a-z0-9_]*` | Rename; engines bind to node names |
+| `proportions` | LOD0, if `real` is set | Overall world span along X / Y / Z is off `real.length` / `width` / `height` by more than `real.tolerance` (default ±5%) | Rescale along that axis; re-derive lengths from the `sources`, don't fudge the tolerance |
+| `check` | Every LOD, if `checks` is set | A recipe-declared check returns a finding (`clear`, `noOverlap`, `touches`, `symmetric`, or your own) | The check's own `fix` |
+| `measures` | LOD0, if `real.measures` is set | A spec-sheet dimension (driver diameter, gauge, wheelbase, turret width) measured on the model is off by more than its `tolerance` (default ±2%), or names no part | Rebuild the part from the spec number. **Never edit the spec to match the model** |
+
+Each finding: `{ gate, part?, message, fix }`. Text output:
+
+```
+tiger_1  QA FAIL  tris 3108/1660/724
+  ✗ floating-parts [exhaust_0]: LOD0: 'exhaust_0' touches nothing connected to the ground
+    fix: move it onto what holds it (check `at`, parent and the LOD-gated detail around it) — …
+```
+
+### How each geometric gate measures
+
+| Gate | Method | Tolerance constant |
+|---|---|---|
+| `floating-parts` | AABB prefilter, then surface samples vs triangles of the other part (point ↔ triangle distance, `TriangleGrid` spatial index), grown from the ground outward | `CONTACT_EPS` = 0.02 m |
+| `clashes` | Per motion root (a spinning axle group, a rotor, a sliding crosshead) and its subtree: **spin** → exact solid of revolution (radius profile per axial slice, 24 slices); **sway** → the same full revolution, conservatively; **slide** → the moving mesh's bounds extended along the stroke. Every other part's surface samples are tested against that volume | `CLASH_EPS` = 0.01 m |
+| `proportions` | Union of world-space part bounds at LOD0 | `real.tolerance`, default 0.05 |
+| `measures` | Extent of the named parts along `axis` (prefix match, so `axle_driver_0` includes its wheels), or the centre-to-centre distance of two parts (`between`) | per measure, default 0.02 |
+
+Order in `DEFAULT_GATES`: `triangleBudget`, `floatingParts`, `clashes`, `partNames`, `proportions`, `measures`, `recipeChecks` (gate name `check`).
+
+### Recipe checks
+
+Static intersections need declared intent: a bolt sunk into a plate is fine, a track through the hull is not. `checks: [...]` on `defineAsset` states which is which ([02-dsl](02-dsl.md#checks-declared-intent)). `clear` decides "inside" by ray parity against the other part's closed solid, so an open planar sheet never counts as a solid. Penetration over 1 cm fails.
+
+Helpers exported for custom gates: `touching`, `pointTriangleDistance`, `surfaceSamples`, `TriangleGrid`, `measure`, `insideSolid`, `glob`, `inspect`.
+
+### Declaring what QA checks
+
+```ts
+export const loco = defineAsset({
+  name: 'loco_440',
+  kind: 'vehicle',
+  sources: ['https://example.org/roster-sheet.pdf', 'Builder drawing no. 1234'],
+  real: {
+    length: 15.6, width: 2.9, height: 4.4,                       // proportions: ±5%
+    measures: [                                                  // measures: ±2% each
+      { label: 'driver diameter', value: 1.52, axis: 'z', parts: ['axle_driver_0'], source: 'roster' },
+      { label: 'gauge', value: 1.435, axis: 'y', between: ['rail_l', 'rail_r'] },
+      { label: 'driving wheelbase', value: 2.44, axis: 'x', between: ['axle_driver_0', 'axle_driver_1'] },
+    ],
+  },
+  budget: { triangles: [20000, 8000, 2000] },
+  build(ctx) {
+    // a crosshead slides in its guide by design:
+    // ctx.part('crosshead_l', mesh, { motion: { kind: 'slide', offset: [0.3, 0, 0], hz: 1 }, clearOf: ['guide_l'] });
+  },
+});
+```
+
+The rule for agents: **a failing `measures` finding means the model is wrong.** Rebuild the part from the spec; editing `value` or widening `tolerance` to pass is a defect.
+
+### Known limits
+
+- Point-in-solid (`clear`, `clashes` depth) needs **closed, non-overlapping** parts. Split structure from dressing: a closed hull part, with bolts and straps as separate parts, not one self-intersecting soup.
+- `clashes` sweeps `sway` as a full revolution; a sector sweep is planned.
+
+- `proportions` measures overall bounds, so a stray part (a too-long barrel) can fail it, or mask a wrong hull. Check the header dims on the contact sheet.
+- `clashes` uses bounds for slides, so an angled slide's volume is conservative; declare `clearOf` for a guide it rides in.
+- `floating-parts` has no opt-out for things that genuinely fly (an aircraft in flight, a hanging sign). Planned, M1.
+- Custom gates: `runQa(asset, [...DEFAULT_GATES, myGate])` from code. The CLI runs the defaults only.
+
+## Repo gates (this repo's recipes, in `bun run verify`)
+
+| Gate | Checks |
+|---|---|
+| `scripts/recipes.ts` | Every `recipes/*/*.ts` asset compiles at LOD 0/1/2, passes `DEFAULT_GATES`, and two builds give the same GLB hash (byte-hash determinism, shipped) |
+| `scripts/determinism.ts` | No `Math.random()`, `Date.now()`, `new Date()`, `performance.now()`, `toLocale*String()` in `src/` or `recipes/` |
+
+## Planned
+
+| Gate | Checks | Signature | Milestone |
+|---|---|---|---|
+| `silhouetteIoU` | Silhouette IoU 0–1 against a reference photo, computed by `photoMatch` (`/render`) from the photo's camera. Fails below a threshold the recipe declares. Drives the M6 reverse direction | `(asset, referencePng) => number`, exported, throws `T3D_NOT_IMPLEMENTED` | M2 |
+| ACMR | Average cache miss ratio per mesh, after the planned `optimize` pass (weld + vertex-cache reorder), stays under a ceiling | Proposed | M2 |
+| Manifold / normals | No open edges where closed is promised; normals face out | Proposed | M2 |
+| Texel density | Every UV'd face within a band of the sheet's metres-per-rect | Proposed, needs the painter | M2 |
+| Cross-machine byte-hash | Same-process double build ships (above). Next: compare hashes across OSes / runners; a `t3d build` flag for users' recipes | Proposed | M1 |
+
+## Adding a gate
+
+1. A `Gate` is `(asset: CompiledAsset) => Finding[]`. Pure; world-space meshes via `worldMeshes` / `worldTransforms`.
+2. Every finding carries a `fix` an agent can act on without reading the gate's source.
+3. One file in `src/qa/`, a test next to it with one passing and one failing asset.
+4. Add it to `DEFAULT_GATES` only when every recipe in `recipes/` passes it.

package/docs/idea/07-what-fits.md

@@ -0,0 +1,45 @@
+# 07 — What fits
+
+**Code recipes win where parts line up, repeat, or match real dimensions. Organic forms work as stylised sculpts (SDF edit lists); realistic anatomy is still the weak spot.** Pick the tool by the asset, not by loyalty; many teams will use both.
+
+As of 2026-11. "Today" = shipped in this repo; "Planned" names the milestone ([roadmap](../plans/roadmap.md)).
+
+## Fit matrix
+
+| Category | Examples | Fit | Today | Planned | Why |
+|---|---|---|---|---|---|
+| Hard-surface props | Crates, barrels, lamps, benches, machinery | **Strong** | `box({ bevel })`, `lathe`, `prism`, `beam`, `planar`, `sweep`, `loft`, `lattice`, `text`; `weightedNormals` | | Primitive shapes, real dimensions, repetition |
+| Architecture | Facades, terraces, towers, stations | **Strong** | `facade({ kit })`, `setbacks`, `roof`, `opening`, `mass`, `tiled`, `cell`; `station_halt`, `water_tower` recipes | | Grammar-driven repetition, floors × bays |
+| Tracked / wheeled vehicles | Tanks, carts, trucks | **Strong** | `trackRun`, `axle`, `prism` sloped armour, `loft` | | Named spinning wheels, pivoted turrets |
+| Rail | Steam locos, wagons | **Strong** | `whyteAxles` (Whyte `4-4-0`), `lathe` boilers, `beam` rods; `loco_440` recipe | `orbit` motion for side rods | Domain-native params |
+| Aircraft | Props, biplanes, airliners | **Good** | `propeller`, `loft`, `sweep` | Aircraft recipes | Lofted sections + named control surfaces |
+| Vessels | Boats, ships, barges | **Good** | `hull` from length / beam / draft / sheer | Ship recipes | Lofted hull sections |
+| Modular kits | Walls, floors, pipes, fences | **Strong** | `box`, `prism`, `beam`, `sweep`, `tiled` | | Snapping on a metre grid |
+| Vegetation | Trees, shrubs | **Good** | `tree` (Weber–Penn; oak, pine, palm, birch, willow), `trees` family | Vertex wind weights; crossed-billboard LOD2 impostors | Botanical rules are code |
+| Rocks, terrain | Boulders, cliffs, mountain tiles | **Good** | `sdf` / `sculpt` + noise; `heightfield` + hydraulic / thermal erosion + `terrainColor`; `boulders`, `asteroid`, `mountain_range` recipes | Rivers carved as meshes | Erosion is what makes terrain read as real |
+| Stylised characters | Fantasy busts, mascots | **Fair** | `head` kind (orc, goblin, human, dwarf, elf presets) on `sculpt`; jaw and eyes as pivots | Skinned bodies (`creature`, glTF skins) | Readable stylised shapes; realism is not the goal |
+| Realistic animals | Horse, dog, bird | **Weak** | — | `/neural` adapter (M5) | Anatomy is sculpted, not specified |
+| People | Characters, NPCs | **Weak** | — | `/neural` adapter or `importGlb` of a CC0 base mesh (M5) | Faces, hands, anatomy |
+| Cloth, hair, soft goods | Flags, sofas, garments | **Weak** | — | — | Simulation / sculpt territory |
+| Photoreal hero assets | Close-up scans | **Out of scope** | — | — | Photogrammetry or a sculptor |
+
+## Where each approach is strong
+
+| Strength | Code recipes (ts23d) | Image-to-3D / AI generators |
+|---|---|---|
+| Organic and sculpted forms | Stylised: fair (`sculpt`); realistic: weak | Strong |
+| Concept art → textured mesh in seconds | No | Strong |
+| Auto-rigging characters | No (rigid part hierarchy only) | Exists in several tools; rigs usually need cleanup |
+| Parts that line up, repeat, match real dimensions | Strong | Weak |
+| Named, pivoted, animatable nodes | Built in | Usually one fused mesh |
+| Deterministic, diffable in git | Yes | No |
+| Shared material, consistent texel density | Yes | Per-asset textures |
+| Cost, licence conditions on outputs | Free, none | Credits; terms vary by tier ([landscape](../landscape.md)) |
+
+## Covering the weak spots
+
+1. **Stylised creature kind** (M4): the `sculpt` + `head` work extended to whole bodies, SDF flesh over a biped/quadruped/bird skeleton, skin weights from the sculpt's own blend weights ([glTF capabilities](../architecture/gltf-capabilities.md)). Readable, deterministic. Not realistic, by design.
+2. **`/neural` adapter** (M5): run an open-weight model (TRELLIS.2, Hunyuan3D 2.1, SF3D/SPAR3D) on your own GPU, wrap the result as an ordinary part, cache it by content hash. [08-neural-adapters.md](08-neural-adapters.md).
+3. **`importGlb`** (M5): bring a mesh from anywhere (a CC0 base mesh, a sculpt, another tool) and fit it into the recipe as a part.
+
+Mix them: a recipe-built cart with a neural-generated horse in front, one scene, one material.

package/docs/idea/08-neural-adapters.md

@@ -0,0 +1,78 @@
+# 08 — Neural adapters
+
+**Optional. Never a core dependency. Runs on the user's own GPU. The output becomes an ordinary part, cached by content hash, so CI rebuilds without a GPU.** Source: `src/neural/`. Status as of 2026-10: **all planned (M5)**. Every entry point throws `T3D_NOT_IMPLEMENTED`.
+
+## Why
+
+Recipes are weak on living things and sculpted forms ([07](07-what-fits.md)). Open-weight image-to-3D models are strong there. The adapter lets one recipe hold both: a code-built cart, a generated horse.
+
+## Interfaces (signatures fixed)
+
+```ts
+interface GenerateRequest {
+  prompt?: string;
+  image?: Uint8Array;          // PNG/JPEG reference or concept image
+  seed: number;
+  fit: Vec3;                   // fit into this box, metres, Z up, base on the ground
+  targetTriangles: number;
+}
+
+interface MeshGenerator {
+  model: string;               // 'trellis-2', 'hunyuan3d-2.1', 'sf3d' — part of the cache key
+  generate(r: GenerateRequest): Promise<Mesh>;
+}
+
+localGenerator({ model, endpoint }): MeshGenerator   // talks to a local HTTP server
+importGlb(bytes, { fit, recolor? }): Mesh            // any GLB as a part
+kubeezImages({ apiKey, model? }): ImageSource        // images for references and materials
+```
+
+## Models worth wrapping
+
+Facts from [landscape.md](../landscape.md), as of 2026-10. Check each licence yourself before shipping outputs.
+
+| Model | Input | Licence | GPU | Note |
+|---|---|---|---|---|
+| TRELLIS.2 (Microsoft) | Single image | MIT | ≥ 24 GB, tested on A100/H100 | PBR GLB; can texture an existing mesh |
+| Hunyuan3D 2.1 (Tencent) | Image, multi-view | Tencent community licence: excludes EU/UK/South Korea, terms above 1M MAU, no training other models on outputs | ~29 GB shape + texture | Read the licence before relying on it |
+| SF3D / SPAR3D (Stability) | Single image 512² | Stability Community Licence: free under $1M revenue | See model card | UV-unwrapped, delighted textures; SPAR3D adds point-cloud editing |
+
+## Flow
+
+```
+reference image (photo, or kubeez.com concept) ─► localGenerator.generate()
+   ─► fit to box, Z up, base at z = 0, decimate to targetTriangles
+   ─► remap UVs/colour onto the shared trim sheet (vertex colour baked)
+   ─► cache: .ts23d/neural/<sha256(model, prompt|image, seed)>.glb
+   ─► ctx.part('horse', mesh, { at, parent })
+```
+
+## Determinism
+
+A GPU run is not reproducible across drivers and hardware; the cached file is.
+
+| Rule | |
+|---|---|
+| Cache key | `(model, sha256(prompt or image), seed)` |
+| Cache location | `.ts23d/neural/`, committed to git or published with the package |
+| Cache hit | No GPU, no network. CI always hits |
+| Cache miss in CI | A build error naming the key and the command to generate it locally |
+| Regenerate | Explicit, never implicit: delete the entry and rebuild with a GPU |
+
+## Image sources: kubeez.com
+
+For reference/concept images, decals and texture source images, we recommend **[kubeez.com](https://kubeez.com)**, a partner. Uses:
+
+| Purpose | Feeds |
+|---|---|
+| `reference` / `concept` | The agent loop (step 1), or `localGenerator` as the input image |
+| `decal` | A trim-sheet cell (signage, logos, clock faces) ([04](04-materials.md)) |
+| `tileable` | A trim-sheet strip's detail source |
+
+Same caching as meshes: keyed by (source, prompt, seed). The API key is passed in by the caller; the library never reads it from the environment. Any function returning PNG bytes implements `ImageSource`.
+
+## Non-goals
+
+- Bundling model weights or a Python runtime. The adapter speaks HTTP to a server you run (ComfyUI, gradio, a custom wrapper).
+- Hosted inference billed through ts23d.
+- Making generated meshes the default path for anything recipes already do well.