@developerz.ai/ts23d 0.0.0-stage → 0.2.0

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,117 @@
+# 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` (vendor, complete) | three LODs in one file with screen-coverage hints: `<asset>.glb`, `toLodGlb` | shipped (below) |
+| `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 |
+
+## LODs in one file: `MSFT_lod`
+
+`t3d build` writes `lod0/1/2.glb` **and** `<asset>.glb` holding all three (`--lods split|single|both`,
+default `both`). Default is `both` because separate files import into every engine's LOD tooling
+today, while the single file serves MSFT_lod-aware loaders and one-file pipelines; disk is the only cost.
+
+Layout (per the [spec](https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/MSFT_lod)):
+- LOD0's root node is the only scene root. It carries `extensions.MSFT_lod.ids` = the LOD1, LOD2 root
+  nodes (lower quality in order) and `extras.MSFT_screencoverage` = one value per LOD: the screen-height
+  fraction where that LOD hands over to the next, the last one being the cull (`[0.43, 0.086, 0.01]`
+  for tiger_1: LOD0 above 43 %, LOD1 to 8.6 %, LOD2 to 1 %, then nothing). Same convention as Unity
+  LODGroup's screen-relative transition height.
+- LOD1/LOD2 roots (`<asset>_LOD1`, `<asset>_LOD2`) are parentless and **not** in `scenes[0].nodes`: the
+  spec says a client without the extension loads the highest LOD and ignores the rest, which only
+  holds if the alternates are outside the scene graph. Part names inside each LOD are unchanged
+  (`turret`, `wheel_l_0`), so game code binds the same names at any LOD.
+- `MSFT_lod` is in `extensionsUsed`, never `extensionsRequired` (Godot refuses unknown required
+  extensions). Materials, the trim sheet, lights and identical motion samplers are written once; the
+  `rest` and `run` clips hold one channel per LOD node.
+- Thresholds: `lodCoverage: [a, b, cull]` on `defineAsset`, else derived: a LOD with r × the
+  triangles reads equally dense at √r × the screen size (a ∈ [0.1, 0.6], b ∈ [0.02, a/2]); cull 1 %
+  for props, 0.2 % for anything ≥ 10 m so landmarks stay on the skyline.
+
+| Loader | Reads MSFT_lod? | What a single file shows | Verified how |
+|---|---|---|---|
+| Babylon.js | yes, node + material level (progressive: loads low LODs first, ends on LOD0) | all LODs, switching | Babylon docs / spec "Known Implementations" |
+| three.js `GLTFLoader` | no (community plugin `three-gltf-extensions`, in progress) | LOD0 only; the mixer warns "No target node found" for the alternates' tracks (harmless) | loaded tiger_1.glb with three 0.186: 23 meshes, same bounds as lod0.glb |
+| Godot 4.5+ | no (not in `GLTFDocument` supported list) | LOD0 only (scene roots only, `gltf/naming_version` 2 default) | Godot master `gltf_document.cpp` |
+| Godot 4.0–4.4 (or naming_version < 2) | no | **all three overlapping**: treats every parentless node as a root. Use `lod0.glb` there | same source, `_compute_node_heights` |
+| Unity glTFast | "not investigated yet" in its docs | expected LOD0 only (instantiates the scene) — unverified | glTFast 6.0 features page |
+| Unreal Interchange | not documented | unverified; use `lod0/1/2.glb` and Unreal's LOD import | — |
+| Khronos glTF-Validator | info `UNSUPPORTED_EXTENSION` | 0 errors, 0 warnings (test `src/export/lod-glb.test.ts`) | test |
+| ArcGIS Pro | yes, node level on the scene's first node | all LODs | Esri docs |
+
+Engines that build LOD groups from names (Unity's FBX `_LOD0/_LOD1` convention) don't apply it to glTF
+imports, so the split files plus each engine's own LOD importer remain the portable path.
+
+## 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/architecture/materials.md

@@ -0,0 +1,151 @@
+# Materials: one trim sheet, many physically distinct surfaces
+
+Every asset is still **one material, one draw call**: a shared atlas with albedo, normal and ORM
+(occlusion, roughness, metalness). A surface looks like oak, rusty iron or chrome because of what
+its **strip** holds. Vertex colour multiplies the albedo: it tints a classic strip and sets the paint
+colour of a painted strip.
+
+## Layout (v2): 2048² atlas
+
+| V range | Contents |
+|---|---|
+| 0 – 0.25 | 8 **classic** strips: `plain brick stone slate iron wood glass concrete`. Greyscale, tinted by vertex colour, unchanged from v1. |
+| 0.25 – 0.75 | 16 **library** strips with their own colour (`MATERIAL_LIBRARY`, below) |
+| 0.75 – 0.875 | 4 **custom** rows for project materials (`defineMaterial`) |
+| 0.875 – 1 | 128 px cells: decals (row 0), foliage cards (from slot 8) |
+
+Each strip row is 1/32 of the sheet: 64 px at 2048², the same V resolution v1 strips had at 1024².
+The U density doubles, and cells keep their 128 px. That is why the house sheet moved to 2048².
+
+**Cost.** Painting takes about 4 s at 2048² (about 1 s at 1024²). The three PNGs total about 3.6 MB at 2048² (v1 at 1024² was about 1 MB).
+GPU memory is 16 MB per map plus mips. The site's trim-sheet set is shared by every gallery asset.
+`--sheet-size 1024` still works (32 px strip rows). The CLI default is 1024 until `src/cli/args.ts`
+moves it to 2048.
+
+**Compatibility.** UVs come from `stripRect()`/`cellRect()` at compile time, so geometry and triangle
+counts are unchanged and every recipe recompiles onto the new layout. Classic strips paint byte for
+byte as before; only their atlas position moved.
+
+## The library and its numbers
+
+Metal colours are the measured reflectance (F0) from [physicallybased.info](https://physicallybased.info)
+(API: `api.physicallybased.info/materials`, which cites refractiveindex.info). Each value is
+converted to sRGB here. Dielectric albedos stay inside the 30–240 sRGB range from the
+[PBR guide](https://www.adobe.com/learn/substance-3d-designer/web/the-pbr-guide-part-2). Roughness
+ranges come from the [Roblox material reference](https://create.roblox.com/docs/art/modeling/material-reference),
+which uses glTF metal/rough conventions.
+
+| Strip | Kind | Albedo (sRGB) / 2nd | Rough | Metal | Basis |
+|---|---|---|---|---|---|
+| `oak` | planks + rings + ray flecks | `#a27b52` / latewood `#6a482b` | 0.68 | 0 | worn wood 0.7–0.9, glossy 0.2–0.3 (Roblox) |
+| `pine` | planks + strong rings, knots | `#d2b183` / `#9b6a3c` | 0.72 | 0 | same |
+| `wood_weathered` | planks + checks (eroded grain, splits) | `#9b968c` / `#4f463c` | 0.86 | 0 | worn wood upper range |
+| `wood_painted` | planks + paint film + chips | paint `#ededed` (×vertex colour) / bare wood `#a08c74` | wood 0.84, film 0.62 | 0 | painted surfaces are dielectric |
+| `iron_rust` | metal + oxide + streaks | iron `#8e8a85` / rust `#764323` | 0.55 → rust ≈ 0.9 | 0.9 → 0 in rust | Iron F0 0.53 linear; Rust (0.181, 0.057, 0.017) linear, non-metal (physicallybased) |
+| `iron_cast` | metal, sand-cast pits, oxide | `#6c6966` / `#55372a` | 0.68 | 0.75 | darker weathered iron skin |
+| `steel_painted` | metal + paint film + chips | paint `#eeeeee` (×vertex colour) / rusty steel `#5a3b2a` | film 0.42 | 0 film, 1 under | painted metal 0.3 (Roblox) |
+| `steel_galvanised` | metal + zinc spangle | `#d5dadc` / white rust `#9a9c98` | 0.42 | 1 | Zinc (0.808, 0.844, 0.865) linear |
+| `brass` | metal, light brush, tarnish | `#f5e5ae` / `#6b5a3a` | 0.28 | 1 | Brass (0.910, 0.778, 0.423) linear; pure metals 0.2–0.3 |
+| `copper` | metal + verdigris | `#f2b89c` / `#6fa58f` | 0.32 | 1 | Copper (0.932, 0.623, 0.522) linear, nudged warmer to match photographs |
+| `aluminium` | metal, brushed along U | `#e6e8e9` | 0.34 | 1 | Aluminium (0.916, 0.923, 0.924) linear, brushed is a little darker |
+| `chrome` | metal, near mirror | `#d3d9dc` | 0.07 | 1 | Chromium (0.654, 0.685, 0.701) linear |
+| `rubber` | noise | `#2c2c2c` | 0.78 | 0 | Tire 0.023 linear, roughness 0.7 (physicallybased); rubber 0.5–0.6 (Roblox) |
+| `canvas` | weave + folds + stains | `#cbbea2` / `#8a7c62` | 0.88 | 0 | cotton/canvas 0.8–0.9 |
+| `leather` | pebble grain + creases + wear | `#7c5438` / `#3e281a` | 0.58 | 0 | worn leather 0.5–0.7 |
+| `plastic` | quiet noise | `#ececec` (×vertex colour) | 0.35 | 0 | matte plastic 0.4, glossy 0.1 |
+
+Unverified: the wood albedos are chosen within the dielectric range and checked against photographs
+by eye. They are not spectrometer data, because no published wood-species albedo table was found.
+Emissive panels have no strip: glTF emission is a separate per-material slot, not ORM. Glowing parts
+use `glow` rules in export.
+
+**How to colour library strips.** Use `NATURAL` (white) as the vertex colour on library strips, so
+the measured albedo reads true. On painted strips (`wood_painted`, `steel_painted`, `plastic`) the
+vertex colour is the paint colour. Chips multiply the bare surface by it too, so they read as
+darker, rougher wear.
+
+## Painters (src/material/paint/)
+
+Every painter writes float layers in real metres: `height`, `tone`, `rough`, `metal`, `mix` (blend
+from albedo to albedo2) and `occl`. `compose` then derives the normal (Sobel of height) and the
+cavity AO, and packs the result. These painters are new or extended in v2:
+
+- `planks`: `rings` (latewood colour at a frequency the strip's V texels can hold), `rays`, `checks`, `paint`/`chips`/`paintRough`.
+- `metal`: `brush`, `cast`, `spangle`, `oxide`, `paint`/`chips`, `streaks`.
+- `weave`, `leather` (fabric.ts).
+
+All painters are seeded and tileable along U, so the output is deterministic.
+
+## Project materials: `defineMaterial`
+
+```ts
+import { defineMaterial, NATURAL, box } from '@developerz.ai/ts23d';
+
+export const teak = defineMaterial({
+  id: 'teak_deck',
+  kind: 'planks',              // start from any painter kind
+  scaleMetres: 0.6,
+  roughness: 0.6,
+  albedo: '#8a5a32',           // sRGB hex or linear RGB
+  albedo2: '#5a3a1e',          // latewood
+  params: { width: 0.12, rings: 0.5, knots: 0.5 },
+  // optional: your own layer on top, deterministic via kit.noise / kit.hash
+  paint: (s, kit) => kit.each((i, xm, ym) => {
+    s.tone[i] *= 1 - 0.1 * kit.smooth(0.4, 0.8, kit.noise(xm, ym, 0.5, 0.05, 1));
+  }),
+  sources: ['https://…'],
+});
+
+box({ size: [4, 2, 0.05], strip: teak, color: NATURAL });
+```
+
+- It validates first: bad input throws `T3D_MATERIAL_INVALID`, an unknown id `T3D_MATERIAL_UNKNOWN`, a
+  built-in or differently redefined id `T3D_MATERIAL_CONFLICT`, and a fifth custom row
+  `T3D_SHEET_FULL`. A painter that writes NaN or ∞ fails the paint with `T3D_MATERIAL_INVALID`.
+- Rows are given out in registration order. Define materials in one shared module that every recipe
+  imports, so the same program always produces the same bytes. Redefining an id with the identical
+  definition is a no-op.
+- `DEFAULT_SHEET` paints defined materials automatically. To restyle a built-in for one project,
+  override its recipe: `paintTrimSheet({ ...DEFAULT_SHEET, strips: { ...DEFAULT_SHEET.strips, oak: {...} } })`.
+- `materialOf(id)` returns the recipe, origin (classic/library/defined), description and sources.
+  `resetMaterials()` is for tests and long-lived workers.
+
+## CC0 image strips (opt-in)
+
+A strip can come from a photo-scanned CC0 PBR set instead of a painter:
+
+```ts
+defineMaterial({ id: 'ph_wood_planks_grey', roughness: 0.85, texture: {
+  source: 'polyhaven', id: 'wood_planks_grey', license: 'CC0-1.0',
+  page: 'https://polyhaven.com/a/wood_planks_grey', author: 'Rob Tuytel', metres: [1.5, 1.5],
+  maps: { albedo: { url: '…_diff_1k.png', sha256: '…' }, normal: { … nor_gl … }, arm: { … } },
+} });
+```
+
+`CC0_WOOD_PLANKS_GREY` ships as a working example. It is not registered by default.
+
+- **Offline compile.** `bun run textures [module…]` downloads every declared map once into
+  `node_modules/.cache/ts23d/textures/<sha256>.png` (gitignored). It checks each file's sha256 and
+  refuses a mismatch. `provideTextures(await loadTextureCache())` (from `scripts/textures.ts`) hands
+  the bytes to the painter. The library never touches the network. If a map is missing, painting
+  throws `T3D_TEXTURE_MISSING`, and the error names the command to run.
+- **Painting.** PNGs are 8- or 16-bit (JPEG is not decoded). They are box-filtered onto the strip at
+  true scale, with whole repeats along U so the strip still tiles. V is flipped so the image's top is
+  world up. The OpenGL normal's green channel is flipped to the sheet's convention. `arm` fills
+  occlusion, roughness and metalness.
+- **Credits.** Only CC0 licences are accepted. When an asset samples an image strip, the GLB's XMP
+  packet gets a `dc:contributor` line with the set, author, licence and page. Assets without image
+  strips are byte-identical to before.
+- **Next (planned).** ambientCG ships its sets as zips, and zip extraction is not built yet, so
+  ambientCG sets work only when pointed at a PNG URL or a local file (`source: 'file'`). The CLI
+  does not load the cache yet (see the roadmap request).
+
+## Seeing it: the beauty renderer
+
+`src/render/shade.ts` reads roughness and metalness per texel from the ORM. Specular uses a
+normalised Blinn–Phong sun lobe plus a **studio environment reflection** (`envRadiance` in
+`lighting.ts`). The environment has a bright cyclorama horizon, a cooler zenith, a dark band where
+the floor meets the wall, and the lit floor. Roughness blurs it toward its mean, so chrome shows the
+horizon line, brass looks gold, and oak stays matte. Fresnel uses Schlick with a roughness-limited
+grazing term. Glass keeps its own path. The site viewer gets the same ORM through three.js
+`MeshStandardMaterial`.

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.