@developerz.ai/ts23d 0.1.0 → 0.2.0

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)

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/plans/roadmap.md

@@ -66,6 +66,10 @@ Materials:
 - [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)
@@ -110,6 +114,12 @@ Exit bar: a 4-4-0 with tender matching [`docs/reference/loco-photo-match.png`](h
 - [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
 
@@ -118,6 +128,8 @@ Exit bar: a 4-4-0 with tender matching [`docs/reference/loco-photo-match.png`](h
 - [ ] `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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@developerz.ai/ts23d",
-  "version": "0.1.0",
+  "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",
@@ -75,6 +75,7 @@
     "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",

package/recipes/boxcar/README.md

@@ -44,3 +44,10 @@ children `*_wheel_l/_r`) · `door_l`, `door_r` (slide one way toward −X, `oneW
 - Truck centres are not published in the sources found: 9.37 m is scaled from the photo.
 - Lettering is painted on the boards and post faces; the diagonal braces cross over it (a stroke
   painted on a brace face jumps sideways in parallax and garbles the word at 3/4 views).
+
+## Materials
+Painted plank sheathing and door (`wood_painted`: car colour over grey wood, worn at board edges and
+ends), silver-grey running board and saddles (`wood_weathered`), painted steel frame, sills and roof
+(`steel_painted`), sand-cast trucks, wheels and bolsters (`iron_cast`), and rusty hardware: grab
+irons, couplers, brake gear (`iron_rust`). The numbers and sources are in
+`docs/architecture/materials.md`.