@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/docs/decisions/004-z-up-metres.md

@@ -0,0 +1,21 @@
+# 004 — Author in metres, Z up, +X front
+
+Status: accepted; export orientation superseded by 009
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+Recipes are written from reference data: drawings, spec sheets, Wikipedia infoboxes. Those are in metres (or convertible), in plan + elevation. glTF is Y-up; engines differ (Unity Y-up left-handed, Unreal Z-up, Godot Y-up, Blender Z-up). Every asset also needs one agreed "front" so a scene can place and orient it.
+
+## Decision
+Author in metres, right-handed, **Z up, +X front**, +Y left, ground at z = 0. The GLB writer applies one −90° X rotation on the root node to meet glTF's Y-up; part nodes keep their Z-up numbers.
+
+## Alternatives considered
+- **Y-up, matching glTF** — why not: plan coordinates become (x, z) and height becomes y, so every architectural and vehicle dimension is transposed while writing. More agent mistakes.
+- **Centimetres or engine units** — why not: reference data is in metres; a factor of 100 is a silent class of bugs.
+- **−Y or +Y front (Blender convention)** — why not: +X front keeps "length along X" for vehicles and ships, matching how specs list L × W × H.
+
+## Consequences
+- Easier: dimensions drop straight in from references; `SIDE -Y` in the contact sheet shows the profile with the front on the right.
+- Harder: one root rotation to remember when reading raw glTF nodes. `extras.up` records it.
+- Revisit when: never, short of a 1.0 → 2.0 break. It's in every recipe.

package/docs/decisions/005-zero-runtime-deps.md

@@ -0,0 +1,21 @@
+# 005 — Zero runtime dependencies
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+Recipes run in the CLI, in tests and in the browser gallery. Output must be byte-deterministic. Each dependency adds supply-chain risk, version drift that can change output bytes, and install weight. The things we need (a glTF writer, a PNG encoder, a rasteriser, a PRNG) are each a few hundred lines.
+
+## Decision
+`dependencies` is empty. The library writes GLB, PNG (via `node:zlib`, present in Bun and Node) and rasterises on its own. Dev tooling (Biome, TypeScript, lefthook) and the gallery app's `three` + `vite` are dev or workspace-private dependencies. Optional integrations (neural adapters, engine adapters) talk over HTTP or are separate entry points, never required imports.
+
+## Alternatives considered
+- **`@gltf-transform/core` for export** — why not: excellent, but its output bytes move with its versions; we need to own byte determinism.
+- **`sharp` / `canvas` for PNGs** — why not: native binaries, platform-specific installs, heavier than the problem.
+- **`three` for geometry** — why not: pulls a renderer into a compiler, and its geometry classes aren't the IR we want.
+
+## Consequences
+- Easier: `bun add` installs one package; no native builds; nothing upstream changes our bytes.
+- Harder: we maintain a GLB writer, PNG encoder and rasteriser. Each is small and tested.
+- Revisit when: a needed format (Draco, KTX2, meshopt) costs more to own than to depend on. Then add it behind an optional subpath.

package/docs/decisions/006-single-package-subpath-exports.md

@@ -0,0 +1,20 @@
+# 006 — One npm package with subpath exports
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+The library has ten modules (core, grammar, material, primitives, neural, kinds, qa, export, render, cli). Publishing them as separate packages means versioning them in lockstep, one npm OIDC trusted publisher per package, and a bootstrap publish for every new package (a package added after a release run stays unpublished until someone does it by hand). The sibling `ultimate` repo pays that tax across 31 packages.
+
+## Decision
+Publish one package, `@developerz.ai/ts23d`. Modules are subpaths: `@developerz.ai/ts23d/core`, `/grammar`, `/render`, and so on, via an `exports` wildcard. The root re-exports everything. Module boundaries are enforced inside the repo by `scripts/boundaries.ts`, not by package boundaries.
+
+## Alternatives considered
+- **A package per module (`@ts23d/core`, …)** — why not: N trusted publishers, N bootstraps, lockstep versioning machinery, for no user benefit at this size.
+- **One package, root export only** — why not: no way to import one layer (e.g. `/render` in a tool) without the rest in view; worse tree-shaking story.
+
+## Consequences
+- Easier: one version, one tag, one trusted publisher, one bootstrap ([PUBLISHING.md](../../PUBLISHING.md)).
+- Harder: boundaries are a repo lint, not a package graph; a consumer can import any subpath.
+- Revisit when: a module needs its own release cadence or its own heavy optional dependency (e.g. a neural adapter with a native runtime).

package/docs/decisions/007-cpu-contact-sheets.md

@@ -0,0 +1,21 @@
+# 007 — Agent feedback is a CPU-rendered contact sheet
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+The agent loop needs to see the asset. Options are many images (one per view) or one. Each image read costs context and a turn. Proportion errors show only from some angles (height in elevation, footprint in plan). The loop must also run in CI and on headless VPSes with no GPU and no display.
+
+## Decision
+`t3d shot` renders **one** PNG: six labelled orthographic views (3/4 front, front, side, top, 3/4 rear, LOD2 far) on a shared metre grid, with a header giving bounding-box dimensions, grid step and LOD. Rendering is a z-buffered CPU rasteriser with flat Lambert shading over vertex colour: no GPU, no WebGL, no native dependency.
+
+## Alternatives considered
+- **Headless GPU (Puppeteer + three.js, or EGL)** — why not: a browser or GPU driver in CI, non-deterministic pixels across drivers, slow cold start.
+- **One image per view** — why not: six reads instead of one; the agent compares across turns instead of within one image.
+- **Perspective beauty renders** — why not: perspective hides proportion errors; a metre grid under an orthographic view makes them measurable.
+
+## Consequences
+- Easier: one read shows every side; runs anywhere Bun runs; deterministic pixels.
+- Harder: no textures, shadows or AO in the sheet; it judges form, not surface. The gallery shows the real material.
+- Revisit when: surface quality (texture painter, M2) needs judging in the loop. Then add a textured view to the sheet, still on the CPU.

package/docs/decisions/008-surface-materials.md

@@ -0,0 +1,21 @@
+# 008 — One trim sheet, up to four surface materials
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: 003
+
+## Context
+ADR 003 put every asset on exactly one material. Real assets need glass (windows, lenses), cutouts (leaves, grilles, fences) and translucent parts (bottles, liquids). One opaque material can't shade those, and per-asset materials would bring back the draw-call and texture cost 003 removed.
+
+## Decision
+Keep ONE shared texture set (the trim sheet) and vertex-colour tint. A part picks `surface: 'opaque' | 'cutout' | 'glass' | 'translucent'`; each GLB carries at most four materials, one per surface in use, differing only in shading model. Glass and translucent use `KHR_materials_transmission`, `_volume` and `_ior`, with an alpha-blend fallback. Batching splits per pivot and surface (`<pivot>_<surface>`).
+
+## Alternatives considered
+- **Opaque only (keep 003 as is)** — why not: no windows, foliage or bottles that read correctly.
+- **Per-part materials** — why not: draw calls scale with parts again.
+- **Fake glass via vertex alpha on the opaque material** — why not: engines sort and shade it wrongly; no refraction.
+
+## Consequences
+- Easier: windows, foliage and bottles in the same pipeline; a shampoo bottle is 2 draw calls.
+- Harder: transmission isn't supported everywhere; the fallback looks flatter.
+- Revisit when: an engine target needs a fifth shading model (e.g. emissive-only, subsurface).

package/docs/decisions/009-gltf-front-axis.md

@@ -0,0 +1,21 @@
+# 009 — Exported GLBs face glTF +Z
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: 004 (export orientation only; authoring stays metres, Z up, +X front)
+
+## Context
+ADR 004 exported with one −90° X rotation on the root (`[-√½, 0, 0, √½]`). That makes glTF Y-up, but maps authoring +X front to glTF **+X**, which the glTF spec defines as the asset's *left* ("the front side of a glTF asset faces +Z, the left side faces +X", [spec §coordinate-system-and-units](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#coordinate-system-and-units)). Every asset faced sideways in engines that honour model-front. Found by [glb-production.md](../architecture/glb-production.md) (M10, G1).
+
+## Decision
+The root node's rotation is `[-0.5, -0.5, -0.5, 0.5]`. It maps authoring +X (front) → glTF +Z, +Z (up) → +Y, +Y (left) → +X, verified numerically in the exporter tests. Authoring conventions from ADR 004 are unchanged; part nodes keep their Z-up numbers under the root.
+
+## Alternatives considered
+- **Keep `[-√½, 0, 0, √½]`** — why not: violates the spec's front axis; assets face left in every engine that uses model-front.
+- **Author in +Z front (or Y-up, +Z front) so no root rotation is needed** — why not: breaks every recipe's readable numbers. Length along X, height along Z is how specs and drawings read; transposing them invites the unit and axis mistakes ADR 004 exists to prevent.
+- **Bake the rotation into every vertex** — why not: part pivots and node translations would no longer match the recipe's numbers, and engines bind to those nodes.
+
+## Consequences
+- Easier: assets face forward in Godot, Unity (glTFast), three.js, Babylon and Unreal without per-asset fixes.
+- Harder: **breaking** for anyone who placed earlier GLBs by hand: rotate them −90° about Y. Raw node data is still Z-up below the root.
+- Revisit when: never, short of a glTF spec change.

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 }) });
+```