@developerz.ai/ts23d 0.0.0-stage → 0.2.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

@@ -0,0 +1,46 @@
+// 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). 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';
+
+export function rustStreaks(c: Canvas, amount: number, seed: number): void {
+  if (amount <= 0) return;
+  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 xm = (x + 0.5) * pu;
+      const run = noiseAt(c, xm, ym, 0.025, 0.6, seed, 3);
+      const patch = noiseAt(c, xm, ym, 0.3, 0.3, seed + 1, 2);
+      const m = amount * smooth(0.15, 0.6, run) * smooth(-0.1, 0.4, patch);
+      if (m <= 0) continue;
+      const i = y * c.w + x;
+      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);
+    }
+  }
+}
+
+export function grime(c: Canvas, amount: number, seed: number): void {
+  if (amount <= 0) return;
+  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;
+    const low = (1 - ym / c.metresV) ** 2;
+    for (let x = 0; x < c.w; x++) {
+      const xm = (x + 0.5) * pu;
+      const streak = smooth(0, 0.7, noiseAt(c, xm, ym, 0.05, 0.5, seed, 3));
+      const blot = 0.6 + 0.4 * noiseAt(c, xm, ym, 0.2, 0.2, seed + 1, 3);
+      const m = amount * Math.min(1, low * blot + 0.35 * streak);
+      const i = y * c.w + x;
+      c.tone[i] = (c.tone[i] ?? 1) * (1 - 0.3 * m);
+      c.rough[i] = Math.min(1, (c.rough[i] ?? 0.8) + 0.1 * 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/noise.ts

@@ -0,0 +1,52 @@
+// Seeded integer-hash value noise and fBm, periodic along X so strips tile seamlessly along U.
+// Pure functions of (coords, seed): no state, no allocation, safe in per-pixel loops.
+
+/** Integer hash of a lattice point to [0, 1). */
+export function hash2(ix: number, iy: number, seed: number): number {
+  let h = Math.imul(ix | 0, 0x27d4eb2d) ^ Math.imul(iy | 0, 0x165667b1) ^ seed;
+  h = Math.imul(h ^ (h >>> 15), 0x85ebca6b);
+  h = Math.imul(h ^ (h >>> 13), 0xc2b2ae35);
+  return ((h ^ (h >>> 16)) >>> 0) / 4294967296;
+}
+
+/** Value noise in [0, 1] on a unit lattice, periodic in x with an integer `period` (cells). */
+export function valueNoise(x: number, y: number, period: number, seed: number): number {
+  const xi = Math.floor(x);
+  const yi = Math.floor(y);
+  const fx = x - xi;
+  const fy = y - yi;
+  const sx = fx * fx * (3 - 2 * fx);
+  const sy = fy * fy * (3 - 2 * fy);
+  const x0 = ((xi % period) + period) % period;
+  const x1 = (x0 + 1) % period;
+  const a = hash2(x0, yi, seed);
+  const b = hash2(x1, yi, seed);
+  const c = hash2(x0, yi + 1, seed);
+  const d = hash2(x1, yi + 1, seed);
+  return a + (b - a) * sx + (c - a + (d - c - b + a) * sx) * sy;
+}
+
+/**
+ * Fractal Brownian motion in [-1, 1]: `octaves` layers of value noise, each at double frequency
+ * and `gain` amplitude. Doubling keeps the period an integer, so the sum stays tileable.
+ */
+export function fbm(
+  x: number,
+  y: number,
+  period: number,
+  seed: number,
+  octaves = 4,
+  gain = 0.5,
+): number {
+  let sum = 0;
+  let amp = 1;
+  let norm = 0;
+  let f = 1;
+  for (let o = 0; o < octaves; o++) {
+    sum += amp * valueNoise(x * f, y * f, period * f, seed + o * 1013);
+    norm += amp;
+    amp *= gain;
+    f *= 2;
+  }
+  return (sum / norm) * 2 - 1;
+}

package/src/material/paint/normal.ts

@@ -0,0 +1,52 @@
+// Normal from height: a Sobel gradient of the canvas height (metres) over its texel size (metres),
+// so relief reads at true scale. glTF tangent space, +Y = toward decreasing V (OpenGL "green up").
+// Wraps along U for strips, clamps for cells and along V.
+
+import type { Canvas } from './canvas.ts';
+
+/** Neighbour column indices, precomputed so the hot loop does no modulo. */
+export function neighbours(n: number, wrap: boolean): { lo: Int32Array; hi: Int32Array } {
+  const lo = new Int32Array(n);
+  const hi = new Int32Array(n);
+  for (let i = 0; i < n; i++) {
+    lo[i] = i > 0 ? i - 1 : wrap ? n - 1 : 0;
+    hi[i] = i < n - 1 ? i + 1 : wrap ? 0 : n - 1;
+  }
+  return { lo, hi };
+}
+
+/** RGBA8 tangent-space normals for the canvas; `strength` scales the slope. */
+export function sobelNormals(c: Canvas, strength = 1): Uint8Array {
+  const { w, h, height } = c;
+  const out = new Uint8Array(w * h * 4);
+  const cx = neighbours(w, c.wrapU);
+  const cy = neighbours(h, false);
+  const sx = strength / (8 * (c.metresU / w));
+  const sy = strength / (8 * (c.metresV / h));
+  for (let y = 0; y < h; y++) {
+    const r0 = (cy.lo[y] ?? 0) * w;
+    const r1 = y * w;
+    const r2 = (cy.hi[y] ?? 0) * w;
+    for (let x = 0; x < w; x++) {
+      const xl = cx.lo[x] ?? 0;
+      const xr = cx.hi[x] ?? 0;
+      const tl = height[r0 + xl] ?? 0;
+      const tc = height[r0 + x] ?? 0;
+      const tr = height[r0 + xr] ?? 0;
+      const ml = height[r1 + xl] ?? 0;
+      const mr = height[r1 + xr] ?? 0;
+      const bl = height[r2 + xl] ?? 0;
+      const bc = height[r2 + x] ?? 0;
+      const br = height[r2 + xr] ?? 0;
+      const gx = (tr + 2 * mr + br - tl - 2 * ml - bl) * sx;
+      const gy = (bl + 2 * bc + br - tl - 2 * tc - tr) * sy;
+      const inv = 1 / Math.sqrt(gx * gx + gy * gy + 1);
+      const o = (r1 + x) * 4;
+      out[o] = Math.round((-gx * inv * 0.5 + 0.5) * 255);
+      out[o + 1] = Math.round((gy * inv * 0.5 + 0.5) * 255);
+      out[o + 2] = Math.round((inv * 0.5 + 0.5) * 255);
+      out[o + 3] = 255;
+    }
+  }
+  return out;
+}

package/src/material/paint/orm.ts

@@ -0,0 +1,108 @@
+// ORM + albedo packing. Occlusion comes from the height cavity (blurred height minus height: deep
+// where a texel sits below its surroundings — mortar, seams, grain); roughness and metalness are
+// the painted layers. Albedo is the linear tone, sRGB-encoded, with a mild cavity darkening baked
+// in so engines that ignore the occlusion map still read the joints.
+
+import type { Canvas } from './canvas.ts';
+
+/** Depth (metres) below the local mean that counts as fully occluded. */
+const AO_DEPTH = 0.006;
+const AO_STRENGTH = 0.75;
+/** Blur radius of the cavity estimate, metres. */
+const AO_RADIUS = 0.02;
+
+/** Separable sliding-window box blur: O(1) per texel. Wraps along x when `wrap`, else clamps. */
+function boxBlur(
+  src: Float32Array,
+  w: number,
+  h: number,
+  rx: number,
+  ry: number,
+  wrap: boolean,
+): Float32Array {
+  const tmp = new Float32Array(src.length);
+  const out = new Float32Array(src.length);
+  const ix = (i: number): number =>
+    i < 0 ? (wrap ? (i % w) + w : 0) : i >= w ? (wrap ? i % w : w - 1) : i;
+  for (let y = 0; y < h; y++) {
+    const row = y * w;
+    let s = 0;
+    for (let k = -rx; k <= rx; k++) s += src[row + ix(k)] ?? 0;
+    for (let x = 0; x < w; x++) {
+      tmp[row + x] = s / (2 * rx + 1);
+      s += (src[row + ix(x + rx + 1)] ?? 0) - (src[row + ix(x - rx)] ?? 0);
+    }
+  }
+  const iy = (j: number): number => (j < 0 ? 0 : j >= h ? h - 1 : j);
+  for (let x = 0; x < w; x++) {
+    let s = 0;
+    for (let k = -ry; k <= ry; k++) s += tmp[iy(k) * w + x] ?? 0;
+    for (let y = 0; y < h; y++) {
+      out[y * w + x] = s / (2 * ry + 1);
+      s += (tmp[iy(y + ry + 1) * w + x] ?? 0) - (tmp[iy(y - ry) * w + x] ?? 0);
+    }
+  }
+  return out;
+}
+
+/** Per-texel ambient occlusion in [1 - AO_STRENGTH, 1]. */
+export function cavityOcclusion(c: Canvas): Float32Array {
+  const rx = Math.max(1, Math.round(AO_RADIUS / (c.metresU / c.w)));
+  const ry = Math.max(1, Math.round(AO_RADIUS / (c.metresV / c.h)));
+  const blur = boxBlur(boxBlur(c.height, c.w, c.h, rx, ry, c.wrapU), c.w, c.h, rx, ry, c.wrapU);
+  const ao = new Float32Array(c.height.length);
+  for (let i = 0; i < ao.length; i++) {
+    const cavity = (blur[i] ?? 0) - (c.height[i] ?? 0);
+    const t = cavity <= 0 ? 0 : cavity >= AO_DEPTH ? 1 : cavity / AO_DEPTH;
+    ao[i] = (1 - AO_STRENGTH * t) * (c.occl[i] ?? 1);
+  }
+  return ao;
+}
+
+export const SRGB = new Uint8Array(4096).map((_, i) => {
+  const l = i / 4095;
+  const s = l <= 0.0031308 ? l * 12.92 : 1.055 * l ** (1 / 2.4) - 0.055;
+  return Math.round(s * 255);
+});
+
+const byte = (v: number): number => (v <= 0 ? 0 : v >= 1 ? 255 : Math.round(v * 255));
+
+/** RGBA8 ORM: R = occlusion, G = roughness, B = metalness, A = 255. */
+export function packOrm(c: Canvas, ao: Float32Array): Uint8Array {
+  const out = new Uint8Array(c.w * c.h * 4);
+  for (let i = 0, o = 0; i < ao.length; i++, o += 4) {
+    out[o] = byte(ao[i] ?? 1);
+    out[o + 1] = byte(c.rough[i] ?? 0.8);
+    out[o + 2] = byte(c.metal[i] ?? 0);
+    out[o + 3] = 255;
+  }
+  return out;
+}
+
+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;
+    out[o] = g;
+    out[o + 1] = g;
+    out[o + 2] = g;
+    out[o + 3] = 255;
+  }
+  return out;
+}

package/src/material/paint/planks.ts

@@ -0,0 +1,101 @@
+// 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. 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';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+export function paintPlanks(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const width = param(p, 'width', 0.15);
+  const length = param(p, 'length', 1);
+  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);
+    const dy = Math.min(ym - boards.y0, boards.y1 - ym);
+    const vy = (ym - boards.y0) / (boards.y1 - boards.y0);
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const id = boards.id[x] ?? 0;
+      const h = hash2(k, id, seed);
+      const d = Math.min((boards.dx[x] ?? 0) * 1.5, dy);
+      const edge = smooth(gap * 0.5, gap * 1.5, d);
+      // Grain: rings warped by a long, thin noise; the board's own seed shifts its figure.
+      const warp = noiseAt(c, xm, ym, 0.4, 0.05, seed + id * 31 + k * 7, 3);
+      const ring = Math.sin((vy * 9 + warp * 3 + h * 6) * Math.PI * 2);
+      const fibre = noiseAt(c, xm, ym, 0.08, 0.002, seed + 17, 2);
+      let knot = 0;
+      const nk = Math.floor(knots * length * h * 2);
+      for (let q = 0; q < nk; q++) {
+        const kx = hash2(k * 13 + q, id, seed + 41) * c.metresU;
+        const ky =
+          boards.y0 + (0.25 + 0.5 * hash2(k, id * 5 + q, seed + 43)) * (boards.y1 - boards.y0);
+        let ddx = Math.abs(xm - kx);
+        if (c.wrapU) ddx = Math.min(ddx, c.metresU - ddx);
+        const rr = Math.sqrt((ddx / 2.2) ** 2 + (ym - ky) ** 2) / (width * 0.12);
+        if (rr < 1) knot = Math.max(knot, 1 - rr);
+      }
+      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);
+      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/plates.ts

@@ -0,0 +1,72 @@
+// Riveted iron plates (kind 'plates'): lapped plates (each overlaps its left neighbour by a
+// step), domed rivet rows along every seam, hammered surface, rust streaks running down from
+// rivets, chipped paint showing bare metal on edges.
+// params: width 1.0 · height 0.5 · lap 0.003 · rivet 0.014 (radius) · pitch 0.09 · inset 0.05
+//         rust 0.4 · chips 0.3
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import { Courses } from './courses.ts';
+import { rustStreaks } from './masks.ts';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+/** Distance (m) from `q` to the nearest multiple of `pitch`. */
+function along(q: number, pitch: number): number {
+  const t = q / pitch;
+  return Math.abs(t - Math.round(t)) * pitch;
+}
+
+export function paintPlates(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const lap = param(p, 'lap', 0.003);
+  const rivet = param(p, 'rivet', 0.014);
+  const pitch = param(p, 'pitch', 0.09);
+  const inset = param(p, 'inset', 0.05);
+  const chips = param(p, 'chips', 0.3);
+  const metal = r.metalness ?? 0;
+  const plates = new Courses(c, {
+    course: param(p, 'height', 0.5),
+    length: param(p, 'width', 1),
+    irregular: 0,
+    stagger: 0.5,
+    seed,
+  });
+  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;
+    const k = plates.at(ym);
+    const dy = Math.min(ym - plates.y0, plates.y1 - ym);
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const ux = plates.ux[x] ?? 0;
+      const dx = plates.dx[x] ?? 0;
+      const id = plates.id[x] ?? 0;
+      const hammer = noiseAt(c, xm, ym, 0.05, 0.05, seed + 3, 3);
+      const fine = noiseAt(c, xm, ym, 0.004, 0.004, seed + 9, 2);
+      // Lap: the plate sits `lap` proud of the one to its left; a tiny groove on every seam.
+      const seam = Math.min(dx, dy);
+      let h = lap * smooth(0, 0.004, ux) + 0.0004 * hammer - 0.001 * (1 - smooth(0, 0.0015, seam));
+      // Rivet rows: `inset` from each vertical seam and from each course edge, every `pitch`.
+      const ry = Math.abs(dy - inset);
+      const rx = Math.abs(dx - inset);
+      const d1 = Math.sqrt(rx * rx + along(ym - plates.y0, pitch) ** 2);
+      const d2 = Math.sqrt(ry * ry + along(xm, pitch) ** 2);
+      const d = Math.min(dx > inset * 2 ? 1 : d1, dy > inset * 2 ? 1 : d2);
+      const dome = d < rivet ? Math.sqrt(1 - (d / rivet) ** 2) : 0;
+      h += dome * rivet * 0.5;
+      const chip = smooth(
+        0.35,
+        0.45,
+        noiseAt(c, xm, ym, 0.03, 0.03, seed + 21, 4) - (seam * 6 + 0.2) + chips * 0.3,
+      );
+      c.height[i] = h - chip * 0.0003;
+      c.tone[i] =
+        (0.8 + 0.06 * hash2(k, id, seed)) * (1 + 0.06 * hammer + 0.03 * fine) * (1 + 0.15 * dome);
+      c.rough[i] = r.roughness + 0.08 * fine - 0.25 * chip;
+      c.metal[i] = metal + (1 - metal) * chip;
+    }
+  }
+  rustStreaks(c, param(p, 'rust', 0.4), seed + 77);
+}

package/src/material/paint/shapes.ts

@@ -0,0 +1,28 @@
+// Tiny SDF-style helpers for cell motifs: distances in metres, no allocation.
+
+/** Distance from (px, py) to the segment (ax, ay)–(bx, by). */
+export function segment(px: number, py: number, ax: number, ay: number, bx: number, by: number) {
+  const dx = bx - ax;
+  const dy = by - ay;
+  const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / (dx * dx + dy * dy)));
+  return Math.hypot(px - ax - t * dx, py - ay - t * dy);
+}
+
+/** Signed distance to an axis-aligned rectangle (negative inside). */
+export function rect(px: number, py: number, x0: number, y0: number, x1: number, y1: number) {
+  const qx = Math.max(x0 - px, px - x1);
+  const qy = Math.max(y0 - py, py - y1);
+  return qx > 0 || qy > 0 ? Math.hypot(Math.max(qx, 0), Math.max(qy, 0)) : Math.max(qx, qy);
+}
+
+/** Dome profile in [0, 1] for a round boss of radius `r` at distance `d`. */
+export const dome = (d: number, r: number): number => (d < r ? Math.sqrt(1 - (d / r) ** 2) : 0);
+
+/** Distance to the nearest of `n` points evenly spaced on a circle of radius `ring`. */
+export function boltRing(px: number, py: number, ring: number, n: number, phase = 0): number {
+  const a = Math.atan2(py, px) - phase;
+  const step = (Math.PI * 2) / n;
+  const k = Math.round(a / step);
+  const ba = k * step + phase;
+  return Math.hypot(px - ring * Math.cos(ba), py - ring * Math.sin(ba));
+}

package/src/material/paint/slate.ts

@@ -0,0 +1,52 @@
+// Roof slate (kind 'slate'): overlapping courses — each visible slate rises from where it slides
+// under the course above to a thick, chipped lower edge that casts the shadow line — staggered
+// vertical gaps, riven (laminar) face, per-slate tone and tilt.
+// params: course 0.11 (exposure) · length 0.25 · gap 0.003 · thick 0.007 · variation 0.3
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import { Courses } from './courses.ts';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+export function paintSlate(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const course = param(p, 'course', 0.11);
+  const gap = param(p, 'gap', 0.003);
+  const thick = param(p, 'thick', 0.007);
+  const variation = param(p, 'variation', 0.3);
+  const rows = new Courses(c, {
+    course,
+    length: param(p, 'length', 0.25),
+    irregular: 0.15,
+    stagger: 0.5,
+    seed,
+  });
+  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;
+    const k = rows.at(ym);
+    const span = rows.y1 - rows.y0;
+    for (let x = 0; x < c.w; x++) {
+      const i = y * c.w + x;
+      const xm = (x + 0.5) * pu;
+      const id = rows.id[x] ?? 0;
+      const h = hash2(k, id, seed);
+      const chip = (noiseAt(c, xm, ym, 0.015, 0.01, seed + 5, 3) + 0.3) * span * 0.08;
+      const uy = Math.max(0, ym - rows.y0 - Math.max(0, chip));
+      const t = uy / span;
+      const lam = noiseAt(c, xm, ym, 0.12, 0.004, seed + 9, 3);
+      const fine = noiseAt(c, xm, ym, 0.005, 0.005, seed + 13, 2);
+      const sideGap = smooth(gap * 0.5, gap * 1.2, rows.dx[x] ?? 0);
+      const bevel = smooth(0, 0.004, uy);
+      const tilt = (hash2(id, k, seed + 1) - 0.5) * 0.002 * ((rows.ux[x] ?? 0) / 0.25);
+      c.height[i] =
+        (thick * (1 - t) * bevel + 0.0005 * lam + tilt) * sideGap - thick * (1 - sideGap);
+      c.tone[i] =
+        (0.62 - variation * 0.5 + variation * h) *
+        (1 + 0.08 * lam + 0.04 * fine) *
+        (0.55 + 0.45 * sideGap);
+      c.rough[i] = r.roughness + 0.08 * lam + 0.05 * fine;
+    }
+  }
+}