@developerz.ai/ts23d 0.0.0-stage → 0.1.0

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.

package/docs/architecture/glb-production.md

@@ -0,0 +1,214 @@
+# Production GLB
+
+**A ts23d GLB is production-ready when it passes glTF-Validator with zero errors and warnings, faces glTF +Z, uses only core glTF 2.0 by default, and keeps engine-bound names stable across LODs. Compression, instancing and draft physics are opt-in profiles, never the default.** Godot 4 refuses any file whose `extensionsRequired` lists something it does not implement, and in 2026-10 that includes `KHR_mesh_quantization`, `EXT_meshopt_compression` and `KHR_draco_mesh_compression` ([Godot `_parse_gltf_extensions` and `get_supported_gltf_extensions_hashset`](https://github.com/godotengine/godot/blob/master/modules/gltf/gltf_document.cpp)). Those extensions must be required, so a "drop into any engine" default cannot use them ([KHR_mesh_quantization §Overview](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_mesh_quantization), [KHR_draco_mesh_compression](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_draco_mesh_compression)).
+
+As of 2026-10. The exporter here is `src/export/glb.ts` (`toGlb`), `bin-writer.ts` (`BinWriter`), `motion.ts` (`motionChannel`) and `merge-pivots.ts` (`mergeToPivots`). These were read on 2026-10-25, while another agent was adding emitter `extras` to `glb.ts`. The spec is cited as [glTF 2.0 Specification.adoc](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc) by section anchor, written **[spec §anchor]**. The rendered copy is at [registry.khronos.org](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html).
+
+**Status updated 2026-10-25 after the exporter work (G1, G2, G4, G5, G10, surfaces, `rest` clip). Sections (b) and (d) keep the original findings, with an update block on top.**
+
+Status legend: **done** · **partial** · **missing** · **n/a (not yet)**. *Verified by*: `code` means read in the exporter, `val` means glTF-Validator 2.0.0-dev.3.10 output, and `insp` means the byte-level inspection script run on the tiger_1 GLBs (section b).
+
+---
+
+## (a) Production checklist
+
+### Must
+
+| # | Rule | Source | Status | Verified by |
+|---|---|---|---|---|
+| M1 | 0 validator errors and 0 warnings | [glTF-Validator ISSUES.md](https://github.com/KhronosGroup/glTF-Validator/blob/main/ISSUES.md) | **done**: 0 / 0 on all 6 tiger GLBs; glTF-Validator now runs in the test suite (`src/export/validator.test.ts`, devDependency) and caught a sealed-buffer bug, since fixed | val |
+| M2 | `POSITION` accessors carry `min`/`max` that match the data exactly (`ACCESSOR_MIN_MISMATCH`/`MAX_MISMATCH` are errors) | [spec §meshes-attributes](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-attributes): "Accessors for the `POSITION` semantic MUST have their bounds… defined" | **done**: `BinWriter.accessor(…, bounds=true)` computes bounds from the same `Float32Array` | code, val |
+| M3 | Animation sampler `input` has `min`/`max` and strictly increasing times | [spec §animations](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#animations) | **done**: `motionChannel` passes `bounds=true` | code, val |
+| M4 | Vertex attribute offsets are 4-byte aligned; buffer views ≥ accessor extent; no `byteStride` on non-vertex views | [spec §data-alignment](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#data-alignment) | **done**: `BinWriter.push` pads every view to 4 bytes and views are tightly packed | code, val |
+| M5 | GLB: JSON chunk padded with `0x20`, BIN chunk padded with `0x00`, lengths multiple of 4, header length equals file size | [spec §glb-file-format-specification](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#glb-file-format-specification) | **done**: `toGlb` tail and `BinWriter.bytes` | code, val |
+| M6 | `bufferView.target` set for vertex (34962) and index (34963) data; unset for animation data | [ISSUES.md `BUFFER_VIEW_TARGET_MISSING`](https://github.com/KhronosGroup/glTF-Validator/blob/main/ISSUES.md) | **done** | code, val (no hint) |
+| M7 | Node hierarchy is disjoint strict trees: one parent at most, no cycles | [spec §nodes-and-hierarchy](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#nodes-and-hierarchy) | **done**: single root, parents resolved by name; `T3D_PART_UNKNOWN` rejects forward references at authoring | code, val |
+| M8 | Normals unit length; rotation quaternions normalised (`ACCESSOR_VECTOR3_NON_UNIT`, `ROTATION_NON_UNIT`) | [ISSUES.md](https://github.com/KhronosGroup/glTF-Validator/blob/main/ISSUES.md) | **done**: 0 non-unit normals out of 37,749 | val, insp |
+| M9 | Indices use u8/u16/u32 and never contain the type's max value (primitive restart) | [spec §meshes-topology](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-topology) | **done**: u16 when ≤ 65,535 vertices, else u32 (G4) | code, val |
+| M10 | Y-up, metres, **front faces +Z, left faces +X** | [spec §coordinate-system-and-units](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#coordinate-system-and-units): "the front side of a glTF asset faces +Z, the left side of a glTF asset faces +X" | **done** (G1): root quaternion `[-0.5,-0.5,-0.5,0.5]` maps authoring +X front → glTF +Z, +Z up → +Y, +Y left → +X, checked numerically. Was `[-√½,0,0,√½]` (assets faced glTF +X, the left side). [ADR 009](../decisions/009-gltf-front-axis.md) | code, insp |
+| M11 | `COLOR_0` is linear and in [0,1]; it multiplies baseColor | [spec §meshes-attributes](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-attributes), [spec §metallic-roughness-material](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#metallic-roughness-material): "encoded with the linear transfer function" | **done**: `src/material/palette.ts` converts sRGB hex to linear; measured range 0.009–1.0 | code, insp |
+| M12 | Every node that engine code binds to (pivots) has a stable, unique name **in every LOD** | Engines bind by node path (glTFast/Godot/Unreal all keep node names) | **partial**: names are unique and stable at LOD0/LOD1 (24 nodes). LOD2 has only `tiger_1, body, turret, gun`, so the 18 wheel/sprocket/idler pivots disappear and game code that drives `wheel_l_0` breaks at LOD2 (G3) | insp |
+| M13 | No accidental engine name hints: no node or mesh name ends in a Godot suffix (`-col`, `_col`, `$col`, `-colonly`, `-convcol`, `-convcolonly`, `-noimp`, `-occ`, `-occonly`, `-navmesh`, `-vehicle`, `-wheel`, `-rigid`), and no clip name starts or ends with `loop`/`cycle` unless looping is intended. Suffix matching is case-insensitive and accepts `-`, `$` or `_` | [Godot: node type customization](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.html) | **missing as a gate**. No current recipe violates it (repo grep), but a part named `spare_wheel` would import into Godot as a `VehicleWheel3D` (G6) | code (grep) |
+| M14 | A looping clip's last key equals its first key | [spec §animations](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#animations) clamps outside the input range; it does not define looping, so any seam is the asset's fault | **done** (G2): clip length 4 s, each motion rounded to whole cycles (`cyclesOf`), spins get ≥ 12 keys per turn, so the last key equals the first. Was a fixed 2 s clip that popped 216° on `rps 0.8` | code, insp |
+
+### Should
+
+| # | Rule | Source | Status | Verified by |
+|---|---|---|---|---|
+| S1 | Smallest index type that fits: u16 when the primitive has at most 65,535 vertices (index 65,535 is the restart value, so the highest usable index is 65,534), u8 is legal but slow on some GPUs | [spec §meshes-topology](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-topology) | **done** (G4): u16 indices whenever the primitive has ≤ 65,535 vertices | code, insp |
+| S2 | `COLOR_0` as normalised `unorm16` VEC4 (8 B/v) instead of float VEC4 (16 B/v). This is core glTF, needs no extension, and every loader supports it | [spec §meshes-attributes](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-attributes): COLOR_n is float32, unorm8 or unorm16 | **done** (G5): COLOR_0 is normalised u16 RGBA (8 B/v). Was float VEC4, 27 % of LOD0 | code, insp |
+| S3 | No unused attributes (`UNUSED_OBJECT`) | [ISSUES.md](https://github.com/KhronosGroup/glTF-Validator/blob/main/ISSUES.md) | **done**: the painted trim sheet is bound (embedded or external), so `TEXCOORD_0` is used. Infos remain only with `--sheet none` | val |
+| S4 | Reuse one `mesh` index across nodes with identical local geometry; engines then share one mesh asset | [spec §meshes-overview](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-overview) (nodes reference meshes by index) | **missing** (G9) | insp |
+| S5 | `asset.copyright`, plus provenance in `asset.extras` (recipe, ts23d version, seed, content hash) | [spec §asset](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#asset): "metadata MAY be stored in… `generator` or `copyright`" | **partial**: `generator: "@developerz.ai/ts23d"` has no version; there is no copyright and no provenance | code |
+| S6 | Clip names follow engine conventions: Godot loops a clip only if its name starts or ends with `loop`/`cycle` | [Godot node type customization](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.html); [`gltf_document.cpp` `begins_with("loop")`](https://github.com/godotengine/godot/blob/master/modules/gltf/gltf_document.cpp) | **missing** (G7): clips are `rest` and `run`; Godot imports `run` non-looping | code |
+| S7 | Default to no clip, or a harmless idle; viewers autoplay the first clip | [spec §animations](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#animations) (runtime behaviour undefined); Babylon `animationStartMode = FIRST` ([source](https://github.com/BabylonJS/Babylon.js/blob/master/packages/dev/loaders/src/glTF/glTFFileLoader.pure.ts)); model-viewer `autoplay` plays the first ([docs](https://modelviewer.dev/docs/index.html)) | **done**: `toGlb` exports no clip unless `animations: true`. When it does (and `t3d build` does by default), the first clip is `rest` (static, two keys), so viewers open paused and `run` plays on request | code |
+| S8 | One sampler `input` accessor shared by channels with the same keyframe times | [spec §animations](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#animations) | **done** (G10): time accessors shared per key count | code |
+| S9 | Root transform: rotation-only on one named root; no scale | [Godot import configuration: Apply Root Scale](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.html) | **done** (rotation only; corrected quaternion, see M10) | code |
+| S10 | `TANGENT` only when a normal map is bound. Without one, omit it (the spec says it "SHOULD NOT" be present without normals). With one, either ship MikkTSpace tangents or accept the `MESH_PRIMITIVE_GENERATED_TANGENT_SPACE` warning | [spec §meshes-usage](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-usage): tangents not specified means "calculated using default MikkTSpace algorithms" | **done**: `TANGENT` is emitted only when a sheet (with its normal map) is bound | code |
+| S11 | Collision proxies available in a form each engine imports (section 6) | Per-engine (section c) | **missing** | code |
+| S12 | LODs consumable without hand work: one file with MSFT_lod plus `MSFT_screencoverage`, and/or `_LODn` names, plus the per-LOD files | [MSFT_lod](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/MSFT_lod) | **partial**: three separate files `tiger_1.lod{0,1,2}.glb` with `extras.lod`; no switch distances | code |
+
+### Nice
+
+| # | Rule | Source | Status |
+|---|---|---|---|
+| N1 | `--profile web`: `KHR_mesh_quantization` + `EXT_meshopt_compression` (or `KHR_meshopt_compression`, Release Candidate) for three.js/Babylon/glTFast | [EXT_meshopt_compression](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression) (Complete, Ratified); [KHR_meshopt_compression](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_meshopt_compression) | missing |
+| N2 | `EXT_mesh_gpu_instancing` for bolts, rivets and track links in a web/Unity profile | [EXT_mesh_gpu_instancing](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_mesh_gpu_instancing): "files that use the extension should specify it in `extensionsRequired`" | missing |
+| N3 | KTX2 (`KHR_texture_basisu`) trim sheet: UASTC for normal and ORM, ETC1S for base colour | [KTX Artist Guide](https://github.com/KhronosGroup/3D-Formats-Guidelines/blob/main/KTXArtistGuide.md) | n/a (no textures yet) |
+| N4 | `KHR_materials_emissive_strength` for lit windows and headlights | [spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_emissive_strength) (Ratified) | missing |
+| N5 | `KHR_xmp_json_ld` with `dc:creator`, `dc:rights`, `xmpRights:UsageTerms` | [KHR_xmp_json_ld](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_xmp_json_ld) (Ratified) | missing |
+| N6 | `KHR_physics_rigid_bodies` + `KHR_implicit_shapes` (in `extensionsUsed` only, never required) | Draft PRs [#2424](https://github.com/KhronosGroup/glTF/pull/2424), [#2370](https://github.com/KhronosGroup/glTF/pull/2370), both open | missing (wait) |
+
+---
+
+## (b) Validator results: tiger_1
+
+**Update 2026-10-25, after G1/G2/G4/G5/G10:** tiger_1 is now 88,176 / 16,304 / 648 triangles (the recipe was reworked). LOD0 dropped from 13.0 MB to 11.0 MB with 0 validator errors. Build plus QA at 3 LODs, contact sheet included, takes about 4.7 s. The table below is the original run on the older, smaller recipe.
+
+**Verdict: VALID. 0 errors, 0 warnings, 0 hints on all six files. The only infos are `UNUSED_OBJECT` on `TEXCOORD_0` (one per primitive), because no texture is bound.** The real problems (sideways front, u32 indices, fat colours, loop seam, LOD2 losing pivots) are outside the validator's scope and were found by the inspection script.
+
+The build was `bun run t3d build recipes/tiger_1/tiger_1.ts --out …/glbcheck`, then again with `--animations`. Both print `QA FAIL` (clashes and floating parts in the recipe, not the exporter) and both still write all three GLBs. The validator was npm `gltf-validator@2.0.0-dev.3.10` (`validateBytes`, `maxIssues: 0`), run from the scratchpad.
+
+| File | Bytes | Err | Warn | Info | Hint | Draw calls | Verts | Tris | Anim |
+|---|---|---|---|---|---|---|---|---|---|
+| `tiger_1.lod0.glb` | 2,209,336 | 0 | 0 | 23 | 0 | 23 | 37,749 | 31,148 | 0 |
+| `tiger_1.lod1.glb` | 426,376 | 0 | 0 | 23 | 0 | 23 | 6,592 | 7,212 | 0 |
+| `tiger_1.lod2.glb` | 36,012 | 0 | 0 | 3 | 0 | 3 | 584 | 384 | 0 |
+| `--animations` lod0 | 2,226,572 | 0 | 0 | 23 | 0 | 23 | 37,749 | 31,148 | 1 (`run`, 20 rotation channels, LINEAR, 0–2 s) |
+| `--animations` lod1 | 443,576 | 0 | 0 | 23 | 0 | 23 | 6,592 | 7,212 | 1 |
+| `--animations` lod2 | 36,012 | 0 | 0 | 3 | 0 | 3 | 584 | 384 | 0 (no motion pivots left) |
+
+All infos have the same form:
+
+```json
+{ "code": "UNUSED_OBJECT", "severity": 2, "pointer": "/meshes/N/primitives/0/attributes/TEXCOORD_0" }
+```
+
+Findings from the inspection script, which the validator does not check:
+
+| Check | LOD0 result | Rule |
+|---|---|---|
+| u32 indices on primitives with fewer than 65k verts | 23/23 | S1 |
+| Byte split: POSITION / TEXCOORD_0 / COLOR_0 / indices (NORMAL ≈ POSITION) | 453 K / 302 K / **604 K** / 374 K | S1, S2 |
+| Degenerate triangles | 0 | (`ACCESSOR_INDEX_TRIANGLE_DEGENERATE`) |
+| Non-unit normals (more than 5e-4 off) | 0 | M8 |
+| COLOR_0 range | 0.0092–1.0, alpha always 1 | M11, S2 |
+| Root rotation | `[-0.7071, 0, 0, 0.7071]`: authoring +X goes to glTF +X (left) | M10 |
+| Node names, LOD0 / LOD2 | 24 / 4 (all wheels gone at LOD2) | M12 |
+| Spin loop seam (`rps 0.8`) | key 0 `[0,0,0,1]`, key 24 `[0,-0.951,0,0.309]` | M14 |
+| Animation time accessors | 20 identical | S8 |
+| `extensionsUsed` | none (core-only, which is good for Godot) | — |
+
+Re-run: write the two `.mjs` scripts below into a scratch directory with `npm i gltf-validator`, then run `node validate.mjs out/*.glb`. `gltf-validator` is now a devDependency used by `src/export/validator.test.ts`; ADR 005 restricts runtime dependencies only.
+
+---
+
+## (c) Per-engine import table
+
+"glTF" below means the engine's default glTF importer, as of 2026-10.
+
+| | **Unity (glTFast 6.x)** | **Unreal 5 (Interchange glTF)** | **Godot 4** | **three.js (GLTFLoader)** | **Babylon.js** |
+|---|---|---|---|---|---|
+| Importer | glTFast is Unity's glTF package. Unity has no built-in glTF importer ([glTFast manual](https://docs.unity3d.com/Packages/com.unity.cloud.gltfast@6.14/manual/index.html)) | Interchange is the default for glTF static meshes ([format support](https://dev.epicgames.com/documentation/en-us/unreal-engine/gltf-file-format-support-in-unreal-engine)) | Built-in `GLTFDocument` | `examples/jsm` loader | `@babylonjs/loaders` |
+| Naming | Node names become GameObject names. Mesh name becomes the asset name | Mesh name becomes the Static Mesh asset name. Interchange has renamed collision meshes in the past ([UE-248981](https://issues.unrealengine.com/issue/UE-248981), fixed May 2025) | Node names are kept. Suffix hints are stripped and acted on (`-col`, `-noimp`, …), with `-`, `$` or `_` and case-insensitive ([docs](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.html)) | `Object3D.name` = node name (sanitised) | `TransformNode.name` = node name |
+| Collision | None imported. Add colliders in-engine | Prefixes `UBX_` box, `UCP_` capsule, `USP_` sphere, `UCX_` convex, matched to the unprefixed mesh name (`UCX_body`, `UCX_body_01`) ([Interchange Generic Mesh Pipeline](https://api.unrealengine.com/INT/PythonAPI/class/InterchangeGenericMeshPipeline.html), [FBX pipeline](https://dev.epicgames.com/documentation/en-us/unreal-engine/fbx-static-mesh-pipeline-in-unreal-engine)). **glTF path unverified:** test-import a fixture | `-col` adds a trimesh body, `-convcol` a convex one; `-colonly` and `-convcolonly` replace the mesh with a collider; `-rigid` makes a RigidBody3D. `OMI_physics_body`/`OMI_physics_shape` are the import extensions it declares. `KHR_physics_rigid_bodies` / `KHR_collision_shapes` appear only in its JSON-pointer mapping so far ([physics ext source](https://github.com/godotengine/godot/blob/master/modules/gltf/extensions/physics/gltf_document_extension_physics.cpp)) | None | None (no physics import) |
+| LOD | MSFT_lod is listed "not investigated", so only LOD0 loads ([features](https://github.com/Unity-Technologies/com.unity.cloud.gltfast/blob/main/Packages/com.unity.cloud.gltfast/Documentation~/features.md)). Unity's `_LOD0` naming applies to the model importer (FBX), not glTFast ([manual](https://docs.unity3d.com/Manual/importing-lod-meshes.html)) | No glTF LOD import found. Import LOD1/2 files into LOD slots, or auto-generate them | Ignores MSFT_lod (not in the supported set). Generates its own LODs on import ("Generate LODs", [import configuration](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/import_configuration.html)). Use [visibility ranges](https://docs.godotengine.org/en/stable/tutorials/3d/visibility_ranges.html) for hand LODs | MSFT_lod not supported ([GLTFLoader docs](https://threejs.org/docs/pages/GLTFLoader.html)). Build `THREE.LOD` from the per-LOD files | **MSFT_lod supported** with progressive loading and `maxLODsToLoad` ([source](https://github.com/BabylonJS/Babylon.js/blob/master/packages/dev/loaders/src/glTF/2.0/Extensions/MSFT_lod.pure.ts)) |
+| Animation | Legacy Animation ✅, Mecanim partial (clips not assigned), Playables ⛔ ([features](https://github.com/Unity-Technologies/com.unity.cloud.gltfast/blob/main/Packages/com.unity.cloud.gltfast/Documentation~/features.md)) | Imports node animation as Level Sequence or anim assets (verify on fixture) | AnimationPlayer. A clip loops only if its name starts or ends with `loop`/`cycle` ([source](https://github.com/godotengine/godot/blob/master/modules/gltf/gltf_document.cpp)) | `gltf.animations` holds `AnimationClip`s; no autoplay | Autoplays the **first** clip by default (`animationStartMode = FIRST`) |
+| Quantization / meshopt / Draco | ✅ / ✅ (needs package) / ✅ (needs package) | Exporter supports quantization; import support for the three is undocumented | ⛔ / ⛔ / ⛔: the file **fails to import** if they are required | ✅ / ✅ (`setMeshoptDecoder`; `KHR_meshopt_compression` also built in) / ✅ (`setDRACOLoader`) | ✅ / ✅ / ✅ |
+| KTX2 basisu | ✅ (KTX package) | Undocumented | ✅ (`gltf_document_extension_texture_ktx`) | ✅ (`setKTX2Loader`) | ✅ |
+| GPU instancing | ✅ (no custom `_ID` attrs) | Undocumented | ⛔ (not in supported set) | ✅ (`InstancedMesh`) | ✅ |
+| Emissive strength | ⛔ (blank in features table) | Undocumented | ✅ | ✅ | ✅ |
+| `extras` | Kept in the glTFast API; not on components | Interchange metadata (verify) | `GLTFNode` metadata (opt-in) | `userData` | `metadata` (`ExtrasAsMetadata`) |
+
+**Consequence:** the default GLB uses core glTF only. A `web` profile adds compression and instancing. An engine profile adds collision naming. Where this table says Unreal is "undocumented" or "verify", import a test file before relying on the behaviour.
+
+---
+
+## Topics 3–7: rules
+
+### 3. Optimisation extensions: when to use
+
+| Extension | Use when | Don't use when | Registry status |
+|---|---|---|---|
+| `KHR_mesh_quantization` | Web/Unity/Babylon profile. Positions as int16 with a node scale/offset dequantisation, normals as int8 normalised (stride 4) | Default export (Godot refuses it because it must be required) | Complete, Ratified ([spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_mesh_quantization)) |
+| `EXT_meshopt_compression` | Web profile. Pair with quantization. Decoding is fast, it compresses animation (quaternion filter 2) too, and a `fallback` buffer can keep it optional | Godot targets (unless a fallback buffer is shipped, which doubles the size) | Complete, Ratified ([spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression)). `KHR_meshopt_compression` is the RC successor with a v1 bitstream and colour filter ([spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_meshopt_compression)) |
+| `KHR_draco_mesh_compression` | Only when a target lacks meshopt. Geometry only, slower decode, must be required without a fallback | Prefer meshopt for everything we ship ([meshoptimizer gltfpack](https://github.com/zeux/meshoptimizer/blob/master/gltf/README.md)) | Ratified |
+| `KHR_texture_basisu` | When the trim sheet ships. UASTC for normal and ORM, ETC1S for base colour ([KTX Artist Guide](https://github.com/KhronosGroup/3D-Formats-Guidelines/blob/main/KTXArtistGuide.md)). Keep a PNG `source` fallback so it stays optional | Required without a fallback in the default profile | Ratified ([spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_texture_basisu)) |
+| `KHR_texture_transform` | Only if strips get tiled by material instead of UVs | Our trim sheet bakes the UV rect into `TEXCOORD_0`, so it is not needed | Ratified |
+| `EXT_mesh_gpu_instancing` | Bolts, rivets, track links, fence posts: ≥ ~16 copies of one sub-mesh in a web/Unity profile | Default (no fallback, so it should be required; Godot lacks it) | Complete, Ratified ([spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_mesh_gpu_instancing)) |
+| `MSFT_lod` + `extras.MSFT_screencoverage` | Ship a single-file LOD set: extension on the LOD0 root node, `ids` → LOD1/LOD2 roots, coverage like `[0.25, 0.08, 0.01]`. It can live in `extensionsUsed` only, because non-supporting loaders load the highest LOD | — (safe additive; costs about 20 % more bytes) | Vendor ([spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/MSFT_lod)) |
+
+### 4. Materials
+
+| Rule | Source | Us |
+|---|---|---|
+| ORM packing: one linear texture, R = occlusion (`occlusionTexture`), G = roughness, B = metallic (`metallicRoughnessTexture`), both pointing at the same texture | [spec §additional-textures-occlusion](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#additional-textures-occlusion) note: "could point to the same texture that packs all three" | Planned ORM in ADR 003. Bind both slots to one texture index |
+| baseColor and emissive textures are sRGB; ORM and normal are linear | [spec §metallic-roughness-material](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#metallic-roughness-material) | Painter must write the albedo as sRGB and the ORM as linear |
+| `COLOR_0` is linear and multiplies baseColor (texture × factor × COLOR_0) | same | done |
+| Foliage cards: `alphaMode: "MASK"`, `alphaCutoff` (default 0.5), `doubleSided: true` | [spec §alpha-coverage](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#alpha-coverage), [§double-sided](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#double-sided) | **done**: `surface: 'cutout'` ([ADR 008](../decisions/008-surface-materials.md)) |
+| Tangents: omit them and let the importer run MikkTSpace (the spec default) unless a baked normal map needs bit-exact tangents. Our tiling trim normals don't | [spec §meshes-usage](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#meshes-usage) | correct today |
+| Lit windows: `emissiveFactor` up to 1 plus `KHR_materials_emissive_strength`. Unity glTFast ignores the extension and falls back to strength 1 | [spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_emissive_strength) | missing |
+
+### 5. Animation
+
+| Rule | Source |
+|---|---|
+| glTF defines no autoplay, loop or order. Loaders choose: Babylon and model-viewer play the first clip; three and Godot don't autoplay | [spec §animations](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#animations) |
+| LINEAR on `rotation` is slerp; keep consecutive keys under 180° apart (we use 15° steps or finer) | same, [§interpolation-slerp](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#interpolation-slerp) |
+| Loops: last key = first key, and the clip length is an integer number of periods for every channel | consequence of clamping (same section) |
+| One clip per behaviour, named `<verb>_loop` (Godot loop flag); keep pivot-driving clips out of the first slot | Godot source above |
+| Each (node, path) appears at most once per animation | [spec §animations](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#animations) |
+
+### 6. Collision and physics
+
+| Approach | Engines | Ship how |
+|---|---|---|
+| Godot suffix nodes `<pivot>-colonly` / `-convcolonly` | Godot | Engine profile `godot`; the collider node is a child of the pivot |
+| Unreal prefix meshes `UCX_<mesh>_NN`, `UBX_`, `USP_`, `UCP_` | Unreal (FBX documented; glTF via Interchange unverified) | Engine profile `unreal`; the collision mesh is a sibling, named after the render mesh |
+| `extras.ts23d.collision` on a hidden child node (box/convex hull data) | Unity, three, Babylon (scripts read it) | Default: no visible mesh. Shapes go in extras so nothing renders by accident |
+| `KHR_physics_rigid_bodies` + `KHR_implicit_shapes` | None import it yet (Godot imports the OMI equivalents) | Draft PRs [#2424](https://github.com/KhronosGroup/glTF/pull/2424) and [#2370](https://github.com/KhronosGroup/glTF/pull/2370), open as of 2026-10. Emit in `extensionsUsed` only, after ratification |
+
+A collider mesh in a generic GLB renders as visible geometry in Unity, three and Babylon. So collision geometry is never in the default visual file. It goes in extras, an engine profile, or a sibling `*.collision.glb`.
+
+### 7. Metadata
+
+| Field | Rule | Source |
+|---|---|---|
+| `asset.generator` | `"@developerz.ai/ts23d <version>"` | [spec §asset](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#asset) |
+| `asset.copyright` | From the recipe (`license`/`author`), else `"ts23d recipe <name>, MIT"` per repo license | same |
+| `asset.extras.ts23d` | `{ recipe, version, seed, lod, lodCount, units:"m", up:"+Y", front:"+Z", sourceUp:"+Z", sourceFront:"+X", contentHash }` | [spec §specifying-extensions](https://github.com/KhronosGroup/glTF/blob/main/specification/2.0/Specification.adoc#specifying-extensions) and the `extras` property (any JSON) |
+| LOD switch distances | `extras.MSFT_screencoverage` on the MSFT_lod node, plus `extras.ts23d.lodScreenCoverage` in each per-LOD file | [MSFT_lod](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/MSFT_lod) |
+| Rights | `KHR_xmp_json_ld` packet with `dc:creator`, `dc:rights`, `xmpRights:UsageTerms` (in `extensionsUsed` only) | [KHR_xmp_json_ld](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_xmp_json_ld) |
+
+Today the exporter writes `extras` at the glTF **root** (`kind, lod, units, up`), not in `asset.extras`. Root `extras` are legal, but many importers surface only node and `asset` extras.
+
+---
+
+## (d) Prioritised gap list
+
+`ZERO-DEP WIN` means pure gain: core glTF only, no new dependency, valid in every engine, byte-deterministic. Every test lives next to the file it tests and runs in `bun run verify`.
+
+| P | Gap | Exact change | Test that proves it | Tag |
+|---|---|---|---|---|
+| **G1** | Asset faces glTF +X (glTF's left) instead of +Z (M10) | `src/export/glb.ts` `toGlb`: root `rotation` changes from `[-Math.SQRT1_2,0,0,Math.SQRT1_2]` to `[-0.5,-0.5,-0.5,0.5]`, which maps authoring +X front to +Z, +Y left to +X and +Z up to +Y (checked numerically). Amend ADR 004's "one −90° X rotation" line, and set `extras.up/front`. Breaking for anyone who has already placed assets: CHANGELOG | `glb.test.ts`: rotate `[1,0,0]` by the root quaternion and expect `[0,0,1]`; rotate `[0,1,0]` and expect `[1,0,0]` | **done** · ZERO-DEP WIN (breaking) |
+| **G2** | Loop seam: spin ends at 1.6 rev (M14) | `src/export/motion.ts` `motionChannel`: replace the fixed `LOOP_SECONDS` with a clip length `D` passed from `toGlb`. Per channel, round cycles to `n = max(1, round(rate·D))` and sample `max(24, 8n)` keys so steps stay under 45°. Record the true rate in `extras.ts23d.motion`. `toGlb` picks `D` = the smallest of 2, 4 or 8 s that keeps every channel's rounding error under 10 % | `motion.test.ts` (new): for spin `rps 0.8`, the first and last output quaternions are equal up to sign (`|dot| > 0.9999`); same for sway and bob | **done** · ZERO-DEP WIN |
+| **G3** | Pivots vanish at LOD2 (M12) | `src/cli/run.ts`: collect the LOD0 pivot list (names, parent, `at`) and pass it as `GlbOptions.pivots`. `src/export/glb.ts` `toGlb` emits an empty node for each pivot missing from this LOD, under its LOD0 parent | `glb.test.ts`: an asset whose LOD2 build omits `wheel_0` still has node `wheel_0` in the LOD2 GLB, and its node-name set equals LOD0's | ZERO-DEP WIN |
+| **G4** | u32 indices everywhere (S1) | `src/export/bin-writer.ts` `BinWriter.accessor`: accept `Uint16Array` and set `componentType: 5123`. `toGlb` converts to `Uint16Array` when `positions.length/3 <= 65535`. `push` already 4-aligns the following view | `glb.test.ts`: the box crate's index accessor has `componentType === 5123`; a 70k-vertex mesh keeps 5125; scratch run of glTF-Validator stays 0/0 | **done** · ZERO-DEP WIN (−187 KB on tiger LOD0) |
+| **G5** | COLOR_0 float VEC4 is 27 % of the file (S2) | `bin-writer.ts`: `accessor` takes `Uint16Array` + `normalized: true` (componentType 5123, add `normalized`). `glb.ts` `toGlb` writes the colour as `Math.round(c·65535)` into VEC4 unorm16 (8 B/v, aligned) | `glb.test.ts`: the COLOR_0 accessor has `componentType 5123`, `normalized: true`, and the decoded value is within 1/65535 of the source | **done** · ZERO-DEP WIN (−302 KB on tiger LOD0) |
+| **G6** | No guard against Godot name hints (M13) | New gate `src/qa/` `engineNames` (tier 3; QA already sees all part names): fail on `/[-_$](col|colonly|convcol|convcolonly|noimp|occ|occonly|navmesh|vehicle|wheel|rigid)$/i`, with `fix: rename to <name>_part or opt in via exportHint`. Exporter-side mirror is optional | `qa/*.test.ts`: a part named `spare_wheel` makes `runQa` report `engine-names`; `wheel_l_0` passes | ZERO-DEP WIN |
+| **G7** | Clip named `run`: Godot won't loop it, and it is the first clip that viewers autoplay (S6) | `src/export/glb.ts` `toGlb`: name the clip `motion_loop` and set `extras.ts23d.loop: true` | `glb.test.ts`: `animations[0].name` matches `/loop$/` | ZERO-DEP WIN |
+| **G8** | No provenance or copyright (S5, section 7) | `glb.ts` `toGlb`: `asset.generator` with the package version (import from `package.json` at build or a `VERSION` const in core). Add `asset.copyright` and `asset.extras.ts23d = {recipe, version, seed, lod, lodCount, up, front, units}`. Move root `extras` into it, keeping the old root `extras` one minor release for compatibility | `glb.test.ts`: `asset.copyright` is a non-empty string; `asset.extras.ts23d.front === '+Z'`; determinism test still passes | ZERO-DEP WIN |
+| **G9** | Identical geometry not shared (S4) | `src/export/glb.ts` `toGlb`: hash each merged mesh (positions, normals, uvs, colors, indices bytes) and reuse the `meshes[]` index on a hit. Today only 4 wheel pairs match, because grime noise is seeded per part. Follow-up: let `kinds/vehicle.ts` seed grime per wheel class so all 16 road wheels share a few meshes | `glb.test.ts`: two `ctx.use` copies of the same sub-asset yield two nodes with the same `mesh` index | ZERO-DEP WIN |
+| **G10** | 20 duplicate animation time accessors (S8) | `motion.ts` `motionChannel`: take an `inputs: Map<string, number>` cache keyed by `(D, keyCount)` from `toGlb` | `glb.test.ts`: crate with two spinning parts has `new Set(samplers.map(s=>s.input)).size === 1` | **done** · ZERO-DEP WIN |
+| G11 | LODs are three files and engines get no switch distances (S12) | `src/cli/run.ts` + new `toGlbLodSet(compiled[])` in `src/export/glb.ts`. One GLB with LOD0 root `extensions.MSFT_lod.ids` → LOD1/LOD2 roots (named `<asset>_LOD1`, `_LOD2`, excluded from `scenes[0].nodes`) and `extras.MSFT_screencoverage` from a new `budget.screenCoverage` (default `[0.25, 0.08, 0.01]`). `extensionsUsed: ["MSFT_lod"]`, never required. Keep the per-LOD files | `glb.test.ts`: `extensionsUsed` has `MSFT_lod`; `extensionsRequired` is undefined; the `ids` length is 2; validator 0/0. Load it in Babylon in the apps gallery smoke test | ZERO-DEP WIN |
+| G12 | No collision export (S11) | `src/core/asset.ts`: `ctx.collider(name, {shape:'box'|'convex', of?: part})`. `src/export/glb.ts` gains `GlbOptions.engine: 'generic'|'godot'|'unreal'`. Generic writes `extras.ts23d.collision` on an empty child; godot writes a `<pivot>-convcolonly` mesh node; unreal writes a `UCX_<mesh>_01` sibling mesh. CLI `--engine` | `glb.test.ts` per profile: node and mesh names match the convention, and the generic profile has no extra mesh. Manual: import a fixture into Godot 4 and UE 5 and check that a collider appears | ZERO-DEP (needs an API addition) |
+| G13 | Single opaque material blocks foliage cutouts and lit windows (section 4) | `src/material`: add part flags `surface: 'cutout'|'emissive'`. `glb.ts` `toGlb` writes up to three materials: `ts23d_trim`; `ts23d_trim_cutout` (`alphaMode:"MASK"`, `alphaCutoff:0.5`, `doubleSided:true`); `ts23d_trim_emissive` (`emissiveFactor`, `KHR_materials_emissive_strength` in `extensionsUsed` only). `mergeToPivots` splits primitives per material. Needs an ADR 003 amendment ("exactly one material") | `glb.test.ts`: a cutout part lands in a primitive whose material has `alphaMode MASK`; with no flagged parts the GLB still has exactly 1 material | **partial**: cutout, glass, translucent shipped as `surface`; emissive missing · ZERO-DEP (ADR change) |
+| G14 | Web profile size (N1, N2) | New optional subpath `src/export/web/` (ADR 005 "behind an optional subpath"): quantize positions (int16 plus a node dequant transform), normals (int8, stride 4) and UVs (unorm16); meshopt encode (own port of the codec or the `meshoptimizer` npm package as an optional peer); `EXT_mesh_gpu_instancing` for repeated sub-parts. All of these go in `extensionsRequired`, so never for Godot | Snapshot: `--profile web` tiger LOD0 is under 40 % of default bytes; validator 0/0; three.js gallery loads it with `setMeshoptDecoder` | **runtime dep (optional)** |
+| G15 | Textures (N3) | With the M2 painter: PNG baseColor (sRGB) + ORM + normal, plus an optional KTX2 profile (UASTC for ORM/normal, ETC1S for albedo) with a PNG fallback `source` | Validator 0/0 with `hasTextures: true` and no `UNUSED_OBJECT` on TEXCOORD_0 | **done** (PNG, embedded or external; KTX2 profile still missing) · dep for KTX2 (optional) |
+| G16 | Physics extensions (N6) | Wait for #2424/#2370 to ratify. Then emit from the G12 collider data in `extensionsUsed` only | Godot import test | wait |
+
+**Combined size effect of G4 + G5 on tiger LOD0:** 2,209 KB drops to about 1,720 KB (−22 %) with no extension, no dependency and no engine risk. G9 and G10 add a little more.
+
+### Inspection scripts (for reproducibility; not in the repo)
+
+`validate.mjs`: `validateBytes(bytes, { maxIssues: 0 })` from `gltf-validator@2.0.0-dev.3.10`, printing `numErrors/numWarnings/numInfos/numHints`, `info`, and issue counts by code. `inspect.mjs` parses the GLB and reports index component type against vertex count, per-attribute byte totals, normal length, COLOR_0 range, duplicate geometry signatures, root rotation, node names, and animation sampler input sharing and first/last keys.

package/docs/architecture/gltf-capabilities.md

@@ -0,0 +1,80 @@
+# What a GLB can carry, and what ts23d writes
+
+**glTF 2.0 / GLB stays the output format.** It is open and royalty-free, one compact binary file, and
+first-class in Godot, three.js and Babylon, imported by Unreal (Interchange) and Unity (glTFast). FBX is
+proprietary (Autodesk SDK) and inconsistent across versions; USD/USDZ is built for film-style scene
+composition and Apple AR (a later USDZ export is possible); OBJ/STL carry no hierarchy, motion or
+materials. This page maps the whole glTF surface onto the DSL: shipped, next, later, never.
+
+Status legend: **shipped** = on `main` with a test · **next** = the current roadmap slice ·
+**later** = wanted, unscheduled · **no** = out of scope, with the reason.
+
+## Core glTF 2.0
+
+| Capability | glTF | ts23d | Status |
+|---|---|---|---|
+| Named node hierarchy, pivots | `nodes` | `ctx.part` / `ctx.group`, parent + pivot | shipped |
+| Static batching | one mesh per pivot | `mergeToPivots` | shipped |
+| Vertex colour albedo | `COLOR_0` (u16 normalised) | every primitive's `color` | shipped |
+| PBR metal/rough + normal + ORM | `pbrMetallicRoughness`, `normalTexture`, `occlusionTexture` | procedural trim sheet | shipped |
+| Alpha modes | `OPAQUE` / `MASK` / `BLEND` | surfaces opaque / cutout / glass / translucent | shipped |
+| Node animation (TRS) | `animations` | `spin`, `slide`, `sway` → `rest` + `run` clips | shipped |
+| Sockets, emitters | `extras` on empty nodes | `ctx.socket`, `ctx.emitter` | shipped |
+| Skins (bones) | `skins`, `JOINTS_0` / `WEIGHTS_0`, `inverseBindMatrices` | `ctx.bone` + skinned sculpt (below) | later |
+| Morph targets | `targets` + `weights` | face shapes: blink, jaw open, snarl | later |
+| Cameras | `cameras` | preview / hero camera per asset | later |
+
+### Skins: how ts23d will rig without auto-rigging
+Heat-diffusion auto-rigging (Pinocchio, Baran & Popović 2007; Blender "bone heat"; Maya heat map) guesses
+which bone owns which vertex, and fails on messy meshes. ts23d knows. A sculpted character is an ordered
+list of SDF edits (Dreams' model: Evans, SIGGRAPH 2015). Tag each edit with its bone, and the per-vertex
+smooth-min blend weights that already mix the edits' colours *are* the skin weights. Keep the strongest
+4 per vertex (`JOINTS_0`/`WEIGHTS_0`; Unreal's Interchange importer truncates to 4) and renormalise.
+`skin.joints` order must match `inverseBindMatrices`; that ordering is the classic broken-skin bug, so
+a test pins it. Rigid parts (`ctx.part`) stay node-animated: a tank has no skin.
+
+## Ratified extensions worth writing
+
+| Extension | Use in ts23d | Status |
+|---|---|---|
+| `KHR_materials_emissive_strength` | lit windows, lamps, sci-fi panel glow | shipped |
+| `KHR_lights_punctual` | headlamps, street lamps, cockpit lights as light nodes | shipped |
+| `KHR_materials_variants` | liveries / camo schemes as switchable sets in one file | later: variants swap materials, and ts23d colour is vertex colour, so a livery needs a per-asset baked albedo first |
+| `KHR_xmp_json_ld` | licence, author, generator version, `sources` inside the file | shipped |
+| `KHR_materials_clearcoat` | glossy vehicle paint over the base | later |
+| `KHR_materials_transmission` + `ior` + `volume` | real glass (bottles, cockpit canopies) | later |
+| `KHR_materials_sheen` | cloth, banners, upholstery | later |
+| `KHR_texture_transform` | strip offset / scale without re-baking UVs | later |
+| `EXT_mesh_gpu_instancing` | rivets, bolts, scatter trees: one mesh, N transforms | later |
+| `KHR_mesh_quantization` + `EXT_meshopt_compression` | `web` profile (smaller files) | later (opt-in: Godot rejects *required* extensions) |
+| `MSFT_lod` | three LODs in one file with screen-coverage hints | later |
+| `KHR_animation_pointer` | animate material / light values (blinking lamp, heat glow) | later |
+| `KHR_texture_basisu` | KTX2 GPU-compressed trim sheet | later |
+| `KHR_draco_mesh_compression` | — | no: meshopt is faster to decode and preferred |
+| `KHR_gaussian_splatting` | — | no: we generate meshes, not captures |
+| `KHR_interactivity` | — | no: behaviour is engine code, out of scope |
+
+## Physics (drafts: write behind a flag, plus engine conventions)
+
+`KHR_physics_rigid_bodies` and `KHR_collision_shapes` (formerly `KHR_implicit_shapes`) are **Khronos
+review drafts**, with importers in Blender, Godot and Babylon. ts23d will write:
+- **Collision shapes** per part: box / sphere / capsule / cylinder fitted from the part's own geometry,
+  or a convex hull. Also as engine-convention nodes for importers without the extension:
+  `UCX_<name>` (Unreal) and `<name>-col` / `-colonly` (Godot).
+- **Mass and centre of mass** from real volume × material density (steel 7850 kg/m³, oak 750,
+  brick 1900). A 57 t Tiger I is a QA check, not a guess: `real.mass` + tolerance.
+- **Physics material**: friction / restitution per surface kind.
+Status: later, behind `--physics`.
+
+## Everything else: `extras`
+Any JSON fits in `extras` on any object. ts23d uses `extras.ts23d` for sockets, emitters, the
+generator version and provenance. Engines read it on import (Godot `meta`, Unity glTFast extras
+callbacks, three.js `userData`).
+
+## Sources
+- Khronos extension registry: https://github.com/KhronosGroup/glTF/blob/main/extensions/README.md
+- Skins tutorial: https://github.khronos.org/glTF-Tutorials/gltfTutorial/gltfTutorial_020_Skins.html
+- Unreal Interchange 4-influence truncation: https://forums.unrealengine.com/t/interchange-gltf-importer-truncates-skeletal-mesh-bone-influences-to-4-per-vertex/2745391
+- glTF physics drafts: https://github.com/eoineoineoin/glTF_Physics
+- Automatic rigging: Baran & Popović, "Automatic Rigging and Animation of 3D Characters", SIGGRAPH 2007
+- Dreams SDF sculpting: Alex Evans, SIGGRAPH 2015, https://advances.realtimerendering.com/s2015/AlexEvans_SIGGRAPH-2015-sml.pdf

package/docs/decisions/001-recipe-compiler-over-ai-meshes.md

@@ -0,0 +1,27 @@
+# 001 — Assets are compiled from recipes, not generated by AI mesh models
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+The pipeline this project is inspired by started on AI mesh generation (Meshy plus an image model) and froze it. Measured pains:
+- Credits per attempt; iteration multiplies cost.
+- No reproducibility: same prompt, different mesh. Nothing to diff, nothing to regenerate in CI.
+- One fused mesh: no named parts, no pivots, so nothing animates without manual work.
+- A texture per asset: a draw call per asset, inconsistent texel density.
+- Every mesh needed repair: scale, pivots, holes, topology.
+It replaced generation with a recipe compiler, and those problems went away for hard-surface assets.
+
+## Decision
+The core path is a deterministic compiler: recipe source → mesh IR → GLB. AI enters as the **author** of the recipe (a coding agent), not as the mesh generator. Mesh-generating models are an optional, cached adapter for what recipes do badly ([idea/08](../idea/08-neural-adapters.md)).
+
+## Alternatives considered
+- **AI mesh generation as the core** — why not: the five pains above; outputs aren't reproducible or partitioned into named parts.
+- **Procedural modelling in a DCC (Blender geometry nodes, Houdini)** — why not: a heavy external runtime, node graphs agents edit poorly, and no plain-text diff.
+- **Kitbashing from asset libraries** — why not: licence per asset, mismatched styles and texel density.
+
+## Consequences
+- Easier: free iteration, reproducible builds, named animatable parts, one material, CI gates.
+- Harder: organic and sculpted forms (people, animals) are a weak spot. Answered by the planned `creature` kind and `/neural` adapter.
+- Revisit when: an open-weight model outputs part-segmented, reproducible, low-poly meshes with consistent UVs on CPU.

package/docs/decisions/002-typescript-not-json.md

@@ -0,0 +1,22 @@
+# 002 — Recipes are TypeScript modules, not JSON
+
+Status: accepted
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+The predecessor pipeline used JSON recipes. They worked, then grew: repeat syntax for windows, `$ref` for shared wheels, variant tables for streets, an expression mini-language for derived sizes. Each was a worse copy of a programming-language feature, with no type checker, no editor support and a schema the agent had to learn. The authors are coding agents, and TypeScript is what they write most fluently.
+
+## Decision
+An asset is a TypeScript module exporting `defineAsset({ …, build(ctx) })`. Loops, functions, imports and types are the composition model. String mini-languages (split grammar, Whyte notation) stay as small, parsed helpers called *from* TS, where the domain notation is better than code.
+
+## Alternatives considered
+- **JSON / YAML recipes** — why not: every growth step re-invents loops, references and expressions, untyped.
+- **A custom DSL with its own parser** — why not: an agent has never seen it; we'd own a language, tooling and error messages.
+- **Python** — why not: a second runtime next to a TS/Bun toolchain and a browser gallery; recipes must also run in the browser.
+- **Lua / sandboxed scripting** — why not: weaker typing and agent fluency, an extra interpreter.
+
+## Consequences
+- Easier: composition (`ctx.use`), shared helpers, typed options with docs on hover, the same module runs in the CLI, tests and the browser gallery.
+- Harder: a recipe is code, so it can do anything code can, including breaking determinism. Mitigated by the determinism rules and a sealed `Math.random` in tests. Running untrusted recipes means running untrusted code ([SECURITY.md](../../SECURITY.md)).
+- Revisit when: recipes must be authored by non-programmers in a GUI. Then emit TS from the GUI; don't add a data format.

package/docs/decisions/003-shared-trim-sheet.md

@@ -0,0 +1,21 @@
+# 003 — Every asset shares one trim-sheet material
+
+Status: superseded by 008
+Date: 2026-10-25
+Supersedes: —
+
+## Context
+Per-asset textures meant a material and a draw call per asset, texel density that varied by asset size, and a new texture for every recolour. Game scenes with hundreds of props pay for that in draw calls and memory.
+
+## Decision
+One 1024² trim sheet (albedo + normal + ORM) holds tiling strips and fixed decal cells. Every primitive maps UVs into it by world size (metres per rect). Hue comes from linear vertex colour multiplied over the greyscale sheet. Every GLB carries exactly one material, `ts23d_trim`. As of 2026-10 the material has no texture bound; the painter is M2.
+
+## Alternatives considered
+- **Per-asset unwrapped textures** — why not: a draw call per asset, uneven texel density, needs a painter per asset.
+- **Flat colour only, no textures** — why not: caps visual quality; no brick, grain or rivet detail.
+- **Texture arrays / bindless per asset** — why not: engine-specific, defeats "drop the GLB into any engine".
+
+## Consequences
+- Easier: a whole scene batches into one material; palette swaps are recipe edits; equal texel density everywhere.
+- Harder: unique details (a specific logo, a painted mural) must fit a cell; a hero asset can't have its own unwrap.
+- Revisit when: a target engine needs per-asset PBR for hero assets. Then add a second, opt-in path; keep the trim sheet the default.

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.