@developerz.ai/ts23d 0.1.0 → 0.2.0

package/src/material/paint/default-sheet.ts

@@ -1,38 +1,50 @@
-// The house sheet: every strip and cell, tuned so albedo stays near-greyscale and bright (vertex
-// colour carries hue) and each strip reads at its typical face height (`scaleMetres`).
+// The house sheet: every strip and cell. Classic strips stay near-greyscale and bright (vertex
+// colour carries hue); the material library strips carry measured colour. Each strip reads at its
+// typical face height (`scaleMetres`). `HOUSE_STRIPS` is the one mutable table: defineMaterial()
+// adds project strips to it, so `DEFAULT_SHEET` always paints every strip the layout knows.
 
+import { MATERIAL_LIBRARY } from '../library.ts';
+import { toStripRecipe } from '../material-def.ts';
+import type { StripId } from '../trim-sheet.ts';
 import type { SheetRecipe, StripRecipe } from './types.ts';
 
 const leaf: StripRecipe = { kind: 'flat', scaleMetres: 1, roughness: 0.6 };
 
-export const DEFAULT_SHEET: SheetRecipe = {
-  seed: 1,
-  size: 1024,
-  strips: {
-    plain: { kind: 'noise', scaleMetres: 1, roughness: 0.6 },
-    brick: { kind: 'bond', scaleMetres: 0.45, roughness: 0.85, params: { grime: 0.2 } },
-    stone: {
-      kind: 'bond',
-      scaleMetres: 0.9,
-      roughness: 0.9,
-      params: {
-        course: 0.22,
-        length: 0.4,
-        mortar: 0.016,
-        depth: 0.012,
-        bevel: 0.025,
-        irregular: 0.5,
-        relief: 0.004,
-        variation: 0.3,
-        grime: 0.2,
-      },
+const library = Object.fromEntries(
+  Object.values(MATERIAL_LIBRARY).map((d) => [d.id, toStripRecipe(d)]),
+);
+
+export const HOUSE_STRIPS: Partial<Record<StripId, StripRecipe>> = {
+  plain: { kind: 'noise', scaleMetres: 1, roughness: 0.6 },
+  brick: { kind: 'bond', scaleMetres: 0.45, roughness: 0.85, params: { grime: 0.2 } },
+  stone: {
+    kind: 'bond',
+    scaleMetres: 0.9,
+    roughness: 0.9,
+    params: {
+      course: 0.22,
+      length: 0.4,
+      mortar: 0.016,
+      depth: 0.012,
+      bevel: 0.025,
+      irregular: 0.5,
+      relief: 0.004,
+      variation: 0.3,
+      grime: 0.2,
     },
-    slate: { kind: 'slate', scaleMetres: 0.66, roughness: 0.7 },
-    iron: { kind: 'plates', scaleMetres: 0.5, roughness: 0.55, metalness: 0 },
-    wood: { kind: 'planks', scaleMetres: 0.6, roughness: 0.75 },
-    glass: { kind: 'glass', scaleMetres: 1, roughness: 0.05 },
-    concrete: { kind: 'concrete', scaleMetres: 1, roughness: 0.9, params: { grime: 0.3 } },
   },
+  slate: { kind: 'slate', scaleMetres: 0.66, roughness: 0.7 },
+  iron: { kind: 'plates', scaleMetres: 0.5, roughness: 0.55, metalness: 0 },
+  wood: { kind: 'planks', scaleMetres: 0.6, roughness: 0.75 },
+  glass: { kind: 'glass', scaleMetres: 1, roughness: 0.05 },
+  concrete: { kind: 'concrete', scaleMetres: 1, roughness: 0.9, params: { grime: 0.3 } },
+  ...library,
+};
+
+export const DEFAULT_SHEET: SheetRecipe = {
+  seed: 1,
+  size: 2048,
+  strips: HOUSE_STRIPS,
   cells: {
     window_sash: { kind: 'noise', scaleMetres: 1, roughness: 0.5 },
     door_panel: { kind: 'noise', scaleMetres: 1, roughness: 0.6 },

package/src/material/paint/fabric.ts

@@ -0,0 +1,63 @@
+// Soft goods. 'weave': canvas / duck cloth — an over-under thread lattice (warp along U, weft
+// along V, never finer than the texel), slubbed threads, soft folds and water stains toward the
+// bottom. 'leather': pebbled grain, creases running across the hide and burnished wear where it
+// is handled (smoother, a little lighter, darker in the creases).
+// params (weave): pitch 0.004 · folds 0.6 · stains 0.3
+// params (leather): pebble 0.004 · creases 0.5 · wear 0.4
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import type { StripRecipe } from './types.ts';
+
+export function paintWeave(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  // Threads below ~2 texels alias into moiré: keep the lattice resolvable on both axes.
+  const pitchU = Math.max(param(p, 'pitch', 0.004), 2 * pu);
+  const pitchV = Math.max(param(p, 'pitch', 0.004), 2 * pv);
+  const folds = param(p, 'folds', 0.6);
+  const stains = param(p, 'stains', 0.3);
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    const wy = Math.sin((ym / pitchV) * Math.PI * 2);
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const wx = Math.sin((xm / pitchU) * Math.PI * 2);
+      const over = Math.floor(xm / pitchU) + Math.floor(ym / pitchV);
+      const thread = over % 2 === 0 ? Math.abs(wy) : Math.abs(wx);
+      const slub = noiseAt(c, xm, ym, 0.05, 0.01, seed, 2);
+      const fold = noiseAt(c, xm, ym, 0.5, 0.35, seed + 1, 3);
+      const stain = stains * smooth(0.1, 0.6, noiseAt(c, xm, ym, 0.2, 0.15, seed + 2, 4));
+      c.height[i] = 0.0002 * thread + 0.003 * folds * fold;
+      c.tone[i] = (0.9 + 0.06 * thread + 0.05 * slub) * (1 - 0.25 * stain);
+      c.rough[i] = Math.min(1, r.roughness + 0.04 * slub - 0.03 * thread);
+      c.metal[i] = 0;
+      c.mix[i] = stain;
+    }
+  }
+}
+
+export function paintLeather(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  const pebble = param(p, 'pebble', 0.004);
+  const creases = param(p, 'creases', 0.5);
+  const wear = param(p, 'wear', 0.4);
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const grain = noiseAt(c, xm, ym, pebble, pebble, seed, 3);
+      const crease = smooth(0.4, 0.6, noiseAt(c, xm, ym, 0.12, 0.012, seed + 1, 3)) * creases;
+      const rub = wear * smooth(0, 0.6, noiseAt(c, xm, ym, 0.3, 0.3, seed + 2, 4));
+      c.height[i] = 0.00025 * grain - 0.0008 * crease;
+      c.tone[i] = (0.95 + 0.05 * grain) * (1 - 0.45 * crease) * (1 + 0.12 * rub);
+      c.rough[i] = Math.min(1, Math.max(0, r.roughness + 0.06 * grain - 0.2 * rub + 0.1 * crease));
+      c.metal[i] = 0;
+      c.mix[i] = crease;
+    }
+  }
+}

package/src/material/paint/image-strip.ts

@@ -0,0 +1,88 @@
+// Paint a strip from a CC0 texture set: decode the cached PNGs, box-filter them onto the strip's
+// texel grid at true scale (the set's `metres`, snapped so a whole number of repeats spans the
+// strip's U length — it still tiles), V flipped so the image's top is world up. Albedo stays sRGB
+// colour (tint with NATURAL); the OpenGL normal's green is flipped to the sheet's +Y = −V; `arm`
+// fills occlusion / roughness / metalness, else the recipe's constants.
+
+import type { TextureFile, TextureSource } from '../texture-source.ts';
+import { textureBytes } from '../texture-source.ts';
+import type { Canvas } from './canvas.ts';
+import { decodePng, type Rgba } from './decode-png.ts';
+import type { StripRecipe } from './types.ts';
+
+const decoded = new Map<string, Rgba>();
+function image(f: TextureFile, where: string): Rgba {
+  const hit = decoded.get(f.sha256);
+  if (hit) return hit;
+  const img = decodePng(textureBytes(f, where));
+  decoded.set(f.sha256, img);
+  return img;
+}
+
+/** Average of `img` over the canvas texel footprint, per channel, into out[0..3]. */
+function resample(
+  c: Canvas,
+  t: TextureSource,
+  img: Rgba,
+  fn: (i: number, px: Float32Array) => void,
+) {
+  const reps = Math.max(1, Math.round(c.metresU / (t.metres[0] ?? 1)));
+  const su = c.metresU / reps;
+  const sv = t.metres[1] ?? 1;
+  const W = img.width;
+  const H = img.height;
+  const px = new Float32Array(4);
+  for (let y = 0; y < c.h; y++) {
+    const v0 = ((y * c.metresV) / c.h / sv) * H;
+    const v1 = (((y + 1) * c.metresV) / c.h / sv) * H;
+    for (let x = 0; x < c.w; x++) {
+      const u0 = ((x * c.metresU) / c.w / su) * W;
+      const u1 = (((x + 1) * c.metresU) / c.w / su) * W;
+      px.fill(0);
+      let n = 0;
+      for (let sy = Math.floor(v0); sy < Math.max(Math.floor(v0) + 1, Math.ceil(v1)); sy++) {
+        const row = H - 1 - (((sy % H) + H) % H);
+        for (let sx = Math.floor(u0); sx < Math.max(Math.floor(u0) + 1, Math.ceil(u1)); sx++) {
+          const o = (row * W + (((sx % W) + W) % W)) * 4;
+          for (let k = 0; k < 4; k++) px[k] = (px[k] ?? 0) + (img.data[o + k] ?? 0);
+          n++;
+        }
+      }
+      for (let k = 0; k < 4; k++) px[k] = (px[k] ?? 0) / n;
+      fn(y * c.w + x, px);
+    }
+  }
+}
+
+export function paintImageStrip(c: Canvas, r: StripRecipe, t: TextureSource, where: string): void {
+  const albedo = new Uint8Array(c.w * c.h * 4);
+  resample(c, t, image(t.maps.albedo, where), (i, p) => {
+    albedo.set([p[0] ?? 0, p[1] ?? 0, p[2] ?? 0, 255], i * 4);
+  });
+  c.rgba = albedo;
+  c.height.fill(0);
+  if (t.maps.normal) {
+    const nrm = new Uint8Array(c.w * c.h * 4);
+    resample(c, t, image(t.maps.normal, where), (i, p) => {
+      const x = (p[0] ?? 128) / 127.5 - 1;
+      const y = -((p[1] ?? 128) / 127.5 - 1);
+      const z = (p[2] ?? 255) / 127.5 - 1;
+      const l = Math.hypot(x, y, z) || 1;
+      nrm.set(
+        [(x / l) * 127.5 + 127.5, (y / l) * 127.5 + 127.5, (z / l) * 127.5 + 127.5, 255],
+        i * 4,
+      );
+    });
+    c.normalRgba = nrm;
+  }
+  if (t.maps.arm) {
+    resample(c, t, image(t.maps.arm, where), (i, p) => {
+      c.occl[i] = (p[0] ?? 255) / 255;
+      c.rough[i] = (p[1] ?? 204) / 255;
+      c.metal[i] = (p[2] ?? 0) / 255;
+    });
+  } else {
+    c.rough.fill(r.roughness);
+    c.metal.fill(r.metalness ?? 0);
+  }
+}

package/src/material/paint/kit.ts

@@ -0,0 +1,37 @@
+// The helper kit a project painter (`defineMaterial({ paint })`) receives, and the post-check that
+// its layers stayed finite: a NaN written by user code fails loudly instead of corrupting a sheet.
+
+import { Ts23dError } from '../../core/index.ts';
+import { type Canvas, noiseAt, smooth } from './canvas.ts';
+import { hash2 } from './noise.ts';
+import type { PaintKit } from './types.ts';
+
+export function paintKit(c: Canvas, seed: number): PaintKit {
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  return {
+    seed,
+    noise: (xm, ym, sizeU, sizeV, salt = 0, octaves = 4) =>
+      noiseAt(c, xm, ym, sizeU, sizeV, seed + salt * 7919, octaves),
+    hash: (a, b, salt = 0) => hash2(a, b, seed + salt),
+    smooth,
+    each(fn) {
+      for (let y = 0; y < c.h; y++) {
+        const ym = (y + 0.5) * pv;
+        for (let x = 0; x < c.w; x++) fn(y * c.w + x, (x + 0.5) * pu, ym);
+      }
+    },
+  };
+}
+
+/** Throw T3D_MATERIAL_INVALID if any layer holds a non-finite value. */
+export function checkFinite(c: Canvas, where: string): void {
+  const layers = { height: c.height, tone: c.tone, rough: c.rough, metal: c.metal, mix: c.mix };
+  for (const [name, a] of Object.entries(layers))
+    for (let i = 0; i < a.length; i++)
+      if (!Number.isFinite(a[i] ?? 0))
+        throw new Ts23dError('T3D_MATERIAL_INVALID', {
+          cause: `${where}: the painter wrote ${a[i]} into '${name}' at texel ${i}`,
+          fix: 'write finite numbers only (guard divisions; clamp with Math.min/Math.max)',
+        });
+}

package/src/material/paint/masks.ts

@@ -1,6 +1,7 @@
 // Weathering masks applied over a painted canvas: rust streaks (vertical runs from a patchy
 // source, darker and rougher, killing metalness) and grime (dirt pooling toward the bottom of the
-// region — world-down is low V — plus soft vertical rain streaks).
+// region — world-down is low V — plus soft vertical rain streaks). Rust also pushes `mix` toward
+// albedo2, which only shows on material strips that carry a colour pair.
 
 import { type Canvas, noiseAt, smooth } from './canvas.ts';
 
@@ -20,6 +21,7 @@ export function rustStreaks(c: Canvas, amount: number, seed: number): void {
       c.tone[i] = (c.tone[i] ?? 1) * (1 - 0.4 * m);
       c.rough[i] = Math.min(1, (c.rough[i] ?? 0.8) + 0.2 * m);
       c.metal[i] = (c.metal[i] ?? 0) * (1 - m);
+      c.mix[i] = Math.min(1, (c.mix[i] ?? 0) + m);
     }
   }
 }

package/src/material/paint/metal.ts

@@ -0,0 +1,109 @@
+// Bare and finished metal sheet (kind 'metal'): a continuous metallic base with polish mottling,
+// then optional finishes, each a param in 0..1 — `brush` (fine streaks along U, brushed aluminium),
+// `cast` (sand-cast pits and a rougher skin), `spangle` (galvanised zinc crystals), `oxide`
+// (patches of rust / verdigris: blend to albedo2, dielectric, rough, slightly raised) and `paint`
+// (a dielectric paint film over it whose `chips` reveal the oxidised metal). Rust runs down from
+// the oxide (`streaks`).
+// params: brush 0 · cast 0 · spangle 0 · oxide 0 · paint 0 · paintRough 0.45 · chips 0.25
+//         crystal 0.03 (spangle size, m) · streaks 0
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import { rustStreaks } from './masks.ts';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+/** Nearest jittered grid point id on a `size` m lattice that wraps after `wrapU` metres. */
+function crystal(xm: number, ym: number, size: number, cellsU: number, seed: number): number {
+  const gx = Math.floor(xm / size);
+  const gy = Math.floor(ym / size);
+  let best = 1e9;
+  let id = 0;
+  for (let j = -1; j <= 1; j++)
+    for (let i = -1; i <= 1; i++) {
+      const cx = (((gx + i) % cellsU) + cellsU) % cellsU;
+      const px = (gx + i + hash2(cx, gy + j, seed)) * size;
+      const py = (gy + j + hash2(cx, gy + j, seed + 1)) * size;
+      const d = (xm - px) ** 2 + (ym - py) ** 2;
+      if (d < best) {
+        best = d;
+        id = hash2(cx, gy + j, seed + 2) * 1e6;
+      }
+    }
+  return id;
+}
+
+export function paintMetal(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const brush = param(p, 'brush', 0);
+  const cast = param(p, 'cast', 0);
+  const spangle = param(p, 'spangle', 0);
+  const oxide = param(p, 'oxide', 0);
+  const paint = param(p, 'paint', 0);
+  const paintRough = param(p, 'paintRough', 0.45);
+  const chips = param(p, 'chips', 0.25);
+  const size = param(p, 'crystal', 0.03);
+  const metal = r.metalness ?? 1;
+  const cellsU = Math.max(1, Math.round(c.metresU / size));
+  const cs = c.metresU / cellsU;
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const big = noiseAt(c, xm, ym, 0.25, 0.25, seed, 4);
+      const fine = noiseAt(c, xm, ym, 0.01, 0.01, seed + 1, 2);
+      let tone = 1 + 0.05 * big;
+      let rough = r.roughness + 0.06 * big + 0.03 * fine;
+      let h = 0.00015 * big;
+      if (brush > 0) {
+        const s = noiseAt(c, xm, ym, 0.6, 0.002, seed + 2, 3);
+        tone *= 1 + 0.06 * brush * s;
+        rough += 0.08 * brush * s;
+        h += 0.00003 * brush * s;
+      }
+      if (cast > 0) {
+        const pit = noiseAt(c, xm, ym, 0.012, 0.012, seed + 3, 3);
+        const lump = noiseAt(c, xm, ym, 0.08, 0.08, seed + 4, 3);
+        h += cast * (0.0006 * pit + 0.0008 * lump);
+        rough += cast * (0.1 + 0.12 * pit);
+        tone *= 1 + cast * (0.16 * pit + 0.08 * lump - 0.04);
+      }
+      if (spangle > 0) {
+        const k = crystal(xm, ym, cs, cellsU, seed + 5);
+        const v = hash2(k, 7, seed) * 2 - 1;
+        tone *= 1 + 0.12 * spangle * v;
+        rough += 0.12 * spangle * v;
+      }
+      // Oxide: patchy, gathering in low-frequency blotches; dielectric, rough and a touch proud.
+      let ox = 0;
+      if (oxide > 0) {
+        const blot = noiseAt(c, xm, ym, 0.18, 0.18, seed + 6, 5);
+        const grain = noiseAt(c, xm, ym, 0.02, 0.02, seed + 7, 3);
+        ox = smooth(0.45, 0.75, blot * 0.5 + 0.5 + oxide - 0.5 + 0.15 * grain);
+        h += ox * 0.0004 * (1 + grain);
+      }
+      let m = metal * (1 - ox);
+      let mix = ox;
+      rough = rough * (1 - ox) + (0.88 + 0.06 * fine) * ox;
+      if (paint > 0) {
+        // Chips gather where the noise peaks; the film is everywhere else.
+        const n = noiseAt(c, xm, ym, 0.05, 0.05, seed + 8, 4);
+        const chip = smooth(0.42, 0.5, n * 0.5 + 0.5 - (1 - chips) * 0.5 + 0.1);
+        const film = paint * (1 - chip);
+        m *= 1 - film;
+        mix = mix * (1 - film) + chip * paint;
+        rough = rough * (1 - film) + (paintRough + 0.05 * big) * film;
+        tone = tone * (1 - film) + (0.96 + 0.03 * big) * film;
+        h -= chip * paint * 0.00015;
+      }
+      c.height[i] = h;
+      c.tone[i] = tone;
+      c.rough[i] = Math.min(1, Math.max(0, rough));
+      c.metal[i] = Math.min(1, Math.max(0, m));
+      c.mix[i] = mix;
+    }
+  }
+  rustStreaks(c, param(p, 'streaks', 0), seed + 77);
+}

package/src/material/paint/orm.ts

@@ -79,10 +79,23 @@ export function packOrm(c: Canvas, ao: Float32Array): Uint8Array {
   return out;
 }
 
-/** RGBA8 sRGB albedo: the stamped image if any, else grey tone × mild cavity. */
+const enc = (t: number): number => SRGB[t <= 0 ? 0 : t >= 1 ? 4095 : Math.round(t * 4095)] ?? 255;
+
+/** RGBA8 sRGB albedo: the stamped image if any, else (colour pair by mix or grey) × tone × cavity. */
 export function packAlbedo(c: Canvas, ao: Float32Array): Uint8Array {
   if (c.rgba) return c.rgba;
   const out = new Uint8Array(c.w * c.h * 4);
+  const pair = c.colours;
+  if (pair) {
+    const [a, b] = pair;
+    for (let i = 0, o = 0; i < ao.length; i++, o += 4) {
+      const t = (c.tone[i] ?? 1) * (0.8 + 0.2 * (ao[i] ?? 1));
+      const m = Math.min(1, Math.max(0, c.mix[i] ?? 0));
+      for (let k = 0; k < 3; k++) out[o + k] = enc(((a[k] ?? 1) * (1 - m) + (b[k] ?? 1) * m) * t);
+      out[o + 3] = 255;
+    }
+    return out;
+  }
   for (let i = 0, o = 0; i < ao.length; i++, o += 4) {
     const t = (c.tone[i] ?? 1) * (0.8 + 0.2 * (ao[i] ?? 1));
     const g = SRGB[t <= 0 ? 0 : t >= 1 ? 4095 : Math.round(t * 4095)] ?? 255;

package/src/material/paint/planks.ts

@@ -1,6 +1,10 @@
 // Timber boards (kind 'planks'): boards run along U, butt joints staggered at random, dark gaps,
-// stretched grain with growth-ring streaks, occasional knots, per-board tone.
+// stretched grain with growth-ring streaks, occasional knots, per-board tone. Species and finish
+// come from params on top: `rings` blends latewood to albedo2, `rays` adds oak's ray flecks,
+// `checks` weathers (eroded soft grain, splits along it, silvering), `paint` lays a film over the
+// grain whose `chips` reveal bare wood (albedo2), mostly along board edges.
 // params: width 0.15 · length 1.0 · gap 0.004 · depth 0.004 · knots 1.5 (per board-metre)
+//         rings 0 · rays 0 · checks 0 · paint 0 · paintRough 0.5 · chips 0.3
 
 import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
 import { Courses } from './courses.ts';
@@ -14,9 +18,16 @@ export function paintPlanks(c: Canvas, r: StripRecipe, seed: number): void {
   const gap = param(p, 'gap', 0.004);
   const depth = param(p, 'depth', 0.004);
   const knots = param(p, 'knots', 1.5);
+  const rings = param(p, 'rings', 0);
+  const rays = param(p, 'rays', 0);
+  const checks = param(p, 'checks', 0);
+  const paint = param(p, 'paint', 0);
+  const paintRough = param(p, 'paintRough', 0.5);
+  const chips = param(p, 'chips', 0.3);
   const boards = new Courses(c, { course: width, length, irregular: 0.6, stagger: 0, seed });
   const pu = c.metresU / c.w;
   const pv = c.metresV / c.h;
+  const ringsN = Math.max(1, Math.min(9, Math.floor(width / pv / 4)));
   for (let y = 0; y < c.h; y++) {
     const ym = (y + 0.5) * pv;
     const k = boards.at(ym);
@@ -44,13 +55,47 @@ export function paintPlanks(c: Canvas, r: StripRecipe, seed: number): void {
         const rr = Math.sqrt((ddx / 2.2) ** 2 + (ym - ky) ** 2) / (width * 0.12);
         if (rr < 1) knot = Math.max(knot, 1 - rr);
       }
-      c.height[i] = -depth * (1 - edge) + 0.0004 * ring * edge + 0.0003 * fibre - 0.0008 * knot;
-      c.tone[i] =
+      let height = -depth * (1 - edge) + 0.0004 * ring * edge + 0.0003 * fibre - 0.0008 * knot;
+      let tone =
         (0.66 + 0.22 * h) *
         (1 + 0.08 * ring + 0.06 * fibre) *
         (1 - 0.5 * knot) *
         (0.5 + 0.5 * edge);
-      c.rough[i] = r.roughness + 0.05 * fibre + 0.1 * (1 - edge);
+      let rough = r.roughness + 0.05 * fibre + 0.1 * (1 - edge);
+      // Colour rings at a frequency the strip's V texels can hold (≥ ~4 texels per ring).
+      const ring2 = Math.sin((vy * ringsN + warp * 2.5 + h * 6) * Math.PI * 2);
+      const late = smooth(0.1, 0.8, ring2) * (0.75 + 0.25 * fibre);
+      let mix = rings * Math.max(late, knot);
+      if (rays > 0) {
+        const fleck = smooth(0.55, 0.8, noiseAt(c, xm, ym, 0.03, 0.004, seed + 23, 2));
+        tone *= 1 + 0.25 * rays * fleck;
+        mix *= 1 - rays * fleck;
+      }
+      if (checks > 0) {
+        // Soft earlywood erodes, leaving latewood ridges; splits open along the grain.
+        const split = smooth(0.45, 0.6, noiseAt(c, xm, ym, 0.3, 0.003, seed + 29 + id, 3));
+        height += checks * (0.0006 * late - 0.002 * split);
+        tone *= 1 - checks * (0.45 * split + 0.08 * (1 - late));
+        rough += checks * 0.1 * (1 - late);
+        mix = Math.max(mix, checks * split);
+      }
+      if (paint > 0) {
+        // Paint fails first at board edges and ends, then in blotches across the face.
+        const n = noiseAt(c, xm, ym, 0.04, 0.03, seed + 31, 4) * 0.5 + 0.5;
+        const nearEdge = 1 - smooth(gap, gap * 6, d);
+        const chip = smooth(0.5, 0.56, n + chips * 0.5 + nearEdge * 0.15 - 0.45);
+        const film = paint * (1 - chip);
+        height = height * (1 - 0.4 * film) - chip * paint * 0.0002;
+        // The film follows the grain: board tone and rings still read through it, faintly.
+        const under = (0.9 + 0.06 * h) * (1 + 0.05 * ring + 0.04 * fibre) * (0.55 + 0.45 * edge);
+        tone = tone * (1 - film) + under * film;
+        rough = rough * (1 - film) + (paintRough + 0.04 * fibre) * film;
+        mix = mix * (1 - film) + paint * chip;
+      }
+      c.height[i] = height;
+      c.tone[i] = tone;
+      c.rough[i] = Math.min(1, rough);
+      c.mix[i] = mix;
     }
   }
 }

package/src/material/paint/strip.ts

@@ -1,42 +1,48 @@
-// Dispatch a StripRecipe to its painter, then the shared grime pass (`params.grime`, 0..1).
+// Dispatch a StripRecipe to its painter, then the shared grime pass (`params.grime`, 0..1), then
+// the recipe's own `paint` layer (project materials), checked for finite output. A `texture`
+// recipe paints from its cached CC0 image set instead of a kind (no grime: the photo has its own).
 
 import { paintBond } from './bond.ts';
 import type { Canvas } from './canvas.ts';
 import { param } from './canvas.ts';
 import { paintConcrete } from './concrete.ts';
+import { paintLeather, paintWeave } from './fabric.ts';
+import { paintImageStrip } from './image-strip.ts';
+import { checkFinite, paintKit } from './kit.ts';
 import { grime } from './masks.ts';
+import { paintMetal } from './metal.ts';
 import { paintPlanks } from './planks.ts';
 import { paintPlates } from './plates.ts';
 import { paintSlate } from './slate.ts';
 import { paintFlat, paintGlass, paintNoise } from './surface.ts';
-import type { StripRecipe } from './types.ts';
+import type { StripKind, StripRecipe } from './types.ts';
 
-export function paintStrip(c: Canvas, r: StripRecipe, seed: number): void {
-  switch (r.kind) {
-    case 'bond':
-      paintBond(c, r, seed);
-      break;
-    case 'planks':
-      paintPlanks(c, r, seed);
-      break;
-    case 'plates':
-      paintPlates(c, r, seed);
-      break;
-    case 'slate':
-      paintSlate(c, r, seed);
-      break;
-    case 'concrete':
-      paintConcrete(c, r, seed);
-      break;
-    case 'glass':
-      paintGlass(c, r, seed);
-      return;
-    case 'noise':
-      paintNoise(c, r, seed);
-      break;
-    case 'flat':
-      paintFlat(c, r);
-      return;
+type Painter = (c: Canvas, r: StripRecipe, seed: number) => void;
+
+const PAINTERS: Readonly<Record<StripKind, Painter>> = {
+  bond: paintBond,
+  planks: paintPlanks,
+  plates: paintPlates,
+  slate: paintSlate,
+  concrete: paintConcrete,
+  metal: paintMetal,
+  weave: paintWeave,
+  leather: paintLeather,
+  noise: paintNoise,
+  glass: paintGlass,
+  flat: (c, r) => paintFlat(c, r),
+};
+
+export function paintStrip(c: Canvas, r: StripRecipe, seed: number, where = 'strip'): void {
+  if (r.texture) paintImageStrip(c, r, r.texture, where);
+  else {
+    if (r.albedo || r.albedo2)
+      c.colours = [r.albedo ?? [1, 1, 1], r.albedo2 ?? r.albedo ?? [1, 1, 1]];
+    PAINTERS[r.kind](c, r, seed);
+    if (r.kind !== 'glass' && r.kind !== 'flat') grime(c, param(r.params, 'grime', 0), seed + 101);
+  }
+  if (r.paint) {
+    r.paint(c, paintKit(c, seed + 211));
+    checkFinite(c, where);
   }
-  grime(c, param(r.params, 'grime', 0), seed + 101);
 }

package/src/material/paint/types.ts

@@ -1,11 +1,14 @@
 // The generator's public data contract (re-exported by generator.ts): what a sheet recipe says
 // and what the painter returns.
 
+import type { Vec3 } from '../../core/index.ts';
+import type { TextureSource } from '../texture-source.ts';
 import type { CellId, StripId } from '../trim-sheet.ts';
+import type { Canvas } from './canvas.ts';
 
 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;
@@ -21,7 +24,39 @@ export type StripKind =
   | 'flat'
   | 'slate'
   | 'concrete'
-  | 'glass';
+  | '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;
@@ -34,6 +69,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. */