@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/docs/idea/13-asset-pipeline-research.md

@@ -0,0 +1,89 @@
+# 13 — The professional game-asset pipeline, free CC0 libraries, and where ts23d sits
+
+**The studio pipeline is blockout → high poly → low poly → UV → bake → texture → present. ts23d collapses most of it into one compile: the recipe is the blockout and the low poly, the trim sheet replaces per-asset UV + bake + texture, and `shot` / `hero` / `review` are the presentation. What it borrows from the pipeline is the taste: bevels, roughness variation, consistent texel density, readable silhouettes.** This page records the pipeline as practitioners describe it, the free CC0 libraries (with exact licence wording) that can feed ts23d as inputs, and the gaps. Research as of 2026-11-07; "Proposed" items are **planned, not shipped**. Neutral positioning: artists, DCC tools and AI generators all produce good assets; ts23d is the free, code-based option.
+
+## The pipeline as practitioners describe it
+
+| Stage | What happens | Typical tools | ts23d equivalent | Where |
+|---|---|---|---|---|
+| Reference | Photos, drawings, specs, front/side sheets | PureRef, browser | `recipes/<name>/README.md` written first; `real` + `sources` + `measures` | CLAUDE.md recipe loop |
+| **Blockout** | Primitive masses at real scale, read the silhouette in-engine | Any DCC | Step 2 "Masses", `proportions` ±5% / `measures` ±2% gates | [05](05-agent-loop.md) |
+| High poly | Sub-D or sculpt with every bevel and detail, for baking only | ZBrush, Blender, Maya | Not a separate artefact: LOD0 *is* the dense mesh; SDF normals come from the exact field | `src/primitives/sdf.ts` |
+| Low poly | Game mesh around the high poly; hard edges at UV splits | DCC, retopo tools | Same recipe at LOD1/LOD2, gated by `ctx.lod`, never decimated | [02](02-dsl.md), CLAUDE.md |
+| UV | Unwrap, pack, consistent texel density | RizomUV, Blender | Primitives author UVs onto the trim sheet at true metres | `src/material/trim-sheet.ts` |
+| **Bake** | High → low: normal, AO, curvature, ID; cage controls the ray search so hard edges shade soft | Marmoset Toolbag, Substance, xNormal, Blender | Vertex AO (`bakeAo`), weighted normals, field-gradient normals; no per-asset maps by design | `src/passes/bake-ao.ts`, `weighted-normals.ts` |
+| Texture | Smart materials on baked maps: edge wear from curvature, dirt from AO, roughness breakup | Substance Painter, ArmorPaint | Procedural trim sheet + vertex colour + `grime` / `livery`; edge wear planned ([11](11-materials-authoring.md)) | `src/material/paint/`, `src/passes/` |
+| Present | Marmoset turntable, ArtStation renders, in-engine shots | Marmoset, engine | `t3d shot` (six views), `t3d hero` (beauty), `t3d review` (AI review pack) | `src/render/` |
+
+Order varies: some artists build the high poly first and the low poly around it, others go blockout → mid → high → low; hard-surface flows often add an in-between mesh ([Polycount thread](https://polycount.com/discussion/comment/1771950), practitioner opinions). The bake cage "allows the baker to search for high-poly detail as if edges were soft, while the actual low-poly retains hard edges" (Gnomon course description, [Creating Props for Games](https://bit.thegnomonworkshop.com/workshops/creating-props-for-games-vol-1)).
+
+## The two realism keys
+
+**Bevels.** Real objects have no razor edges; a 1–5 mm chamfer catches a highlight and reads as "manufactured" even at a distance. Studios fake bevels in textures to save triangles: Insomniac's "Ultimate Trim" (GDC 2015, Sunset Overdrive) is a sheet of horizontal trim strips with 45° normal-map bevels, standardised so materials swap without re-UVing ([GDC Vault](https://gdcvault.com/play/1022323/The-Ultimate-Trim-Texturing-Techniques), [CG Channel summary](https://www.cgchannel.com/2019/07/download-justen-lazarros-free-ultimate-trim-texturing-tools)). The Last of Us Part I used baked-bevel trims to save texture memory ([80.lv](https://80.lv/articles/the-last-of-us-remake-s-trim-pipeline-in-substance-3d-explained)).
+ts23d today: geometric bevels via `box({ bevel })` + `weightedNormals` (the mid-poly look; `src/primitives/bevel-box.ts`).
+
+**Roughness variation.** A flat roughness value reads as plastic CG; smudges, wear and dirt varying the specular response read as a material. ts23d today: every painter writes a `rough` layer with mottling; there is no gate on it. Proposed: `roughnessVariation` + a flat-roughness test ([11](11-materials-authoring.md)).
+
+### Trim sheets
+
+ts23d's sheet *is* a trim sheet in the studio sense ([ADR 003](../decisions/003-shared-trim-sheet.md) → [ADR 008](../decisions/008-surface-materials.md)): 28 strip rows tiling along U, then decal and foliage cells, one 2048² set (`src/material/trim-sheet.ts`). What studio trims have that ts23d's lacks:
+
+| Studio trim feature | ts23d | Proposed |
+|---|---|---|
+| Bevel/edge strips with baked 45° normal + worn edge | No; bevels are geometry | A `worn_edge` strip; map `box({ bevel })` chamfers onto it (S–M) |
+| Strip heights doubling (small to large trims) | Equal 64 px rows | Only if a recipe needs fine trims; layout change = ADR |
+| Decals over trims (bolts, vents, grates) as floating quads | Cells, mapped by `cell()` | `decal()` primitive: a quad offset 1–2 mm along the normal, cutout surface (S) |
+
+### Texel density
+
+Examples from vendor docs: 10.24 px/cm first person, 5.12 px/cm third person, 2.56 px/cm or less top-down; closer cameras need more ([Maxon](https://help.maxon.net/c4d/en-us/Content/html/Texel_Density.html)). ts23d's strips give 1024 px/m along U at 2048² (a strip spans 2 m), constant across assets by construction; along V it depends on `scaleMetres`. The planned texel-density gate (roadmap M2) should measure both axes.
+
+## Free CC0 libraries
+
+All five below state CC0 or public-domain terms. CC0 means no attribution required and commercial use and redistribution allowed; it also means **no warranty** (no indemnity for trademarks, likeness or third-party IP depicted). Verified on each site 2026-11-07 unless noted.
+
+| Library | What | Licence wording | Exceptions | Fits ts23d as |
+|---|---|---|---|---|
+| [Poly Haven](https://polyhaven.com/license) | HDRIs, PBR textures, models | "Our assets are all licensed as CC0"; "You can redistribute them"; "You do not need to give credit" | Site content other than the assets (logos, renders) is protected | **HDRIs** for the Blender bridge's Cycles renders ([12](12-blender-bridge.md)) and a future image-based-light option in `beauty()`; texture calibration |
+| [ambientCG](https://docs.ambientcg.com/license/) | PBR materials, HDRIs, models | "provided under the Creative Commons CC0 1.0 Universal License"; "You don't need to give credit" | None stated | Calibrating `MaterialDef` roughness/albedo; CC0 **height** maps as strip sources ([11](11-materials-authoring.md)) |
+| [cgbookcase](https://www.cgbookcase.com) | PBR textures (hundreds of sets) | CC0 per the author's announcements ([BlenderNation 2018](https://www.blendernation.com/2018/09/14/250-free-cc0-high-quality-pbr-textures-from-cgbookcase-com/), [CG Channel 2019](https://www.cgchannel.com/2019/03/download-380-free-pbr-texture-sets-from-cgbookcase-com/)) | **Licence page not reachable when checked (404)**; verify on the site before vendoring | Same as ambientCG |
+| [Kenney](https://kenney.nl/support) | Low-poly game kits, UI, audio | "all game assets on the asset pages are public domain licensed (CC0)"; "Attribution is not required" | "Do not use our logo" | `importGlb` (planned, M5) inputs; scale/style references for stylised recipes |
+| [Quaternius](https://quaternius.com/packs/fantasypropsmegakit.html) | Low-poly models, some rigged/animated, glTF included | CC0, "free to use in personal, educational and commercial projects" (pack pages; [OpenGameArt mirrors](https://opengameart.org/content/low-poly-rpg-pack)) | None stated | `importGlb` inputs: rigged characters for what recipes do weakly ([07](07-what-fits.md)) |
+
+Other licences to know, **not** CC0: Sketchfab downloads carry per-model CC-BY / CC-BY-NC etc. (check each); Fab/Quixel Megascans have their own EULA; Substance Source is subscription content. None of these should be vendored into the repo.
+
+### How CC0 assets enter ts23d without breaking determinism
+
+| Rule | Why |
+|---|---|
+| **Vendor, never fetch at build time.** Commit the file (or publish it with the package) with its sha256 | A URL can change or vanish; bytes in git cannot |
+| **Record provenance in `sources`** (URL, licence, date) and in GLB XMP (`KHR_xmp_json_ld`, shipped) | CC0 needs no credit, but provenance is how a reviewer checks it |
+| **Images are inputs, not the only path** ([04](04-materials.md#image-sources)) | The sheet must still paint with no image present |
+| **Imported meshes go through `importGlb` → fit → recolour onto the sheet** | Keeps one material and real units |
+| A `licence` field per vendored input, checked by a script in `bun run verify` (proposed) | "A rule without a script is a suggestion" (CLAUDE.md) |
+
+## Where ts23d differs on purpose
+
+| Studio practice | ts23d choice | Reason |
+|---|---|---|
+| Per-asset baked normal/AO/curvature maps | One shared sheet; wear in vertex data | One draw call, swap palette by recipe edit ([ADR 008](../decisions/008-surface-materials.md)) |
+| Decimate the high poly for LODs | LOD-gated emission from one source | Cleaner silhouettes, named parts survive every LOD |
+| Hand UVs | UVs by construction at true metres | Agents don't unwrap; consistent density for free |
+| Quad retopology | Triangles, vertex-cache ordered (`optimize`) | Engines draw triangles; ts23d doesn't subdivide |
+
+## Next steps for ts23d (prioritised)
+
+1. **Texel-density gate** (px/m along U and V per part; V-stretch warning). S–M. Already on roadmap M2.
+2. **`worn_edge` strip + bevel-to-strip mapping** in `box({ bevel })`: the Ultimate-Trim idea with real geometry. S–M.
+3. **`decal()` primitive**: offset quad on a cell, cutout surface, for bolts/vents/grates. S.
+4. **Vendored-input convention + `licence` check** in `bun run verify` (sha256, URL, licence, date per file under `assets/vendor/` or similar). S.
+5. **Roughness-variation knob + flat-roughness test** ([11](11-materials-authoring.md)). S.
+6. **CC0 HDRI support**: Poly Haven `.hdr` loader for an optional IBL term in `beauty()` (zero-dep RGBE decode is ~100 lines) and for the Blender bridge. M.
+7. **Document the calibration workflow** in `.claude/skills/author-recipe/SKILL.md`: sample a CC0 texture's albedo/roughness, put the numbers in `MaterialDef`, cite the URL. S.
+
+## Sources
+
+- Pipeline: [Polycount threads](https://polycount.com/discussion/comment/1771950), [Gnomon: Creating Props for Games](https://bit.thegnomonworkshop.com/workshops/creating-props-for-games-vol-1) (course description) — practitioner accounts, not a standard
+- Trims: [GDC Vault, "The Ultimate Trim: Texturing Techniques of Sunset Overdrive"](https://gdcvault.com/play/1022323/The-Ultimate-Trim-Texturing-Techniques) (Insomniac, 2015), [CG Channel](https://www.cgchannel.com/2019/07/download-justen-lazarros-free-ultimate-trim-texturing-tools), [80.lv on The Last of Us Part I trims](https://80.lv/articles/the-last-of-us-remake-s-trim-pipeline-in-substance-3d-explained)
+- Texel density: [Maxon Cinema 4D docs](https://help.maxon.net/c4d/en-us/Content/html/Texel_Density.html)
+- Licences: [Poly Haven](https://polyhaven.com/license), [ambientCG](https://docs.ambientcg.com/license/), [Kenney](https://kenney.nl/support), [Quaternius](https://quaternius.com/packs/fantasypropsmegakit.html), cgbookcase via [BlenderNation](https://www.blendernation.com/2018/09/14/250-free-cc0-high-quality-pbr-textures-from-cgbookcase-com/) and [CG Channel](https://www.cgchannel.com/2019/03/download-380-free-pbr-texture-sets-from-cgbookcase-com/)

package/docs/landscape.md

@@ -0,0 +1,49 @@
+# Landscape: AI 3D generators
+
+**A neutral survey, as of Oct 2026. ts23d isn't a competitor to these tools; it's a different approach (code recipes, free, no GPU, no service) with different strengths.** Many teams will use both. Prices and features change monthly, so check the linked source before relying on a row.
+
+Rows marked **(3rd-party)** come from aggregators or press, not the vendor's own page. Treat them as indicative.
+
+## Hosted / commercial
+
+| Tool | Inputs | Outputs | Rig / anim | Pricing (as of Oct 2026) | Open? | Source |
+|---|---|---|---|---|---|---|
+| Meshy (Meshy 7.1 / 6) | Text, image, multi-view | GLB / glTF / FBX / OBJ / USDZ / STL / 3MF; PBR (albedo / normal / metal / rough); quad/tri remesh, Low Poly mode, Smart Topology | Auto-rig humanoid + quadruped, 500–600+ motion presets | Free 100 credits/mo, outputs CC BY 4.0. Pro $20 (1,000 cr), Premium $40 (3,000), Ultra $100 (8,000), Studio $70/team. ~20–25 credits per generation | No (paid = private + commercial) | [pricing](https://www.meshy.ai/pricing) · [docs](https://docs.meshy.ai/en/webapp/pricing) · [animate](https://docs.meshy.ai/en/webapp/guides/animate) |
+| Tripo (Tripo 3.x) | Text, image, multi-view | GLB / FBX / OBJ / USD / STL; PBR, smart low-poly, quad topology **(3rd-party)** | Auto-rig + animation | Free ~200–300 cr/mo (public, non-commercial); Pro ~$20/mo (3,000 cr); Max ~$90 (25,000); API per task **(3rd-party)** | No | [docs](https://platform.tripo3d.ai/docs/introduction) · [CostBench](https://www.costbench.com/software/ai-3d-generation/tripo-ai/) |
+| Rodin / Hyper3D (Gen-2.5) | Text, image, multi-view, sketch, 3D ControlNet (bbox / voxel / point cloud), mesh edit | GLB / glTF / FBX / OBJ / USDZ / STL; PBR + UVs; quad/tri, polycount presets (~4K–50K quads) | Not mentioned on official page | Free pay-per-result ($1.50/credit); Creator $30/mo (~60 models); Business $120/mo (~416, API) | No | [pricing](https://hyper3d.ai/pricing) · [site](https://hyper3d.ai/) |
+| Luma Genie | Text (originally) | GLB / OBJ / USDZ (2024 coverage) | No | Free research preview at 2024 launch; current status unclear **(3rd-party)** | No | [The Decoder](https://the-decoder.com/genie-by-luma-ai-is-a-free-text-to-3d-generator-for-discord/) |
+| CSM (Cube) | Image, text | Part-based meshes, AI retopology **(3rd-party)** | Not confirmed | Free tier, then ~$20 / $60 / $499+/mo (May 2026); reported acquired by Google Jan 2026, unconfirmed **(3rd-party)** | No | [CostBench](https://costbench.com/software/ai-3d-generation/csm/) |
+| Kaedim | Concept art, sketches, photos, briefs | Production 3D with review / markup / revision loop | Not stated | No public pricing; $50 trial to $400–$1,200/mo **(3rd-party)** | No (customer owns outputs) | [site](https://www.kaedim3d.com/) |
+| Sloyd | Text, image, multi-image, parametric templates | GLB / OBJ / FBX / STL; polycount + tri/quad control; Unity / Unreal / Blender / Godot / Roblox plugins | AI rig + anim | Guest 1 gen/day personal; Plus $15/mo (50 cr); Pro $50/mo (350 cr) | No | [pricing](https://www.sloyd.ai/pricing) |
+| Autodesk Wonder 3D (Mar 2026) | Text, image | OBJ / STL for Maya / 3ds Max / Flow Studio | Not stated | Free 300 cr/mo at 20/gen; Pro ~$64/mo | No | [Autodesk news](https://adsknews.autodesk.com/en/news/autodesk-flow-studio-launches-wonder-3d-gen-ai-model-to-help-creators-make-3d-characters-and-objects-faster-and-easier/) |
+
+## Open weights / self-hosted
+
+| Tool | Inputs | Outputs | Rig / anim | Cost / hardware | Licence | Source |
+|---|---|---|---|---|---|---|
+| Hunyuan3D (Tencent) | Open 2.x: image, multi-view. Hosted 3.x: text / image / sketch, up to 4–8 views | Mesh + PBR texture pipeline (Paint 2.1) | No | Open 2.1 free, ~29 GB VRAM shape + texture; hosted ~20 free gens/day then ~$0.02/credit | 2.0 / 2.1 open weights, Tencent community licence (excludes EU / UK / South Korea, terms above 1M MAU, no training other models on outputs); 2.5 / 3.x hosted only | [GitHub](https://github.com/Tencent-Hunyuan/Hunyuan3D-2.1) |
+| TRELLIS.2 (Microsoft) | Single image; can texture an existing mesh | GLB with PBR incl. opacity, 4K textures | No | Free self-hosted; ≥ 24 GB GPU, tested Linux A100 / H100 | MIT | [Hugging Face](https://huggingface.co/microsoft/TRELLIS.2-4B) |
+| Stable Fast 3D / SPAR3D (Stability) | Single image 512² | UV-unwrapped textured mesh, delighted textures, rough/metal; SPAR3D point-cloud editing | No | Free self-host; hosted API credit-based | Stability Community Licence (free under $1M revenue) | [Hugging Face](https://huggingface.co/stabilityai/stable-point-aware-3d) |
+| SAM 3D Objects (Meta, Nov 2025) | Real photos; an object from a cluttered scene | Textured object + pose / layout | No | Free self-hosted | Open weights, custom SAM licence **(3rd-party)** | [Roboflow](https://roboflow.com/model/sam-3d-objects) |
+
+## Caveats on the data
+
+- The Tripo site returned 403 to our research run; its pricing comes from CostBench.
+- csm.ai did not resolve; the CSM row is entirely third-party.
+- The Luma Genie page now redirects; current status unknown.
+- Gallery themes as shown by vendors: Meshy, riggable characters and stylised props. Rodin, a robot, a sci-fi weapon, a motorcycle, architecture. Sloyd, creatures, avatars, furniture, vehicles, weapons, trees, buildings. Kaedim, products, game props, characters.
+
+## Where each approach fits
+
+| Strength | Image/text-to-3D generators | Code recipes (ts23d) |
+|---|---|---|
+| Organic and sculpted forms | Strong | Weak ([what fits](idea/07-what-fits.md)) |
+| Concept art → textured mesh in seconds | Strong | No |
+| Auto-rigging | Several tools have it; meshes and rigs usually still need cleanup | Rigid part hierarchy only |
+| Parts that line up, repeat or match real dimensions | Weaker | Strong |
+| Named, animatable nodes | Usually one fused mesh | Built in |
+| Determinism, diffable git history | No | Yes |
+| Shared materials, consistent texel density | Per-asset textures | One trim sheet |
+| Cost, licence conditions on outputs | Credits; terms vary by tier | Free; none |
+
+The open-weight rows are what the planned [`/neural` adapter](idea/08-neural-adapters.md) wraps for the organic cases, on your own GPU, cached by content hash.

package/docs/plans/roadmap.md

@@ -0,0 +1,139 @@
+# Roadmap
+
+**Each milestone ships something an agent can use end to end, gated by `bun run verify`. Scope ends at the GLB, textures and manifest; engines and game code are out of scope.** Ticked = on `main` with a test and, where it makes geometry, a recipe. Order within a milestone is a suggestion; order between milestones is a dependency. No dates promised.
+
+Status as of 2026-11-07: **M0 done, M1 done but for recipes, M2 under way.** Every exported entry point that isn't ticked throws `T3D_NOT_IMPLEMENTED` with a pointer here.
+
+## M0: Scaffold (0.x)
+
+- [x] Mesh IR, `MeshBuilder`, seeded forkable RNG, vector math
+- [x] `defineAsset` / `compile` / `ctx.part` / `ctx.group` / `ctx.use`, LODs by re-run
+- [x] `real` dimensions + `sources` on `defineAsset`
+- [x] Mesh transforms: `place`, `affine`, `frame`, `applyAffine`
+- [x] `Ts23dError` with code + cause + fix
+- [x] Split grammar (`split`, `parseSplit`, `layoutSplit`), Whyte notation
+- [x] Trim-sheet layout, palettes, `hex()`
+- [x] Primitives: `box`, `lathe`, `cylinder`
+- [x] Kinds: `facade`, `setbacks`, `axle`, `trackRun`, `whyteAxles`, `propeller`
+- [x] `grime` pass
+- [x] QA: `triangle-budget`, `floating-parts` (surface contact), `clashes` (swept motion, `clearOf`), `part-names`, `proportions`, `measures` (`real.measures`)
+- [x] GLB writer: one material, baked spin/slide clip, Z-up → Y-up root
+- [x] `defineFamily`: variants and derived families
+- [x] `ctx.emitter`: particle sources as named nodes
+- [x] `sway` motion; `run` clip baked by `t3d build`, opt-in in `toGlb`
+- [x] Recipe `checks` (`clear`, `noOverlap`, `touches`, `symmetric`) and `inspect`
+- [x] `ctx.socket`; surfaces (opaque / cutout / glass / translucent, ≤ 4 materials)
+- [x] CLI output: `out/<asset>/` with GLBs, sheet, manifest; `out/index.json`
+- [x] `heightfield` terrain
+- [x] GLB production pass: front axis +Z, seamless loops, `rest` + `run` clips, u16 indices, u16 colours, shared time accessors, glTF-Validator in tests ([glb-production.md](../architecture/glb-production.md) G1, G2, G4, G5, G10)
+- [x] `mergeToPivots`: static geometry batched into its nearest pivot (default in `toGlb`; `keepParts` opts out)
+- [x] CPU contact sheet: six views, metre grid, header dims
+- [x] CLI: `t3d build | shot | list`, `--out`, `--json`
+- [x] Repo gates: lint, typecheck, boundaries, determinism, filesize, tests, recipes (QA + double-build hash), build
+- [x] Release flow: stamp → PR → tag → OIDC publish
+- [x] Recipes: `tiger_1`, `t34` + `t34_1941` (family), `loco_440` (family; the Jupiter, drivers 1.626 m sourced), `material_swatches`
+- [x] Asset gallery site (every recipe, compiled in the browser)
+- [ ] First npm publish (bootstrap, [PUBLISHING.md](../../PUBLISHING.md))
+
+## M1: Architecture primitives
+
+- [x] `prism`: extrude a 2D profile in the `xy` / `xz` / `yz` plane
+- [x] `beam`: member between two points, square or round
+- [x] `planar`: flat polygon in 3D
+- [x] `triangulate`: ear clipping
+- [x] `tiled`: quad tiling a strip at true scale
+- [x] `cell`: quad mapped to a decal cell (with `inset` reveals)
+- [x] `roof`: hip, gable, pyramid, mansard, gambrel, shed; `opening` window/door kit, `mass` true-scale masonry
+- [ ] Opt-out for genuinely floating parts (aircraft in flight, hanging signs)
+- [ ] Cross-machine determinism check; a `t3d build` flag for users' recipes
+- [x] Recipe: `eiffel_tower` (188,016 / 21,860 / 1,062 triangles, 1 draw call; profile from Weidman & Pinelis 2004 and Eiffel's 1887 drawing)
+- [x] `lattice` truss primitive (Warren / Pratt / Howe / X)
+- [ ] Recipes: a terrace street, a station, an Art Deco tower, townhouse, gas lamp (landing)
+
+## Recipe-agent backlog (unscheduled)
+
+- [ ] `orbit` motion + `phase` for side rods and quartering
+- [x] Sector sweep for `sway` clashes; `oneWay` slide / sway
+- [ ] `recipes/_lib/` shared helpers: `trackLoop`, `roadWheel`, decal font with Cyrillic
+- [ ] `subdivide(mesh, maxEdge)` pass for vertex-colour camo
+- [ ] Exact-match option for measure `parts` (today: prefix match)
+- [ ] TriangleGrid filling only the cells a triangle crosses
+
+## M2: High definition, cheap to draw
+
+Materials:
+- [x] `paintTrimSheet`: procedural albedo / normal / ORM; strips bond, planks, plates, noise, flat, slate, concrete, glass; 6 decal + 11 foliage cells
+- [x] Sheet in the GLB: embedded or shared external PNGs (`--sheet`, `--sheet-size`)
+- [ ] KTX2 profile; fix mip bleed between strips; per-face V mapping on `box`
+- [ ] Image-stamped cells (decals from any `ImageSource`)
+- [ ] Painter curvature + `edgeWear` mask (`params.edgeWear`, `PaintKit.curvature`) ([11](../idea/11-materials-authoring.md))
+- [ ] `edgeWear(mesh)` pass (dihedral / SDF-Laplacian convexity → vertex colour; `_WEAR` attribute for shader sources)
+- [ ] `roughnessVariation` on `MaterialDef` + flat-roughness test
+- [ ] `worn_edge` strip mapped by `box({ bevel })` chamfers; `decal()` offset-quad primitive
+
+Optimisation and GLB production (gap ids from [glb-production.md](../architecture/glb-production.md)):
+- [x] `optimize(mesh)`: vertex weld + vertex-cache reorder, reports ACMR (default in export)
+- [ ] Gate: ACMR ceiling
+- [ ] Opt-in `web` profile: `KHR_mesh_quantization` + `EXT_meshopt_compression` (G14). Default stays core glTF: Godot refuses required extensions
+- [ ] `MSFT_lod` single-file LOD set + screen-coverage switch hints (G11)
+- [ ] Placeholder pivots at LOD2 so engine-bound names exist in every LOD (G3)
+- [ ] `engine-names` gate against Godot suffix hints like `_wheel`, `-col` (G6)
+- [ ] Clip naming Godot loops (`*_loop`) (G7)
+- [x] Asset metadata: generator version, copyright, XMP provenance (G8)
+- [ ] Mesh dedupe: identical geometry shares one mesh (G9)
+- [x] Emissive surface (`KHR_materials_emissive_strength`) for lit windows (G13 remainder)
+
+Shape:
+- [x] `sweep`: parallel-transport frames, taper, twist
+- [x] `loft` over `rings`, `ringXY` with wobble
+- [x] `hull` (vessel kind) from length / beam / draft / freeboard
+- [ ] Lofted vehicle bodies, fuselages, wings
+
+Checking:
+- [ ] `photoMatch(asset, { photo, camera })`: photo · model · overlay in one PNG + silhouette IoU
+- [ ] `silhouetteIoU` gate on top of it
+- [ ] Gates: manifold + outward normals, texel density
+
+Exit bar: a 4-4-0 with tender matching [`docs/reference/loco-photo-match.png`](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/reference/loco-photo-match.png) (predecessor output: ~16k triangles, 17 named nodes, one embedded trim-sheet material, baked `run`). Recipes: that loco, a harbour tug, a biplane.
+
+## M3: Vegetation and engine import adapters
+
+- [x] `tree`: Weber–Penn skeleton, leaf cards; presets oak / pine / palm / birch / willow; `trees` family; `treeReal`
+- [x] Recipes: `oak`, `pine`, `palm`
+- [ ] Per-vertex wind weights (crown `sway` today)
+- [ ] LOD2 impostors as crossed billboards from the foliage cells
+- [ ] Species presets as data
+- [x] `threeMaterialSource` (TSL) and `godotShaderSource`: wind, window glow, wear
+- [ ] Engine import adapters as data, not runtime: import settings for Unity (glTFast), Godot, Unreal; mapping extras + shader hints onto each engine's material
+- [ ] Engine collision naming: `ctx.collider` → Godot `-convcolonly`, Unreal `UCX_`, generic extras (G12)
+- [ ] Motion baked into vertex attributes (pivot + spin axis per vertex): a shader animates every wheel in one draw call
+- [ ] Recipes: a park, an orchard
+
+## M4: Creatures
+
+- [x] `sdf`: surface nets or marching cubes over a signed-distance field; `sculpt` edit lists (Dreams-style)
+- [ ] `creature`: SDF flesh over biped / quadruped / bird skeletons, bones as named parts
+- [ ] Recipes: stylised critters, rocks
+- [ ] `roundCone` sculpt shape + `skin()` (draw-skin capsule chains) ([10](../idea/10-sculpting.md))
+- [ ] Sculpt `form` tags (primary/secondary/tertiary) as an LOD filter + primary-only review view
+- [ ] Group `pose` (pivot + rotate) and `warp` (twist/bend/taper) with declared Lipschitz factors
+- [ ] `ffd()` cage deform pass (Sederberg–Parry)
+- [ ] Sculpt strokes along a path: `crease`, `clay`, `inflate` (then `pinch`, `flatten`); `revolve` SDF shape
+- [ ] `t3d shot --ref front=… side=…` overlays + per-view silhouette IoU
+
+## M5: Neural adapters and import
+
+- [ ] `localGenerator`: HTTP adapter for a local TRELLIS.2 / Hunyuan3D 2.1 / SF3D server
+- [ ] Content-hash cache under `.ts23d/neural/`; a CI cache miss is an error naming the regenerate command
+- [ ] `importGlb`: any GLB as a part, fitted and recoloured onto the trim sheet
+- [ ] `kubeezImages`: kubeez.com image source for references, decals, texture sources
+- [ ] Recipe: a code-built cart drawn by a generated horse
+- [ ] Optional Blender bridge, never in the gate ([12](../idea/12-blender-bridge.md)): ADR, shared content-hash cache with /neural, `t3d blender doctor | render | remesh | convert`
+- [ ] Vendored-input convention (sha256 + URL + licence) and a `licence` check in `bun run verify`; CC0 HDRI loader for `beauty()` IBL
+
+## M6: Reverse direction and reach
+
+- [ ] Camera solve for `photoMatch` from ≥ 4 marked correspondences
+- [ ] Reverse direction: a VLM proposes recipe params from photos, scored by silhouette IoU, best kept
+- [ ] MCP server: `build`, `shot`, `list` as tools, PNG inline
+- [ ] Playground: edit a recipe in the browser, see GLB + contact sheet live

package/examples/build-with-bun.ts

@@ -0,0 +1,41 @@
+// Build assets without the CLI: the library is plain TypeScript, so a script is all you need.
+// Run: bun examples/build-with-bun.ts [out-dir]   (Node ≥ 22 works too, against the built dist/)
+// Pick exactly what you want — which LODs, textures or not, QA or not, sheets or not.
+
+import {
+  compile,
+  contactSheet,
+  DEFAULT_SHEET,
+  type Lod,
+  paintTrimSheet,
+  runQa,
+  toGlb,
+} from '@developerz.ai/ts23d';
+import { tiger_1 } from '../recipes/tiger_1/tiger_1.ts';
+
+const out = process.argv[2] ?? 'out/example';
+const asset = tiger_1;
+const lods: Lod[] = [0, 2]; // near + far only — your call
+
+// Textures are optional: paint once, embed (or pass { external: true } and ship the PNGs).
+const sheet = paintTrimSheet({ ...DEFAULT_SHEET, size: 512 });
+
+for (const lod of lods) {
+  const compiled = compile(asset, { lod });
+
+  // QA is a function too: gate however your pipeline wants.
+  const findings = runQa(compiled);
+  if (findings.length > 0) {
+    for (const f of findings) console.error(`LOD${lod} ${f.gate}: ${f.message}\n  fix: ${f.fix}`);
+    process.exit(1);
+  }
+
+  await Bun.write(
+    `${out}/${asset.name}.lod${lod}.glb`,
+    toGlb(compiled, { sheet, animations: true }),
+  );
+}
+
+// The six-view contact sheet, for you or your agent to look at.
+await Bun.write(`${out}/${asset.name}.png`, contactSheet(compile(asset, { lod: 0 })));
+console.log(`✔ ${asset.name}: LOD ${lods.join(', ')} + contact sheet → ${out}/`);

package/llms.txt

@@ -0,0 +1,47 @@
+# ts23d
+
+> @developerz.ai/ts23d — a free, deterministic 3D asset generator driven by coding agents. Assets are TypeScript modules (never JSON) built with a DSL: `defineAsset({ name, kind, real, sources, budget, build(ctx) })`, where `build` adds named, pivoted, animatable parts from primitives (`box`, `lathe`, `cylinder`, `prism`, `beam`, `planar`), places detail with `place`/`merge`, composes other assets with `ctx.use`, and gates detail on `ctx.lod`. It compiles to glTF/GLB for any engine (Unity, Unreal, Godot, three.js, Babylon) — ts23d generates assets only, the engine is yours — (3 LODs, one shared trim-sheet material, baked motion), fails a QA gate on floating parts, budget overruns and wrong real-world proportions, and renders a zero-GPU six-view contact-sheet PNG so a vision-capable agent can check its own work. Bun only, zero runtime dependencies, MIT. Status 0.x: stubs throw T3D_NOT_IMPLEMENTED with the roadmap slice that builds them.
+
+## Offline (inside your project)
+The npm package ships every doc, skill and example, versioned with the code — read them without internet:
+- `node_modules/@developerz.ai/ts23d/AGENTS.md` — rules and the loop
+- `node_modules/@developerz.ai/ts23d/docs/` — DSL, IR, materials, agent loop, QA, kinds, decisions, roadmap
+- `node_modules/@developerz.ai/ts23d/recipes/<name>/` — idiomatic recipes, each with its research dossier (`README.md`) and committed hero + contact sheet (`out/`)
+- `node_modules/@developerz.ai/ts23d/.claude/skills/author-recipe/SKILL.md` — copy into your `.claude/skills/`
+
+## The workflow
+The human names a thing ("Tiger I, mid-production 1943"). The agent researches specs and real photos into `recipes/<name>/README.md` (every number sourced), writes `recipes/<name>.ts` with `sources` + `real.measures` from that dossier, compiles until QA PASS (budget, surface contact, clashes, proportions ±5%, measures ±2%), renders the six-view contact sheet, looks at it, adds LOD-gated detail, and iterates.
+
+## Programmatic (no CLI)
+`t3d` is optional: `compile` → `runQa` → `toGlb` / `contactSheet` / `paintTrimSheet` are plain functions returning bytes. Runnable script: `examples/build-with-bun.ts` (also in the npm package).
+
+## Start
+- [README](https://raw.githubusercontent.com/developerz-ai/ts23d/main/README.md): what it is, quickstart, the agent loop
+- [AGENTS.md](https://raw.githubusercontent.com/developerz-ai/ts23d/main/AGENTS.md): rules for agents using or changing the library
+- [CLAUDE.md](https://raw.githubusercontent.com/developerz-ai/ts23d/main/CLAUDE.md): commands, axioms, module tiers, CI
+- [Author-recipe skill](https://raw.githubusercontent.com/developerz-ai/ts23d/main/.claude/skills/author-recipe/SKILL.md): the closed loop, step by step, with a skeleton
+
+## DSL and concepts
+- [The DSL](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/02-dsl.md): defineAsset, ctx API, composition, determinism
+- [IR, units, axes](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/03-ir.md)
+- [Materials](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/04-materials.md): trim sheet, palettes, generator, image sources (kubeez.com)
+- [Agent loop](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/05-agent-loop.md): contact sheet layout, iteration
+- [QA gates](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/06-qa.md)
+- [What fits](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/07-what-fits.md): hard-surface vs organic; sculpted stylised characters and terrain today; realistic creatures via local-GPU adapters
+- [Kinds](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/09-kinds.md): buildings, vehicles, vessels, vegetation, scenes
+
+## Reference
+- [Public API barrel](https://raw.githubusercontent.com/developerz-ai/ts23d/main/src/index.ts)
+- [Error codes](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/architecture/errors.md): every T3D_* with cause and fix
+- [Module tiers](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/architecture/README.md)
+- [glTF capabilities](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/architecture/gltf-capabilities.md): every extension, skins, physics drafts; what ts23d writes
+- [Roadmap](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/plans/roadmap.md): shipped vs planned
+- [Decisions](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/decisions/): why TS not JSON, why one material, why CPU renders
+- [Example recipe: Tiger I](https://raw.githubusercontent.com/developerz-ai/ts23d/main/recipes/tiger_1/tiger_1.ts)
+- [Reference dossier template](https://raw.githubusercontent.com/developerz-ai/ts23d/main/recipes/README.md)
+
+## Optional
+- [Landscape](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/landscape.md): neutral overview of AI 3D generators and where each approach fits
+- [Gallery](https://developerz-ai.github.io/ts23d/): every asset compiled live in the browser — orbit, LODs, textures, download GLB
+- kubeez.com — recommended for reference/concept images and texture sources
+- developerz.ai — 100% AI-managed software engineering; builds and maintains this project

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@developerz.ai/ts23d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Free, deterministic 3D asset generation in TypeScript — a DSL your coding agent writes, compiled to game-ready glTF.",
+  "type": "module",
+  "license": "MIT",
+  "author": "developerz.ai",
+  "homepage": "https://developerz-ai.github.io/ts23d/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ts23d.git"
+  },
+  "bugs": "https://github.com/developerz-ai/ts23d/issues",
+  "keywords": [
+    "3d",
+    "procedural",
+    "gltf",
+    "glb",
+    "dsl",
+    "game-assets",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "three"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "bun": "./src/*/index.ts",
+      "default": "./dist/*/index.js"
+    }
+  },
+  "bin": {
+    "t3d": "./dist/cli/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "docs",
+    "!docs/reference/*.png",
+    "recipes",
+    "!recipes/*/out",
+    "!docs/media",
+    "examples",
+    "README.md",
+    "CLAUDE.md",
+    "llms.txt",
+    "CHANGELOG.md",
+    "LICENSE",
+    ".claude/skills",
+    ".claude/agents",
+    ".claude/commands",
+    "!examples/**/*.test.ts"
+  ],
+  "workspaces": [
+    "apps/*"
+  ],
+  "scripts": {
+    "setup": "bun run scripts/setup.ts",
+    "verify": "bun run scripts/verify.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test src scripts examples",
+    "build": "bun run scripts/build.ts",
+    "boundaries": "bun run scripts/boundaries.ts",
+    "determinism": "bun run scripts/determinism.ts",
+    "filesize": "bun run scripts/filesize.ts",
+    "recipes": "bun run scripts/recipes.ts",
+    "shots": "bun run scripts/shots.ts",
+    "textures": "bun run scripts/textures.ts",
+    "release": "bun run scripts/release.ts",
+    "t3d": "bun run src/cli/bin.ts",
+    "site:dev": "bun run --filter @ts23d/site dev",
+    "site:build": "bun run --filter @ts23d/site build",
+    "site:shots": "bun run scripts/site-shots.ts",
+    "bench": "bun run scripts/bench.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.3",
+    "@types/bun": "1.4.4",
+    "gltf-validator": "2.0.0-dev.3.10",
+    "lefthook": "2.2.2",
+    "typescript": "7.0.2"
+  },
+  "trustedDependencies": [],
+  "engines": {
+    "bun": ">=1.4.4",
+    "node": ">=22"
+  }
+}

package/recipes/README.md

@@ -0,0 +1,38 @@
+# recipes/ — one folder per asset
+
+Each asset is a folder: `recipes/<name>/<name>.ts` (the recipe), `recipes/<name>/README.md` (this dossier)
+and `recipes/<name>/out/<asset>/` (hero.png, sheet.png, manifest.json — committed, refreshed by
+`bun run shots`, checked by the recipes gate). The dossier is `recipes/<name>/README.md`. The agent writes it BEFORE the recipe; the recipe's
+`sources` and `real.measures` are copied from it, and the `measures` gate proves the model matches.
+Photos are linked, never committed (licences); downloads go to `tmp/refs/<name>/` (gitignored).
+
+## Template
+
+```md
+# <Name> — <variant / year>
+
+## Identity
+Variant chosen and why (one line). What makes it THIS object: the 3–5 signature features.
+
+## Specs
+| Dimension | Value (m) | Source |
+|---|---|---|
+| overall length | 6.316 | <url> |
+| width | 3.56 | <url> |
+| height | 3.00 | <url> |
+| road wheel diameter | 0.80 | <url> |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| side elevation | <url> | scale reference: wheel diameter |
+| front 3/4 | <url> | |
+| top | <url> | |
+| detail: <thing> | <url> | |
+
+## Parts the engine needs
+`turret` (yaw), `gun` (pitch), `road_wheel_*` (spin) …
+
+## Open questions
+What the sources disagree on, and which value was chosen.
+```

package/recipes/asteroid/README.md

@@ -0,0 +1,46 @@
+# Mineable asteroid (`asteroid`, `asteroid_b`, `asteroid_c`)
+
+## Identity
+A ~10 m rubble-pile asteroid for a mining game, in three seeded variants: `asteroid` (seed 1,
+5.0 × 3.8 × 3.0 m radii), `asteroid_b` (seed 2, rounder) and `asteroid_c` (seed 3, an elongated
+shard). The rocks are original and procedural.
+
+Signature features: a lumpy mass chipped by flat fracture planes; impact craters with raised rims
+and dark floors; very dark carbonaceous rock with lighter dust on up-facing slopes; thin metallic
+ore veins; glowing teal crystal clusters at the mining points.
+
+## References
+| Fact | Value | Source |
+|---|---|---|
+| C-type (carbonaceous) albedo | 0.03–0.09, ~75 % of asteroids, very dark | https://starlust.org/what-are-the-different-types-of-asteroids |
+| S-type (silicate) albedo | 0.10–0.22 | same |
+| M-type (metallic, nickel-iron) | bright, metallic, the mining target | https://www.esa.int/Science_Exploration/Space_Science/Rosetta/Debris_of_the_Solar_System_Asteroids |
+
+The base rock (`#3b3632`/`#4f4841`) is C-type dark. The ore veins (`#b78a45`) stand in for
+M-type metal. The glowing crystals (`#3fe0d0`) are a game convention, not science.
+
+## How it is built
+`sdf({ field, resolution: ctx.pick([0.17, 0.38, 0.95]) })` over one field:
+1. An ellipsoid core plus three smooth-unioned ellipsoid lobes.
+2. `valueNoise` displacement: 0.65 m at a 2.8 m feature size, plus 0.12 m pitting at 0.8 m.
+3. Twelve fracture half-spaces, smooth-max'd (k = 0.12 m), which give the angular facets.
+4. Nine craters. Each is a radial rim bump that displaces the surface, then a smooth-subtracted
+   bowl sphere. All shape draws come from `ctx.rng.fork('shape')`, so the shape is identical at
+   every LOD.
+5. Colour per vertex: blended tone noise, dust where n·z > 0.55, ore veins where |noise| < 0.05
+   (teal near crystals), dark crater floors.
+6. `bakeAo` (16 / 8 rays at LOD0 / LOD1) for crevice darkening.
+
+The bottom is clipped flat at z = 0 by the SDF bounds, so the rock rests on the ground (or in a
+field). The core sits below every variant's z radius, so the clip always happens.
+
+## Parts the engine needs
+`rock` (the mass; also usable as a collider at LOD2), `ore_crystals` (glow), interact sockets
+`mine_point_0…3` (at each cluster, facing into the rock, `data: { resource, yield }`), emitter
+`dust` (`event`, for mining debris).
+
+## Open questions
+- `real` is not declared: the size of a procedural rock is a design choice, not a spec, and the
+  noise moves its extents by ±10 %. The budget is measured per seed instead.
+- No in-library "surface point along a ray" helper exists, so the recipe bisects its own field to
+  seat the crystals. A `sdfSurface(field, from, dir)` helper would make this reusable.