@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/src/material/paint/foliage-conifer.ts

@@ -0,0 +1,143 @@
+// Needle and blade foliage cells, growing from the bottom-centre anchor toward +V: spruce comb
+// (needle tufts off both sides of an axis and its side shoots), snow-loaded spruce (the same with
+// snow lumps riding the upper side of each shoot), conifer needle spray (pine bundles fanning from
+// twig tips) and reeds/grass (tapering blades, some dry).
+
+import { createRng, type Rng } from '../../core/index.ts';
+import type { Canvas } from './canvas.ts';
+import { at, type Curve, curve, dim, drawStem, LEAF, vary } from './foliage-common.ts';
+import { Foliage } from './foliage-raster.ts';
+
+/** Needles off both sides of a shoot, angled forward, densest mid-shoot. */
+function comb(f: Foliage, rng: Rng, shoot: Curve, len: number, k: number, lift: number): void {
+  const n = shoot.x.length - 1;
+  for (let i = 0; i <= n; i++) {
+    for (const side of [-1, 1]) {
+      const a = (shoot.a[i] ?? 0) + side * rng.range(0.7, 1.0);
+      const col = dim(vary(rng, LEAF.spruce, 0.2), k);
+      f.leaf(
+        'needle',
+        shoot.x[i] ?? 0,
+        shoot.y[i] ?? 0,
+        a,
+        len * rng.range(0.8, 1.1),
+        0.006,
+        col,
+        0,
+        lift,
+      );
+    }
+  }
+}
+
+function spruce(c: Canvas, seed: number, snow: boolean): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  const axis = curve(0.5, 0.02, 0.5 + rng.range(-0.04, 0.04), 0.5, 0.5, 0.95, 60);
+  const shoots: Curve[] = [];
+  for (let s = 0; s < 8; s++) {
+    const t = 0.15 + (s / 8) * 0.75;
+    const i = at(axis, t);
+    const side = s % 2 === 0 ? 1 : -1;
+    const bx = axis.x[i] ?? 0.5;
+    const by = axis.y[i] ?? 0.5;
+    const len = 0.32 * (1 - t * 0.6);
+    const a = side * rng.range(0.9, 1.2);
+    shoots.push(
+      curve(
+        bx,
+        by,
+        bx + Math.sin(a) * len * 0.5,
+        by + Math.cos(a) * len * 0.5,
+        bx + Math.sin(a) * len,
+        by + Math.cos(a) * len + 0.03,
+        24,
+      ),
+    );
+  }
+  for (const sh of shoots) comb(f, rng, sh, 0.045, 0.55, 0);
+  drawStem(f, axis, 0.012, 0.004, LEAF.bark);
+  for (const sh of shoots) drawStem(f, sh, 0.005, 0.002, LEAF.bark);
+  comb(f, rng, axis, 0.05, 1, 0.002);
+  for (const sh of shoots) comb(f, rng, sh, 0.04, 1, 0.002);
+  if (snow) {
+    for (const sh of [axis, ...shoots]) {
+      const n = sh.x.length - 1;
+      for (let i = 2; i < n; i += 3) {
+        const col = vary(rng, LEAF.snow, 0.05);
+        f.leaf(
+          'ovate',
+          (sh.x[i] ?? 0) - 0.02,
+          (sh.y[i] ?? 0) + 0.008,
+          Math.PI / 2 + rng.range(-0.3, 0.3),
+          rng.range(0.04, 0.07),
+          rng.range(0.025, 0.04),
+          col,
+          0,
+          0.006,
+        );
+      }
+    }
+  }
+  f.finish(0.5, 0.25);
+}
+
+export const paintSpruce = (c: Canvas, seed: number): void => spruce(c, seed, false);
+export const paintSpruceSnow = (c: Canvas, seed: number): void => spruce(c, seed, true);
+
+export function paintNeedles(c: Canvas, seed: number): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  const twigs: Curve[] = [];
+  for (let s = 0; s < 5; s++) {
+    const ex = 0.5 + (s - 2) * 0.13 + rng.range(-0.03, 0.03);
+    twigs.push(curve(0.5, 0.02, 0.5 + (ex - 0.5) * 0.4, 0.3, ex, rng.range(0.55, 0.7), 12));
+  }
+  for (const [s, tw] of twigs.entries()) {
+    drawStem(f, tw, 0.012, 0.006, LEAF.bark);
+    const k = s % 2 === 0 ? 0.6 : 1;
+    // Bundles along the outer third and a full brush at the tip, fanning forward.
+    for (let i = 6; i < tw.x.length; i++) {
+      const fan = i === tw.x.length - 1 ? 14 : 4;
+      for (let q = 0; q < fan; q++) {
+        const a = (tw.a[i] ?? 0) + rng.range(-1.1, 1.1) * (fan > 4 ? 0.8 : 1.2);
+        const col = dim(vary(rng, LEAF.pine, 0.2), k);
+        f.leaf(
+          'needle',
+          tw.x[i] ?? 0,
+          tw.y[i] ?? 0,
+          a,
+          rng.range(0.12, 0.2),
+          0.006,
+          col,
+          0,
+          k * 0.002,
+        );
+      }
+    }
+  }
+  f.finish(0.5, 0.3);
+}
+
+export function paintReeds(c: Canvas, seed: number): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  for (let b = 0; b < 22; b++) {
+    const back = b < 8;
+    const x = 0.5 + rng.range(-0.2, 0.2);
+    const tilt = (x - 0.5) * 1.2 + rng.range(-0.25, 0.25);
+    const col = dim(vary(rng, rng.next() < 0.2 ? LEAF.dry : LEAF.reed, 0.2), back ? 0.55 : 1);
+    f.leaf(
+      'blade',
+      x,
+      0.0,
+      tilt,
+      rng.range(0.55, 0.97),
+      rng.range(0.018, 0.032),
+      col,
+      0,
+      back ? 0 : 0.002,
+    );
+  }
+  f.finish(0.5, 0.15);
+}

package/src/material/paint/foliage-raster.ts

@@ -0,0 +1,196 @@
+// Rasteriser for foliage cells: tapered stems and leaf shapes composited back-to-front into
+// linear colour + coverage, with leaf-dome and midrib relief. `finish` writes sRGB RGBA (alpha =
+// leaf mask, transparent texels bled with leaf colour so mips don't halo), height, roughness and
+// an occlusion term that darkens toward the twig axis. Shapes iterate only their pixel bounds.
+
+import { type Canvas, clamp01, smooth } from './canvas.ts';
+import { SRGB } from './orm.ts';
+import { segment } from './shapes.ts';
+
+export type Rgb = readonly [number, number, number];
+/** Width profile of a leaf along its length t ∈ [0, 1]; 1 = full half-width. */
+export type LeafShape = 'ovate' | 'lance' | 'needle' | 'blade' | 'palmate';
+
+const total = (a: Float32Array): number => a.reduce((s, v) => s + v, 0);
+
+/** Angle between palmate lobe axes. */
+const LOBE = (Math.PI * 2) / 5;
+
+export class Foliage {
+  private readonly r: Float32Array;
+  private readonly g: Float32Array;
+  private readonly b: Float32Array;
+  private readonly a: Float32Array;
+  private readonly c: Canvas;
+  private readonly px: number;
+
+  constructor(c: Canvas) {
+    this.c = c;
+    const n = c.w * c.h;
+    this.r = new Float32Array(n);
+    this.g = new Float32Array(n);
+    this.b = new Float32Array(n);
+    this.a = new Float32Array(n);
+    this.px = c.metresU / c.w;
+    c.height.fill(0);
+  }
+
+  /** Composite `cov` of colour (cr, cg, cb) × shade over texel i. */
+  private put(i: number, cov: number, col: Rgb, shade: number, h: number, rough: number): void {
+    if (cov <= 0) return;
+    const k = 1 - cov;
+    const s = shade * cov;
+    this.r[i] = (this.r[i] ?? 0) * k + col[0] * s;
+    this.g[i] = (this.g[i] ?? 0) * k + col[1] * s;
+    this.b[i] = (this.b[i] ?? 0) * k + col[2] * s;
+    this.a[i] = (this.a[i] ?? 0) * k + cov;
+    this.c.height[i] = (this.c.height[i] ?? 0) * k + h * cov;
+    this.c.rough[i] = (this.c.rough[i] ?? 0.8) * k + rough * cov;
+  }
+
+  /** Pixel bounds of a metre-space box, clipped to the canvas. */
+  private span(x0: number, y0: number, x1: number, y1: number): readonly number[] {
+    const { w, h } = this.c;
+    const p = this.px;
+    return [
+      Math.max(0, Math.floor(x0 / p) - 1),
+      Math.max(0, Math.floor(y0 / p) - 1),
+      Math.min(w - 1, Math.ceil(x1 / p) + 1),
+      Math.min(h - 1, Math.ceil(y1 / p) + 1),
+    ];
+  }
+
+  /** A tapered stem / twig / rachis from (ax, ay) width w0 to (bx, by) width w1, metres. */
+  stem(ax: number, ay: number, bx: number, by: number, w0: number, w1: number, col: Rgb): void {
+    const m = Math.max(w0, w1);
+    const [sx0 = 0, sy0 = 0, sx1 = 0, sy1 = 0] = this.span(
+      Math.min(ax, bx) - m,
+      Math.min(ay, by) - m,
+      Math.max(ax, bx) + m,
+      Math.max(ay, by) + m,
+    );
+    const lx = bx - ax;
+    const ly = by - ay;
+    const l2 = lx * lx + ly * ly || 1;
+    for (let y = sy0; y <= sy1; y++) {
+      const ym = (y + 0.5) * this.px;
+      for (let x = sx0; x <= sx1; x++) {
+        const xm = (x + 0.5) * this.px;
+        const t = clamp01(((xm - ax) * lx + (ym - ay) * ly) / l2);
+        const half = (w0 + (w1 - w0) * t) / 2;
+        const d = segment(xm, ym, ax, ay, bx, by);
+        const cov = clamp01(0.5 - (d - half) / this.px);
+        const round = half > 0 ? Math.sqrt(Math.max(0, 1 - (d / half) ** 2)) : 0;
+        this.put(y * this.c.w + x, cov, col, 1, 0.0015 + half * 0.4 * round, 0.85);
+      }
+    }
+  }
+
+  /**
+   * A leaf from its base (bx, by) along `angle` (radians, 0 = +V, positive = toward +U), `len`
+   * long and `wid` wide at its widest. `serrate` adds teeth; `lift` raises it over earlier layers.
+   */
+  leaf(
+    shape: LeafShape,
+    bx: number,
+    by: number,
+    angle: number,
+    len: number,
+    wid: number,
+    col: Rgb,
+    serrate = 0,
+    lift = 0,
+  ): void {
+    const ux = Math.sin(angle);
+    const uy = Math.cos(angle);
+    // Bounds: the base-to-tip segment padded by the half-width (palmate: the whole blade disc).
+    const tx = bx + ux * len;
+    const ty = by + uy * len;
+    const pad = shape === 'palmate' ? len : wid;
+    const [sx0 = 0, sy0 = 0, sx1 = 0, sy1 = 0] = this.span(
+      Math.min(bx, tx) - pad,
+      Math.min(by, ty) - pad,
+      Math.max(bx, tx) + pad,
+      Math.max(by, ty) + pad,
+    );
+    for (let y = sy0; y <= sy1; y++) {
+      const ym = (y + 0.5) * this.px - by;
+      for (let x = sx0; x <= sx1; x++) {
+        const xm = (x + 0.5) * this.px - bx;
+        const along = xm * ux + ym * uy;
+        const across = xm * uy - ym * ux;
+        let sd: number;
+        let rib: number;
+        if (shape === 'palmate') {
+          // Five pointed lobes around the petiole tip; notch at the stem side.
+          const rr = Math.hypot(along - len * 0.45, across);
+          const th = Math.atan2(across, along - len * 0.45);
+          const lobe = 1 - Math.abs(Math.sin(2.5 * th)) ** 0.6;
+          const edge =
+            len * 0.5 * (0.35 + 0.65 * lobe) * (1 + serrate * Math.abs(Math.sin(18 * th)));
+          sd = rr - edge;
+          const axis = Math.round(th / LOBE) * LOBE;
+          rib = rr * Math.abs(Math.sin(th - axis));
+        } else {
+          const t = along / len;
+          if (t < 0 || t > 1) {
+            sd = Math.max(-along, along - len) + Math.abs(across) * 0.5;
+          } else {
+            const prof =
+              shape === 'ovate'
+                ? Math.sin(Math.PI * t ** 0.8) ** 0.9
+                : shape === 'lance'
+                  ? Math.sin(Math.PI * t ** 0.6)
+                  : shape === 'blade'
+                    ? (1 - t) ** 0.4
+                    : 1 - 0.6 * t;
+            const teeth = 1 - serrate * Math.abs(Math.sin(t * 40));
+            sd = Math.abs(across) - (wid / 2) * prof * teeth;
+          }
+          rib = Math.abs(across);
+        }
+        const cov = clamp01(0.5 - sd / this.px);
+        if (cov <= 0) continue;
+        const inside = clamp01(-sd / (wid * 0.5 + 1e-6));
+        const vein = 1 - smooth(0, this.px * 1.5, rib);
+        const shade = 0.85 + 0.15 * inside;
+        this.put(
+          y * this.c.w + x,
+          cov,
+          col,
+          shade,
+          0.002 + lift + 0.0015 * inside + 0.0006 * vein,
+          0.6,
+        );
+      }
+    }
+  }
+
+  /** Write the layers to the canvas: sRGB RGBA with bled colour, occlusion toward the twig. */
+  finish(axisX = 0.5, reach = 0.35): void {
+    const { w, h } = this.c;
+    const n = w * h;
+    const sa = total(this.a);
+    const mean: Rgb =
+      sa > 0 ? [total(this.r) / sa, total(this.g) / sa, total(this.b) / sa] : [0.1, 0.2, 0.05];
+    const out = new Uint8Array(n * 4);
+    const enc = (v: number): number => SRGB[Math.round(clamp01(v) * 4095)] ?? 0;
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const i = y * w + x;
+        const a = this.a[i] ?? 0;
+        // Un-premultiply; transparent texels take the mean leaf colour (mip-safe bleed).
+        const k = a > 0.02 ? 1 / a : 0;
+        const mix = clamp01(a * 4);
+        out[i * 4] = enc((this.r[i] ?? 0) * k * mix + mean[0] * (1 - mix));
+        out[i * 4 + 1] = enc((this.g[i] ?? 0) * k * mix + mean[1] * (1 - mix));
+        out[i * 4 + 2] = enc((this.b[i] ?? 0) * k * mix + mean[2] * (1 - mix));
+        out[i * 4 + 3] = Math.round(clamp01(a) * 255);
+        const d = Math.abs((x + 0.5) * this.px - axisX);
+        this.c.occl[i] = 0.55 + 0.45 * smooth(0, reach, d + (y + 0.5) * this.px * 0.4);
+      }
+    }
+    this.c.rgba = out;
+    this.c.metal.fill(0);
+  }
+}

package/src/material/paint/foliage.ts

@@ -0,0 +1,23 @@
+// Foliage cell dispatch: FoliageCellId → painter. Each paints colour + alpha mask (cutout leaf
+// cards), anchor at the cell's bottom-centre, growth toward +V.
+
+import type { FoliageCellId } from '../trim-sheet.ts';
+import type { Canvas } from './canvas.ts';
+import { paintBirch, paintBroadleaf, paintMaple, paintMapleAutumn } from './foliage-broad.ts';
+import { paintAcacia, paintPalm, paintWillow } from './foliage-compound.ts';
+import { paintNeedles, paintReeds, paintSpruce, paintSpruceSnow } from './foliage-conifer.ts';
+
+export const FOLIAGE_PAINTERS: Readonly<Record<FoliageCellId, (c: Canvas, seed: number) => void>> =
+  {
+    foliage_broadleaf: paintBroadleaf,
+    foliage_maple: paintMaple,
+    foliage_maple_autumn: paintMapleAutumn,
+    foliage_birch: paintBirch,
+    foliage_acacia: paintAcacia,
+    foliage_palm: paintPalm,
+    foliage_spruce: paintSpruce,
+    foliage_spruce_snow: paintSpruceSnow,
+    foliage_willow: paintWillow,
+    foliage_reeds: paintReeds,
+    foliage_needles: paintNeedles,
+  };

package/src/material/paint/masks.ts

@@ -0,0 +1,44 @@
+// 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).
+
+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);
+    }
+  }
+}
+
+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/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,95 @@
+// 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;
+}
+
+/** RGBA8 sRGB albedo: the stamped image if any, else grey tone × mild cavity. */
+export function packAlbedo(c: Canvas, ao: Float32Array): Uint8Array {
+  if (c.rgba) return c.rgba;
+  const out = new Uint8Array(c.w * c.h * 4);
+  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,56 @@
+// 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.
+// params: width 0.15 · length 1.0 · gap 0.004 · depth 0.004 · knots 1.5 (per board-metre)
+
+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 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;
+  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);
+      }
+      c.height[i] = -depth * (1 - edge) + 0.0004 * ring * edge + 0.0003 * fibre - 0.0008 * knot;
+      c.tone[i] =
+        (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);
+    }
+  }
+}