@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/docs/idea/09-kinds.md

@@ -0,0 +1,105 @@
+# 09 — Kinds
+
+**A kind is a library of builders a recipe calls, not a class the recipe fills in.** `facade(ctx, {...})` adds parts to the caller's `ctx`; the recipe stays in charge of layout, naming and LOD. `kind: '…'` on `defineAsset` is a free string for metadata. Source: `src/kinds/`.
+
+Status as of 2026-11:
+
+| Kind | Builders | Status |
+|---|---|---|
+| Building / tower | `facade`, `setbacks` | Shipped |
+| | `roof` / `roofMesh` (gable, hip, pyramid, mansard, gambrel, shed; chimneys), `opening` (window/door kit), `facade({ kit })`, `mass` (true-scale masonry) | Shipped |
+| Vehicle | `axle`, `trackRun`, `whyteAxles`, `propeller` | Shipped |
+| | lofted bodies, fuselages, wings | Possible now with `loft`, `sweep`; no dedicated builder yet |
+| Vessel | `hull` / `hullMesh` / `hullLines` | Shipped |
+| Vegetation | `tree`, `trees` family, `treeReal`; presets `oak`, `pine`, `palm`, `birch`, `willow` | Shipped |
+| Character | `head` (orc, goblin, human, dwarf, elf via `HEADS`), `headParams`, `headEdits`, `checkHead` | Shipped (stylised busts) |
+| Creature | `creature` (whole bodies, skinned) | Planned, M4 |
+| Scene | `ctx.use` (core), `heightfield` terrain with erosion and `terrainColor` | Shipped |
+| Families | `defineFamily` (core): variants of any kind | Shipped |
+
+## Building / tower
+
+**Masses, then details.** Block the volumes with `box` or `prism`, then wrap them with `facade`.
+
+`facade(ctx, opts)` runs a [split-grammar](#split-grammar) line along each side, per floor. Slots named `win`, `door`, `arch`, `shop` become inset panels; every other symbol stays wall.
+
+| Option | Meaning |
+|---|---|
+| `prefix` | Part name prefix → `<prefix>_<side>_<floor>_<slot>` |
+| `at`, `footprint` | Base centre and `[width X, depth Y]` of the mass it wraps |
+| `floors`, `floorHeight` | Storeys, metres per storey |
+| `grammar`, `ground?` | The line for every floor; `ground` overrides floor 0 |
+| `sides` | Any of `front` (+X), `back`, `left` (+Y), `right` |
+| `glass`, `frame?`, `windowRatio?` | Colours; window height as a fraction of the floor (default 0.6) |
+
+`setbacks(ctx, { prefix, tiers, floorHeight, color, grammar, glass, detail })` stacks shrinking masses (Empire State, Chrysler-style). Each tier: `{ footprint, floors }`. Returns the top z for the spire. Pass `detail: ctx.lod < 2`.
+
+### Split grammar
+
+After CGA shape grammar (Müller et al. 2006). One string lays out one strip.
+
+```
+"pier:0.9 | {arch:2.5}* | door:3 | pier:~"
+```
+
+| Term | Meaning |
+|---|---|
+| `sym:1.2` | Fixed width, metres |
+| `sym:~` / `sym:~2` | Stretch: shares the leftover, by weight (default 1) |
+| `{a:1.4 \| b:0.6}*` | Repeat: as many whole copies as fit. Fixed sizes only; one repeat per line |
+
+With no stretch term, repeat copies widen evenly to fill. Fixed terms longer than the strip → `T3D_GRAMMAR_OVERFLOW`. `split(src, length)` returns `{ symbol, start, size }[]`.
+
+## Vehicle
+
+Named parts follow the engine contract: `axle_*` and `wheel_*` spin about local Y; `prop_*` / `rotor_*` spin about their own axis.
+
+| Builder | Adds | Notes |
+|---|---|---|
+| `axle(ctx, { name, at, radius, gauge, width, color, rps })` | Group `name` (spinning about Y) + `name_wheel_l`, `name_wheel_r` | Segments drop per LOD (24 → 12 → 6) |
+| `trackRun(ctx, { side, y, length, wheels, radius, width, color, track })` | `road_wheel_<side>_<i>` (spinning), `track_<side>_top`, `track_<side>_bottom` | Tracked running gear, one side per call |
+| `whyteAxles('4-4-0', { leading, driving, trailing, spacing })` | Nothing; returns `{ role, x, radius }[]` | Whyte notation → axle positions along X, leading end at +X |
+| `propeller(ctx, { name, at, radius, blades, color, parent? })` | Group spinning about X + hub + blades | |
+
+Domain-native params are the point: a loco recipe says `'2-6-2'`, not twelve wheel coordinates.
+
+## Vessel
+
+`hull(ctx, o)` adds `hull` + `hull_deck`; `hullMesh(o, lod)` returns the mesh for `place`/`merge`; `hullLines(o)` exposes the shape functions. Required: `length`, `beam`, `draft`, `freeboard`, `colors: { topsides, bottom, boot?, deck, bulwark? }`. Optional: `sheer: [bow, stern]`, `stern: 'round' | 'transom'`, `transomWidth`, `fullness`, `entrance`, `flare`, `deadriseDeg`, `bulwark`, `camber`, `bootTop`, `fender`, `at` (the waterline). Bow toward +X. Watertight at every LOD; waterline and boot-top bands are crisp.
+
+## Roofs and openings
+
+Every builder has a pure mesh form (`roofMesh(o, lod)`, `opening(o, lod)`, `mass(o, lod)`) and recipes compose them with `place`/`merge`; `roof(ctx, o)` is the thin ctx wrapper and returns `{ ridge, eave, heightAt(x, y) }`. A roof is the lower envelope of its slope planes, so ridges and hips fall out exactly; the underside sits on the walls' top outer edge, gable and shed ends get infill walls, LOD0/1 add slab thickness, soffit, fascia, ridge/hip caps and chimneys (pots at LOD0), LOD2 is bare slopes (≤ 40 triangles). `opening` is a window or door with a true-scale reveal, sill, lintel, sash and glazing bars; `facade(…, { kit })` places one in every opening slot. `mass` is a wall block whose masonry courses start at the ground line, unlike `box`, which stretches its strip over the face.
+
+## Vegetation
+
+`tree(ctx, { … })`: Weber–Penn botanical skeleton. Recursive branch levels (length, curve, split, taper per level) swept with `sweep`, leaves as cards on the foliage cells (`cutout` surface).
+
+| API | Does |
+|---|---|
+| `tree(ctx, options)` | One tree into the caller's `ctx` |
+| `trees` | A family: `trees.variant({ name, params: { species: 'pine', … } })` |
+| `treeReal(params)` | `real` dimensions for the `proportions` gate |
+| `SPECIES`: `oak`, `pine`, `palm`, `birch`, `willow` | Presets as data (`TreeParams`) |
+
+The `oak`, `pine` and `palm` recipes are about 18 lines each. Wind is a crown `sway` for now. Planned: per-vertex wind weights; LOD2 impostors as crossed billboards from the foliage cells (today's are crude).
+
+## Character
+
+`head(ctx, { race: 'orc' | 'goblin' | 'human' | 'dwarf' | 'elf' | HeadParams, params?, prefix?, at?, jawSway? })` sculpts a stylised head and bust from SDF edits (`sculpt`) and adds `bust` (on z = 0), `head`, `jaw` (pivot at the hinge, optional sway) and `eye_l` / `eye_r` (pivots at the eyeball centres, looking along +X). Races are data (`HEADS`); `params` overrides one level deep; `checkHead` rejects impossible proportions with a fix. Vertex AO is baked at LOD0/1. Recipes: `orc_head`, `goblin_head`, `human_head`.
+
+## Creature (planned, M4)
+
+`creature(ctx, { skeleton: 'biped' | 'quadruped' | 'bird', height })`: SDF flesh over a skeleton, meshed with marching cubes (`sdf` primitive). **Stylised, not realistic.** Bones become named parts for posing. Realistic animals and people go through [`/neural`](08-neural-adapters.md).
+
+## Scene
+
+A scene is an asset whose `build` calls `ctx.use(other, { prefix, at, yaw, seed })`. No special kind is needed. Example (a street of varied houses): [02-dsl.md#composition-ctxuse](02-dsl.md#composition-ctxuse). Planned on top: layout helpers (street grids, scatter on a footprint) built on the split grammar.
+
+Terrain for scenes and presentation dioramas: `heightfield({ rect: [x0, y0, x1, y1], cells: [nx, ny], height: (x, y) => z, color, strip? })`. `color` may be a function of `(x, y, z)` (ruts darker, slopes greener); `cells` is the LOD knob.
+
+## Families and emitters
+
+Any kind can be wrapped in a family: `defineFamily({ defaults, build })` → `variant` / `extend` ([02-dsl](02-dsl.md#families-one-build-many-assets)). Vehicles and buildings add `ctx.emitter` nodes for exhaust, steam, chimney smoke and muzzle flash ([02-dsl](02-dsl.md#emitters)).
+
+Adding a kind: [architecture/adding-a-kind.md](../architecture/adding-a-kind.md).

package/docs/idea/10-sculpting.md

@@ -0,0 +1,166 @@
+# 10 — Sculpting: what artists do, and what it means for SDF edit lists
+
+**Artists fight topology so they can push clay; ts23d has no topology until it meshes. Most of the sculpting toolbox maps onto the existing `sculpt` edit list as new edit kinds, not as a mesh editor.** This page surveys how sculptors work (Blender, ZBrush, the SpeedSculpt add-on), maps each technique onto `src/primitives/sculpt*.ts` and `sdf*.ts`, and proposes the next DSL steps. Research as of 2026-11; everything under "Proposed" is **planned, not shipped**.
+
+## How sculptors work
+
+| Technique | What it does | Source |
+|---|---|---|
+| **Voxel remesh** (Blender Remesh, ZBrush DynaMesh) | Rebuild the whole mesh as an even, manifold grid at one resolution. Blender's Remesh modifier has Blocks / Smooth / Sharp / Voxel modes; Voxel "generate[s] a new manifold mesh from the current geometry" via OpenVDB. Used for **base forms**: merge blobs, keep brush strokes even | [Blender: Remesh](https://docs.blender.org/manual/en/latest/modeling/modifiers/generate/remesh.html), [ZBrush base mesh creation](https://help.maxon.net/zbr/en-us/Content/html/features/main-features/base-mesh-creation/base-mesh-creation.html) |
+| **Dyntopo** (dynamic topology) | Subdivides/collapses under the brush during a stroke: "most brushes will subdivide the mesh during the stroke". Detail size is Relative (screen pixels), Constant (fraction of a unit), Brush or Manual. Used for **local detail** without densifying everything | [Blender: Dyntopo](https://docs.blender.org/manual/en/latest/sculpt_paint/sculpting/tool_settings/dyntopo.html) |
+| **Retopology** (ZRemesher, QuadriFlow, by hand) | After the form is final, a clean low-poly cage with controlled edge flow; community order is "DynaMesh first, ZRemesher last" | [ZBrushCentral thread](https://zbrushcentral.com/t/what-is-the-difference-between-dynamesh-and-zremesher-advantages/324598) (practitioner opinion) |
+| **Skin / ZSpheres** | A vertex-and-edge skeleton with a radius per vertex becomes a mostly-quad tube surface. Blender: one **root** per connected set; **branch smoothing** relaxes joints "with the side effect of shrinking it". ZSpheres: "Adaptive Skin" around a sphere chain | [Blender: Skin](https://docs.blender.org/manual/en/latest/modeling/modifiers/generate/skin.html), [ZBrush ZSpheres](https://help.maxon.net/zbp/en-us/Content/html/4_palettes_tool-3-zsphere-settings.html) |
+| **Lattice deform** | A coarse control cage bends everything inside it; non-destructive, keeps UVs, one lattice drives several objects. Theory: free-form deformation with trivariate Bernstein polynomials (Sederberg & Parry, SIGGRAPH 1986) | [Blender: Lattice modifier](https://docs.blender.org/manual/en/latest/modeling/modifiers/deform/lattice.html), [Sederberg & Parry 1986](https://history.siggraph.org/?p=116034) |
+| **SpeedSculpt** (paid add-on, Pitiwazou) | A workflow wrapper over Blender: build from primitives with auto mirror + parenting, curves, **Draw Skin** (tails, horns), Dyntopo + Remesh, **Geomesh** ("create a final version of your meshes without having to combine them": non-destructive union preview), Booleans, Lattice from a mask, **Quick Pose** (bones for a part), Decimate, masks, cutters. Lathe appears in forum discussion but not on the current product page | [Superhive: SpeedSculpt](https://superhivemarket.com/products/speedsculpt), [Blender Artists thread](https://blenderartists.org/t/speedsculpt-addon/673722) |
+| **Primary → secondary → tertiary** | Block the big planes (skull, cheekbones, sockets, jaw), then features and folds, then surface detail (pores, wrinkles). Stylised work exaggerates primaries and keeps planes crisp | [Polycount discussion](https://polycount.com/discussion/comment/2555887), Gnomon "Sculpting the Planes of the Head" (course; description only) |
+| **Reference planes** | Front and side orthographic images behind the model; today often AI-generated turnarounds. Sculptors check silhouette against them in ortho views | Common practice; no single authoritative source |
+
+**The pattern:** remesh, Dyntopo and retopology all exist because a triangle mesh stores the form *and* its sampling in the same data. Push a region and it runs out of triangles; merge two blobs and the topology tangles. An SDF edit list stores only the form. Sampling happens once, at the end, at whatever `resolution` the LOD asks for.
+
+## What ts23d already has
+
+| Artist concept | ts23d today | Where |
+|---|---|---|
+| Ordered clay edits: add, subtract, intersect, paint | `sculpt({ edits })`, Dreams-style smooth-min fold with `blend` radius; colour rides the same weights | `src/primitives/sculpt.ts`, `sculpt-tree.ts` |
+| Non-destructive booleans (Geomesh) | Edits never collapse; `op: 'subtract' \| 'intersect'`; **groups** fold their own edits first, so a subtract inside a group trims only that group | `sculpt-edit.ts` (`SculptGroup`) |
+| Voxel remesh (base forms) | `sdf()` samples a cubic grid; `resolution` (cell edge, metres) *is* the voxel size and the LOD knob; surface nets (default) or marching cubes; always closed | `sdf.ts`, `sdf-grid.ts`, `surface-nets.ts` |
+| Symmetry (mirror X in Blender) | `mirror: 'y'`, per-edit opt-out | `sculpt.ts` |
+| Primitive library | sphere, ellipsoid, capsule, roundBox, cone, torus + rotation | `sculpt-edit.ts`, `sdf-ops.ts` (`shapes`, `sd`) |
+| Noise displacement (tertiary skin, rock pitting) | `sd.displace(f, valueNoise(rng), amount)`; `sculptField` exposes the field for it | `sdf-ops.ts`, `value-noise.ts` |
+| Primary → secondary → tertiary order | The `head` kind writes skull edits primary → secondary, explicitly "the ZBrush order" | `src/kinds/head-face.ts`, `head-extras.ts` |
+| Hand-painted cavity + top-light tone | `toned()` samples the field: cavity, warm key, cool bounce, into vertex colour | `src/kinds/head-tone.ts` |
+| Smooth normals at low res | Normals from the field gradient, so a coarse LOD2 still shades like the exact surface (vertex-frequency "high→low") | `sdf.ts` |
+| Sparse evaluation | Bounding-sphere skips, 8³ block culling by Lipschitz bound | `sculpt-tree.ts`, `sdf-grid.ts` |
+| Lathe | Polygon `lathe` for hard surface (not an SDF shape) | `lathe.ts` |
+| Lattice | **Name clash:** `lattice` is the truss primitive, not a deformer | `lattice.ts` |
+
+Missing: brush strokes along a path, tapered tubes (draw-skin), revolve as an SDF shape, cage/lattice deformation, bend/twist/taper warps, posing a group about a pivot, adaptive resolution, reference-image overlays.
+
+## Proposed: brushes as SDF edits (planned)
+
+Each brush is a new **edit kind** in the same list, so it composes with groups, mirror, colour and blend for free. Every proposal keeps determinism (pure functions of the edit data) and the zero-dependency rule.
+
+### 1. Strokes: `crease`, `inflate`, `flatten`, `pinch` along a path
+
+```ts
+interface SculptStroke {
+  readonly brush: 'clay' | 'crease' | 'inflate' | 'flatten' | 'pinch';
+  readonly path: readonly Vec3[];          // polyline, metres (a curve stroke)
+  readonly radius: number | readonly number[];   // per path point = pressure taper
+  readonly strength?: number;              // metres of push at the centre, signed
+  readonly falloff?: 'smooth' | 'sharp' | 'linear';
+  readonly color?: Vec3;  readonly mirror?: boolean;
+}
+type SculptEdit = SculptShapeEdit | SculptGroup | SculptStroke;   // sculpt-edit.ts
+```
+
+| Brush | Field operation | Lipschitz cost |
+|---|---|---|
+| `clay` | smooth-union a flattened tapered capsule chain along the path | 1 (exact-ish) |
+| `crease` | smooth-subtract a thin tapered capsule chain with a small `blend`: a V-groove (eyelid fold, armour seam, knuckle) | 1 |
+| `inflate` | `d − strength · w(p)`, w = falloff of distance to the path | 1 + strength/radius |
+| `flatten` | blend `d` toward the distance to the plane fitted through the path, weight w(p) | ≤ 2 |
+| `pinch` | domain warp: pull `p` toward the path by `strength · w(p)` before evaluating everything earlier | 1/(1 − max warp gradient) |
+
+The Lipschitz column matters: `sdf-grid.ts` skips whole 8³ blocks using a Lipschitz bound. Inflate and warps stretch distances, so each stroke must raise the bound it hands to `sampleGrid`, or the grid can cull real surface (a hole, not an error). The compiler sums the bounds; a test fails if a stroke's declared bound is exceeded at sample points. Size: **M** (crease/clay/inflate), **M** more for pinch/flatten.
+
+### 2. Draw-skin: `skin()` as a capsule chain with two radii
+
+```ts
+interface SkinNode { readonly at: Vec3; readonly r: number }
+function skin(o: {
+  nodes: readonly SkinNode[]; edges: readonly (readonly [number, number])[];
+  blend?: number;            // branch smoothing: smooth-min radius at joints (metres)
+  color?: Vec3; op?: 'add' | 'subtract';
+}): SculptGroup;             // pure helper: returns edits, no new evaluator
+```
+
+Needs one new shape: `roundCone` (a capsule with radius `r1` at `at`, `r2` at `to`; Quílez's exact round-cone distance). `blend` *is* Blender's branch smoothing, without the shrink: smooth-min adds material at joints instead of relaxing it away. Tails, horns, tentacles, roots, limbs. The same node graph becomes the bone list for glTF skins later ([gltf-capabilities](../architecture/gltf-capabilities.md#skins-how-ts23d-will-rig-without-auto-rigging)). Size: **S**.
+
+### 3. Revolve: lathe as an SDF shape
+
+`{ shape: 'revolve', profile: Vec2[], at, rotate? }`: the 2D polygon distance evaluated at `(√(x²+y²), z)`. Vases, helmets, pommels, mushroom caps that must blend into organic edits (the polygon `lathe` cannot smooth-union). Size: **S–M**.
+
+### 4. Cage deform (FFD): `ffd()`
+
+Named `ffd` because `lattice` is taken by the truss.
+
+```ts
+interface Ffd {
+  readonly box: readonly [Vec3, Vec3];          // the undeformed cage
+  readonly divisions: readonly [number, number, number];  // control points per axis, 2..6
+  readonly move: ReadonlyArray<{ readonly index: readonly [number, number, number]; readonly by: Vec3 }>;
+}
+function ffd(mesh: Mesh, cage: Ffd): Mesh;      // passes tier: Bernstein FFD on vertices
+```
+
+Apply it **after** meshing, to vertices (Sederberg–Parry forward map), then recompute normals. Works on any mesh (sculpt, loft, lathe, imported), keeps UVs and colours, is exact and cheap. Inverting FFD to warp an SDF query point needs Newton iteration per sample and breaks the Lipschitz cull, so field-space FFD is not proposed. Size: **S–M**. Use: squash a whole bust into a chibi, lean a tower, bulge a barrel.
+
+### 5. Bend, twist, taper on groups
+
+```ts
+interface SculptGroup { /* … */ readonly warp?: { twist?: number /* °/m about local Z */;
+  bend?: number /* °/m */; taper?: number /* scale/m */; pivot?: Vec3; axis?: Vec3 } }
+```
+
+Domain warps on the query point before the group's edits, like Quílez's twist/bend operators; each reports its Lipschitz factor (same rule as strokes). Horns that curl, banners, bent pipes in an organic piece. Size: **S**.
+
+### 6. Quick pose: a group about a pivot
+
+```ts
+interface SculptGroup { /* … */ readonly pose?: { readonly pivot: Vec3; readonly rotate: Vec3 } }
+```
+
+Rotate a whole group (an arm, the jaw, a tail) about a joint before folding. Sculptors pose to check silhouette; here it also prepares rigging: the posed group *is* the joint. Size: **S**.
+
+### 7. Forms as an LOD and review axis
+
+```ts
+interface SculptShapeEdit { /* … */ readonly form?: 'primary' | 'secondary' | 'tertiary' }
+sculpt({ edits, resolution, forms: ctx.pick([['primary','secondary','tertiary'], ['primary','secondary'], ['primary']]) })
+```
+
+Tertiary forms below the cell size cost triangles and alias anyway; dropping them by LOD makes LOD2 cleaner *and* faster to sample. `t3d review` can render a "primary only" view: a stylised character that reads from that view reads at a distance (a classic sculpting check). Size: **S**.
+
+### 8. Reference overlays: front/side images in the contact sheet
+
+```
+t3d shot recipes/goblin_head/goblin_head.ts --ref front=refs/front.png --ref side=refs/side.png
+```
+
+The contact sheet is already orthographic with a metre grid (`src/render/sheet.ts`), so an aligned overlay of a front/side turnaround (AI-generated or drawn) is a blend into the matching tile, plus a silhouette IoU number per view. This is the orthographic cousin of the planned `photoMatch` (`src/render/photo-match.ts`, throws `T3D_NOT_IMPLEMENTED`). Images are inputs only; nothing ships them. Size: **M**.
+
+### 9. Adaptive resolution (the Dyntopo analogue)
+
+Uniform grids spend cells on flat cranium as on lips. Options: an octree of cells refined where `|d| < h` and the edit tree is dense, meshed by dual contouring (Ju et al., SIGGRAPH 2002) to keep sharp features; or a per-edit `detail` hint that refines only inside that edit's bounds. Deterministic if refinement order is fixed. Size: **L**; only worth it once a recipe hits `MAX_POINTS` (`sdf-grid.ts`) or the 1 s budget.
+
+## What not to build
+
+| Idea | Why not |
+|---|---|
+| Interactive mesh brushes on triangle meshes | Stroke-by-stroke mesh mutation is what remesh/Dyntopo exist to patch; it is not text an agent can diff. The edit list is the sculpt |
+| Retopology to quads | glTF engines draw triangles; edge flow matters for subdivision and hand-skinning, neither of which ts23d does. Skin weights come from blend weights instead |
+| Realistic anatomy as a goal | Stylised readable forms are the fit ([07](07-what-fits.md)); realism goes through `importGlb` / `/neural` |
+
+## Next steps for ts23d (prioritised)
+
+1. **`roundCone` shape + `skin()` helper** (draw-skin). S. Unlocks tails, horns, limbs, roots; feeds the `creature` kind (M4).
+2. **`form` tags + `forms` LOD filter** on sculpt edits, and a primary-only review view. S.
+3. **Group `pose` and `warp` (twist/bend/taper)** with declared Lipschitz factors. S.
+4. **`ffd()` cage deform pass** on any mesh (Bernstein, vertices). S–M.
+5. **Strokes: `crease`, `clay`, `inflate`** along a path with a radius taper, Lipschitz-aware culling and a test that catches an under-declared bound. M.
+6. **`--ref front=… side=…` overlays + per-view silhouette IoU** in `t3d shot`. M.
+7. **`revolve` SDF shape.** S–M.
+8. **`pinch` / `flatten` strokes.** M.
+9. **Adaptive (octree / dual contouring) meshing**, only when a recipe needs it. L.
+
+## Sources
+
+- Blender Manual 5.2 LTS: [Remesh](https://docs.blender.org/manual/en/latest/modeling/modifiers/generate/remesh.html) · [Dyntopo](https://docs.blender.org/manual/en/latest/sculpt_paint/sculpting/tool_settings/dyntopo.html) · [Skin](https://docs.blender.org/manual/en/latest/modeling/modifiers/generate/skin.html) · [Lattice](https://docs.blender.org/manual/en/latest/modeling/modifiers/deform/lattice.html)
+- Maxon ZBrush docs: [Base mesh creation (DynaMesh, ZRemesher, ZSpheres)](https://help.maxon.net/zbr/en-us/Content/html/features/main-features/base-mesh-creation/base-mesh-creation.html)
+- SpeedSculpt: [Superhive product page](https://superhivemarket.com/products/speedsculpt), [Blender Artists thread](https://blenderartists.org/t/speedsculpt-addon/673722)
+- T. Sederberg, S. Parry, "Free-form deformation of solid geometric models", SIGGRAPH 1986, [archive](https://history.siggraph.org/?p=116034)
+- A. Evans, "Learning from failure" (Dreams SDF sculpting), SIGGRAPH 2015, [slides](https://advances.realtimerendering.com/s2015/AlexEvans_SIGGRAPH-2015-sml.pdf)
+- I. Quílez, distance functions and domain operators, iquilezles.org/articles/distfunctions (page unreachable when checked 2026-11-07; formulas as widely reproduced)
+- T. Ju et al., "Dual Contouring of Hermite Data", SIGGRAPH 2002
+- Forms order: [Polycount discussion](https://polycount.com/discussion/comment/2555887) (practitioner convention, not a standard)

package/docs/idea/11-materials-authoring.md

@@ -0,0 +1,132 @@
+# 11 — Authoring materials: node graphs, edge wear, and the one trim sheet
+
+**Substance Designer, Material Maker and ArmorPaint all run the same chain: noise → height → normal / AO / curvature → masks → albedo, roughness, metalness. ts23d's painter already runs that chain in TypeScript; what it lacks is curvature, so edges can't wear yet.** This page maps the material-authoring toolbox onto `src/material/` and proposes where edge wear and roughness variation should live, given that every asset shares one trim sheet ([04](04-materials.md), [ADR 008](../decisions/008-surface-materials.md)). Research as of 2026-11; everything under "Proposed" is **planned, not shipped**.
+
+## How material artists work
+
+| Tool | Model | Licence / cost | Source |
+|---|---|---|---|
+| Substance 3D Designer (Adobe) | Node graph of generators and filters, output = tileable PBR maps; **mesh-based mask generators** take baked curvature + AO | Commercial subscription | [Edge Damages node](https://helpx.adobe.com/substance-3d-designer/substance-compositing-graphs/nodes-reference-for-substance-compositing-graphs/node-library/mesh-based-generators/mask-generators/edge-damages.html) |
+| Substance 3D Painter | Paint on the mesh; "smart materials" are generator stacks (Metal Edge Wear, …) driven by baked mesh maps | Commercial | [Metal Edge Wear](https://experienceleague.adobe.com/en/docs/substance-3d-painter/using/effects/generators/metal-edge-wear) |
+| Material Maker | Node graph like Designer, also paints models; built on Godot | MIT ("files in this repository are licensed under the MIT license") | [GitHub](https://github.com/RodZill4/material-maker) |
+| ArmorPaint (ArmorTools) | Painter-style 3D texture painting, node materials | Source zlib/libpng; "Distributed binaries are paid" | [GitHub](https://github.com/armory3d/armortools), [licence](https://raw.githubusercontent.com/armory3d/armortools/main/license.md) |
+| Blender shader nodes + bake | Procedural nodes, baked to images with Cycles | GPL software; output is yours | [Blender licence](https://www.blender.org/about/license/) |
+
+### The chain, step by step
+
+| Step | What artists do | Why |
+|---|---|---|
+| 1. Shapes + noise | Tile generators (bricks, planks), Perlin/cells/fBm, warps | All structure starts as a greyscale field |
+| 2. **Height** | Combine shapes into one height map | The single source of truth: everything else derives from it |
+| 3. Normal | Gradient of height (Sobel / Scharr) at known texel size | Relief that lights correctly |
+| 4. AO / cavity | Blur(height) − height, or ray-marched | Dirt collects, light doesn't reach |
+| 5. **Curvature** | Convex edges (+) vs concave creases (−) from the height Laplacian, or baked from the mesh | Drives edge wear, dust, highlights |
+| 6. Masks | Thresholded noise × curvature × AO; **slope blur in Min mode** to chew a mask edge into chips | Wear goes where it would happen physically |
+| 7. Albedo / roughness / metal | Gradient-map masks into colour, roughness and metalness | Realism lives here: roughness *variation* reads as material more than colour does |
+
+Edge damage specifically: Designer's **Edge Damages** "represents damage done to raised, convex edges based on curvature and baked AO" (both inputs required); Adobe's own tutorial chips a height map with slope blur / multi-directional warp in Min mode, then subtracts the damaged height from the original to extract the damaged areas ([tutorial](https://www.adobe.com/learn/substance-3d-designer/web/create-edge-damage)). Practitioners note low-poly hard edges give weak curvature bakes and UV seams break edge masks ([Unreal forum](https://forums.unrealengine.com/t/help-with-turning-a-curvature-map-into-a-mask-for-edge-wear/48349), [Polycount](https://polycount.com/discussion/comment/2571946)).
+
+## What ts23d already has
+
+| Chain step | ts23d today | Where |
+|---|---|---|
+| Canvas in real metres | Layers `height` (m), `tone`, `rough`, `metal`, `mix` (two-colour blend), `occl` | `src/material/paint/canvas.ts` |
+| Shapes | Running-bond layout shared by bricks, stone, planks, slates, plates; SDF helpers for decal motifs | `paint/courses.ts`, `paint/shapes.ts` |
+| Noise | Seeded, periodic-in-U value noise + fBm (strips tile) | `paint/noise.ts` |
+| Normal | Sobel of height over texel size in metres, glTF tangent space | `paint/normal.ts` |
+| AO / cavity | Blurred height − height, packed into ORM R; mild cavity darkening baked into albedo | `paint/orm.ts` |
+| Masks | `rustStreaks`, `grime` (bottom pooling + rain streaks) | `paint/masks.ts` |
+| Edge chips, texture-space | Paint films with `chips` revealing albedo2 (planks: mostly along board edges; metal; plates: chipped paint on edges) | `paint/planks.ts`, `paint/metal.ts`, `paint/plates.ts` |
+| Measured PBR | 16 library strips with physicallybased.info reflectance, sRGB 30–240 albedo range | `src/material/library.ts` |
+| Project materials | `defineMaterial({ kind, roughness, albedo, albedo2, params, paint })`; a `paint` layer gets a `PaintKit` (tileable noise, hash, smooth, `each`) and is NaN-checked | `define.ts`, `material-def.ts`, `paint/kit.ts` |
+| Image inputs | PNG stamped into cells | `paint/stamp.ts`, `paint/decode-png.ts` |
+| Mesh-space wear | `grime` (vertex colour near ground / zones), `bakeAo` (ray-cast AO into vertex colour), `livery` (paint by rules) | `src/passes/` |
+| Shader-side wear | `ShaderHints.wear`: darkens + roughens **cavities** (1 − AO) and ground grime | `src/material/shader.ts` |
+| Hard-surface realism | `box({ bevel })` chamfers, `weightedNormals` (big faces flat, bevels catch light) | `primitives/bevel-box.ts`, `passes/weighted-normals.ts` |
+
+**The structural constraint.** A strip is shared by every asset and tiles along U, so the texture cannot know where *this* mesh's edges are. Substance bakes curvature per asset; ts23d can't, without giving up one material. So wear splits in two: **texture-space** wear (edges *inside* the pattern: brick arrises, plank ends, plate laps), which belongs in the painter, and **mesh-space** wear (the silhouette edges of this hull), which belongs in vertex data and the shader. Today only cavities are handled mesh-side; convex edges are not.
+
+## Proposed (planned)
+
+### 1. Texture-space curvature and `edgeWear` in the painter
+
+```ts
+// src/material/paint/curvature.ts — Laplacian of height (metres⁻¹), wraps along U for strips
+export function curvature(c: Canvas, radiusMetres: number): Float32Array; // + convex, − concave
+// src/material/paint/masks.ts
+export function edgeWear(c: Canvas, o: {
+  amount: number;        // 0..1, share of convex edge exposed
+  width: number;         // metres of edge the wear can reach
+  chip: number;          // 0..1 noise erosion of the mask edge (slope-blur-min analogue)
+  to: 'albedo2' | 'lighter';   // reveal the second colour (bare metal, raw wood) or just lighten
+  roughness?: number; metalness?: number;   // what is exposed (bare steel: 0.35, 1)
+}, seed: number): void;
+```
+
+Exposed via `PaintKit.curvature()` and a shared `params.edgeWear` (like today's `params.grime`, `paint/strip.ts`), so every strip kind gets it. Chipping: threshold `curvature × (1 + chip·fbm)`, then a min-filter pass in a noise-warped direction: deterministic, a few lines, no GPU. Size: **S**.
+
+### 2. Mesh-space convexity → edge wear in vertex data
+
+```ts
+// src/passes/edge-wear.ts
+export interface EdgeWearOptions {
+  readonly angle?: number;       // dihedral (°) that counts as an edge; default 30
+  readonly width?: number;       // metres the wear spreads from the edge (geodesic, capped)
+  readonly amount: number;       // 0..1
+  readonly lighten?: number;     // vertex-colour lift on worn edges (scuffed paint)
+  readonly attribute?: boolean;  // also write a `_WEAR` 0..1 vertex attribute for the shader
+}
+export function edgeWear(mesh: Mesh, o: EdgeWearOptions): Mesh;
+```
+
+Per-vertex convexity from the signed dihedral angles of incident edges (polygon meshes), or from the field Laplacian for `sdf`/`sculpt` meshes (the SDF Laplacian is the level set's mean curvature up to a convention factor, because |∇d| = 1; [StEik, eq. 14](https://arxiv.org/pdf/2305.18414)). `head-tone.ts` already probes the field for cavity; convexity is the same probe with the other sign. Lightening vertex colour works in every engine with no shader; `_WEAR` follows the `_WIND` precedent and lets `threeMaterialSource` / `godotShaderSource` blend toward bare metal (`mix`, roughness down, metalness up) per pixel. Needs the GLB writer to emit `_WEAR` (an UNOWNED change in `src/export/`). Size: **M**.
+
+### 3. An `edge` trim row: the trim-sheet way to wear edges
+
+Production trim sheets carry dedicated bevel/edge strips: a chamfer mapped to a strip that is painted worn ([docs/idea/13](13-asset-pipeline-research.md#trim-sheets)). `box({ bevel })` already emits chamfer quads; mapping them to a `worn_edge` strip (bright scuffed metal or paint over primer, `edgeWear` at 100%) gives pixel-sharp wear on every bevelled asset with no new attribute and no new material. Costs one strip row (28 rows today, 4 custom slots: `trim-sheet.ts`). Size: **S–M**.
+
+### 4. Roughness variation as a first-class knob
+
+Every painter writes `rough`; add `roughnessVariation` (0..1, default from the library) to `MaterialDef`, applied as low-frequency fBm + cavity-driven increase (dirt is rougher) + edge-driven decrease (handled edges polish). Validate that a strip's roughness histogram is not flat: a `material` test fails a strip whose roughness standard deviation is below a floor (a flat roughness map is the first sign of a CG look). Size: **S**.
+
+### 5. A node-graph-shaped helper API, as functions
+
+Node graphs are hard for agents to diff ([ADR 001](../decisions/001-recipe-compiler-over-ai-meshes.md)); plain composable functions are not. Wrap the painter internals as pure layer ops a `defineMaterial({ paint })` can chain:
+
+```ts
+paint(s, kit) {
+  const h = kit.layer();                        // Float32Array, metres
+  kit.cells(h, { size: 0.04, jitter: 0.8 });    // Voronoi stones
+  kit.add(h, kit.fbm({ size: 0.3, amp: 0.002 }));
+  const wear = kit.mask(kit.curvature(h), { above: 0.6, chip: 0.5 });
+  kit.write(s, { height: h, rough: kit.lerp(0.7, 0.4, wear), mix: wear });
+}
+```
+
+`PaintKit` (`paint/types.ts`) is the place. Ops: `layer`, `fbm`, `cells` (Voronoi/Worley), `tiles`, `warp`, `slopeBlur`, `blur`, `curvature`, `mask`, `levels`, `lerp`, `write`. Each is a tested pure function over typed arrays, periodic in U. Size: **M**.
+
+### 6. Texel-density gate
+
+The sheet is 2048² at 64 px per strip row; a strip is 2 m along U (`trim-sheet.ts`), i.e. ~1024 px/m along U at 2048². Industry examples: 10.24 px/cm first person, 5.12 px/cm third person ([Maxon: Texel density](https://help.maxon.net/c4d/en-us/Content/html/Texel_Density.html)). Strips are anisotropic (V spans `scaleMetres`), so a `texel-density` QA gate should report px/m along U and V per part and flag parts below a target, and faces where V is stretched (the `box` known limit in [04](04-materials.md#known-limits)). The roadmap already lists "Gates: … texel density" (M2). Size: **S–M**.
+
+### 7. CC0 photo textures as *inputs* to strips (not as maps)
+
+ambientCG / Poly Haven / cgbookcase sets are CC0 ([13](13-asset-pipeline-research.md#free-cc0-libraries)). Copying their colour maps into the sheet breaks the greyscale-tint model and the size budget. Better: use them as **calibration** (sample albedo and roughness histograms to set `MaterialDef` numbers, cite the URL in `sources`) and, for a few strips, as a **height source**: a vendored CC0 displacement PNG, resampled to the strip, then run through the same normal/AO/curvature chain so it stays consistent. Vendored with a hash; never fetched at build time. Size: **M**.
+
+## Next steps for ts23d (prioritised)
+
+1. **`curvature()` + `edgeWear` mask in the painter**, exposed as `params.edgeWear` on every strip and on `PaintKit`. S.
+2. **`edgeWear(mesh)` pass**: dihedral convexity (polygon) / Laplacian (SDF) → vertex-colour lift. S–M. Then `_WEAR` attribute + shader-source support. M.
+3. **`roughnessVariation`** on `MaterialDef` + the flat-roughness test. S.
+4. **`worn_edge` strip** mapped by `box({ bevel })` chamfers. S–M.
+5. **`PaintKit` layer ops** (fbm, cells, slopeBlur, mask, levels, lerp, write). M.
+6. **Texel-density gate** (px/m per part, V-stretch warning). S–M.
+7. **CC0 height sources + calibration workflow** documented in the author-recipe skill. M.
+
+## Sources
+
+- Adobe: [Edge Damages](https://helpx.adobe.com/substance-3d-designer/substance-compositing-graphs/nodes-reference-for-substance-compositing-graphs/node-library/mesh-based-generators/mask-generators/edge-damages.html), [Leather Wear](https://helpx.adobe.com/substance-3d-designer/substance-compositing-graphs/nodes-reference-for-substance-compositing-graphs/node-library/mesh-based-generators/mask-generators/leather-wear.html), [Create edge damage tutorial](https://www.adobe.com/learn/substance-3d-designer/web/create-edge-damage), [Painter Metal Edge Wear](https://experienceleague.adobe.com/en/docs/substance-3d-painter/using/effects/generators/metal-edge-wear)
+- [Material Maker](https://github.com/RodZill4/material-maker) (MIT, Godot) · [ArmorTools](https://github.com/armory3d/armortools) (zlib source, paid binaries)
+- Curvature of an SDF: Yang et al., "StEik", 2023, [arXiv:2305.18414](https://arxiv.org/pdf/2305.18414)
+- Texel density examples: [Maxon Cinema 4D docs](https://help.maxon.net/c4d/en-us/Content/html/Texel_Density.html)
+- Edge-mask pitfalls: [Unreal forum](https://forums.unrealengine.com/t/help-with-turning-a-curvature-map-into-a-mask-for-edge-wear/48349), [Polycount](https://polycount.com/discussion/comment/2571946) (practitioner reports)

package/docs/idea/12-blender-bridge.md

@@ -0,0 +1,136 @@
+# 12 — Blender bridge (design + feasibility)
+
+**Status: all planned. Nothing here is shipped, and the core library never needs Blender.** An optional adapter could call a user-installed Blender headless (`blender -b --python`) for things ts23d's CPU paths do not do: Cycles path-traced beauty renders under a CC0 HDRI, high→low bakes, voxel remesh / decimate of imported meshes, and GLB round-trips through other formats. Blender output is not byte-deterministic across versions or hardware, so every Blender result is a **cached input**, keyed by content hash, exactly like the `/neural` cache ([08](08-neural-adapters.md)). Research as of 2026-11-07; Blender was not run on the authoring machine, so every command below is unverified on hardware.
+
+## Why at all
+
+| Need | ts23d today | What Blender adds |
+|---|---|---|
+| Hero image for a README / store page | `beauty()`: zero-GPU rasteriser, key sun + PCF shadows, sky fill, AO, ORM-driven specular (`src/render/beauty.ts`, `shade.ts`) | Path-traced GI, HDRI lighting, depth of field, real glass |
+| Bring in a messy mesh (CC0 base mesh, a sculpt, a neural output) | `importGlb` planned (M5) | Voxel remesh to a manifold, decimate to a budget, clean normals, before ts23d fits it |
+| Per-asset baked maps | Not in the one-sheet model (vertex AO via `bakeAo`) | Selected-to-active normal/AO/curvature bakes, for an opt-in per-asset texture (needs an ADR, see below) |
+| Format reach | GLB only | FBX/USD/OBJ in or out through Blender's importers (out of scope for core; [gltf-capabilities](../architecture/gltf-capabilities.md)) |
+
+Not a reason: modelling. Recipes stay TypeScript; [ADR 001](../decisions/001-recipe-compiler-over-ai-meshes.md) rejected DCC node graphs because agents diff them poorly.
+
+## Verified facts the design rests on
+
+| Fact | Source |
+|---|---|
+| `-b/--background` "Run in background (often used for UI-less rendering)"; `-P/--python <file>`; `--python-expr`; `--python-exit-code <code>` sets the exit code on a Python exception; `--factory-startup` skips the user's startup.blend; `-noaudio`; `--` ends option processing, rest goes to `sys.argv`; `-t/--threads` | [Blender CLI arguments](https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html) |
+| `--python-use-system-env` is *opt-in*: by default Blender's Python ignores `PYTHONPATH` and user site-packages | same |
+| LTS: 5.2 LTS and 4.5 LTS maintained (both updated 2026-10-22), "critical fixes throughout a 2-year time span", no new features or API changes | [Blender LTS](https://www.blender.org/download/lts/) |
+| Bake settings: `use_selected_to_active`, `cage_extrusion` ("Inflate the active object…"), `cage_object`, `max_ray_distance` (0 = no limit) | [bpy BakeSettings](https://docs.blender.org/api/latest/bpy.types.BakeSettings.html) |
+| glTF importer/exporter (Khronos) bundled since 2.80; `bpy.ops.export_scene.gltf(filepath=…, export_format='GLB')` headless | [glTF-Blender-IO](https://github.com/KhronosGroup/glTF-Blender-IO), [example](https://til.jakelazaroff.com/blender/export-a-blender-file-to-glb-from-the-command-line/) |
+| Voxel remesh uses OpenVDB and makes a manifold mesh | [Remesh modifier](https://docs.blender.org/manual/en/latest/modeling/modifiers/generate/remesh.html) |
+| Cycles is not bit-reproducible run to run in general (a user report: identical only with `-t 1`); CPU and GPU tiles drew different random values | [blender#101726](https://projects.blender.org/blender/blender/issues/101726) (could not open, 403; summarised from search), [T72141](https://developer.blender.org/T72141) — treat as unverified |
+| Licence: "What you create with Blender is your sole property"; scripts using the Python API, if published, must be under a GPL-compliant licence | [Blender licence](https://www.blender.org/about/license/) |
+
+## Architecture
+
+```
+ts23d (TypeScript, zero deps)                    user's machine, optional
+─────────────────────────────                    ────────────────────────
+t3d blender render recipe.ts ─┐
+  compile → toGlb (bytes)     │  job.json + in.glb + hdri path
+  hash(job) → cache lookup ───┼─ miss ─► Bun.spawn(blender, ['-b', '--factory-startup',
+                              │            '-noaudio', '--python-exit-code', '3',
+  cache hit: read out.*  ◄────┘            '--python', 'ts23d_job.py', '--', 'job.json'])
+                                         ◄─ out.png / out.glb + report.json (stdout last line)
+.ts23d/blender/<sha256>/{out.*, report.json}   committed or published like the neural cache
+```
+
+| Piece | Where | Notes |
+|---|---|---|
+| Discovery | `blender` on PATH, or `T3D_BLENDER` / `--blender <path>` | Env is read by the **CLI only**, never by `src/` library code (same rule as API keys in [08](08-neural-adapters.md)) |
+| Version pin | `blender --version` parsed; supported list in code (e.g. `['4.5', '5.2']`); others refused | Version (major.minor + build hash) goes into the cache key and `report.json` |
+| Job | A JSON file: `{ op, input, params, seed, ts23dVersion }` | One Python entry script dispatches on `op`; no Python ever imported by TS |
+| Python scripts | `blender/ts23d_job.py` + one file per op, shipped in the npm package as data | GPL-compliant licence required if published (Blender licence page). MIT is generally considered GPL-compatible; **confirm with counsel before publishing** |
+| Module | New `src/blender/` at tier 3 (needs `export` for GLB bytes and `render` types), or `cli`-only | Must stay out of `src/index.ts` main barrel; subpath `@developerz.ai/ts23d/blender`. Needs `scripts/lib/tiers.ts` entry (UNOWNED) |
+| Isolation | `--factory-startup` (no user add-ons, prefs), `--python-use-system-env` **off**, a temp working dir, timeout | User add-ons are the biggest source of "works on my machine" |
+
+### Operations
+
+```ts
+// @developerz.ai/ts23d/blender — planned API, all async, all cache-first
+interface BlenderOptions { readonly blender?: string; readonly cacheDir?: string; readonly offline?: boolean }
+
+render(asset: CompiledAsset, o: BlenderOptions & {
+  hdri?: string;                 // path to a vendored CC0 .hdr/.exr (Poly Haven), hashed into the key
+  camera?: 'hero' | PerspectiveCamera;  // default = beauty()'s cameraFor(), so shots line up
+  samples?: number;              // default 128; denoise: 'oidn' | 'none'
+  size?: readonly [number, number];
+}): Promise<Uint8Array>;          // PNG
+
+remesh(glb: Uint8Array, o: BlenderOptions & { voxel: number; decimate?: number /* target tris */ }): Promise<Uint8Array>;   // GLB
+bake(high: Uint8Array, low: Uint8Array, o: BlenderOptions & {
+  maps: readonly ('normal' | 'ao' | 'curvature')[]; size: 512 | 1024 | 2048;
+  cageExtrusion: number; maxRayDistance?: number;
+}): Promise<Record<string, Uint8Array>>;   // PNGs, low's UVs
+convert(bytes: Uint8Array, o: BlenderOptions & { from: 'fbx' | 'obj' | 'usd'; }): Promise<Uint8Array>;  // → GLB
+```
+
+```
+t3d blender render recipes/t34/t34.ts --hdri refs/studio_small_09_2k.hdr --out renders   # → cycles.png
+t3d blender remesh in/horse.glb --voxel 0.01 --decimate 8000 --out in/horse_clean.glb
+t3d blender bake  --high in/rock_high.glb --low out/rock/lod2.glb --maps normal,ao --size 1024
+t3d blender doctor            # finds Blender, prints version, runs a 1-triangle job, reports timings
+```
+
+Every command prints the cache key and, with `--json`, a machine-readable report, like the rest of the CLI.
+
+## Determinism: how to live with a non-deterministic tool
+
+1. **Blender never runs in the gate.** `bun run verify` and CI never call Blender. Committed `hero.png` stays the CPU `beauty()` render.
+2. **Results are inputs, cached by content.** Key = `sha256(op, params, input bytes, hdri bytes, script bytes, blender version+hash)`. A recipe that consumes a Blender result (say, a remeshed imported mesh) reads it from `.ts23d/blender/<key>/`; the compile stays byte-deterministic because the bytes are fixed.
+3. **Cache miss in CI = error, never a silent rebuild:** `T3D_BLENDER_CACHE_MISS` with `fix: run "t3d blender remesh … " locally with Blender 5.2 and commit .ts23d/blender/<key>`. Share the miss logic with the neural cache (one `src/core` or `src/cache` helper; design choice for the implementer).
+4. **Regeneration is explicit.** `--refresh` deletes the entry and reruns. A version bump of Blender changes the key, so old results keep working until someone regenerates.
+5. **Renders are compared perceptually, not by bytes.** If a Cycles image is ever checked in CI-like flows, compare by a downscaled mean-absolute-error threshold, not a hash. Fixed `scene.cycles.seed`, fixed samples, `-t 1` when bit-stability on one machine matters (slow; per the bug report above).
+6. **Geometry from Blender is normalised on the way back**: ts23d's own `optimize` (weld + Forsyth) runs on the imported mesh, so vertex order no longer depends on Blender internals once cached.
+
+## Errors (proposed codes)
+
+| Code | When | `fix:` |
+|---|---|---|
+| `T3D_BLENDER_NOT_FOUND` | No binary on PATH / flag / `T3D_BLENDER` | Install Blender 5.2 LTS from blender.org, or pass `--blender /path/to/blender` |
+| `T3D_BLENDER_VERSION` | Version not in the supported list | Use 4.5 LTS or 5.2 LTS, or `--allow-blender-version` (key still records it) |
+| `T3D_BLENDER_FAILED` | Non-zero exit (`--python-exit-code`), timeout, missing output | The last 40 lines of Blender's stderr + the job file path to rerun by hand |
+| `T3D_BLENDER_CACHE_MISS` | Offline/CI and no cached result | The exact command that regenerates it |
+
+## High→low baking vs the one-material rule
+
+A Blender normal bake makes a **per-asset** texture; [ADR 008](../decisions/008-surface-materials.md) says every asset shares the trim sheet. Options, in order of preference:
+
+| Option | Keeps one material? | Notes |
+|---|---|---|
+| A. Don't bake normals; SDF meshes already take normals from the exact field at every LOD (`sdf.ts`) | Yes | Covers sculpts today; polygon recipes get `weightedNormals` + bevels |
+| B. Bake AO / curvature into **vertex colour / `_WEAR`** on the low mesh (sample the bake at vertices) | Yes | Cheap; ts23d can do this itself (`bakeAo` exists) without Blender |
+| C. Opt-in `surface: 'baked'` with its own texture set for hero assets | No: a second material per asset | Needs an ADR; only worth it for imported organic hero assets |
+
+Recommendation: ship A/B in core first; Blender baking only serves C, so it waits for that ADR.
+
+## Feasibility
+
+| Item | Feasible? | Effort | Risk |
+|---|---|---|---|
+| `render` (Cycles + HDRI, same camera as `beauty`) | Yes: standard headless pattern | M | Camera/axis conversion (ts23d Z-up +X front → glTF Y-up → Blender Z-up); test against `beauty()` silhouette |
+| `remesh` / `decimate` on imported GLB | Yes | S–M | Vertex colours / UVs lost by voxel remesh; re-colour on the ts23d side (`importGlb` already plans recolouring) |
+| `convert` FBX/OBJ/USD → GLB | Yes | S | Importer quirks per format; GLB stays the only output |
+| `bake` selected-to-active | Yes technically | M–L | Only useful with option C above |
+| CI coverage | Partial | S | Tests mock the spawn (fake `blender` script printing a canned report); a manual `t3d blender doctor` is the real smoke test |
+
+## Next steps for ts23d (prioritised, all planned)
+
+1. **New ADR "Optional external tools"**: Blender runs only via the CLI/subpath, results are cached inputs, never in the gate; licence note on shipped Python. S.
+2. **Shared content-hash cache helper** for `/neural` and `/blender` (key, lookup, miss error). S–M.
+3. **`t3d blender doctor` + discovery + version pin** with the four error codes. S.
+4. **`t3d blender render`** (Cycles, CC0 HDRI path, `beauty()`'s camera), output `cycles.png` beside `hero.png`, never gated. M.
+5. **`remesh` / `decimate` / `convert`** feeding the planned `importGlb`. M.
+6. **Baking** only after an ADR accepts a per-asset `baked` surface. L.
+
+## Sources
+
+- [Blender command-line arguments](https://docs.blender.org/manual/en/latest/advanced/command_line/arguments.html) · [LTS](https://www.blender.org/download/lts/) · [Licence](https://www.blender.org/about/license/)
+- [bpy.types.BakeSettings](https://docs.blender.org/api/latest/bpy.types.BakeSettings.html) · [Remesh modifier](https://docs.blender.org/manual/en/latest/modeling/modifiers/generate/remesh.html)
+- [glTF-Blender-IO](https://github.com/KhronosGroup/glTF-Blender-IO) · [headless GLB export example](https://til.jakelazaroff.com/blender/export-a-blender-file-to-glb-from-the-command-line/)
+- Cycles reproducibility reports: [blender#101726](https://projects.blender.org/blender/blender/issues/101726), [T72141](https://developer.blender.org/T72141) (not opened directly; status unverified)