@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/docs/decisions/README.md

@@ -0,0 +1,15 @@
+# Decisions
+
+**One record per one-way door, with the rejected options written down.** Read the matching record before proposing to reopen a decision; reopening requires naming what changed since its "why not". Format: context / decision / alternatives / consequences. Supersede, never edit history.
+
+| # | Decision | Status | Date |
+|---|---|---|---|
+| [001](001-recipe-compiler-over-ai-meshes.md) | Assets are compiled from recipes, not generated by AI mesh models | accepted | 2026-10-25 |
+| [002](002-typescript-not-json.md) | Recipes are TypeScript modules, not JSON | accepted | 2026-10-25 |
+| [003](003-shared-trim-sheet.md) | Every asset shares one trim-sheet material | superseded by [008](008-surface-materials.md) | 2026-10-25 |
+| [004](004-z-up-metres.md) | Author in metres, Z up, +X front | accepted; export orientation superseded by [009](009-gltf-front-axis.md) | 2026-10-25 |
+| [005](005-zero-runtime-deps.md) | Zero runtime dependencies | accepted | 2026-10-25 |
+| [006](006-single-package-subpath-exports.md) | One npm package with subpath exports | accepted | 2026-10-25 |
+| [007](007-cpu-contact-sheets.md) | Agent feedback is a CPU-rendered contact sheet | accepted | 2026-10-25 |
+| [008](008-surface-materials.md) | One trim sheet, up to four surface materials | accepted | 2026-10-25 |
+| [009](009-gltf-front-axis.md) | Exported GLBs face glTF +Z (root `[-0.5,-0.5,-0.5,0.5]`) | accepted | 2026-10-25 |

package/docs/idea/01-vision.md

@@ -0,0 +1,117 @@
+# 01 — Vision
+
+**Free 3D asset generator for coding agents. The agent writes TypeScript; ts23d compiles it, deterministically, to game-ready glTF for Unity, Unreal, Godot, three.js, Babylon or anything that reads glTF.** Use the LLM you already pay for to write the assets your project needs (vehicles, buildings, props, whole streets), optimised by construction, with a contact sheet so the agent checks its own work.
+
+## Scope: ts23d ends at the GLB
+
+| In scope | Out of scope |
+|---|---|
+| Recipes → GLB × 3 LODs, the trim-sheet textures, `manifest.json`, contact sheets | Engines, game frameworks, runtime code |
+| Hooks an engine can use: named pivots, sockets, emitter extras, the `run` clip | Driving those hooks: that's your engine code |
+| Engine *import adapters* as data (import settings, collision naming): planned, M3 | Engine plugins or runtimes |
+| An asset gallery that shows every recipe ([site](https://developerz-ai.github.io/ts23d/)) | A playable demo or game |
+
+## From prompt to asset
+
+| Step | You do | ts23d gives you |
+|---|---|---|
+| 1. Install | `bun add @developerz.ai/ts23d`; copy `node_modules/@developerz.ai/ts23d/.claude/skills/author-recipe` into `.claude/skills/` (Claude Code), or point your `AGENTS.md` at `node_modules/@developerz.ai/ts23d/AGENTS.md` (Codex) | The agent knows the loop |
+| 2. Ask | `/new-recipe Tiger I, mid-production 1943, fully stowed` · `/new-recipe 4-4-0 steam loco with tender` · `/new-recipe 1940s city street with townhouses and gas lamps` (townhouse, lamp, street recipes: landing) | A recipe that passes QA, three LODs, textures, a manifest, a contact sheet |
+| 3. Import | Load `out/<asset>/lod0.glb` in your engine | Named nodes (`turret`, `gun`, `wheel_*`), sockets, emitter extras, the `run` clip as hooks ([README](../../README.md#3-use-the-glb-in-your-engine)) |
+
+## The pitch
+
+| You bring | ts23d gives you |
+|---|---|
+| A coding agent (Claude Code, Codex, any model that writes TS) | A DSL that agent already knows: TypeScript |
+| A description, a reference photo, real dimensions | GLB × 3 LODs, named + pivoted parts, baked loop animations |
+| A machine with Bun | No GPU, no credits, no account, no service |
+| A target engine (yours) | GLBs it imports: one texture set, batched draw calls, LODs, compact core-glTF buffers |
+| Git | Assets as diffable source; same seed → same bytes |
+
+## The promise, both halves
+
+| Half | Means | How |
+|---|---|---|
+| **High definition up close** | Hero detail: rivets, rods, window sashes, real proportions | Code places detail N times for free; `real` dimensions + the `proportions` gate; painted trim sheet |
+| **Cheap to draw** | Games pay per draw call, per vertex fetch, per byte | One shared material, static geometry batched into its pivot, so draw calls = the parts your engine moves (a static building: 1); 3 LODs from one source; u16 indices and colours today; welded, vertex-cache-ordered buffers via `optimize`, an opt-in web profile (quantisation + meshopt) and LOD switch hints planned (M2) |
+
+## No Blender for most hard-surface asset production
+
+**The DSL does the modelling.** Scoped to asset production; the engine stays yours. For hard-surface assets (vehicles, buildings, props, whole scenes) the LLM writes TypeScript, and ts23d does the rest:
+
+| Blender-era step | In ts23d |
+|---|---|
+| Modelling | `primitives` + `kinds`, real units, pivots where parts hinge |
+| LODs | `ctx.lod`: the same recipe re-run at lower detail |
+| UV unwrap | UVs land on the shared trim sheet by world metres, automatically |
+| Batching / joining meshes | `toGlb` merges static geometry into its nearest pivot |
+| Checking | QA gates + contact sheet |
+| Export | `toGlb`, zero dependencies |
+
+Blender stays useful for organic sculpting: people, animals, hero rocks. Those come in through the planned [`/neural` adapter or `importGlb`](08-neural-adapters.md).
+
+## One asset pipeline, no other libraries
+
+**Asset production needs nothing else between "describe the asset" and "a GLB your engine imports".**
+
+| Stage | Module | Status (2026-10) | Replaces |
+|---|---|---|---|
+| Geometry | `primitives`, `kinds` | Shipped: `box`, `lathe`, `prism`, `beam`, `planar`, `sweep`, `loft`, `heightfield`, facades, vehicles, Weber–Penn trees. Planned: `sdf`, roofs, hulls, creatures | Blender modelling |
+| Materials and textures | `material` (generator) | Shipped: procedural albedo / normal / ORM trim sheet, embedded or shared PNGs, palettes, `grime`. No KTX2 yet | Substance / texture tools |
+| Optimisation | `passes/optimize`, `export` | Shipped: u16 indices, u16 colours, batching. Planned, M2: weld, vertex-cache reorder, ACMR; opt-in `web` profile (quantisation + meshopt) | meshoptimizer / gltfpack |
+| LODs | `ctx.lod` | Shipped | Decimators |
+| QA | `qa` | Shipped: budget, surface-contact floating parts, motion clashes, names, proportions, spec measures. Silhouette IoU and ACMR planned | Manual review |
+| Renders and photo match | `render` | Contact sheet shipped. Photo match planned, M2 | — |
+| GLB export | `export` | Shipped: core glTF only, faces +Z, seamless loops, trim-sheet textures, 0 glTF-Validator errors (tested) | — |
+| Engine import adapters | `threeMaterialSource` (TSL), `godotShaderSource` | Shipped: shader sources. Planned, M3: import settings and collision naming per engine, as hooks, not runtime | — |
+
+Every stage has zero runtime dependencies ([ADR 005](../decisions/005-zero-runtime-deps.md)).
+
+## Origin
+
+Inspired by an in-house pipeline that started on AI mesh generation (Meshy plus an image model) and moved to a JSON recipe compiler. Why it moved:
+
+| Problem with generated meshes | What a recipe compiler does instead |
+|---|---|
+| Credit cost per attempt, per iteration | Free; iteration costs a rebuild |
+| No reproducibility: same prompt, different mesh | Same source + seed → same bytes |
+| One fused mesh, no named parts | `turret`, `gun`, `axle_0`: pivoted, animatable |
+| A texture per asset → a draw call per asset | One shared trim sheet → one material |
+| Every mesh needed repair (holes, scale, pivots, topology) | Built correct: real units, pivots set where parts hinge |
+
+ts23d keeps that pipeline's ideas and goes one step further: recipes are **TypeScript, not JSON** ([ADR 002](../decisions/002-typescript-not-json.md)).
+
+## Ideas carried over
+
+| Idea | Where it lives | Status (2026-10) |
+|---|---|---|
+| CGA split grammar for facades: `"pier:0.9 \| {arch:2.5}* \| door:3 \| pier:~"` | `grammar/split.ts`, `kinds/building.ts` | Shipped |
+| Domain-native params: Whyte `4-4-0` for locomotives | `grammar/whyte.ts`, `kinds/vehicle.ts` | Shipped |
+| Masses, then details | Recipe convention; `setbacks` + `facade` | Shipped |
+| Real units (metres) | Everywhere | Shipped |
+| Real dimensions with sources, held by QA | `defineAsset({ real, sources })`, `proportions` + `measures` gates | Shipped |
+| Era/region palettes | `material/palette.ts` | Shipped (4 palettes) |
+| LODs by re-running the recipe at a detail level | `compile(asset, { lod })` | Shipped |
+| A QA gate that fails the build | `qa/gates.ts` | Shipped (7 gates incl. recipe `checks`); more planned |
+| Closed-loop agent iteration with multi-view renders | `render/sheet.ts`, `t3d shot` | Shipped |
+| Weber–Penn botanical skeletons | `kinds/vegetation.ts` → `tree`, `trees` | Shipped |
+| Photo match: photo · model · overlay in one PNG, plus silhouette IoU | `render` → `photoMatch` | Planned, M2 |
+| Reverse direction: a VLM infers recipe params from photos, scored by silhouette IoU | builds on `photoMatch` | Planned, M6 |
+
+## Principles
+
+- **Code is the asset.** The GLB is a build artefact. Recipes are committed; `out/` is not.
+- **Deterministic.** No ambient entropy, no wall clock. Byte-identical output for the same source + seed.
+- **Errors are instructions.** Every failure carries a `T3D_*` code, the cause and the fix ([errors](../architecture/errors.md)).
+- **The agent is the user.** Contact sheets, `--json`, and fix lines exist for an agent reading them, not for a human at a GUI.
+- **Zero runtime dependencies** ([ADR 005](../decisions/005-zero-runtime-deps.md)).
+- **Honest about fit.** Strong on hard-surface; weak on living things ([what fits](07-what-fits.md)).
+
+## Non-goals
+
+- Beating image-to-3D models at organic, sculpted forms. Use them, or the planned [neural adapter](08-neural-adapters.md).
+- Engines, game frameworks, gameplay or demo code. ts23d ends at the GLB, textures and manifest.
+- A modelling GUI. The editor is your agent; the viewer is the [gallery](https://developerz-ai.github.io/ts23d/).
+- Photoreal hero assets. Target: game-ready, stylised-to-realistic props at consistent texel density.
+- A hosted service. Everything runs on your machine.

package/docs/idea/02-dsl.md

@@ -0,0 +1,343 @@
+# 02 — The DSL
+
+**An asset is a named export: `defineAsset({ …, build(ctx) })`.** `build` is a plain TypeScript function. It adds named parts to `ctx`; the compiler runs it once per LOD.
+
+## Layers
+
+**Every layer is plain TypeScript. You extend the DSL by writing functions; there is no plugin API to learn.**
+
+| Layer | Shape | Example |
+|---|---|---|
+| Primitive | `(options) => Mesh` | `box`, `lathe`, `prism`, `beam`, `planar`, `sweep`, `loft`, `heightfield` |
+| Component | `(ctx, params) => void`: adds named parts | your `bogie(ctx, …)`, `chimney(ctx, …)` |
+| Kind | A library of components | `facade`, `setbacks`, `axle`, `trackRun` |
+| Family | `defineFamily({ defaults, build(ctx, p) })` | `t34` with `turret: '1941' \| '1943'` |
+| Asset | `defineAsset(…)` or `family.variant(…)` | `t34_1943` |
+| Scene | An asset that calls `ctx.use(other, …)` | a street, a rail yard |
+
+## Primitives (shipped)
+
+| Primitive | Key options | For |
+|---|---|---|
+| `box` | `size`, `at`, `strip`, `omit`, `bevel?` | Hulls, walls, crates; `bevel` = the mid-poly chamfer |
+| `lathe` / `cylinder` | `profile` or `radius`+`length`, `segments`, `axis`, `creaseDeg?`, `uv?: 'metres'`, `faceted?` | Wheels, boilers, domes, n-sided tanks |
+| `prism` | `profile`, `depth`, `plane: 'xy'\|'xz'\|'yz'` | Sloped armour, gables, fins |
+| `beam` | `from`, `to`, `width`, `segments?`, `up?`, `caps?` | Girders, rods, rails |
+| `planar` | `points`, `doubleSided?` | Plates, decks, signs |
+| `sweep` | `section` (polygon or `{ radius, segments }`), `path`, `scale?` (taper), `twist?`, `caps?` | Branches, pipes, handrails, cables. Parallel-transport frames; triangles = 2·S·(P−1) + S per cap |
+| `loft` | `rings` (Vec3 rings), `capStart?`, `capEnd?`, `uv?` | Trunks, fuselages, bottles. `ringXY(centre, rx, ry, …)` builds a ring, with wobble |
+| `heightfield` | `rect`, `cells`, `height(x, y)`, `color`, `skirt?` | Terrain, dioramas; with `terrainGrid` + `hydraulicErosion` / `thermalErosion` + `terrainColor` for real-looking mountains |
+| `tiled` | `origin`, `u`, `v`, `strip`, `segments?` | Walls, roofs, decks at true texture scale |
+| `cell` | `origin`, `u`, `v`, `cell`, `inset?` | Windows, doors, clocks, signs; `inset` adds reveals |
+| `lattice` | `from`, `to`, `depth`, `pattern: warren\|pratt\|howe\|x`, `bays`, `chord`, `web`, `section` | Bridges, towers, cranes, gantries |
+| `text` | `str`, `origin`, `along`, `up`, `height`, `font`, `depth?`, `align?`, `maxWidth?`, `surface?` | Name boards, wagon lettering, hull markings (5×7 font, Latin + Cyrillic) |
+| `sdf` | `field(p)`, `bounds`, `resolution`, `mesher?`, `symmetry?` | Any signed-distance shape; `sd.*` combinators, `valueNoise` |
+| `sculpt` | `edits` (shape, op, blend, color, groups), `resolution`, `mirror?` | Busts, rocks, asteroids: Dreams-style edit lists |
+
+Noise for any primitive: `gradientNoise2`, `valueNoise2`, `fbm`, `billow`, `ridged`, `warp`, `terrace` — all seeded from an `Rng`.
+
+## Why TypeScript, not JSON
+
+| Need | JSON recipe | TS recipe |
+|---|---|---|
+| 12 windows per floor, 9 floors | Spell out 108 entries, or invent a repeat syntax | `for` loop |
+| Reuse a wheel across 8 vehicles | Invent `$ref` / templating | Import a function |
+| Vary 10 houses on a street | Invent a variant system | `ctx.use(house, { seed })` |
+| Catch `colr: …` before build | Schema validator, if anyone wrote one | `tsc` red squiggle |
+| Agent fluency | Must learn your schema | Already writes TS all day |
+
+Full reasoning and rejected options: [ADR 002](../decisions/002-typescript-not-json.md).
+
+## Anatomy
+
+```ts
+import { box, cylinder, defineAsset, hex } from '@developerz.ai/ts23d';
+
+export const lamp_post = defineAsset({
+  name: 'lamp_post',            // snake_case; becomes the GLB name and root node
+  kind: 'prop',                 // free string; kinds are libraries, not a closed enum
+  description: 'cast-iron street lamp',
+  sources: ['https://example.org/lamp-drawing.pdf'],
+  real: { length: 0.4, width: 0.4, height: 3.5 },  // proportions gate: LOD0 within ±5%
+  tags: ['street', 'victorian'],
+  budget: { triangles: [800, 300, 60] },   // per LOD; QA fails above
+  seed: 1,                      // default 1
+  build(ctx) {
+    const iron = hex('#2b2b2e');
+    ctx.part('base', box({ size: [0.4, 0.4, 0.3], color: iron, strip: 'iron', omit: ['bottom'] }));
+    ctx.part('pole', cylinder({ radius: 0.06, length: 3.2, segments: [12, 8, 6][ctx.lod] ?? 6,
+                               at: [0, 0, 1.9], color: iron }));
+  },
+});
+```
+
+One module may export several assets; `t3d` builds every one. No default exports.
+
+## `defineAsset` fields
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `name` | `string` | yes | `[a-z][a-z0-9_]*`, else `T3D_RECIPE_INVALID` |
+| `kind` | `string` | yes | Written to glTF `extras.kind` |
+| `budget.triangles` | `[lod0, lod1, lod2]` | yes | Enforced by the `triangle-budget` gate |
+| `build` | `(ctx) => void` | yes | Synchronous |
+| `real` | `{ length, width, height, tolerance?, measures? }` | no | Real overall dimensions, metres (X, Y, Z). The `proportions` gate holds LOD0 to them, default ±5% |
+| `real.measures` | `Measure[]` | no | Spec-sheet dimensions checked on LOD0 by the `measures` gate, default ±2%. See below |
+| `sources` | `string[]` | with `real` | Where the numbers came from: spec sheets, rosters, drawings, photos. The type says "required for `real`"; as of 2026-10 nothing enforces it |
+| `checks` | `Check[]` | no | The recipe's own physical intent, run by QA at every LOD ([below](#checks-declared-intent)) |
+| `description`, `tags` | `string`, `string[]` | no | Gallery / search metadata |
+| `seed` | `number` | no | Default `1`; overridden by `compile(…, { seed })` or `ctx.use(…, { seed })` |
+
+## The `ctx` API
+
+| Member | Does |
+|---|---|
+| `ctx.lod` | `0` hero · `1` mid · `2` far. Read it and drop detail; never decimate |
+| `ctx.seed` | The seed this compile runs with |
+| `ctx.rng` | Seeded PRNG: `next()`, `range(a,b)`, `int(a,b)`, `pick(xs)`, `fork(name)` |
+| `ctx.part(name, mesh, opts?)` | Add a named part. `mesh` may be `null` (empty pivot) |
+| `ctx.group(name, opts?)` | An empty pivot other parts parent to (`part(name, null, opts)`). Pivots and parts with `motion` survive export as nodes; static parts merge into them ([batching](03-ir.md#batching-parts--pivots)) |
+| `ctx.use(asset, opts)` | Instance another asset at this LOD: the composition primitive |
+| `ctx.emitter(name, opts)` | A particle source as a named node ([below](#emitters)) |
+| `ctx.socket(name, opts)` | An attachment point as a named node ([below](#sockets)) |
+
+`PartOptions`:
+
+| Option | Meaning |
+|---|---|
+| `at` | Pivot in the parent's space. The mesh is authored relative to it |
+| `parent` | Name of an existing part/group. Parents first, else `T3D_PART_UNKNOWN` |
+| `yaw` | Rotation about local Z, radians |
+| `motion` | `{ kind: 'spin', axis, rps }` · `{ kind: 'slide', offset, hz }` · `{ kind: 'sway', axis, degrees, hz }` (turret scan, gun elevation, tree wind, a door). Baked to a 2 s `run` clip only when exporting with animations ([03](03-ir.md#glb-layout)) |
+| `surface` | `'opaque'` (default) · `'cutout'` · `'glass'` · `'translucent'` ([below](#surfaces)) |
+| `clearOf` | Part names this moving part may pass through by design (an axle in its bearing, a crosshead in its guide). Exempts them from the `clashes` gate |
+
+Rules the compiler enforces:
+
+- Part names are unique per asset (`T3D_PART_DUPLICATE`). Suffix loop indices: `wheel_0`, `wheel_1`.
+- A part can't have both `yaw` and `motion` (`T3D_RECIPE_INVALID`). Yaw the parent group, move the child.
+- Names are snake_case (QA gate `part-names`). Names are the contract with the engine: `axle_*`, `door_*`, `rotor_*`.
+
+## Fidelity: `real.measures`
+
+**Overall size is not enough; players notice the driver diameter.** Each `Measure` names one number from a source and how to measure it on the model:
+
+| Field | Meaning |
+|---|---|
+| `label` | Human name: `'driver diameter'`, `'gauge'` |
+| `value` | Metres, from the source |
+| `axis` | `'x'` · `'y'` · `'z'` |
+| `parts` | Extent of these parts' union along `axis`. Prefix match: `'axle_driver_0'` includes `axle_driver_0_wheel_l` |
+| `between` | Or: centre-to-centre distance of exactly two parts along `axis` (gauge, wheelbase) |
+| `tolerance` | Relative, default 0.02 |
+| `source` | Which of `sources` the number came from |
+
+```ts
+real: {
+  length: 6.68, width: 3.0, height: 2.45,
+  measures: [
+    { label: 'turret width', value: 2.0, axis: 'y', parts: ['turret_body'], source: 'hull drawing' },
+    { label: 'road wheel diameter', value: 0.83, axis: 'z', parts: ['road_wheel_l_0'] },
+  ],
+},
+```
+
+A failing measure means the model is wrong. **Rebuild the part from the number; never edit the spec to pass.** Gate details: [06-qa](06-qa.md).
+
+## Detail: build once, place N times
+
+`place(mesh, { at, yaw, pitch, roll, scale })` rigidly transforms a mesh; `merge` joins meshes into one part. Author a rivet, hatch or bracket once in local space, then place it along a seam:
+
+```ts
+import { cylinder, merge, place } from '@developerz.ai/ts23d';
+
+const rivet = cylinder({ radius: 0.012, length: 0.01, segments: 6, axis: 'x', color: iron });
+const rivets = merge(Array.from({ length: 24 }, (_, i) => place(rivet, { at: [3.0, -1.2 + i * 0.1, 1.1] })));
+if (ctx.lod === 0) ctx.part('glacis_rivets', rivets);
+```
+
+Lower level: `affine(placement)`, `frame(u, v, w, at)` (an explicit basis), `applyAffine(mesh, affine)`.
+
+## Families: one build, many assets
+
+**A variant is a name plus the parameters that differ.** T-34 1941 vs 1943, a 4-4-0 vs a 2-6-0, oak vs birch: one key change, not a copied file.
+
+```ts
+import { defineFamily } from '@developerz.ai/ts23d';
+
+const t34 = defineFamily({
+  kind: 'vehicle',
+  budget: { triangles: [40000, 10000, 1500] },
+  defaults: { turret: '1941' as '1941' | '1943', hullLength: 6.68 },
+  build(ctx, p) { /* hull from p.hullLength; turret shape from p.turret */ },
+});
+
+export const t34_1941 = t34.variant({ name: 't34_1941' });
+export const t34_1943 = t34.variant({ name: 't34_1943', params: { turret: '1943' } });
+
+// Derive: add params, wrap or replace the parent's detail.
+const t34_85 = t34.extend({
+  defaults: { gun: 85 },
+  build(ctx, p, base) { base(); /* swap the turret, add the 85 mm gun */ },
+});
+export const t34_85_1944 = t34_85.variant({ name: 't34_85_1944', tags: ['ww2'] });
+```
+
+| API | Does |
+|---|---|
+| `defineFamily({ defaults, build(ctx, params), ...assetFields })` | Typed defaults; every `defineAsset` field except `name` / `build` |
+| `family.variant({ name, params?, ...overrides })` | One `Asset`: defaults merged with `params`; may override `real`, `budget`, `tags`, … |
+| `family.extend({ defaults, build?(ctx, p, base) })` | A new family with more params. Call `base()` to run the parent's build, or don't, to replace it |
+| `family.defaults` | Read-only defaults, for docs and UIs |
+
+## Emitters
+
+`ctx.emitter(name, opts)` adds an empty named node carrying `extras.ts23d.emitter`. It moves with its parent; the engine binds its own particle system to it. The gallery renders them.
+
+| Option | Meaning |
+|---|---|
+| `kind` | `'smoke'` · `'steam'` · `'dust'` · `'muzzle'` · `'fire'` · `'sparks'` |
+| `at`, `parent` | Position in the parent's space; parent it to a turret or stack so it follows |
+| `dir` | Emission direction, default up (+Z) |
+| `rate`, `life` | Particles per second; seconds each lives |
+| `size` | `[start, end]` metres |
+| `color` | Linear RGB start colour; engines fade to transparent |
+| `speed`, `spreadDeg` | Initial speed along `dir`; cone spread |
+| `when` | `'always'` (chimney) · `'moving'` (track dust) · `'event'` (muzzle flash, fired by engine code) |
+
+```ts
+ctx.emitter('exhaust_l', { kind: 'smoke', at: [-3.2, 0.6, 1.2], dir: [-1, 0, 0.5],
+                           rate: 20, life: 2, size: [0.2, 1.2], when: 'moving' });
+ctx.emitter('muzzle', { kind: 'muzzle', parent: 'gun', at: [2.6, 0, 0], dir: [1, 0, 0],
+                        rate: 200, life: 0.1, size: [0.3, 0.8], when: 'event' });
+```
+
+## Sockets
+
+`ctx.socket(name, { kind, at?, parent?, dir?, data? })`: an empty named node with `extras.ts23d.socket`, for engine code to attach to.
+
+| `kind` | Example |
+|---|---|
+| `seat` | Driver, gunner, passenger |
+| `mount` | Weapon hardpoint, `data: { caliber: 88 }` |
+| `camera` | Gunner sight, chase cam, `data: { fov: 60 }` |
+| `audio` | Engine, `data: { clip: 'engine_idle' }` |
+| `attach` · `spawn` · `interact` · `light` | Tow hook, spawn point, door handle, headlamp |
+
+`dir` is the facing in the parent's space (default +X). `data` is free-form `string | number | boolean` values.
+
+## Surfaces
+
+**One texture set, at most four materials.** `surface` on a part picks the shading model; tint stays in vertex colour.
+
+| Surface | For | glTF |
+|---|---|---|
+| `opaque` (default) | Almost everything | `ts23d_trim` |
+| `cutout` | Leaves, fences, grilles | Alpha-tested, double-sided |
+| `glass` | Windows, lenses, clear bottles | `KHR_materials_transmission` + `_volume` + `_ior` (1.5) |
+| `translucent` | Plastic bottles, liquids, paper | Transmission, tinted; engines without it fall back to alpha blend |
+
+Batching splits by pivot and surface, so a shampoo bottle (opaque cap, translucent body) is 2 draw calls.
+
+## Checks: declared intent
+
+**Static intersections need declared intent.** Modellers sink bolts into plates on purpose, so QA can't fail every overlap. The recipe says what must hold, and the `check` gate enforces it at every LOD.
+
+```ts
+import { clear, noOverlap, symmetric, touches } from '@developerz.ai/ts23d';
+
+checks: [
+  clear('track_*', 'hull_*', 0.02),        // the track never hits the frame; 2 cm running gap
+  noOverlap('road_wheel_l_*'),             // interleaved wheels don't intersect
+  touches('turret_body', 'hull_top'),      // the turret sits on its ring
+  symmetric('_l', '_r', 'y'),              // left matches right across y = 0
+],
+```
+
+| Builder | Fails when |
+|---|---|
+| `clear(a, b, minGap?)` | Anything in `a` sinks more than 1 cm into `b`'s closed solid (ray-parity point-in-solid; open planar sheets are never solids), or is closer than `minGap` |
+| `noOverlap(glob)` | Any two parts matching `glob` interpenetrate |
+| `touches(a, b, eps = 0.02)` | `a`'s surface is further than `eps` from `b`'s |
+| `symmetric(left, right, axis = 'y')` | A part containing `left` has no `right` mirror, or isn't mirrored across `axis = 0` (2 cm) |
+
+Selectors are globs (`*`, `?`) over part names. A custom check is any `(asset: CompiledAsset) => CheckFinding[]`, where `CheckFinding = { message, fix, part? }`.
+
+## Composition: `ctx.use`
+
+A scene is an asset that uses other assets. Each instance is compiled at the parent's LOD, with its own seed, under a prefixed group:
+
+```ts
+import { box, defineAsset, facade, palettes } from '@developerz.ai/ts23d';
+
+const { limestone, glass } = palettes.artDeco;
+
+export const shop_house = defineAsset({
+  name: 'shop_house',
+  kind: 'building',
+  budget: { triangles: [4000, 1500, 400] },
+  build(ctx) {
+    const floors = ctx.rng.int(2, 4);               // varies per seed
+    ctx.part('mass', box({ size: [8, 10, floors * 3.2], color: limestone,
+                           strip: 'stone', omit: ['bottom'] }));
+    if (ctx.lod < 2)
+      facade(ctx, { prefix: 'win', at: [0, 0, 0], footprint: [8, 10], floors, floorHeight: 3.2,
+        grammar: 'pier:0.6 | {win:1.4 | pier:0.6}* | pier:~',
+        ground: 'pier:0.6 | shop:4 | pier:~ | door:1.2 | pier:0.6',
+        sides: ['front'], glass });
+  },
+});
+
+export const street = defineAsset({
+  name: 'street',
+  kind: 'scene',
+  budget: { triangles: [40000, 15000, 4000] },
+  build(ctx) {
+    ctx.part('road', box({ size: [12, 60, 0.05], at: [12, 0, 0],
+                           color: palettes.modernGlass.concrete, omit: ['bottom'] }));
+    for (let i = 0; i < 6; i++)
+      ctx.use(shop_house, { prefix: `house_${i}`, at: [0, -25 + i * 10, 0], seed: 100 + i });
+  },
+});
+```
+
+Result: six different houses (2–4 floors each) as `house_0` … `house_5`, with parts `house_3_mass`, `house_3_win_front_1_2` and so on. LOD2 drops every window on every house at once.
+
+`UseOptions`: `prefix` (required), `at`, `yaw`, `parent`, `seed` (defaults to the parent's seed).
+
+## Determinism rules
+
+**Same source + seed + LOD → same bytes.** Breaking any rule below breaks that.
+
+| Rule | Why | Enforced by (in this repo) |
+|---|---|---|
+| Never `Math.random()`. Use `ctx.rng` or `createRng(seed)` | Ambient entropy | `scripts/determinism.ts` (static ban in `src/` + `recipes/`); test preload makes `Math.random` throw |
+| No `Date.now()`, `new Date()`, `performance.now()` in library or recipe code | Wall clock | `scripts/determinism.ts` |
+| No `toLocale*String()` | Locale changes bytes; format with `toFixed` | `scripts/determinism.ts` |
+| `ctx.rng.fork('name')` per independent feature | Adding a draw in one part must not shift another | Convention |
+| No env vars, file or network reads in `build` | Ambient state | Convention |
+| `build` is synchronous | No ordering races | The type signature |
+| Iterate arrays, not object key order you didn't create | Stable part order → stable node order → stable bytes | Convention |
+| Generated meshes (neural, imported) go through a content-hash cache | A GPU result is not reproducible; the cached file is | Planned, M5 ([08](08-neural-adapters.md)) |
+
+`scripts/recipes.ts` compiles every recipe twice per LOD and fails if the GLB hashes differ. Both run in `bun run verify`. In your own project, copy the rules; the guards ship with this repo, not the package. Cross-machine hash comparison: planned ([06-qa](06-qa.md)).
+
+## Library entry points
+
+One import gives everything; subpaths load one layer ([ADR 006](../decisions/006-single-package-subpath-exports.md)):
+
+```ts
+import { defineAsset, box } from '@developerz.ai/ts23d';
+import { split } from '@developerz.ai/ts23d/grammar';
+import { contactSheet } from '@developerz.ai/ts23d/render';
+```
+
+Programmatic build, without the CLI:
+
+```ts
+import { compile, contactSheet, runQa, toGlb } from '@developerz.ai/ts23d';
+const lod0 = compile(lamp_post, { lod: 0 });
+const findings = runQa(lod0);                      // [] = PASS
+const glb = toGlb(lod0);                           // Uint8Array
+const png = contactSheet(lod0, { far: compile(lamp_post, { lod: 2 }) });
+```

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 |