@developerz.ai/ts23d 0.1.0 → 0.2.0

package/dist/material/paint/canvas.d.ts

@@ -1,3 +1,4 @@
+import type { Vec3 } from '../../core/index.js';
 export interface Canvas {
     readonly w: number;
     readonly h: number;
@@ -12,8 +13,14 @@ export interface Canvas {
     readonly metal: Float32Array;
     /** Extra occlusion multiplied into the cavity AO (foliage darkens toward the twig). */
     readonly occl: Float32Array;
+    /** 0 = `colours[0]`, 1 = `colours[1]` (latewood, rust, bare wood under chipped paint…). */
+    readonly mix: Float32Array;
+    /** Linear albedo pair for material strips; null = greyscale (vertex colour carries hue). */
+    colours: readonly [Vec3, Vec3] | null;
     /** sRGB RGBA override (stamped images, coloured foliage); null when painted greyscale. */
     rgba: Uint8Array | null;
+    /** Tangent-space normal override (image strips); null = derived from `height`. */
+    normalRgba: Uint8Array | null;
 }
 export declare function createCanvas(w: number, h: number, metresU: number, metresV: number, wrapU: boolean): Canvas;
 /** Metres per pixel along x and y. */

package/dist/material/paint/default-sheet.d.ts

@@ -1,2 +1,4 @@
-import type { SheetRecipe } from './types.js';
+import type { StripId } from '../trim-sheet.js';
+import type { SheetRecipe, StripRecipe } from './types.js';
+export declare const HOUSE_STRIPS: Partial<Record<StripId, StripRecipe>>;
 export declare const DEFAULT_SHEET: SheetRecipe;

package/dist/material/paint/fabric.d.ts

@@ -0,0 +1,4 @@
+import { type Canvas } from './canvas.js';
+import type { StripRecipe } from './types.js';
+export declare function paintWeave(c: Canvas, r: StripRecipe, seed: number): void;
+export declare function paintLeather(c: Canvas, r: StripRecipe, seed: number): void;

package/dist/material/paint/image-strip.d.ts

@@ -0,0 +1,4 @@
+import type { TextureSource } from '../texture-source.js';
+import type { Canvas } from './canvas.js';
+import type { StripRecipe } from './types.js';
+export declare function paintImageStrip(c: Canvas, r: StripRecipe, t: TextureSource, where: string): void;

package/dist/material/paint/kit.d.ts

@@ -0,0 +1,5 @@
+import { type Canvas } from './canvas.js';
+import type { PaintKit } from './types.js';
+export declare function paintKit(c: Canvas, seed: number): PaintKit;
+/** Throw T3D_MATERIAL_INVALID if any layer holds a non-finite value. */
+export declare function checkFinite(c: Canvas, where: string): void;

package/dist/material/paint/metal.d.ts

@@ -0,0 +1,3 @@
+import { type Canvas } from './canvas.js';
+import type { StripRecipe } from './types.js';
+export declare function paintMetal(c: Canvas, r: StripRecipe, seed: number): void;

package/dist/material/paint/orm.d.ts

@@ -4,5 +4,5 @@ export declare function cavityOcclusion(c: Canvas): Float32Array;
 export declare const SRGB: Uint8Array<ArrayBuffer>;
 /** RGBA8 ORM: R = occlusion, G = roughness, B = metalness, A = 255. */
 export declare function packOrm(c: Canvas, ao: Float32Array): Uint8Array;
-/** RGBA8 sRGB albedo: the stamped image if any, else grey tone × mild cavity. */
+/** RGBA8 sRGB albedo: the stamped image if any, else (colour pair by mix or grey) × tone × cavity. */
 export declare function packAlbedo(c: Canvas, ao: Float32Array): Uint8Array;

package/dist/material/paint/strip.d.ts

@@ -1,3 +1,3 @@
 import type { Canvas } from './canvas.js';
 import type { StripRecipe } from './types.js';
-export declare function paintStrip(c: Canvas, r: StripRecipe, seed: number): void;
+export declare function paintStrip(c: Canvas, r: StripRecipe, seed: number, where?: string): void;

package/dist/material/paint/types.d.ts

@@ -1,14 +1,36 @@
+import type { Vec3 } from '../../core/index.js';
+import type { TextureSource } from '../texture-source.js';
 import type { CellId, StripId } from '../trim-sheet.js';
+import type { Canvas } from './canvas.js';
 export interface PaintedSheet {
     readonly size: number;
-    /** RGBA8, sRGB. Near-greyscale: hue comes from vertex colour multiplied over it. */
+    /** RGBA8, sRGB. Classic strips are greyscale (vertex colour carries hue); materials carry colour. */
     readonly albedo: Uint8Array;
     /** RGBA8, tangent-space (glTF / OpenGL, +Y toward decreasing V). */
     readonly normal: Uint8Array;
     /** R = occlusion, G = roughness, B = metalness. */
     readonly orm: Uint8Array;
 }
-export type StripKind = 'bond' | 'planks' | 'plates' | 'noise' | 'flat' | 'slate' | 'concrete' | 'glass';
+export type StripKind = 'bond' | 'planks' | 'plates' | 'noise' | 'flat' | 'slate' | 'concrete' | 'glass' | 'metal' | 'weave' | 'leather';
+/**
+ * The surface a painter writes, one float per texel per layer, in real metres. Row y grows with
+ * world up (+V); strips wrap along x. Layers: `height` (metres, + is out), `tone` (linear
+ * brightness multiplier), `rough` and `metal` (0–1), `mix` (0 = albedo, 1 = albedo2), `occl`.
+ */
+export type MaterialSurface = Canvas;
+/** Helpers handed to a custom painter: seeded, tileable noise and smoothstep, all in metres. */
+export interface PaintKit {
+    readonly seed: number;
+    /** Tileable fBm in [−1, 1] with feature size `sizeU` × `sizeV` metres; `salt` varies it. */
+    noise(xm: number, ym: number, sizeU: number, sizeV: number, salt?: number, octaves?: number): number;
+    /** Integer hash in [0, 1). */
+    hash(a: number, b: number, salt?: number): number;
+    smooth(e0: number, e1: number, v: number): number;
+    /** Visit every texel: index into the layers and its centre in metres. */
+    each(fn: (i: number, xm: number, ym: number) => void): void;
+}
+/** A project painter: runs after the base `kind`, layering its own pattern over it. */
+export type MaterialPainter = (s: MaterialSurface, kit: PaintKit) => void;
 export interface StripRecipe {
     readonly kind: StripKind;
     /**
@@ -20,6 +42,14 @@ export interface StripRecipe {
     readonly metalness?: number;
     /** Brick/plank courses, rivet pitch, etc. — read per kind (see each painter's header). */
     readonly params?: Readonly<Record<string, number>>;
+    /** Intrinsic linear albedo; omitted = white (greyscale strip, vertex colour carries hue). */
+    readonly albedo?: Vec3;
+    /** Second linear albedo the painter blends to through `mix` (latewood, rust, bare wood…). */
+    readonly albedo2?: Vec3;
+    /** Extra layer painted after `kind` (see `defineMaterial`). */
+    readonly paint?: MaterialPainter;
+    /** Paint from a cached CC0 texture set instead of `kind` (see texture-source.ts). */
+    readonly texture?: TextureSource;
 }
 /** A cell stamped from PNG bytes (8-bit grey/RGB/RGBA, non-interlaced), e.g. a kubeez.com decal. */
 export interface CellImage {

package/dist/material/palette.d.ts

@@ -2,6 +2,8 @@ import type { Vec3 } from '../core/index.js';
 export type Palette = Readonly<Record<string, Vec3>>;
 /** sRGB hex → linear RGB, the space glTF vertex colours are in. */
 export declare function hex(value: string): Vec3;
+/** Vertex colour for material strips that carry their own colour (oak, brass, rubber…). */
+export declare const NATURAL: Vec3;
 export declare function definePalette(entries: Readonly<Record<string, string>>): Palette;
 /** Era/region palettes ship as data; recipes extend them with object spread. */
 export declare const palettes: {

package/dist/material/slots.d.ts

@@ -0,0 +1,5 @@
+/** Slot index among the custom strips, or −1. */
+export declare const customIndex: (id: string) => number;
+export declare const customIds: () => readonly string[];
+export declare function pushCustom(id: string): number;
+export declare function clearCustom(): void;

package/dist/material/texture-source.d.ts

@@ -0,0 +1,34 @@
+export interface TextureFile {
+    /** Download URL (https) or, for `source: 'file'`, a path relative to the working directory. */
+    readonly url: string;
+    /** Lower-case hex sha256 of the file's bytes: the cache key and the integrity check. */
+    readonly sha256: string;
+}
+export interface TextureSource {
+    readonly source: 'polyhaven' | 'ambientcg' | 'file';
+    /** The set's id at the source, e.g. 'wood_planks_grey'. */
+    readonly id: string;
+    /** Only public-domain sets are accepted, so a generated asset never inherits a licence duty. */
+    readonly license: 'CC0-1.0';
+    /** Human page crediting the set (goes into the GLB's XMP credits). */
+    readonly page: string;
+    readonly author?: string;
+    /** Real-world size the image covers, metres (U × V). Poly Haven lists it as `dimensions`. */
+    readonly metres: readonly [number, number];
+    readonly maps: {
+        /** sRGB base colour. */
+        readonly albedo: TextureFile;
+        /** Tangent-space normal, OpenGL convention (+Y up in the image; Poly Haven `nor_gl`). */
+        readonly normal?: TextureFile;
+        /** Packed AO / roughness / metalness (Poly Haven `arm`, glTF ORM order). */
+        readonly arm?: TextureFile;
+    };
+}
+/** PNG bytes by sha256. */
+export type TextureCache = ReadonlyMap<string, Uint8Array>;
+/** Hand verified texture bytes to the painter (e.g. from `loadTextureCache()` in scripts). */
+export declare function provideTextures(cache: TextureCache): void;
+export declare function textureBytes(file: TextureFile, where: string): Uint8Array;
+export declare function validateTexture(id: string, t: TextureSource): void;
+/** One credit line for the GLB's XMP and the docs. */
+export declare const creditOf: (t: TextureSource) => string;

package/dist/material/trim-sheet.d.ts

@@ -1,4 +1,13 @@
-export type StripId = 'plain' | 'brick' | 'stone' | 'slate' | 'iron' | 'wood' | 'glass' | 'concrete';
+/** The original eight strips: greyscale, tinted by vertex colour. */
+export type ClassicStripId = 'plain' | 'brick' | 'stone' | 'slate' | 'iron' | 'wood' | 'glass' | 'concrete';
+/** Material strips with measured colour: use a near-white vertex colour (`NATURAL`) for truth. */
+export type MaterialStripId = 'oak' | 'pine' | 'wood_weathered' | 'wood_painted' | 'iron_rust' | 'iron_cast' | 'steel_painted' | 'steel_galvanised' | 'brass' | 'copper' | 'aluminium' | 'chrome' | 'rubber' | 'canvas' | 'leather' | 'plastic';
+export type BuiltinStripId = ClassicStripId | MaterialStripId;
+/** A project material's id, as returned by `defineMaterial` (a branded string). */
+export type CustomStripId = string & {
+    readonly __ts23dMaterial: true;
+};
+export type StripId = BuiltinStripId | CustomStripId;
 export type DecalCellId = 'window_sash' | 'door_panel' | 'clock' | 'smokebox' | 'sign' | 'porthole';
 /** Cutout leaf cards: the anchor (twig base) is the cell's bottom-centre, growth toward +V. */
 export type FoliageCellId = 'foliage_broadleaf' | 'foliage_maple' | 'foliage_maple_autumn' | 'foliage_birch' | 'foliage_acacia' | 'foliage_palm' | 'foliage_spruce' | 'foliage_spruce_snow' | 'foliage_willow' | 'foliage_reeds' | 'foliage_needles';
@@ -11,11 +20,18 @@ export interface UvRect {
     /** Metres of world surface one full rect covers, so texel density is equal across assets. */
     readonly metres: number;
 }
-export declare const TRIM_SHEET_SIZE = 1024;
+/** Strip rows in the atlas: built-ins first, then `CUSTOM_STRIP_SLOTS` project materials. */
+export declare const STRIP_ROWS = 28;
+export declare const CUSTOM_STRIP_SLOTS: number;
+export declare const TRIM_SHEET_SIZE = 2048;
+/** Atlas row of a strip id, or −1 when it is neither built in nor defined. */
+export declare function stripRow(id: string): number;
 export declare function stripRect(id: StripId): UvRect;
-/** Cells sit in the lower half (V ≥ 0.5), 8 per row: decals on row 0, foliage from row 1. */
 export declare function cellRect(id: CellId): UvRect;
-export declare const STRIPS: readonly StripId[];
+/** Every built-in strip, classic first. */
+export declare const STRIPS: readonly BuiltinStripId[];
+export declare const CLASSIC_STRIPS: readonly ClassicStripId[];
+export declare const MATERIAL_STRIPS: readonly MaterialStripId[];
 export declare const CELLS: readonly CellId[];
 export declare const DECAL_CELLS: readonly DecalCellId[];
 export declare const FOLIAGE_CELLS: readonly FoliageCellId[];

package/dist/neural/index.js

@@ -2,8 +2,8 @@ import {
   localGenerator2,
   importGlb2,
   kubeezImages2
-} from "../chunk-a8fxakcj.js";
-import"../chunk-4ddzsqtc.js";
+} from "../chunk-6b05mnmx.js";
+import"../chunk-hg7pf34j.js";
 export {
   importGlb2 as importGlb,
   kubeezImages2 as kubeezImages,

package/dist/passes/index.js

@@ -6,8 +6,8 @@ import {
   livery2,
   optimize2,
   weightedNormals2
-} from "../chunk-xnt2sdhf.js";
-import"../chunk-4ddzsqtc.js";
+} from "../chunk-drna2rny.js";
+import"../chunk-hg7pf34j.js";
 export {
   RayGrid2 as RayGrid,
   bakeAo2 as bakeAo,

package/dist/primitives/index.js

@@ -35,9 +35,9 @@ import {
   text2,
   tiled2,
   valueNoise3
-} from "../chunk-wtqhq529.js";
-import"../chunk-kvcep7ft.js";
-import"../chunk-4ddzsqtc.js";
+} from "../chunk-d1fv6hrm.js";
+import"../chunk-y63c6zcv.js";
+import"../chunk-hg7pf34j.js";
 export {
   arcLengths2 as arcLengths,
   beam2 as beam,

package/dist/qa/index.js

@@ -34,8 +34,8 @@ import {
   lodPivots2,
   DEFAULT_LOD_GATES2,
   runLodQa2
-} from "../chunk-w1zyhj40.js";
-import"../chunk-4ddzsqtc.js";
+} from "../chunk-jq4e17tj.js";
+import"../chunk-hg7pf34j.js";
 export {
   CLASH_EPS2 as CLASH_EPS,
   CONTACT_EPS2 as CONTACT_EPS,

package/dist/render/beauty.d.ts

@@ -13,7 +13,7 @@ export interface BeautyOptions {
     readonly fovDeg?: number;
     /** Samples per pixel edge (1–4). Default 2 (4 samples per pixel). */
     readonly supersample?: number;
-    /** The painted trim sheet; default paints `DEFAULT_SHEET` at 512² once per process. */
+    /** The painted trim sheet; default paints `DEFAULT_SHEET` at 1024² once per process. */
     readonly sheet?: PaintedSheet;
     /** Zoom into the default framing: window centre (0–1, 0–1) of the full shot and a zoom ≥ 1. */
     readonly window?: {

package/dist/render/index.js

@@ -18,9 +18,9 @@ import {
   detailWindows2,
   reviewPack2,
   thumbnail2
-} from "../chunk-11v28977.js";
-import"../chunk-kvcep7ft.js";
-import"../chunk-4ddzsqtc.js";
+} from "../chunk-f6yme003.js";
+import"../chunk-y63c6zcv.js";
+import"../chunk-hg7pf34j.js";
 export {
   REVIEW_THRESHOLDS2 as REVIEW_THRESHOLDS,
   VIEWS2 as VIEWS,

package/dist/render/lighting.d.ts

@@ -10,6 +10,13 @@ export interface Rig {
     readonly exposure: number;
 }
 export declare function studioRig(cameraAzDeg: number): Rig;
+/**
+ * The studio environment a reflection sees, channel `k`, along a reflection vector with up
+ * component `rz`: a bright cyclorama horizon fading to a cooler zenith, a dark band where the
+ * floor meets the wall, the lit floor below. Roughness pre-blurs it toward its mean, so polished
+ * metal shows the horizon line and rough metal a soft gradient — what makes metal read as metal.
+ */
+export declare function envRadiance(rz: number, rough: number, k: number): number;
 export declare function pcfTaps(radius: number): Float32Array[];
 /**
  * Tone curve, linear in → linear display out: identity up to 0.6 (mid-tones and the palette stay

package/dist/render/shade.d.ts

@@ -1,6 +1,6 @@
 import type { PerspectiveCamera } from './camera.js';
 import { type DepthMap } from './depth-map.js';
-import type { Rig } from './lighting.js';
+import { type Rig } from './lighting.js';
 import type { Scene } from './scene.js';
 import { type SheetTextures } from './texture.js';
 export interface ShadeContext {

package/dist/testing/index.js

@@ -1,7 +1,7 @@
 import {
   Ts23dError2,
   compile2
-} from "../chunk-4ddzsqtc.js";
+} from "../chunk-hg7pf34j.js";
 import {
   glob2,
   clashes2,
@@ -10,12 +10,12 @@ import {
   runQa2,
   DEFAULT_LOD_GATES2,
   runLodQa2
-} from "../chunk-w1zyhj40.js";
-import"../chunk-kvcep7ft.js";
-import"../chunk-xnt2sdhf.js";
+} from "../chunk-jq4e17tj.js";
+import"../chunk-y63c6zcv.js";
+import"../chunk-drna2rny.js";
 import {
   exportGlb2
-} from "../chunk-gcyp9b4d.js";
+} from "../chunk-dbq4qf52.js";
 
 // src/testing/compiled.ts
 var ALL_LODS = [0, 1, 2];

package/docs/README.md

@@ -30,6 +30,10 @@
 | [07-what-fits.md](idea/07-what-fits.md) | Fit matrix by asset category |
 | [08-neural-adapters.md](idea/08-neural-adapters.md) | Optional local-GPU models for organic shapes, image sources |
 | [09-kinds.md](idea/09-kinds.md) | Domain builders: building, vehicle, vessel, vegetation, creature, scene |
+| [10-sculpting.md](idea/10-sculpting.md) | How artists sculpt, mapped onto SDF edit lists; brushes, skin, FFD, forms |
+| [11-materials-authoring.md](idea/11-materials-authoring.md) | Node-graph material authoring vs the trim-sheet painter; curvature and edge wear |
+| [12-blender-bridge.md](idea/12-blender-bridge.md) | Optional headless Blender adapter: design, determinism, feasibility (planned) |
+| [13-asset-pipeline-research.md](idea/13-asset-pipeline-research.md) | Pro asset pipeline, trim sheets, texel density, CC0 libraries and licences |
 
 ## Decisions
 

package/docs/architecture/gltf-capabilities.md

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

package/docs/architecture/materials.md

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