@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/dist/testing/index.js

@@ -0,0 +1,134 @@
+import {
+  Ts23dError2,
+  compile2
+} from "../chunk-hg7pf34j.js";
+import {
+  glob2,
+  clashes2,
+  measure2,
+  DEFAULT_GATES2,
+  runQa2,
+  DEFAULT_LOD_GATES2,
+  runLodQa2
+} from "../chunk-jq4e17tj.js";
+import"../chunk-y63c6zcv.js";
+import"../chunk-drna2rny.js";
+import {
+  exportGlb2
+} from "../chunk-dbq4qf52.js";
+
+// src/testing/compiled.ts
+var ALL_LODS = [0, 1, 2];
+var compileLods = (asset, o = {}) => (o.lods ?? ALL_LODS).map((lod) => compile2(asset, { lod, ...o.seed !== undefined ? { seed: o.seed } : {} }));
+var describeFinding = (f, lod) => `${lod !== undefined ? `LOD${lod} ` : ""}${f.gate}${f.part ? ` [${f.part}]` : ""}: ${f.message}`;
+function failOn(what, found) {
+  if (found.length === 0)
+    return;
+  const lines = found.map(({ finding, lod }) => `  - ${describeFinding(finding, lod)}`);
+  throw new Ts23dError2("T3D_QA_FAILED", {
+    cause: `${what}: ${found.length} finding(s)
+${lines.join(`
+`)}`,
+    fix: found[0]?.finding.fix ?? "read the findings above"
+  });
+}
+
+// src/testing/assert.ts
+function assertQaPass(asset, o = {}) {
+  const lods = compileLods(asset, o);
+  const found = lods.flatMap((a) => runQa2(a, o.gates ?? DEFAULT_GATES2).map((finding) => ({ finding, lod: a.lod })));
+  const chain = lods.length > 1 ? runLodQa2(lods, o.lodGates ?? DEFAULT_LOD_GATES2) : [];
+  failOn(`${asset.name} QA`, [...found, ...chain.map((finding) => ({ finding }))]);
+}
+function assertBudget(asset, caps = asset.budget.triangles, o = {}) {
+  failOn(`${asset.name} budget`, compileLods(asset, o).flatMap((a) => {
+    const tris = a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+    const cap = caps[a.lod];
+    return tris > cap ? [
+      {
+        lod: a.lod,
+        finding: {
+          gate: "budget",
+          message: `${tris} triangles > ${cap}`,
+          fix: "drop detail at this LOD (ctx.lod / ctx.pick) — never raise a cap to make a test pass"
+        }
+      }
+    ] : [];
+  }));
+}
+function assertParts(asset, selectors, o = {}) {
+  failOn(`${asset.name} parts`, compileLods(asset, o).flatMap((a) => selectors.filter((s) => !a.parts.some((p) => glob2(s).test(p.name))).map((s) => ({
+    lod: a.lod,
+    finding: {
+      gate: "parts",
+      message: `no part matches '${s}'`,
+      fix: "engines bind to these names: add the part/group at this LOD (gate its geometry, not its pivot)"
+    }
+  }))));
+}
+function assertMeasure(asset, m, o = {}) {
+  const [a] = compileLods(asset, { lods: [o.lod ?? 0] });
+  const got = a ? measure2(a, m) : null;
+  const tol = m.tolerance ?? 0.02;
+  const bad = got === null || Math.abs(got - m.value) / m.value > tol;
+  failOn(`${asset.name} measure`, bad ? [
+    {
+      finding: {
+        gate: "measure",
+        message: got === null ? `'${m.label}': no part matches ${JSON.stringify(m.parts ?? m.between)}` : `${m.label}: ${got.toFixed(3)} m on ${m.axis.toUpperCase()}, want ${m.value} m (±${tol * 100}%)`,
+        fix: "rebuild the part from the spec number; never edit the spec to match the model"
+      }
+    }
+  ] : []);
+  return got ?? Number.NaN;
+}
+function assertMotionClear(asset, o = {}) {
+  failOn(`${asset.name} motion`, compileLods(asset, o).flatMap((a) => clashes2(a).map((finding) => ({ finding, lod: a.lod }))));
+}
+// src/testing/hash.ts
+function hashBytes(bytes) {
+  let h1 = 2166136261;
+  let h2 = 3421674724;
+  for (let i = 0;i < bytes.length; i++) {
+    const b = bytes[i] ?? 0;
+    h1 = Math.imul(h1 ^ b, 16777619);
+    h2 = Math.imul(h2 ^ b ^ h1 >>> 24, 16777619);
+  }
+  const hex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+  return `${hex(h2)}${hex(h1)}`;
+}
+// src/testing/snapshot.ts
+function snapshotHash(asset, o = {}) {
+  const a = compile2(asset, {
+    lod: o.lod ?? 0,
+    ...o.seed !== undefined ? { seed: o.seed } : {}
+  });
+  return hashBytes(exportGlb2(a, o.glb ?? {}).glb);
+}
+function assertDeterministic(asset, o = {}) {
+  for (const lod of o.lods ?? ALL_LODS) {
+    const once = snapshotHash(asset, { lod, ...o.seed !== undefined ? { seed: o.seed } : {} });
+    const twice = snapshotHash(asset, { lod, ...o.seed !== undefined ? { seed: o.seed } : {} });
+    if (once !== twice)
+      throw new Ts23dError2("T3D_QA_FAILED", {
+        cause: `${asset.name} LOD${lod} is not byte-deterministic (${once} vs ${twice})`,
+        fix: "remove ambient state from build(): read ctx.rng/ctx.seed only — no Math.random, Date, or module-level counters"
+      });
+  }
+}
+export {
+  ALL_LODS,
+  assertBudget,
+  assertDeterministic,
+  assertMeasure,
+  assertMotionClear,
+  assertParts,
+  assertQaPass,
+  compileLods,
+  describeFinding,
+  hashBytes,
+  snapshotHash
+};
+
+//# debugId=DE0A36904BC8E38564756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1,13 @@
+{
+  "version": 3,
+  "sources": ["../src/testing/compiled.ts", "../src/testing/assert.ts", "../src/testing/hash.ts", "../src/testing/snapshot.ts"],
+  "sourcesContent": [
+    "// Shared plumbing for the assertions: compile an asset at the LODs asked for, and turn QA\n// findings into one thrown Ts23dError an agent can act on (code, every finding, the first fix).\n\nimport { type Asset, type CompiledAsset, compile, type Lod, Ts23dError } from '../core/index.ts';\nimport type { Finding } from '../qa/index.ts';\n\nexport interface LodOptions {\n  /** LODs to check. Default all three. */\n  readonly lods?: readonly Lod[];\n  readonly seed?: number;\n}\n\nexport const ALL_LODS: readonly Lod[] = [0, 1, 2];\n\nexport const compileLods = (asset: Asset, o: LodOptions = {}): CompiledAsset[] =>\n  (o.lods ?? ALL_LODS).map((lod) =>\n    compile(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) }),\n  );\n\nexport const describeFinding = (f: Finding, lod?: Lod): string =>\n  `${lod !== undefined ? `LOD${lod} ` : ''}${f.gate}${f.part ? ` [${f.part}]` : ''}: ${f.message}`;\n\n/** Throw T3D_QA_FAILED listing every finding; no-op when there are none. */\nexport function failOn(what: string, found: ReadonlyArray<{ finding: Finding; lod?: Lod }>): void {\n  if (found.length === 0) return;\n  const lines = found.map(({ finding, lod }) => `  - ${describeFinding(finding, lod)}`);\n  throw new Ts23dError('T3D_QA_FAILED', {\n    cause: `${what}: ${found.length} finding(s)\\n${lines.join('\\n')}`,\n    fix: found[0]?.finding.fix ?? 'read the findings above',\n  });\n}\n",
+    "// Assertions for a recipe's own `bun test` (or any runner): each compiles the asset, checks one\n// property, and throws a Ts23dError with the findings and a fix — no test framework imported.\n//   it('passes QA', () => assertQaPass(tiger_1));\n//   it('has its pivots', () => assertParts(tiger_1, ['turret', 'gun', 'wheel_l_*']));\n\nimport type { Asset, Lod, Measure } from '../core/index.ts';\nimport {\n  clashes,\n  DEFAULT_GATES,\n  DEFAULT_LOD_GATES,\n  type Gate,\n  glob,\n  type LodGate,\n  measure,\n  runLodQa,\n  runQa,\n} from '../qa/index.ts';\nimport { compileLods, failOn, type LodOptions } from './compiled.ts';\n\nexport interface QaOptions extends LodOptions {\n  /** Per-LOD gates. Default the build's DEFAULT_GATES. */\n  readonly gates?: readonly Gate[];\n  /** Chain gates over all compiled LODs. Default DEFAULT_LOD_GATES. */\n  readonly lodGates?: readonly LodGate[];\n}\n\n/** The same gate `t3d build` runs: every LOD passes QA, plus the LOD-chain gates. */\nexport function assertQaPass(asset: Asset, o: QaOptions = {}): void {\n  const lods = compileLods(asset, o);\n  const found = lods.flatMap((a) =>\n    runQa(a, o.gates ?? DEFAULT_GATES).map((finding) => ({ finding, lod: a.lod })),\n  );\n  const chain = lods.length > 1 ? runLodQa(lods, o.lodGates ?? DEFAULT_LOD_GATES) : [];\n  failOn(`${asset.name} QA`, [...found, ...chain.map((finding) => ({ finding }))]);\n}\n\n/** Triangles per LOD at or under `caps` (default: the asset's own budget). */\nexport function assertBudget(\n  asset: Asset,\n  caps: readonly [number, number, number] = asset.budget.triangles,\n  o: LodOptions = {},\n): void {\n  failOn(\n    `${asset.name} budget`,\n    compileLods(asset, o).flatMap((a) => {\n      const tris = a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);\n      const cap = caps[a.lod];\n      return tris > cap\n        ? [\n            {\n              lod: a.lod,\n              finding: {\n                gate: 'budget',\n                message: `${tris} triangles > ${cap}`,\n                fix: 'drop detail at this LOD (ctx.lod / ctx.pick) — never raise a cap to make a test pass',\n              },\n            },\n          ]\n        : [];\n    }),\n  );\n}\n\n/** Each selector (name or glob) matches at least one part at every LOD checked. */\nexport function assertParts(asset: Asset, selectors: readonly string[], o: LodOptions = {}): void {\n  failOn(\n    `${asset.name} parts`,\n    compileLods(asset, o).flatMap((a) =>\n      selectors\n        .filter((s) => !a.parts.some((p) => glob(s).test(p.name)))\n        .map((s) => ({\n          lod: a.lod,\n          finding: {\n            gate: 'parts',\n            message: `no part matches '${s}'`,\n            fix: 'engines bind to these names: add the part/group at this LOD (gate its geometry, not its pivot)',\n          },\n        })),\n    ),\n  );\n}\n\n/** One spec dimension at LOD0, the way the `measures` gate checks `real.measures`. */\nexport function assertMeasure(asset: Asset, m: Measure, o: { lod?: Lod } = {}): number {\n  const [a] = compileLods(asset, { lods: [o.lod ?? 0] });\n  const got = a ? measure(a, m) : null;\n  const tol = m.tolerance ?? 0.02;\n  const bad = got === null || Math.abs(got - m.value) / m.value > tol;\n  failOn(\n    `${asset.name} measure`,\n    bad\n      ? [\n          {\n            finding: {\n              gate: 'measure',\n              message:\n                got === null\n                  ? `'${m.label}': no part matches ${JSON.stringify(m.parts ?? m.between)}`\n                  : `${m.label}: ${got.toFixed(3)} m on ${m.axis.toUpperCase()}, want ${m.value} m (±${tol * 100}%)`,\n              fix: 'rebuild the part from the spec number; never edit the spec to match the model',\n            },\n          },\n        ]\n      : [],\n  );\n  return got ?? Number.NaN;\n}\n\n/** Every moving part sweeps clear of everything else (the `clashes` gate), at every LOD. */\nexport function assertMotionClear(asset: Asset, o: LodOptions = {}): void {\n  failOn(\n    `${asset.name} motion`,\n    compileLods(asset, o).flatMap((a) => clashes(a).map((finding) => ({ finding, lod: a.lod }))),\n  );\n}\n",
+    "// A stable content hash for snapshot tests: 64-bit FNV-1a (two 32-bit lanes), pure JS, so the\n// same bytes give the same hex string on Bun, Node and the browser — no runtime hash API needed.\n\nexport function hashBytes(bytes: Uint8Array): string {\n  let h1 = 0x811c9dc5;\n  let h2 = 0xcbf29ce4;\n  for (let i = 0; i < bytes.length; i++) {\n    const b = bytes[i] ?? 0;\n    h1 = Math.imul(h1 ^ b, 0x01000193);\n    h2 = Math.imul(h2 ^ b ^ (h1 >>> 24), 0x01000193);\n  }\n  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0');\n  return `${hex(h2)}${hex(h1)}`;\n}\n",
+    "// Determinism and snapshot helpers: the GLB an asset compiles to, hashed. Pin a hash in a test to\n// catch any unintended geometry change; compile twice to prove the recipe has no ambient state.\n\nimport { type Asset, compile, type Lod, Ts23dError } from '../core/index.ts';\nimport { exportGlb, type GlbOptions } from '../export/index.ts';\nimport type { LodOptions } from './compiled.ts';\nimport { ALL_LODS } from './compiled.ts';\nimport { hashBytes } from './hash.ts';\n\nexport interface SnapshotOptions {\n  readonly lod?: Lod;\n  readonly seed?: number;\n  /** Exporter options; default the plain optimised GLB (no textures, no clips). */\n  readonly glb?: GlbOptions;\n}\n\n/** 16-hex-digit content hash of the asset's GLB at one LOD. */\nexport function snapshotHash(asset: Asset, o: SnapshotOptions = {}): string {\n  const a = compile(asset, {\n    lod: o.lod ?? 0,\n    ...(o.seed !== undefined ? { seed: o.seed } : {}),\n  });\n  return hashBytes(exportGlb(a, o.glb ?? {}).glb);\n}\n\n/** Compile + export twice per LOD; the bytes must match. */\nexport function assertDeterministic(asset: Asset, o: LodOptions = {}): void {\n  for (const lod of o.lods ?? ALL_LODS) {\n    const once = snapshotHash(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) });\n    const twice = snapshotHash(asset, { lod, ...(o.seed !== undefined ? { seed: o.seed } : {}) });\n    if (once !== twice)\n      throw new Ts23dError('T3D_QA_FAILED', {\n        cause: `${asset.name} LOD${lod} is not byte-deterministic (${once} vs ${twice})`,\n        fix: 'remove ambient state from build(): read ctx.rng/ctx.seed only — no Math.random, Date, or module-level counters',\n      });\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "DE0A36904BC8E38564756E2164756E21",
+  "names": []
+}

package/dist/testing/snapshot.d.ts

@@ -0,0 +1,13 @@
+import { type Asset, type Lod } from '../core/index.js';
+import { type GlbOptions } from '../export/index.js';
+import type { LodOptions } from './compiled.js';
+export interface SnapshotOptions {
+    readonly lod?: Lod;
+    readonly seed?: number;
+    /** Exporter options; default the plain optimised GLB (no textures, no clips). */
+    readonly glb?: GlbOptions;
+}
+/** 16-hex-digit content hash of the asset's GLB at one LOD. */
+export declare function snapshotHash(asset: Asset, o?: SnapshotOptions): string;
+/** Compile + export twice per LOD; the bytes must match. */
+export declare function assertDeterministic(asset: Asset, o?: LodOptions): void;

package/docs/README.md

@@ -0,0 +1,56 @@
+# ts23d docs
+
+**These docs are versioned with the package:** the copy in `node_modules/@developerz.ai/ts23d/docs/` always matches the installed code, and works offline.
+
+**One owning doc per fact.** The idea docs say what and why; ADRs record decisions and the options they rejected; the architecture docs say where things go. The code wins on any conflict. Open an issue when you find one.
+
+## Start here
+
+| If you want to… | Read |
+|---|---|
+| Know what this is and isn't | [idea/01-vision.md](idea/01-vision.md) |
+| Write a recipe | [idea/02-dsl.md](idea/02-dsl.md) → [idea/09-kinds.md](idea/09-kinds.md) |
+| Drive it from an agent | [idea/05-agent-loop.md](idea/05-agent-loop.md) |
+| Decide if your asset fits | [idea/07-what-fits.md](idea/07-what-fits.md) · [landscape.md](landscape.md) |
+| Add code to the library | [architecture/README.md](architecture/README.md) · [../CONTRIBUTING.md](../CONTRIBUTING.md) |
+| Decode an error | [architecture/errors.md](architecture/errors.md) |
+| See what's built vs planned | [plans/roadmap.md](plans/roadmap.md) |
+| Release a version | [../PUBLISHING.md](../PUBLISHING.md) |
+
+## Idea: what and why
+
+| Doc | Covers |
+|---|---|
+| [01-vision.md](idea/01-vision.md) | The pitch, origin, principles, non-goals |
+| [02-dsl.md](idea/02-dsl.md) | `defineAsset`, the `ctx` API, composition with `ctx.use`, determinism rules |
+| [03-ir.md](idea/03-ir.md) | Mesh IR, parts, units, axes, LODs |
+| [04-materials.md](idea/04-materials.md) | Trim sheet, palettes, vertex colour, the procedural sheet painter, TSL / Godot shader sources |
+| [05-agent-loop.md](idea/05-agent-loop.md) | The write → build → shot → read loop, contact sheet layout |
+| [06-qa.md](idea/06-qa.md) | Gates: shipped vs planned |
+| [07-what-fits.md](idea/07-what-fits.md) | Fit matrix by asset category |
+| [08-neural-adapters.md](idea/08-neural-adapters.md) | Optional local-GPU models for organic shapes, image sources |
+| [09-kinds.md](idea/09-kinds.md) | Domain builders: building, vehicle, vessel, vegetation, creature, scene |
+| [10-sculpting.md](idea/10-sculpting.md) | How artists sculpt, mapped onto SDF edit lists; brushes, skin, FFD, forms |
+| [11-materials-authoring.md](idea/11-materials-authoring.md) | Node-graph material authoring vs the trim-sheet painter; curvature and edge wear |
+| [12-blender-bridge.md](idea/12-blender-bridge.md) | Optional headless Blender adapter: design, determinism, feasibility (planned) |
+| [13-asset-pipeline-research.md](idea/13-asset-pipeline-research.md) | Pro asset pipeline, trim sheets, texel density, CC0 libraries and licences |
+
+## Decisions
+
+Index with status: [decisions/README.md](decisions/README.md).
+
+## Architecture: where things go
+
+| Doc | Covers |
+|---|---|
+| [architecture/README.md](architecture/README.md) | Module tiers and the import rule |
+| [architecture/adding-a-primitive.md](architecture/adding-a-primitive.md) | New geometry builder |
+| [architecture/adding-a-kind.md](architecture/adding-a-kind.md) | New domain builder |
+| [architecture/errors.md](architecture/errors.md) | Every `T3D_*` code: cause, fix |
+
+## Other
+
+| Doc | Covers |
+|---|---|
+| [plans/roadmap.md](plans/roadmap.md) | M0–M6 milestones |
+| [landscape.md](landscape.md) | Neutral survey of AI 3D generators (as of 2026-10) |

package/docs/architecture/README.md

@@ -0,0 +1,68 @@
+# Architecture
+
+**Imports only go down a tier.** A module imports from strictly lower tiers, never sideways, never up, and only through the other module's `index.ts`. `scripts/boundaries.ts` enforces it in `bun run verify`; the executable copy of the table below is `scripts/lib/tiers.ts`. Change both together.
+
+## Tiers
+
+| Tier | Module | Job |
+|---|---|---|
+| 0 | `core` | Errors, seeded RNG, vector math, the Mesh IR, `defineAsset` / `compile`, mesh transforms (`place`), world transforms |
+| 1 | `grammar` | String mini-languages: split grammar, Whyte notation |
+| 1 | `material` | Trim-sheet layout, palettes, `paintTrimSheet`, TSL and Godot shader sources |
+| 2 | `primitives` | Geometry builders → `Mesh`: `box`, `lathe`, `cylinder`, `prism`, `beam`, `planar`, `sweep`, `loft`, `heightfield`, `triangulate`; planned `tiled`, `cell`, `sdf` |
+| 2 | `neural` | Optional AI adapters: local-GPU mesh generators, `importGlb`, image sources (all planned) |
+| 2 | `passes` | Whole-mesh post-processing: `grime`; planned `optimize` (weld, vertex-cache reorder, ACMR) |
+| 3 | `kinds` | Domain builders: building, vehicle, vegetation (`tree`, `trees`); planned vessel, creature |
+| 3 | `qa` | Gates over a `CompiledAsset` |
+| 3 | `export` | `CompiledAsset` → GLB |
+| 3 | `render` | CPU rasteriser, PNG encoder, contact sheet; planned `photoMatch` |
+| 4 | `cli` | `t3d build / shot / hero / review / list` |
+| 4 | `testing` | assertions for users' recipe tests (subpath `/testing`) |
+| 5 | `src/index.ts` | Re-exports every public module |
+
+```
+            src/index.ts (5)        cli (4)
+                    │                 │
+     ┌──────────┬───┴──────┬──────────┤
+   kinds      qa       export      render     (3)
+     │
+ primitives   neural   passes                 (2)
+     │
+ grammar   material                           (1)
+     │
+   core                                       (0)
+```
+
+Rules the guard prints with a `fix:`:
+
+| Violation | Fix |
+|---|---|
+| Import from a same or higher tier | Move the shared code lower, or invert the dependency |
+| Deep import (`../core/mesh.ts`) | Import from `../core/index.ts`; export what you need there |
+| Module missing from the tier table | Add it to `scripts/lib/tiers.ts` and this table |
+
+## Data flow
+
+```
+recipe.ts ─► defineAsset ─► compile(asset, { lod }) ─► CompiledAsset { parts[] }
+                                                         ├─► runQa ─► Finding[]
+                                                         ├─► toGlb ─► .glb
+                                                         └─► contactSheet ─► .png
+```
+
+`Mesh` is the only geometry type crossing modules ([IR](../idea/03-ir.md)).
+
+## Module conventions
+
+- `index.ts` per module, one header comment stating the module's job, named re-exports only.
+- Declared-but-unbuilt API lives in a `planned.ts` with its final signature, throwing `notImplemented(what, plan?)`. Recipes and docs can target it; it fails loudly until built.
+- Public subpath per module: `@developerz.ai/ts23d/<module>` ([ADR 006](../decisions/006-single-package-subpath-exports.md)).
+
+## Guides
+
+| Doc | |
+|---|---|
+| [adding-a-primitive.md](adding-a-primitive.md) | New geometry builder |
+| [adding-a-kind.md](adding-a-kind.md) | New domain builder |
+| [errors.md](errors.md) | Every `T3D_*` code |
+| [glb-production.md](glb-production.md) | Production GLB rules, validator results, per-engine import table, gap list |

package/docs/architecture/adding-a-kind.md

@@ -0,0 +1,44 @@
+# Adding a kind
+
+**A kind is a library of builder functions `(ctx, options) => void | value`.** Builders add named parts to the caller's `ctx`; the recipe keeps control of layout, naming and LOD. It lives in `src/kinds/` (tier 3) and may import `core`, `grammar`, `material`, `primitives`, `neural`, `passes`.
+
+## Checklist
+
+| Step | Rule |
+|---|---|
+| 1. Signature | If it's in `src/kinds/planned.ts` (today only `creature`), keep that signature and move it to its own file |
+| 2. Duplicate check | Read the shipped kinds first — `building.ts` (`facade`, `setbacks`), `vehicle.ts` (`axle`, `whyteAxles`, `trackRun`, `propeller`), `vegetation.ts` (`tree`, `trees`, `treeReal`), `roof.ts` (`roof`, `roofMesh`), `openings.ts` (`opening`), `mass.ts`, `hull.ts`, `head.ts` (`head`, `HEADS`). Extend one of them; don't re-add what already ships |
+| 3. Domain params | Take the parameters the domain uses: Whyte `2-6-2`, length/beam/draft, species + height, roof pitch in degrees. Not raw coordinates |
+| 4. Names | Every part prefixed by a caller-supplied `prefix`/`name`. Follow the engine contract: `axle_*` / `wheel_*` spin about Y, `prop_*` / `rotor_*` about their own axis, `door_*` hinge at the pivot |
+| 5. Pivots | Movable pieces get a `ctx.group` at the hinge, the mesh inside it. Yaw on the group, motion on the child |
+| 6. LOD | Read `ctx.lod`: drop details, lower segments. Masses survive to LOD2 |
+| 7. Randomness | Only `ctx.rng.fork('<kind>:<prefix>')`, so adding the kind doesn't shift other draws |
+| 8. Real units | Defaults from real references, cited in a comment (e.g. standard gauge 1.435 m) |
+| 9. Export | Named export from `src/kinds/index.ts` |
+| 10. Test | Next to it: part names, part count per LOD, QA passes on a minimal asset using it |
+| 11. Recipe | At least one `recipes/*/*.ts` using it. Its contact sheet is the review artefact |
+| 12. Docs | [09-kinds](../idea/09-kinds.md), [07-what-fits](../idea/07-what-fits.md), [roadmap](../plans/roadmap.md), `CHANGELOG.md` |
+
+## Shape
+
+```ts
+// Vessel helpers: hulls from naval-architecture params, lofted from sections.
+
+import type { BuildContext, Vec3 } from '../core/index.ts';
+import { loft } from '../primitives/index.ts';
+
+export interface HullOptions {
+  readonly length: number;    // LOA, metres
+  readonly beam: number;
+  readonly draft: number;
+  readonly freeboard: number;
+  readonly color: Vec3;
+}
+
+export function hull(ctx: BuildContext, o: HullOptions): void {
+  const stations = [24, 12, 6][ctx.lod] ?? 6;
+  // sections from sheer + keel curves → loft → ctx.part('hull', …)
+}
+```
+
+A kind that needs a missing primitive adds the primitive first ([adding-a-primitive.md](adding-a-primitive.md)), in its own PR.

package/docs/architecture/adding-a-primitive.md

@@ -0,0 +1,49 @@
+# Adding a primitive
+
+**A primitive is a pure function `(options) => Mesh`.** No `ctx`, no parts, no RNG unless a `seed` is an option. It lives in `src/primitives/` (tier 2) and may import `core` and `material` only.
+
+## Checklist
+
+| Step | Rule |
+|---|---|
+| 1. Signature | One file per primitive (`tiled.ts`, `lattice.ts`). Every planned primitive has shipped; a new one is a new file |
+| 2. Options | Readonly interface `XOptions`, exported. Sizes in metres. `color: Vec3` (linear), `strip?: StripId` (default `'plain'`), `at?: Vec3` |
+| 3. Placement | Base at `at` (z = 0 = ground) unless the shape has a natural centre (axles, `lathe` with `axis`). Say which in the doc comment |
+| 4. Geometry | `MeshBuilder`: `vertex({ p, n, uv, color })`, `quad(a, b, c, d)` counter-clockwise from outside |
+| 5. UVs | Map into `stripRect(strip)` by world metres, so texel density matches across assets. V cannot wrap: cut faces into bands of the strip's V metres (see `strip-uv.ts`), or mirror V for organic surfaces. `box` still stretches V over the face; use `tiled` or kinds' `mass` for true-scale walls |
+| 6. LOD | Take a resolution option (`segments`, `resolution`). The recipe picks it from `ctx.lod`; the primitive never reads LOD |
+| 7. Contact | If the shape rests on something, put a vertex at the contact point (see the `lathe` ring offset; the floating-parts gate caught a coarse wheel missing its rail) |
+| 8. Export | Named export from `src/primitives/index.ts` |
+| 9. Test | `x.test.ts` next to it (see `prism.test.ts`): triangle count, bounds, normals point out, deterministic output |
+| 10. Use it | Add or update a recipe in `recipes/` that uses it, so `scripts/recipes.ts` gates it |
+| 11. Docs | Tick it in [roadmap](../plans/roadmap.md); update [07-what-fits](../idea/07-what-fits.md) if fit changed; add to `CHANGELOG.md` under `[Unreleased]` |
+
+## Skeleton
+
+Real shipped references: `prism.ts`, `beam.ts`, `planar.ts`, `tiled.ts`, `lattice.ts`.
+
+```ts
+// A quad tiling one trim strip at true scale: walls, roofs, decks.
+
+import { cross, length, type Mesh, MeshBuilder, normalize, type Vec3 } from '../core/index.ts';
+import { type StripId, stripRect } from '../material/index.ts';
+
+export interface TiledOptions {
+  readonly origin: Vec3;   // one corner
+  readonly u: Vec3;        // edge along the strip, metres
+  readonly v: Vec3;        // the other edge
+  readonly color: Vec3;
+  readonly strip: StripId;
+}
+
+export function tiled(o: TiledOptions): Mesh {
+  const rect = stripRect(o.strip);
+  const n = normalize(cross(o.u, o.v));
+  const reps = length(o.u) / rect.metres;           // true-scale tiling along U
+  const b = new MeshBuilder();
+  // 4 vertices: origin, +u, +u+v, +v; uv u from 0 to reps across the strip's rect
+  return b.build();
+}
+```
+
+Done = `bun run verify` green, including the recipe that uses it.

package/docs/architecture/errors.md

@@ -0,0 +1,47 @@
+# Errors
+
+**Every failure is a `Ts23dError` with a stable `code`, a `cause` in the message, and a `fix`.** The reader is usually an agent: act on `fix`, don't parse prose. Codes are stable across minor versions. Source: `src/core/errors.ts`.
+
+```
+T3D_PART_UNKNOWN: part 'gun_barrel' parents to 'gun', which does not exist yet
+  fix: add the parent (ctx.group or ctx.part) before its children
+```
+
+`--json`: `{"ok":false,"error":{"code":"…","message":"…","fix":"…"}}`, exit 1.
+
+## Library codes
+
+| Code | Thrown by | Cause | Fix |
+|---|---|---|---|
+| `T3D_NOT_IMPLEMENTED` | Anything still in a `planned.ts` (`creature`), `/neural`, and whatever the roadmap lists as unbuilt | Declared API, not built yet. The message names the doc tracking it | Use a shipped alternative ([roadmap](../plans/roadmap.md)), or implement it ([adding a primitive](adding-a-primitive.md), [adding a kind](adding-a-kind.md)) |
+| `T3D_GRAMMAR_SYNTAX` | `parseSplit`, `split`, `parseWhyte` | Bad split term, empty split, a repeat with stretch terms, more than one repeat; or a Whyte string that isn't three even numbers | Split: `sym:<metres>`, `sym:~`, `sym:~<weight>`, `{a:1 \| b:2}*`, joined by `\|`. Whyte: `'4-4-0'`, `'2-8-2'` |
+| `T3D_GRAMMAR_OVERFLOW` | `layoutSplit`, `split`, `facade` | Fixed terms sum to more than the strip length | Shrink a fixed term or make one a stretch (`sym:~`) |
+| `T3D_PART_DUPLICATE` | `ctx.part`, `ctx.group`, `ctx.use` | A part name added twice in one asset | Suffix the loop index: `wheel_0`, `wheel_1`; give each `ctx.use` a unique `prefix` |
+| `T3D_PART_UNKNOWN` | `ctx.part`, `ctx.group` | `parent` names a part not added yet | Add the parent first |
+| `T3D_RECIPE_INVALID` | `defineAsset`, `ctx.part`, every primitive and kind | Asset name not `[a-z][a-z0-9_]*`; a part with both `yaw` and `motion`; or a primitive/kind given impossible input (zero-length edge, bevel ≥ half a side, roof pitch out of range, SDF grid over the cell cap) | Rename to snake_case; put yaw on a parent `ctx.group`, motion on the child; otherwise the printed `fix:` names the bad option and its valid range |
+| `T3D_NO_ASSET_EXPORT` | CLI loader | The module exports no `defineAsset` result | `export const my_thing = defineAsset({ … })`. Named export, no default |
+| `T3D_QA_FAILED` | `/testing` assertions (`assertQaPass`, `assertBudget`, `assertMeasure`, …) | A recipe test found QA findings; the message lists every one. The CLI itself reports findings and exits 1 instead | Fix each finding's `fix:` line |
+| `T3D_RENDER_OPTIONS` | `beauty`, `t3d hero` / `review` flags, render metrics | Bad image size, camera angle or render option | The printed `fix:` names the valid range |
+
+## Repo tooling codes
+
+In `ErrorCode`, raised by this repo's scripts and test tooling rather than by the library at runtime.
+
+| Code | Where | Cause | Fix |
+|---|---|---|---|
+| `T3D_AMBIENT_RANDOM` | Test preload (`scripts/test-setup.ts`) | Code under test called `Math.random` | Use `ctx.rng` or `createRng(seed)` |
+| `T3D_RELEASE` | `scripts/release.ts` | Bad version string, missing `## [Unreleased]`, or tree not stamped at the version | The printed `fix:` (usually `bun run release <x.y.z>`) |
+| `T3D_BENCH` | `scripts/bench.ts --write` | `README.md` has no bench block | The printed `fix:`; the markers are `<!-- bench:start -->` / `<!-- bench:end -->` on their own lines |
+
+Guards (`boundaries`, `determinism`, `filesize`, `recipes`) print `file:line`, message and `fix:` without a code.
+
+## QA findings are not errors
+
+A gate returns `Finding { gate, part?, message, fix }`. Findings don't throw; `t3d build` prints them all and exits 1. Gate list: [06-qa](../idea/06-qa.md).
+
+## Adding a code
+
+1. Add it to `ErrorCode` in `src/core/errors.ts`. `T3D_` + area + problem, upper snake case.
+2. Throw `new Ts23dError(code, { cause, fix })`. `cause` names the offending value; `fix` is an action, ideally a literal snippet.
+3. Add a row here in the same PR.
+4. Never rename or reuse a code. Retire by leaving it in the union, documented as unused.