@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/.claude/agents/bug-hunter.md

@@ -0,0 +1,21 @@
+---
+name: bug-hunter
+description: Hunts real correctness bugs in a named scope (modules or files) — wrong geometry, broken determinism, bad GLB output, QA gates that pass broken assets. Read-only; reports file:line + reproduction.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+Audit only the scope the brief names. A finding is a defect with evidence: wrong output, a crash, a
+non-deterministic byte, a contract the file's header comment states and the code breaks, a gate that
+passes an asset it should fail.
+
+Hunt list for this repo:
+- winding/normal orientation (backfaces after `place` with negative scale or mirrored frames)
+- UV wrap and metres→UV scale mistakes; trim-sheet regions bleeding into each other
+- GLB layout: alignment, accessor min/max, byteLength, node hierarchy vs parent order
+- world-transform chains (yaw through parents) disagreeing between qa, render and export
+- `ctx.use` prefixing, seed propagation, duplicate names after composition
+- anything reading ambient state (`Math.random`, time, locale, Map iteration order assumptions)
+
+Each finding: `file:line` · one-sentence defect · failing input → wrong output · a minimal repro
+command (`bun -e '…'`). Drop what you can't reproduce. No edits, no git.

package/.claude/agents/docs-author.md

@@ -0,0 +1,13 @@
+---
+name: docs-author
+description: Keeps README, docs/, CHANGELOG and llms.txt true to the code after a change. Give it the diff or the feature; it edits docs only.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+---
+
+Docs follow code, never the reverse. Read the changed code first, then fix every doc that now lies:
+`README.md`, `docs/**`, `CHANGELOG.md` (`## [Unreleased]`), `llms.txt`, `CLAUDE.md` if a rule changed (`AGENTS.md` is a symlink to it).
+Style: lead with the rule, fragments over sentences, tables for ≥3 rows, no fluff, date load-bearing
+claims (`As of YYYY-MM`). Planned features are labelled planned — never describe a stub as shipped.
+Positioning is neutral: ts23d is a free, code-based generator; never claim to beat other tools.
+No git.

package/.claude/agents/dx-auditor.md

@@ -0,0 +1,14 @@
+---
+name: dx-auditor
+description: Audits the agent developer experience — gate speed, error messages (code + fix), CLI --json, docs an agent needs, friction in the recipe loop. Read-only; proposes concrete fixes.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+Run the loop an agent runs: `bun run setup`, write a tiny recipe in `tmp/`, `bun run t3d build`,
+`bun run t3d shot`, break it on purpose (duplicate part, floating part, wrong grammar string, bad
+name) and read what comes back. Time `bun run verify` and each step (`--json` prints ms).
+
+Report friction ranked by cost-per-turn: an error without a `fix:`, a command without `--json`, a step
+over its target (lint < 5 s, unit < 10 s, full gate < 2 min), a doc an agent needed and didn't find, a
+convention enforced only in prose (propose the guard script). No edits, no git.

package/.claude/agents/primitive-author.md

@@ -0,0 +1,22 @@
+---
+name: primitive-author
+description: Adds or completes one geometry primitive or pass in src/primitives or src/passes (e.g. sweep, loft, tiled, cell, sdf) with tests, UVs onto the trim sheet, and LOD knobs. Give it the primitive and its signature in src/primitives/planned.ts.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: opus
+---
+
+Read `CLAUDE.md` and `docs/architecture/adding-a-primitive.md`. You own the primitive's file, its test,
+and its line in the module's `index.ts`. The signature in `planned.ts` is the contract recipes were
+written against — keep it unless the brief says otherwise, and delete the stub when the real one lands.
+
+Requirements:
+- Emits the core `Mesh` IR via `MeshBuilder`; flat or smooth normals deliberately chosen and stated in
+  the header; UVs map onto the trim sheet at true metres (`stripRect`/`cellRect`).
+- Deterministic; no allocation-heavy per-vertex closures in hot loops.
+- One file < 200 LOC; split helpers (like `triangulate.ts`) into siblings.
+- Tests first: bounds, triangle count as a function of the LOD knob, normal orientation, a degenerate
+  input that must throw `Ts23dError` with a fix.
+- `bunx biome check --write <your files>`, `bun test <your test file>`, then `bun run typecheck` once.
+- Use it in one recipe only if the brief gives you that recipe. No git.
+
+Report: the API, test names, triangle formula, and anything the docs must now say.

package/.claude/agents/recipe-author.md

@@ -0,0 +1,36 @@
+---
+name: recipe-author
+description: Writes or upgrades ONE asset recipe (recipes/<name>.ts) to real-asset quality — sourced real dimensions, dense LOD0 detail, lean LOD2 — iterating on contact sheets until it reads as the real thing. Give it the asset, its references, and the file it owns.
+tools: Read, Write, Edit, Glob, Grep, Bash, WebSearch, WebFetch
+model: opus
+---
+
+You author one recipe in `recipes/`. Read `CLAUDE.md`, `docs/idea/02-dsl.md`, `docs/idea/05-agent-loop.md`
+and `src/index.ts` first. Your file set is the one recipe the brief names; never edit `src/`. A missing
+primitive is a finding for your report, not a reason to patch the library.
+
+## The loop — do not skip a step
+1. **Research → dossier.** Spec tables + real photos per view into `recipes/<name>/README.md` (template in
+   `recipes/README.md`; you own that file too). Copy the numbers into `sources`, `real` and 4–8 `measures`.
+2. **Masses first.** Hull/body/tiers with `prism` from real profiles, at true scale. `bun run t3d build
+   recipes/<name>.ts --out out` until QA PASS — `proportions` holds you to `real` ±5%.
+3. **Shoot and LOOK.** `bun run t3d shot recipes/<name>.ts --out renders`, then Read the PNG. Six labelled
+   ortho views on a metre grid. Compare silhouette per view against your references; fix proportions
+   before adding a single detail.
+4. **Detail pass, LOD-gated.** Build each detail once in local space, `place` it N times, `merge` into
+   the part. LOD0: everything a player sees up close (track links, bolts, hatches, handles, cables,
+   tools, vents, rivets). LOD1: drop small parts, fewer segments. LOD2: silhouette, a few hundred tris.
+5. **Grime** (`/passes`) near the ground and at exhausts/chimneys.
+6. Re-shoot, re-read, iterate until a stranger would name the object from the 3/4 view.
+
+## Rules
+- Named parts are the engine contract: `turret`, `gun`, `axle_0`, `wheel_l_3`, `prop_main`, `door_l`.
+  Moving parts get `motion`; yawed parents never also carry motion.
+- `ctx.rng` only. No `Math.random`, no clocks.
+- Budgets are measurements: set them from what LOD0/1/2 actually need, with headroom ≤ 20%.
+- Check only your file: `bunx biome check --write recipes/<name>.ts`, `bun run t3d build …`. Typecheck once at the end.
+- No git operations.
+
+## Report
+Triangles per LOD, QA output, the final contact sheet path, which details are still missing vs the
+references, and any library gap with a concrete API proposal.

package/.claude/agents/visual-reviewer.md

@@ -0,0 +1,23 @@
+---
+name: visual-reviewer
+description: Fresh-eyes visual QA of recipes from their contact sheets against real references. Read-only. Use after a recipe-author finishes, or on a PR's `contact-sheets` artifact.
+tools: Read, Glob, Grep, Bash, WebSearch, WebFetch
+model: opus
+---
+
+You review assets by LOOKING at them. You did not write them; do not assume they are right.
+
+For each recipe in scope: `bun run t3d shot recipes/<name>.ts --out renders` and Read the PNG. Find
+2–3 real reference images/drawings yourself. Judge, per view (3/4 front, front, side, top, 3/4 rear,
+far LOD2):
+
+| Check | Fail when |
+|---|---|
+| silhouette | a stranger could not name it from the 3/4 view |
+| proportions | any major length off the reference by > 5% (use the metre grid) |
+| signature features | the 3 things that make this object THIS object are missing (T-34: sloped glacis, Christie wheels, turret shape) |
+| LOD2 | not recognisable at thumbnail size, or wastes triangles on invisible detail |
+| floating / clipping | visible gaps or interpenetration the QA gate missed |
+
+Report findings as: recipe · view · defect (one sentence) · concrete fix (which part, which number).
+Drop anything you cannot point at in the image. No edits, no git.

package/.claude/commands/feature.md

@@ -0,0 +1,28 @@
+---
+description: Build a feature or sweep with a hive of agents in this ONE checkout — understand, slice by path, build, gate, PR
+argument-hint: <what to build or fix, plain language>
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent, SendMessage, TaskCreate, TaskUpdate, TaskList
+---
+
+Request: $ARGUMENTS
+
+You are the **coordinator**. Read `CLAUDE.md`. Done = `bun run verify` green → PR → merged → CI green
+on main (→ released, if asked).
+
+1. **Understand + falsify.** Read the code the request touches. Docs and plans can be stale; check
+   claims against the code before planning on them.
+2. **Hive only if it pays** (gold-standards hive-mind): broad search or path-separable scale. A change
+   you understand in one or two files — do it yourself.
+3. **Slice by path.** Each slice = an exclusive file set. Two agents needing one file are one slice.
+   Keep an UNOWNED bucket for findings that land outside every slice.
+4. **Brief each agent with the WHY + the nine points:** exclusive files · who else is live on which
+   paths · findings as file:line + failure scenario · permission to drop contradicted findings ·
+   evidence before hypothesis (hypotheses labelled unverified) · house rules (CLAUDE.md) · tests ship
+   with code, failure case first · checks scoped to its own files · **no git at all**.
+   Agents never ask you questions: decide-and-flag, or stop-and-report.
+5. **Never git worktrees.** One checkout, many hands. Only you spawn agents; agents never delegate.
+   Max 4 parallel agents per sweep.
+6. **Collect, interrogate, integrate.** `SendMessage` follow-ups to the agent that owns the files.
+   Look for causal chains across reports. Then ONE `bun run verify`, in the background.
+7. **Ship.** Branch, commit, `gh pr create` (body: what/why, agents × files, contact sheets for
+   recipe changes, deferred items named). Merge on green CI.

package/.claude/commands/new-recipe.md

@@ -0,0 +1,19 @@
+---
+description: Research a real thing (specs + photos) and build it as a ts23d recipe at real-asset quality
+argument-hint: <thing, e.g. "Tiger I mid-production 1943" or "Chrysler Building"> [reference URLs]
+---
+
+Thing: $ARGUMENTS
+
+The human names it; you research it; the library builds it; the gates prove it.
+
+1. **Research first — no code yet.** WebSearch for spec tables (manufacturer data, museum pages,
+   rosters, drawings) and real photos per view (side elevation, front, top, 3/4, details). Pick ONE
+   variant and stay consistent. Write `recipes/<snake_name>/README.md` from the template in `recipes/README.md` (the recipe goes next to it as `recipes/<snake_name>/<snake_name>.ts`):
+   every number with a URL, every photo by view, signature features, engine parts, open questions.
+2. **Recipe.** `recipes/<snake_name>.ts`: copy `sources` and `real` (overall box + 4–8 `measures`)
+   from the dossier. Then follow `.claude/skills/author-recipe/SKILL.md`: masses → QA PASS → shoot →
+   READ the PNG against the dossier photos → LOD-gated detail → grime → iterate.
+3. Big things (a city block, a ship) split into sub-recipes composed with `ctx.use`; one
+   `recipe-author` agent per sub-recipe (disjoint files), then a `visual-reviewer`.
+4. `bun run verify`. Summary: variant, dossier path, tris per LOD (`bun run bench`), contact sheet.

package/.claude/commands/release.md

@@ -0,0 +1,14 @@
+---
+description: Cut a release of @developerz.ai/ts23d (stamp → PR → merge = publish via OIDC)
+argument-hint: <x.y.z>
+---
+
+Version: $ARGUMENTS — follow `PUBLISHING.md`.
+
+1. `bun run verify` on fresh main.
+2. `bun run release $ARGUMENTS` (stamps package.json + CHANGELOG), review the CHANGELOG section.
+3. Branch `release/$ARGUMENTS`, commit `chore: release $ARGUMENTS`, `gh pr create --fill`.
+4. Merge on green. `release-tag.yml` tags `v$ARGUMENTS`, creates the GitHub Release, dispatches
+   `release.yml` → npm publish with provenance via OIDC. Never tag, `gh release create` or
+   `npm publish` by hand.
+5. Confirm: `npm view @developerz.ai/ts23d version` and `gh release view v$ARGUMENTS`.

package/.claude/commands/verify.md

@@ -0,0 +1,9 @@
+---
+description: Run the gate and fix what it reports
+---
+
+Run `bun run verify` (add `--json` if you want machine-readable output; `--only <step>` to re-run one).
+
+Fix every failure at its root, then re-run until green. Never narrow the gate, loosen a Biome rule,
+drop a strict tsconfig flag, raise a budget without a measured reason, or widen a QA tolerance to get
+green. Every `T3D_*` error prints a `fix:` — do that first.

package/.claude/skills/author-recipe/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: author-recipe
+description: The closed agent loop for writing a ts23d asset recipe in TypeScript — research real dimensions, block out masses, compile until QA PASS, render a six-view contact sheet, READ it, add LOD-gated detail, grime, iterate. Use whenever creating or improving anything in recipes/.
+---
+
+# Authoring a recipe
+
+The human names a thing; you research it (specs + real photos) into `recipes/<name>/README.md`; then you build
+it here; the gates prove the model matches the research.
+
+A recipe is a TypeScript module exporting one `defineAsset(...)`. It is code: loops, helpers,
+`ctx.use` composition, `ctx.lod` gating. Never JSON.
+
+## Skeleton
+
+```ts
+// <Name> — <one line>. Real: L × W × H m. Sources below.
+import { beam, box, defineAsset, grime, hex, lathe, merge, place, prism } from '@developerz.ai/ts23d';
+
+const paint = hex('#4b5320');
+
+export const my_asset = defineAsset({
+  name: 'my_asset',
+  kind: 'vehicle',
+  description: '…',
+  tags: ['…'],
+  sources: ['https://…spec table…', 'https://…side elevation…'],
+  real: {
+    length: 6.68, width: 3.0, height: 2.45,
+    measures: [ // spec-sheet numbers, checked on LOD0 to ±2%
+      { label: 'road wheel diameter', axis: 'z', value: 0.83, parts: ['road_wheel_l_0'], source: '…' },
+      { label: 'track centres', axis: 'y', value: 2.45, between: ['track_l', 'track_r'] },
+    ],
+  },
+  budget: { triangles: [40000, 12000, 800] },
+  build(ctx) {
+    const seg = [24, 12, 6][ctx.lod] ?? 6;
+    ctx.part('hull', prism({ plane: 'xz', depth: 3.0, profile: [/* side profile from the drawing */], color: paint }));
+    if (ctx.lod === 0) {
+      const bolt = lathe({ profile: [[0.02, 0], [0.02, 0.01], [0, 0.015]], segments: 6, color: paint });
+      ctx.part('bolts', merge(Array.from({ length: 24 }, (_, i) => place(bolt, { at: [i * 0.2, 1.5, 1.2] }))));
+    }
+  },
+});
+```
+
+## Loop
+| Step | Command | Exit criterion |
+|---|---|---|
+| 1 research | WebSearch + WebFetch: the spec table (manufacturer sheet, museum page, roster, drawing) and real photos per view (side elevation, front, 3/4, top, close-ups of signature details) → `recipes/<name>/README.md` (template: `recipes/README.md`). Link photos, never commit them (licences); Wikimedia Commons is the best first stop. Invented assets (sci-fi, fantasy) get a design dossier instead: scale references from real things, shape language, palette | dossier: every number sourced, one variant chosen, photos linked per view |
+| 2 masses | `bun run t3d build recipes/x/x.ts --out out` | QA PASS: proportions ±5%, measures ±2%, every part's surface touches what holds it, no moving part clashes |
+| 3 look | `bun run t3d shot recipes/x/x.ts --out renders` → Read the sheet PNG; `bun run t3d hero recipes/x/x.ts --out renders` → Read the beauty render | silhouette right in all six views; reads as the real thing in the 3/4 beauty shot |
+| 4 detail | LOD0 dense, LOD1 lean, LOD2 silhouette. Hard surface: `box({ bevel: ctx.pick([0.02, 0.01, 0]) })` + `weightedNormals` (the mid-poly trick); walls: `tiled` / `mass` / `opening` (true-scale masonry, recessed windows); trusses: `lattice`; organic: `sculpt` | budgets met, QA PASS |
+| 5 grime | `grime(mesh, { ground: 1, zones })`; `bakeAo` for crevices | darker near ground / exhausts / creases |
+| 6 review | `bun run t3d review recipes/x/x.ts --out review` → Read `review/*.png`, follow `review/review.md`, clear `review.json` warnings (LOD popping, exposure, tiny-in-frame) | no warnings you can't explain |
+| 7 iterate | repeat 3–6 | a stranger names it from the 3/4 view |
+| 8 publish | `bun run shots <name>` → commit `recipes/<name>/out/` | the recipes gate checks the committed outputs match the recipe |
+
+## Contact sheet layout
+Row 1: 3/4 FRONT · FRONT +X · SIDE -Y. Row 2: TOP · 3/4 REAR · FAR LOD2. Header: name, overall
+dimensions, grid step, LOD. Grid = ground plane, step chosen from the asset size.
+
+## QA gates (all must pass at every LOD)
+| Gate | Fails when | Fix |
+|---|---|---|
+| triangle-budget | LOD over `budget` | drop detail at that LOD |
+| floating-parts | a part's SURFACE is > 2 cm from anything grounded | the support must exist at that LOD too |
+| clashes | anything cuts > 1 cm into a moving part's swept volume | running clearance; `clearOf` only for real interlocks |
+| proportions | overall box off `real` by > 5% | rescale from sources |
+| measures | a spec dimension off by > 2% | rebuild the part — never edit the spec |
+| part-names | not snake_case | rename |
+| check | one of the recipe's own `checks` fails | fix the geometry the check names |
+
+## State your physical intent in code
+Gates can't know that tracks must clear the hull or that wheels interleave without touching —
+the recipe says so, and QA enforces it at every LOD:
+
+```ts
+checks: [
+  clear('track_*', 'hull_*'),        // no sinking into closed solids (+ optional min gap, m)
+  noOverlap('road_wheel_l_*'),       // siblings never interpenetrate
+  touches('turret_body', 'hull_top'),// seated within 2 cm
+  symmetric('_l', '_r', 'y'),        // left mirrors right
+],
+```
+
+Debug with `inspect(compile(asset))` in a scratch script: `distance(a, b)`, `penetration(a, b)`,
+`bounds(glob)`, `parts(glob)` — find the exact offender, fix the cause, never loosen the selector.
+
+## Conventions
+Metres, Z up, +X = front. Named parts are the engine contract. `ctx.rng` only. One asset per
+folder: `recipes/<name>/<name>.ts` + `README.md` + committed `out/`.
+Detail is built once in local space and `place`d N times — never hand-copied coordinates.

package/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to `@developerz.ai/ts23d`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/); in 0.x a minor bump may break. `bun run release <x.y.z>` turns `[Unreleased]` into the dated version section ([PUBLISHING.md](PUBLISHING.md)).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-11-07
+
+### Added
+- Package published as `@developerz.ai/ts23d` (the npm organisation's scope).
+- Material library v2: 16 new PBR strips on a 2048² trim sheet (oak, pine, weathered and painted wood; rusty, cast, painted and galvanised iron/steel; brass, copper, aluminium, chrome; rubber, canvas, leather, plastic) with their own roughness and metalness. `defineMaterial()` registers project materials; opt-in CC0 photo strips (Poly Haven) via `bun run textures` — sha256-pinned, offline compile, credited in the GLB. The beauty renderer reflects metals. `t3d` paints the sheet at 2048² by default.
+- Orc and goblin busts re-sculpted (anatomy, faces, mouths, gear, collectible plinth, painted tone pass); `head` gains `bust.mass`, `wrinkles`, `'vest'` bust style.
+- Boxcar reads as painted planks, weathered roof walk, cast and rusty iron.
+- Gallery: per-category studio lighting, PBR Neutral tone mapping, contact shadows, GTAO + MSAA on a high-quality tier with a phone fallback.
+- Research docs: sculpting, material authoring, Blender bridge design, pro asset pipeline and CC0 libraries.
+- One GLB with all three LODs: `t3d build` also writes `<out>/<asset>/<asset>.glb` — LOD0 in the scene, LOD1/LOD2 as `MSFT_lod` alternates outside it (listed in `extensionsUsed`, never required, so viewers without the extension show LOD0 only), `MSFT_screencoverage` view-distance hints, one shared material/texture set, motion channels on every LOD. `--lods split|single|both` (default `both`); the manifest records `files.single` and `lodCoverage`. API: `toLodGlb` / `exportLodGlb`; recipes may set `lodCoverage: [lod0→1, lod1→2, cull]`, otherwise it is derived from triangle density and size. tiger_1: one 7.07 MB file vs 7.09 MB for three split files (shared sheet); with `--sheet embed`, 10.7 MB vs 17.9 MB.
+
+## [0.1.0] - 2026-11-07
+
+### Added
+- Primitives: `tiled` (true-scale strip tiling, V banded to the strip's real height), `cell` (decal quad with `inset` reveals or raised plaques), `lattice` (Warren / Pratt / Howe / X trusses, square or angle-iron members, planar or box, tapered), `box({ bevel })` (one-segment chamfer for the mid-poly hard-surface look; `bevel: 0` is byte-identical to before).
+- Lettering: `text` sets name boards, wagon lettering, hull markings and signs as geometry from a built-in 5×7 font (Latin, digits, punctuation, Cyrillic; `block` weight), flush or raised, aligned, fitted to `maxWidth`, and kept on top of stepped surfaces with `surface(u, v)`; `measureText` gives the width. `lathe({ uv: 'metres' })` maps the strip at true scale; `lathe({ faceted: true })` makes flat-shaded n-sided solids.
+- Sculpt edits may be groups (`{ group, op, blend, color }`: a subtract inside a group trims only that group); `sculpt({ mirror: 'y' })` / `sdf({ symmetry: 'y' })` give exactly mirror-symmetric meshes; evaluation skips edits whose bounds cannot affect a point (2.4× faster, bit-identical). `bakeAo` reuses its ray grid and walks it allocation-free: 3–4× faster, byte-identical (tiger_1 LOD0 7.2 s → 2.4 s).
+- Organic modelling: `sdf` (surface nets by default, marching cubes on request, gradient normals, sparse evaluation), `sd.*` combinators (sphere, ellipsoid, box, capsule, cone, torus, union, smooth union / subtract, displace), seeded `valueNoise`, and `sculpt` — a Dreams-style ordered edit list (add / subtract / intersect / paint, smooth blends, per-edit colour, `mirror: 'y'`).
+- Characters: `head` kind — a parametric stylised head and bust sculpted from SDF edits, with race presets (`HEADS`: orc, goblin, human, dwarf, elf), a separately pivoted `jaw` (optional sway), aimable `eye_l` / `eye_r`, baked vertex AO, and `headParams` / `headEdits` / `checkHead` for custom races.
+- Terrain: seeded `gradientNoise2` / `valueNoise2`, `fbm`, `billow`, `ridged` (Musgrave), `warp` (domain warping), `terrace`; `terrainGrid`, `sampler`, `slopeMap`; `hydraulicErosion` (droplet erosion with flow and deposit maps; 100k droplets on 257² in ≈0.4 s) and `thermalErosion` (talus); `terrainColor` (forest / grass / scree / rock / snow by altitude, slope and flow); `heightfield({ skirt })` closes a tile into a solid.
+- Kinds: `roof` / `roofMesh` (gable, hip, pyramid, mansard, gambrel, shed; slab, soffit, fascia, ridge and hip caps, gable infill, chimneys; LOD-gated), `opening` window/door kit and `facade({ kit })`, `mass` (true-scale masonry block), `hull` / `hullMesh` / `hullLines` (lofted vessel hull: sheer, stem, round or transom stern, bulwarks, plank deck, waterline and boot-top bands, fenders).
+- Passes: `optimize` (weld, degenerate and duplicate triangle removal, Forsyth vertex-cache order, vertex-fetch order; reports ACMR / ATVR) — on by default in GLB export (tiger_1 LOD0: 254k → 95k vertices, ACMR 2.88 → 1.16, 15.4 → 6.3 MB); `weightedNormals` (face-area × angle weighted, hard-edge split); `bakeAo` / `bakeAoAsset` (deterministic per-vertex ambient occlusion in vertex colour).
+- Export: `exportGlb` returns the bytes plus an optimiser report; `KHR_lights_punctual` from light sockets; emissive glow materials (`KHR_materials_emissive_strength`) from `glow` rules; `KHR_xmp_json_ld` provenance (title, creators, licence, sources) and `asset.copyright`; `asset.generator` names the package version. The glTF-Validator test now demands zero warnings, not just zero errors.
+- Motion: `oneWay: true` on `slide` / `sway` moves from rest to the peak and back (a sliding door, a signal arm dropping) instead of to both sides; the `clashes` gate sweeps a `sway` through its real sector (5° bins) instead of a full revolution, and a one-way slide only along its stroke.
+- Asset definition: `license`, `copyright`, `creators` and `glow` fields; `description` and `sources` travel into the GLB.
+- QA: gates `non-finite`, `vertex-colors`, `hidden-parts`, `normals-winding` (default), `degenerate-triangles`, `z-fighting` (opt-in); cross-LOD gates `lod-triangles` (default, run by the recipes gate), `lod-silhouette`, `lod-pivots` (opt-in).
+- Render: `beauty` / `t3d hero` — a zero-GPU product shot (perspective, trim-sheet textures, sun with soft shadows, sky fill, AO, 2× supersampling, ground contact shadow; tiger_1 at 1600×900 in ≈2.8 s, byte-deterministic). `t3d build` writes `hero.png` too.
+- AI visual QA: `t3d review` writes a review pack — hero, contact sheet, close-ups, an LOD0/1/2 strip, `review.md` (a checklist prompt for a vision agent, pointing at the recipe's dossier) and `review.json` (silhouette coverage, LOD popping IoU per view, exposure, crushed blacks; warnings past thresholds). `maskIoU` is the silhouette core `photoMatch` will use.
+- Site: presentation-first gallery — a live orbiting showcase above the fold, category filters, cards from the committed hero renders (WebP), asset pages with a Studio / Scene viewer, LOD switch, wireframe, part outlines on hover, measures with Δ%, dossier links and GLB downloads; `bun run site:shots` regenerates `docs/media/*.png` with headless Chrome.
+- Recipes are folders: `recipes/<name>/<name>.ts` + `README.md` (the sourced dossier) + committed `out/<asset>/{hero.png, sheet.png, manifest.json}`, refreshed by `bun run shots`; the recipes gate fails on a missing dossier, a stray file or stale outputs.
+- Gallery: `station_halt` (GWR Toddington), `water_tower` (Frisco Beaumont tank), `boxcar` + `boxcar_nw` (USRA single-sheathed), `signal_gantry` + `signal_gantry_4`, `dropship`, `cargo_container_scifi` (ISO 668), `asteroid` ×3, `mountain_range` ×3 (eroded alpine tiles), `boulders`, `orc_head`, `goblin_head`, `human_head`.
+- `@developerz.ai/ts23d/testing`: `assertQaPass`, `assertBudget`, `assertParts`, `assertMeasure`, `assertMotionClear`, `assertDeterministic`, `snapshotHash` — framework-agnostic helpers for your own recipe tests.
+- Docs: [glTF capability map](docs/architecture/gltf-capabilities.md) — every ratified extension, skins and morph targets, physics drafts, what ts23d writes and what is next.
+- `AGENTS.md` is now a link to `CLAUDE.md`: one brain for every coding agent; `CLAUDE.md` gained the "using the library" loop.
+
+### Fixed
+- `applyAffine` / `place` / `frame` with a mirror (negative determinant) left triangles wound inside-out; they are flipped back now (tiger_1's mirrored spare track links).
+- `lathe` smoothed normals across sharp profile folds (the T-34 idler's lip shaded dark); a `creaseDeg` option (default 50°) splits them. Profiles without a fold keep identical bytes.
+- `heightfield` V wrapped per vertex, stretching texture across any triangle that crossed the wrap; it mirrors continuously now.
+- `lathe` / `cylinder` on axis `x` or `y` were wound inside-out (a mirrored frame): every wheel and gun barrel rendered hollow in engines that cull back faces.
+- `SolidIndex` cell size scales with the mesh: the Eiffel tower's 28 solids index in 228 ms (was 4.2 s), which speeds up `clashes` too.
+
+### Added (0.0.x scaffold)
+- Programmatic builds without the CLI documented in the README, with a runnable `examples/build-with-bun.ts` that CI executes.
+- CLI `--lods <list>`: build only the detail levels you need (`--lods 0` for the hero mesh alone); QA, GLBs and `manifest.json` cover exactly those. Every output is opt-in or opt-out: `--sheet none|external|embed`, `--no-animations`, `--no-shot`.
+- Asset DSL: `defineAsset` (with `real` dimensions + `sources`), `compile`, `ctx.part` / `ctx.group` / `ctx.use`, LODs by re-running the recipe.
+- Core: Mesh IR, `MeshBuilder`, seeded forkable RNG, vector math, mesh transforms (`place`, `affine`, `frame`, `applyAffine`), `Ts23dError` with code + cause + fix.
+- Grammar: CGA-style split grammar, Whyte notation.
+- Material: shared trim-sheet layout, era/region palettes, `hex()`.
+- Primitives: `box`, `lathe`, `cylinder`, `prism`, `beam`, `planar`, `triangulate`.
+- Kinds: `facade`, `setbacks`, `axle`, `trackRun`, `whyteAxles`, `propeller`.
+- Passes: `grime`.
+- QA gates: `triangle-budget`, `floating-parts` (true surface contact), `clashes` (moving parts swept through their motion; `clearOf` for intended interlocks), `part-names`, `proportions`, `measures` (`real.measures` spec-sheet dimensions).
+- Export: zero-dependency GLB writer, one material, baked `run` loop; `mergeToPivots` batches static geometry into its nearest pivot by default (`toGlb(asset, { keepParts: true })` opts out).
+- Render: zero-GPU contact sheet (six orthographic views, metre grid).
+- CLI: `t3d build | shot | list` with `--out` and `--json`.
+- Materials: `paintTrimSheet(recipe = DEFAULT_SHEET)` paints albedo / normal / ORM (RGBA8; 1024² ≈ 0.8 s). Strips bond, planks, plates, noise, flat, slate, concrete, glass; 6 decal cells, 11 foliage cells (coloured, alpha leaf mask). `toGlb(a, { sheet })` embeds or `{ sheet: { external: true, prefix } }` references shared PNGs; `TANGENT` only with a sheet.
+- Shader sources: `threeMaterialSource(hints)` (TSL) and `godotShaderSource(hints)` (.gdshader): wind, window glow, wear.
+- CLI: `--sheet external|embed|none` (default external: `out/trim_sheet_{albedo,normal,orm}.png` once, GLBs reference `../trim_sheet_*.png`), `--sheet-size 512|1024|2048`.
+- Primitives: `sweep` (parallel-transport frames, taper, twist), `loft` over `rings` + `ringXY` with wobble; `beam` gains `up` and `caps`.
+- Vegetation: Weber–Penn `tree` kind, presets oak / pine / palm / birch / willow, `trees` family, `treeReal`.
+- Recipes: `tiger_1`, `t34` + `t34_1941`, `loco_440` (4-4-0 Jupiter), `eiffel_tower`, `oak`, `pine`, `palm`, `material_swatches`. Asset gallery site.
+- README benchmarks block filled by `bun run bench --write`.
+- Declared, not built (throw `T3D_NOT_IMPLEMENTED`): `creature`, `localGenerator`, `importGlb`, `kubeezImages`.
+- `defineFamily`: one typed build, many variants (`variant`), derived families (`extend`).
+- `ctx.emitter`: smoke / steam / dust / muzzle / fire / sparks sources as named nodes with `extras.ts23d.emitter`.
+- `sway` motion (`axis`, `degrees`, `hz`); the `clashes` gate sweeps it as a full revolution.
+- `heightfield` primitive for terrain and dioramas.
+- glTF-Validator (Khronos) runs in the test suite on every exported shape: 0 errors required.
+- Recipe checks: `checks: Check[]` on `defineAsset`; builders `clear`, `noOverlap`, `touches`, `symmetric` in `/qa`; gate `check` at every LOD.
+- `inspect(compiled)`: `parts`, `mesh`, `bounds`, `distance`, `penetration` by glob, plus `glob()` and `insideSolid()`, for debugging scripts.
+- `ctx.socket`: seat / mount / camera / audio / attach / spawn / interact / light points as named nodes with `extras.ts23d.socket`.
+- Surfaces: `surface: 'opaque' | 'cutout' | 'glass' | 'translucent'` per part; at most 4 shared materials (glass and translucent via `KHR_materials_transmission`, `_volume`, `_ior`); batching splits per pivot and surface.
+
+### Changed
+- Bun 1.4.4 is the floor (`.bun-version`, `engines.bun`).
+- The site is an asset gallery only; the play mode was removed. ts23d produces assets for your engine and ships no engine or game code.
+- `merge` preallocates its buffers. `symmetric` matches side tokens as whole name segments. `touches` skips LODs where either part is absent. The boundaries guard skips tests and `src/types`.
+- **Breaking:** exported GLBs now face glTF +Z. Root rotation is `[-0.5, -0.5, -0.5, 0.5]` (authoring +X front → glTF +Z, +Z up → +Y). GLBs placed by hand before this face 90° off; rotate them −90° about Y ([ADR 009](docs/decisions/009-gltf-front-axis.md)).
+- Seamless loops: the `run` clip is 4 s, every motion rounded to whole cycles, spins ≥ 12 keys per turn. A static `rest` clip comes first so viewers open paused.
+- Smaller GLBs, core glTF only: u16 indices when ≤ 65,535 vertices; `COLOR_0` as normalised u16 RGBA; shared animation time accessors. tiger_1 LOD0: 13.0 MB → 11.0 MB.
+- QA is much faster: indexed point-in-solid with short-circuited majority rays, cached world meshes and samples, a numeric triangle grid with per-triangle AABB rejection, incremental distance radius. tiger_1 LOD0 QA: minutes → 1.35 s.
+- Animations: `toGlb()` exports none unless `{ animations: true }` (glTF has no autoplay flag; engines drive named pivots from code). `t3d build` bakes the `run` clip by default so viewers show play controls; `--no-animations` skips it.
+- CLI output is one folder per asset: `out/<asset>/{lod0,lod1,lod2}.glb`, `sheet.png`, `manifest.json`, plus `out/index.json`. `t3d build` renders the sheet too (`--no-shot` to skip); `t3d shot` writes sheet + manifest only.

package/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+`AGENTS.md` links here: one brain for Claude Code, Codex, Cursor and the rest, in this repo or in a
+project that installed the package.
+
+## Rules first
+- **Generate assets, not engines.** Output ends at GLB + textures + manifest for Unity, Unreal, Godot, three.js, Babylon or any glTF reader. No game, engine or runtime code here; the site is an asset gallery, never a game.
+- **Code, not data.** Recipes are TypeScript (`recipes/<name>/<name>.ts`), never JSON: loops, functions, `ctx.use` composition.
+- **Deterministic or broken.** Same source + seed = same bytes. `ctx.rng` only; `bun run determinism` refuses the rest.
+- **Real units and references.** Metres, Z up, +X front. Vehicles/buildings declare `real` + `sources` + spec `measures`; gates: `proportions` ±5%, `measures` ±2%. Parts touch their supports (`floating-parts`); moving parts clear everything (`clashes`).
+- **LOD-gate, never decimate.** Recipes read `ctx.lod` and choose what to emit.
+- **One material.** Shared trim sheet, vertex colour, one draw call per asset.
+- **See the result.** Every asset has a contact sheet and a beauty render (`hero.png`); every error has a code and `fix:`.
+- **Enforce rules.** A rule without a script in `bun run verify` is a suggestion.
+
+## Project and stack
+`@developerz.ai/ts23d`: free, coding-agent-driven 3D asset generator. Deterministic game-ready GLB: named pivoted parts, baked motion, 3 LODs from one source, shared trim-sheet material, build-failing QA and zero-GPU six-view contact sheets the agent reads.
+
+| Area | Stack / constraint |
+|---|---|
+| Library | TypeScript; Bun only (pin: `.bun-version`); zero runtime dependencies |
+| Gallery | Vite + three.js; site may depend on three/vite; compiles recipes in-browser |
+| Status | 0.x; anything unbuilt throws `T3D_NOT_IMPLEMENTED` on purpose; `docs/plans/roadmap.md` owns delivery |
+
+## Non-negotiables
+- **No `any`, non-null `!` or default exports; `import type` for types.** Biome fails the build.
+- **No bare `Error` in `src/`.** Use `Ts23dError(code, { cause, fix })`; shipped `T3D_*` codes stay stable.
+- **SRP.** One file, one job; target < 200 LOC, ceiling 300 (`bun run filesize`); header comment states the job.
+- **Tests beside source, failure case first.** A test that can't fail isn't one.
+- **Planned ≠ shipped.** Label stubs as planned; `notImplemented()` names the plan.
+- **Neutral positioning.** Never claim to beat Meshy/Tripo/etc.; we're the free, code-based option.
+
+## Commands (repo root)
+| Task | Command |
+|---|---|
+| Fresh clone → ready | `bun run setup` |
+| Gate (≡ CI) | `bun run verify` · one step: `bun run verify --only <step>` · `--json` |
+| Compile + QA recipe | `bun run t3d build recipes/t34/t34.ts --out out` (lod0/1/2.glb + one `<asset>.glb` with all LODs via MSFT_lod; `--lods split\|single\|both`) |
+| Contact sheet (READ the PNG) | `bun run t3d shot recipes/t34/t34.ts --out renders` |
+| Beauty render (3/4, textured, shadowed) | `bun run t3d hero recipes/t34/t34.ts --out renders` |
+| AI review pack (READ `review/*.png`, follow `review.md`) | `bun run t3d review recipes/t34/t34.ts --out review` |
+| Refresh committed `recipes/*/out/` | `bun run shots [name…]` (the recipes gate fails on stale outputs) |
+| One test file | `bun test src/primitives/prism.test.ts` |
+| Lint fix | `bun run lint:fix` |
+| Gallery | `bun run site:dev` · `bun run site:build` |
+| Release | `bun run release <x.y.z>` → PR `chore: release x.y.z` → merge; see `PUBLISHING.md` |
+
+Gate order (`STEPS` in `scripts/verify.ts`): lint · typecheck · boundaries · determinism · filesize · test · recipes · build.
+
+## Layout
+| Path | Responsibility |
+|---|---|
+| `src/<module>/` | Library; one responsibility per module, tiered below |
+| `src/index.ts` | Public barrel; subpaths `@developerz.ai/ts23d/<module>` |
+| `recipes/<name>/` | One folder per asset: `<name>.ts` · `README.md` (sourced specs + photo links, written first) · `out/<asset>/` (committed hero.png, sheet.png, manifest.json); CI-gated |
+| `apps/site/` | GitHub Pages asset gallery |
+| `scripts/` | Gate/guards, release/build/setup; tested Bun TypeScript |
+| `docs/` | `idea/` (what+why), `decisions/` (ADRs), `architecture/`, `plans/roadmap.md` |
+| `.claude/` · `.dz/` | Repo agents/commands/skills · developerz.ai bot policy |
+
+## Module tiers — imports only go DOWN
+| Tier | Modules |
+|---|---|
+| 0 | `core` (IR, asset DSL, transforms, rng, errors) |
+| 1 | `grammar` (split, Whyte) · `material` (trim sheet, palettes, generator) |
+| 2 | `primitives` · `passes` · `neural` (optional AI adapters) |
+| 3 | `kinds` · `qa` · `export` · `render` |
+| 4 | `cli` · `testing` (assertions for users' recipe tests) |
+
+Cross-module imports use `../<module>/index.ts` only. `bun run boundaries` enforces this; `scripts/lib/tiers.ts` is the executable tier table.
+
+## Recipe loop
+Human names a thing → research specs + real photos into `recipes/<name>/README.md` → `real` + `sources` + `measures` → masses → `t3d build` until QA PASS → `t3d shot` + `t3d hero` → **Read the PNGs** → `t3d review` → LOD-gated detail (build once, `place` N times, `merge`) → `grime` → iterate → `bun run shots <name>`. Full skill: `.claude/skills/author-recipe/SKILL.md`. Quality: competes with real game assets up close; a few hundred triangles at LOD2.
+
+## Coordination and CI
+- **Finish the job:** fix, test, document, run the gate. Decide and state decisions rather than asking what code/docs answer. Ask only before irreversible/outward-facing acts.
+- **Hive** (big tasks: `/feature`): one checkout, never git worktrees; only the top-level agent spawns; exclusive file sets, no git for agents; max 4 parallel; coordinator runs the full gate once at the end.
+- **CI:** free GitHub runners, < 5 min. `ci.yml`: `verify` (= `bun run verify`) + `shots` (contact-sheet artifact per PR). `pages.yml`: gallery to developerz-ai.github.io/ts23d. `release-tag.yml` + `release.yml`: release PR merge → tag → npm via OIDC (no tokens). Every action SHA-pinned; Dependabot moves pins.
+
+## Using the library in another project
+`bun add @developerz.ai/ts23d`, write `assets/<name>.ts` exporting `defineAsset({...})`, then
+`bunx t3d build assets/<name>.ts --out out` (GLB × 3 LODs + QA, exit 1 on a finding) and
+`bunx t3d shot` / `hero` / `review` to look. Fix what QA prints (every finding has a `fix:`) and what
+you see. No CLI needed: the same steps are functions (`compile`, `runQa`, `toGlb`, `contactSheet`,
+`beauty`), see `examples/build-with-bun.ts`; test helpers in `@developerz.ai/ts23d/testing`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.