@developerz.ai/ts23d 0.0.0-stage → 0.1.0

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.

package/docs/idea/09-kinds.md

@@ -0,0 +1,105 @@
+# 09 — Kinds
+
+**A kind is a library of builders a recipe calls, not a class the recipe fills in.** `facade(ctx, {...})` adds parts to the caller's `ctx`; the recipe stays in charge of layout, naming and LOD. `kind: '…'` on `defineAsset` is a free string for metadata. Source: `src/kinds/`.
+
+Status as of 2026-11:
+
+| Kind | Builders | Status |
+|---|---|---|
+| Building / tower | `facade`, `setbacks` | Shipped |
+| | `roof` / `roofMesh` (gable, hip, pyramid, mansard, gambrel, shed; chimneys), `opening` (window/door kit), `facade({ kit })`, `mass` (true-scale masonry) | Shipped |
+| Vehicle | `axle`, `trackRun`, `whyteAxles`, `propeller` | Shipped |
+| | lofted bodies, fuselages, wings | Possible now with `loft`, `sweep`; no dedicated builder yet |
+| Vessel | `hull` / `hullMesh` / `hullLines` | Shipped |
+| Vegetation | `tree`, `trees` family, `treeReal`; presets `oak`, `pine`, `palm`, `birch`, `willow` | Shipped |
+| Character | `head` (orc, goblin, human, dwarf, elf via `HEADS`), `headParams`, `headEdits`, `checkHead` | Shipped (stylised busts) |
+| Creature | `creature` (whole bodies, skinned) | Planned, M4 |
+| Scene | `ctx.use` (core), `heightfield` terrain with erosion and `terrainColor` | Shipped |
+| Families | `defineFamily` (core): variants of any kind | Shipped |
+
+## Building / tower
+
+**Masses, then details.** Block the volumes with `box` or `prism`, then wrap them with `facade`.
+
+`facade(ctx, opts)` runs a [split-grammar](#split-grammar) line along each side, per floor. Slots named `win`, `door`, `arch`, `shop` become inset panels; every other symbol stays wall.
+
+| Option | Meaning |
+|---|---|
+| `prefix` | Part name prefix → `<prefix>_<side>_<floor>_<slot>` |
+| `at`, `footprint` | Base centre and `[width X, depth Y]` of the mass it wraps |
+| `floors`, `floorHeight` | Storeys, metres per storey |
+| `grammar`, `ground?` | The line for every floor; `ground` overrides floor 0 |
+| `sides` | Any of `front` (+X), `back`, `left` (+Y), `right` |
+| `glass`, `frame?`, `windowRatio?` | Colours; window height as a fraction of the floor (default 0.6) |
+
+`setbacks(ctx, { prefix, tiers, floorHeight, color, grammar, glass, detail })` stacks shrinking masses (Empire State, Chrysler-style). Each tier: `{ footprint, floors }`. Returns the top z for the spire. Pass `detail: ctx.lod < 2`.
+
+### Split grammar
+
+After CGA shape grammar (Müller et al. 2006). One string lays out one strip.
+
+```
+"pier:0.9 | {arch:2.5}* | door:3 | pier:~"
+```
+
+| Term | Meaning |
+|---|---|
+| `sym:1.2` | Fixed width, metres |
+| `sym:~` / `sym:~2` | Stretch: shares the leftover, by weight (default 1) |
+| `{a:1.4 \| b:0.6}*` | Repeat: as many whole copies as fit. Fixed sizes only; one repeat per line |
+
+With no stretch term, repeat copies widen evenly to fill. Fixed terms longer than the strip → `T3D_GRAMMAR_OVERFLOW`. `split(src, length)` returns `{ symbol, start, size }[]`.
+
+## Vehicle
+
+Named parts follow the engine contract: `axle_*` and `wheel_*` spin about local Y; `prop_*` / `rotor_*` spin about their own axis.
+
+| Builder | Adds | Notes |
+|---|---|---|
+| `axle(ctx, { name, at, radius, gauge, width, color, rps })` | Group `name` (spinning about Y) + `name_wheel_l`, `name_wheel_r` | Segments drop per LOD (24 → 12 → 6) |
+| `trackRun(ctx, { side, y, length, wheels, radius, width, color, track })` | `road_wheel_<side>_<i>` (spinning), `track_<side>_top`, `track_<side>_bottom` | Tracked running gear, one side per call |
+| `whyteAxles('4-4-0', { leading, driving, trailing, spacing })` | Nothing; returns `{ role, x, radius }[]` | Whyte notation → axle positions along X, leading end at +X |
+| `propeller(ctx, { name, at, radius, blades, color, parent? })` | Group spinning about X + hub + blades | |
+
+Domain-native params are the point: a loco recipe says `'2-6-2'`, not twelve wheel coordinates.
+
+## Vessel
+
+`hull(ctx, o)` adds `hull` + `hull_deck`; `hullMesh(o, lod)` returns the mesh for `place`/`merge`; `hullLines(o)` exposes the shape functions. Required: `length`, `beam`, `draft`, `freeboard`, `colors: { topsides, bottom, boot?, deck, bulwark? }`. Optional: `sheer: [bow, stern]`, `stern: 'round' | 'transom'`, `transomWidth`, `fullness`, `entrance`, `flare`, `deadriseDeg`, `bulwark`, `camber`, `bootTop`, `fender`, `at` (the waterline). Bow toward +X. Watertight at every LOD; waterline and boot-top bands are crisp.
+
+## Roofs and openings
+
+Every builder has a pure mesh form (`roofMesh(o, lod)`, `opening(o, lod)`, `mass(o, lod)`) and recipes compose them with `place`/`merge`; `roof(ctx, o)` is the thin ctx wrapper and returns `{ ridge, eave, heightAt(x, y) }`. A roof is the lower envelope of its slope planes, so ridges and hips fall out exactly; the underside sits on the walls' top outer edge, gable and shed ends get infill walls, LOD0/1 add slab thickness, soffit, fascia, ridge/hip caps and chimneys (pots at LOD0), LOD2 is bare slopes (≤ 40 triangles). `opening` is a window or door with a true-scale reveal, sill, lintel, sash and glazing bars; `facade(…, { kit })` places one in every opening slot. `mass` is a wall block whose masonry courses start at the ground line, unlike `box`, which stretches its strip over the face.
+
+## Vegetation
+
+`tree(ctx, { … })`: Weber–Penn botanical skeleton. Recursive branch levels (length, curve, split, taper per level) swept with `sweep`, leaves as cards on the foliage cells (`cutout` surface).
+
+| API | Does |
+|---|---|
+| `tree(ctx, options)` | One tree into the caller's `ctx` |
+| `trees` | A family: `trees.variant({ name, params: { species: 'pine', … } })` |
+| `treeReal(params)` | `real` dimensions for the `proportions` gate |
+| `SPECIES`: `oak`, `pine`, `palm`, `birch`, `willow` | Presets as data (`TreeParams`) |
+
+The `oak`, `pine` and `palm` recipes are about 18 lines each. Wind is a crown `sway` for now. Planned: per-vertex wind weights; LOD2 impostors as crossed billboards from the foliage cells (today's are crude).
+
+## Character
+
+`head(ctx, { race: 'orc' | 'goblin' | 'human' | 'dwarf' | 'elf' | HeadParams, params?, prefix?, at?, jawSway? })` sculpts a stylised head and bust from SDF edits (`sculpt`) and adds `bust` (on z = 0), `head`, `jaw` (pivot at the hinge, optional sway) and `eye_l` / `eye_r` (pivots at the eyeball centres, looking along +X). Races are data (`HEADS`); `params` overrides one level deep; `checkHead` rejects impossible proportions with a fix. Vertex AO is baked at LOD0/1. Recipes: `orc_head`, `goblin_head`, `human_head`.
+
+## Creature (planned, M4)
+
+`creature(ctx, { skeleton: 'biped' | 'quadruped' | 'bird', height })`: SDF flesh over a skeleton, meshed with marching cubes (`sdf` primitive). **Stylised, not realistic.** Bones become named parts for posing. Realistic animals and people go through [`/neural`](08-neural-adapters.md).
+
+## Scene
+
+A scene is an asset whose `build` calls `ctx.use(other, { prefix, at, yaw, seed })`. No special kind is needed. Example (a street of varied houses): [02-dsl.md#composition-ctxuse](02-dsl.md#composition-ctxuse). Planned on top: layout helpers (street grids, scatter on a footprint) built on the split grammar.
+
+Terrain for scenes and presentation dioramas: `heightfield({ rect: [x0, y0, x1, y1], cells: [nx, ny], height: (x, y) => z, color, strip? })`. `color` may be a function of `(x, y, z)` (ruts darker, slopes greener); `cells` is the LOD knob.
+
+## Families and emitters
+
+Any kind can be wrapped in a family: `defineFamily({ defaults, build })` → `variant` / `extend` ([02-dsl](02-dsl.md#families-one-build-many-assets)). Vehicles and buildings add `ctx.emitter` nodes for exhaust, steam, chimney smoke and muzzle flash ([02-dsl](02-dsl.md#emitters)).
+
+Adding a kind: [architecture/adding-a-kind.md](../architecture/adding-a-kind.md).

package/docs/landscape.md

@@ -0,0 +1,49 @@
+# Landscape: AI 3D generators
+
+**A neutral survey, as of Oct 2026. ts23d isn't a competitor to these tools; it's a different approach (code recipes, free, no GPU, no service) with different strengths.** Many teams will use both. Prices and features change monthly, so check the linked source before relying on a row.
+
+Rows marked **(3rd-party)** come from aggregators or press, not the vendor's own page. Treat them as indicative.
+
+## Hosted / commercial
+
+| Tool | Inputs | Outputs | Rig / anim | Pricing (as of Oct 2026) | Open? | Source |
+|---|---|---|---|---|---|---|
+| Meshy (Meshy 7.1 / 6) | Text, image, multi-view | GLB / glTF / FBX / OBJ / USDZ / STL / 3MF; PBR (albedo / normal / metal / rough); quad/tri remesh, Low Poly mode, Smart Topology | Auto-rig humanoid + quadruped, 500–600+ motion presets | Free 100 credits/mo, outputs CC BY 4.0. Pro $20 (1,000 cr), Premium $40 (3,000), Ultra $100 (8,000), Studio $70/team. ~20–25 credits per generation | No (paid = private + commercial) | [pricing](https://www.meshy.ai/pricing) · [docs](https://docs.meshy.ai/en/webapp/pricing) · [animate](https://docs.meshy.ai/en/webapp/guides/animate) |
+| Tripo (Tripo 3.x) | Text, image, multi-view | GLB / FBX / OBJ / USD / STL; PBR, smart low-poly, quad topology **(3rd-party)** | Auto-rig + animation | Free ~200–300 cr/mo (public, non-commercial); Pro ~$20/mo (3,000 cr); Max ~$90 (25,000); API per task **(3rd-party)** | No | [docs](https://platform.tripo3d.ai/docs/introduction) · [CostBench](https://www.costbench.com/software/ai-3d-generation/tripo-ai/) |
+| Rodin / Hyper3D (Gen-2.5) | Text, image, multi-view, sketch, 3D ControlNet (bbox / voxel / point cloud), mesh edit | GLB / glTF / FBX / OBJ / USDZ / STL; PBR + UVs; quad/tri, polycount presets (~4K–50K quads) | Not mentioned on official page | Free pay-per-result ($1.50/credit); Creator $30/mo (~60 models); Business $120/mo (~416, API) | No | [pricing](https://hyper3d.ai/pricing) · [site](https://hyper3d.ai/) |
+| Luma Genie | Text (originally) | GLB / OBJ / USDZ (2024 coverage) | No | Free research preview at 2024 launch; current status unclear **(3rd-party)** | No | [The Decoder](https://the-decoder.com/genie-by-luma-ai-is-a-free-text-to-3d-generator-for-discord/) |
+| CSM (Cube) | Image, text | Part-based meshes, AI retopology **(3rd-party)** | Not confirmed | Free tier, then ~$20 / $60 / $499+/mo (May 2026); reported acquired by Google Jan 2026, unconfirmed **(3rd-party)** | No | [CostBench](https://costbench.com/software/ai-3d-generation/csm/) |
+| Kaedim | Concept art, sketches, photos, briefs | Production 3D with review / markup / revision loop | Not stated | No public pricing; $50 trial to $400–$1,200/mo **(3rd-party)** | No (customer owns outputs) | [site](https://www.kaedim3d.com/) |
+| Sloyd | Text, image, multi-image, parametric templates | GLB / OBJ / FBX / STL; polycount + tri/quad control; Unity / Unreal / Blender / Godot / Roblox plugins | AI rig + anim | Guest 1 gen/day personal; Plus $15/mo (50 cr); Pro $50/mo (350 cr) | No | [pricing](https://www.sloyd.ai/pricing) |
+| Autodesk Wonder 3D (Mar 2026) | Text, image | OBJ / STL for Maya / 3ds Max / Flow Studio | Not stated | Free 300 cr/mo at 20/gen; Pro ~$64/mo | No | [Autodesk news](https://adsknews.autodesk.com/en/news/autodesk-flow-studio-launches-wonder-3d-gen-ai-model-to-help-creators-make-3d-characters-and-objects-faster-and-easier/) |
+
+## Open weights / self-hosted
+
+| Tool | Inputs | Outputs | Rig / anim | Cost / hardware | Licence | Source |
+|---|---|---|---|---|---|---|
+| Hunyuan3D (Tencent) | Open 2.x: image, multi-view. Hosted 3.x: text / image / sketch, up to 4–8 views | Mesh + PBR texture pipeline (Paint 2.1) | No | Open 2.1 free, ~29 GB VRAM shape + texture; hosted ~20 free gens/day then ~$0.02/credit | 2.0 / 2.1 open weights, Tencent community licence (excludes EU / UK / South Korea, terms above 1M MAU, no training other models on outputs); 2.5 / 3.x hosted only | [GitHub](https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1) |
+| TRELLIS.2 (Microsoft) | Single image; can texture an existing mesh | GLB with PBR incl. opacity, 4K textures | No | Free self-hosted; ≥ 24 GB GPU, tested Linux A100 / H100 | MIT | [Hugging Face](https://huggingface.co/microsoft/TRELLIS.2-4B) |
+| Stable Fast 3D / SPAR3D (Stability) | Single image 512² | UV-unwrapped textured mesh, delighted textures, rough/metal; SPAR3D point-cloud editing | No | Free self-host; hosted API credit-based | Stability Community Licence (free under $1M revenue) | [Hugging Face](https://huggingface.co/stabilityai/stable-point-aware-3d) |
+| SAM 3D Objects (Meta, Nov 2025) | Real photos; an object from a cluttered scene | Textured object + pose / layout | No | Free self-hosted | Open weights, custom SAM licence **(3rd-party)** | [Roboflow](https://roboflow.com/model/sam-3d-objects) |
+
+## Caveats on the data
+
+- The Tripo site returned 403 to our research run; its pricing comes from CostBench.
+- csm.ai did not resolve; the CSM row is entirely third-party.
+- The Luma Genie page now redirects; current status unknown.
+- Gallery themes as shown by vendors: Meshy, riggable characters and stylised props. Rodin, a robot, a sci-fi weapon, a motorcycle, architecture. Sloyd, creatures, avatars, furniture, vehicles, weapons, trees, buildings. Kaedim, products, game props, characters.
+
+## Where each approach fits
+
+| Strength | Image/text-to-3D generators | Code recipes (ts23d) |
+|---|---|---|
+| Organic and sculpted forms | Strong | Weak ([what fits](idea/07-what-fits.md)) |
+| Concept art → textured mesh in seconds | Strong | No |
+| Auto-rigging | Several tools have it; meshes and rigs usually still need cleanup | Rigid part hierarchy only |
+| Parts that line up, repeat or match real dimensions | Weaker | Strong |
+| Named, animatable nodes | Usually one fused mesh | Built in |
+| Determinism, diffable git history | No | Yes |
+| Shared materials, consistent texel density | Per-asset textures | One trim sheet |
+| Cost, licence conditions on outputs | Credits; terms vary by tier | Free; none |
+
+The open-weight rows are what the planned [`/neural` adapter](idea/08-neural-adapters.md) wraps for the organic cases, on your own GPU, cached by content hash.