@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/material/paint/cells.ts

@@ -0,0 +1,111 @@
+// Rectangular decal cells (1 m each), painted over a backdrop of the cell recipe's own kind:
+// window sash (glazing bars, dark panes the shaders' window glow keys on), four-panel door with
+// raised-and-fielded panels, sign blank with a moulded border and corner screws. Row y grows with
+// world up, so "bottom rail" is low y.
+// params (window_sash): cols 2 · rows 2 (panes per sash) · frame 0.07 · bar 0.022
+// params (door_panel): stile 0.12
+
+import { type Canvas, noiseAt, param, smooth } from './canvas.ts';
+import { dome, rect } from './shapes.ts';
+import type { StripRecipe } from './types.ts';
+
+/** Pane tone: dark enough that `luma < 0.3` marks glass for window glow. */
+export const PANE_TONE = 0.12;
+
+export function paintWindowSash(c: Canvas, r: StripRecipe, seed: number): void {
+  const cols = param(r.params, 'cols', 2);
+  const rows = param(r.params, 'rows', 2);
+  const frame = param(r.params, 'frame', 0.07);
+  const bar = param(r.params, 'bar', 0.022);
+  const meet = 0.5;
+  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 lower = ym < meet;
+    const y0 = lower ? frame : meet + bar;
+    const y1 = lower ? meet - bar : 1 - frame;
+    for (let x = 0; x < c.w; x++) {
+      const xm = (x + 0.5) * pu;
+      const i = y * c.w + x;
+      // Distance into a pane: inside the sash opening, away from every glazing bar.
+      const fx = ((xm - frame) / (1 - 2 * frame)) * cols;
+      const fy = ((ym - y0) / (y1 - y0)) * rows;
+      const inX = Math.min(fx - Math.floor(fx), Math.ceil(fx) - fx) * ((1 - 2 * frame) / cols);
+      const inY = Math.min(fy - Math.floor(fy), Math.ceil(fy) - fy) * ((y1 - y0) / rows);
+      const open = -rect(xm, ym, frame, y0, 1 - frame, y1);
+      const pane = Math.min(open, inX - bar / 2, inY - bar / 2);
+      const wood = noiseAt(c, xm, ym, 0.3, 0.02, seed, 3);
+      if (pane > 0) {
+        const sky = noiseAt(c, xm, ym, 0.6, 0.6, seed + 1, 2);
+        c.height[i] = -0.012;
+        c.tone[i] = PANE_TONE + 0.05 * (ym - y0) + 0.03 * sky;
+        c.rough[i] = 0.05;
+        c.metal[i] = 0;
+      } else {
+        const bevel = smooth(0, 0.01, -pane);
+        c.height[i] = -0.012 * (1 - bevel) + 0.0003 * wood;
+        c.tone[i] = 0.9 + 0.03 * wood;
+        c.rough[i] = r.roughness;
+      }
+    }
+  }
+}
+
+export function paintDoorPanel(c: Canvas, r: StripRecipe, seed: number): void {
+  const stile = param(r.params, 'stile', 0.12);
+  const muntin = stile * 0.7;
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  // Four panels: two tall above the lock rail, two short below. [x0, y0, x1, y1].
+  const midX = 0.5;
+  const panels = [
+    [stile, 0.2, midX - muntin / 2, 0.42],
+    [midX + muntin / 2, 0.2, 1 - stile, 0.42],
+    [stile, 0.58, midX - muntin / 2, 1 - stile],
+    [midX + muntin / 2, 0.58, 1 - stile, 1 - stile],
+  ] as const;
+  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 i = y * c.w + x;
+      let d = 1;
+      for (const [x0, y0, x1, y1] of panels) d = Math.min(d, rect(xm, ym, x0, y0, x1, y1));
+      const grain = noiseAt(c, xm, ym, 0.02, 0.4, seed, 3);
+      // Recess, then a bevel rising to the raised field 0.04 m in from the panel edge.
+      const recess = d < 0 ? 1 : 1 - smooth(0, 0.006, d);
+      const field = smooth(0.005, 0.04, -d);
+      c.height[i] = -0.012 * recess + 0.008 * field + 0.0003 * grain;
+      c.tone[i] = (0.8 + 0.08 * grain) * (d < 0 && d > -0.008 ? 0.65 : d < 0 ? 0.92 : 1);
+      c.rough[i] = r.roughness + 0.05 * grain;
+    }
+  }
+}
+
+export function paintSign(c: Canvas, r: StripRecipe, _seed: number): void {
+  const border = param(r.params, 'border', 0.05);
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  const screws = [0.07, 0.93];
+  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 i = y * c.w + x;
+      const inner = -rect(xm, ym, border, border, 1 - border, 1 - border);
+      const edge = Math.min(xm, ym, 1 - xm, 1 - ym);
+      const moulding = inner < 0 ? dome(Math.abs(-inner - border / 2), border / 2) : 0;
+      let screw = 0;
+      for (const sx of screws)
+        for (const sy of screws) screw = Math.max(screw, dome(Math.hypot(xm - sx, ym - sy), 0.012));
+      c.height[i] = 0.006 * moulding + 0.002 * screw - 0.002 * (1 - smooth(0, 0.004, edge));
+      c.tone[i] = inner > 0 ? 0.95 : 0.85 + 0.1 * moulding;
+      if (screw > 0) {
+        c.tone[i] = 0.6;
+        c.metal[i] = 1;
+        c.rough[i] = 0.35;
+      }
+    }
+  }
+}

package/src/material/paint/compose.ts

@@ -0,0 +1,53 @@
+// Finish a region canvas (AO, normal, ORM, albedo) and blit it into the sheet. Edge texels are
+// replicated `pad` deep (rows for strips, rows + columns for cells) so the first mip levels never
+// sample a neighbouring region.
+
+import type { Canvas } from './canvas.ts';
+import { sobelNormals } from './normal.ts';
+import { cavityOcclusion, packAlbedo, packOrm } from './orm.ts';
+import type { PaintedSheet } from './types.ts';
+
+/** An empty sheet: white albedo (vertex colour reads true), flat normal, AO 1, rough 0.8. */
+export function blankSheet(size: number): PaintedSheet {
+  const n = size * size * 4;
+  const albedo = new Uint8Array(n).fill(255);
+  const normal = new Uint8Array(n);
+  const orm = new Uint8Array(n);
+  const flat = new Uint8Array([128, 128, 255, 255]);
+  const base = new Uint8Array([255, 204, 0, 255]);
+  for (let i = 0; i < n; i += 4) {
+    normal.set(flat, i);
+    orm.set(base, i);
+  }
+  return { size, albedo, normal, orm };
+}
+
+export function composeRegion(
+  sheet: PaintedSheet,
+  c: Canvas,
+  x0: number,
+  y0: number,
+  pad: number,
+): void {
+  const ao = cavityOcclusion(c);
+  const maps = [
+    [sheet.albedo, packAlbedo(c, ao)],
+    [sheet.normal, c.normalRgba ?? sobelNormals(c)],
+    [sheet.orm, packOrm(c, ao)],
+  ] as const;
+  const padX = c.wrapU ? 0 : pad;
+  for (let y = 0; y < c.h; y++) {
+    const sy = Math.min(c.h - 1 - pad, Math.max(pad, y));
+    const dst = ((y0 + y) * sheet.size + x0) * 4;
+    const src = sy * c.w;
+    const l = (src + padX) * 4;
+    const r = (src + c.w - 1 - padX) * 4;
+    for (const [to, from] of maps) {
+      to.set(from.subarray(l, r + 4), dst + padX * 4);
+      for (let x = 0; x < padX; x++) {
+        to.set(from.subarray(l, l + 4), dst + x * 4);
+        to.set(from.subarray(r, r + 4), dst + (c.w - 1 - x) * 4);
+      }
+    }
+  }
+}

package/src/material/paint/concrete.ts

@@ -0,0 +1,62 @@
+// Cast concrete (kind 'concrete'): mottled cement tone, air-void pores, pour-lift lines and
+// formwork tie holes on a grid.
+// params: pores 0.35 (fraction of 8 mm cells holding a void) · ties 0.6 (tie grid, m; 0 = none)
+//         lift 0.6 (pour lift spacing, m; 0 = none) · mottle 0.1
+
+import { type Canvas, noiseAt, param, periodFor, smooth } from './canvas.ts';
+import { hash2 } from './noise.ts';
+import type { StripRecipe } from './types.ts';
+
+const PORE_CELL = 0.008;
+
+export function paintConcrete(c: Canvas, r: StripRecipe, seed: number): void {
+  const p = r.params;
+  const pores = param(p, 'pores', 0.35);
+  const ties = param(p, 'ties', 0.6);
+  const lift = param(p, 'lift', 0.6);
+  const mottle = param(p, 'mottle', 0.1);
+  const pu = c.metresU / c.w;
+  const pv = c.metresV / c.h;
+  const cellM = Math.max(PORE_CELL, 2.5 * Math.max(pu, pv));
+  const pPer = periodFor(c, cellM);
+  const pCell = c.wrapU ? c.metresU / pPer : cellM;
+  const tPer = ties > 0 ? periodFor(c, ties) : 1;
+  const tCell = c.wrapU ? c.metresU / tPer : ties;
+  for (let y = 0; y < c.h; y++) {
+    const ym = (y + 0.5) * pv;
+    const liftD = lift > 0 ? Math.abs(ym - Math.round(ym / lift) * lift) : 1;
+    const liftGroove = 1 - smooth(0, 0.003, liftD);
+    const liftBand = lift > 0 ? hash2(Math.floor(ym / lift), 0, seed + 4) - 0.5 : 0;
+    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.004, 0.004, seed + 2, 2);
+      const ix = Math.floor(xm / pCell) % pPer;
+      const iy = Math.floor(ym / pCell);
+      let pit = 0;
+      if (hash2(ix, iy, seed + 5) < pores) {
+        const cx = (ix + 0.2 + 0.6 * hash2(ix, iy, seed + 6)) * pCell;
+        const cy = (iy + 0.2 + 0.6 * hash2(ix, iy, seed + 7)) * pCell;
+        const rad = pCell * (0.12 + 0.25 * hash2(ix, iy, seed + 8));
+        const d = Math.hypot(xm - cx, ym - cy);
+        pit = d < rad ? 1 - d / rad : 0;
+      }
+      let tie = 0;
+      if (ties > 0) {
+        const tx = xm - (Math.floor(xm / tCell) + 0.5) * tCell;
+        const ty = ym - (Math.floor(ym / ties) + 0.5) * ties;
+        const d = Math.hypot(tx, ty);
+        tie = d < 0.012 ? 1 : 0;
+      }
+      c.height[i] =
+        0.0005 * big + 0.00015 * fine - 0.0015 * pit - 0.006 * tie - 0.0012 * liftGroove;
+      c.tone[i] =
+        (0.78 + mottle * big + 0.05 * liftBand) *
+        (1 + 0.04 * fine) *
+        (1 - 0.4 * pit) *
+        (1 - 0.5 * tie);
+      c.rough[i] = r.roughness + 0.05 * fine + 0.05 * big;
+    }
+  }
+}

package/src/material/paint/courses.ts

@@ -0,0 +1,85 @@
+// Running-bond layout shared by bricks, stone, planks, slates and plates: horizontal courses
+// (rows along V) split into tiles by vertical joints, staggered per course and periodic along U.
+// Per-course column tables are filled once per course, so the per-pixel loop only reads arrays.
+
+import { createRng } from '../../core/index.ts';
+import type { Canvas } from './canvas.ts';
+
+export interface CourseSpec {
+  /** Course height, metres (along V). */
+  readonly course: number;
+  /** Mean tile length, metres (along U). */
+  readonly length: number;
+  /** 0 = regular; 0.5 = sizes vary ±25 %. */
+  readonly irregular: number;
+  /** Fraction of a tile each odd course shifts; random offsets when irregular. */
+  readonly stagger: number;
+  readonly seed: number;
+}
+
+export class Courses {
+  /** Tile index within the current course, per column. */
+  readonly id: Int32Array;
+  /** Distance to the nearest vertical joint, metres, per column. */
+  readonly dx: Float32Array;
+  /** Distance from the tile's left joint, metres, per column. */
+  readonly ux: Float32Array;
+  /** The current course: index and its bottom / top in metres. */
+  index = -1;
+  y0 = 0;
+  y1 = 0;
+  private readonly bounds: number[] = [0];
+  private readonly c: Canvas;
+  private readonly spec: CourseSpec;
+
+  constructor(c: Canvas, spec: CourseSpec) {
+    this.c = c;
+    this.spec = spec;
+    this.id = new Int32Array(c.w);
+    this.dx = new Float32Array(c.w);
+    this.ux = new Float32Array(c.w);
+    const rng = createRng(spec.seed).fork('rows');
+    let y = 0;
+    while (y < c.metresV) {
+      y += spec.course * (1 + spec.irregular * (rng.next() - 0.5));
+      this.bounds.push(y);
+    }
+  }
+
+  /** Point the tables at the course containing metres `ym`; returns the course index. */
+  at(ym: number): number {
+    if (this.index >= 0 && ym >= this.y0 && ym < this.y1) return this.index;
+    let k = 0;
+    while (k < this.bounds.length - 2 && ym >= (this.bounds[k + 1] ?? 0)) k++;
+    this.index = k;
+    this.y0 = this.bounds[k] ?? 0;
+    this.y1 = this.bounds[k + 1] ?? this.c.metresV;
+    this.fill(k);
+    return k;
+  }
+
+  private fill(k: number): void {
+    const { w, metresU } = this.c;
+    const s = this.spec;
+    const rng = createRng(s.seed).fork(`course${k}`);
+    const n = Math.max(1, Math.round(metresU / s.length));
+    const lens: number[] = [];
+    for (let i = 0; i < n; i++) lens.push(1 + s.irregular * (rng.next() - 0.5));
+    const total = lens.reduce((a, b) => a + b, 0);
+    const joints = [0];
+    for (const l of lens) joints.push((joints[joints.length - 1] ?? 0) + (l / total) * metresU);
+    const shift = s.irregular > 0 ? rng.next() * metresU : (k % 2) * s.stagger * (metresU / n);
+    const px = metresU / w;
+    for (let x = 0; x < w; x++) {
+      let u = ((x + 0.5) * px - shift) % metresU;
+      if (u < 0) u += metresU;
+      let t = 0;
+      while (t < n - 1 && u >= (joints[t + 1] ?? metresU)) t++;
+      const a = joints[t] ?? 0;
+      const b = joints[t + 1] ?? metresU;
+      this.id[x] = t;
+      this.ux[x] = u - a;
+      this.dx[x] = Math.min(u - a, b - u);
+    }
+  }
+}

package/src/material/paint/decode-png.ts

@@ -0,0 +1,106 @@
+// Minimal PNG decoder for stamping supplied images into cells and image strips: 8- or 16-bit grey,
+// grey+alpha, RGB, RGBA (16-bit keeps the high byte) and 8-bit palette (with tRNS), non-interlaced. Zero dependencies beyond node:zlib. Anything else
+// throws T3D_RECIPE_INVALID with the conversion to make.
+
+import { inflateSync } from 'node:zlib';
+import { Ts23dError } from '../../core/index.ts';
+
+export interface Rgba {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8Array;
+}
+
+const SIG = [137, 80, 78, 71, 13, 10, 26, 10];
+const CHANNELS: Readonly<Record<number, number>> = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+
+function bad(cause: string): never {
+  throw new Ts23dError('T3D_RECIPE_INVALID', {
+    cause: `cell image: ${cause}`,
+    fix: 'pass PNG bytes, 8 or 16 bits per channel, non-interlaced (e.g. re-save as RGBA8 PNG)',
+  });
+}
+
+function paeth(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+export function decodePng(bytes: Uint8Array): Rgba {
+  if (bytes.length < 33 || SIG.some((s, i) => bytes[i] !== s)) bad('not a PNG (bad signature)');
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  let width = 0;
+  let height = 0;
+  let type = -1;
+  let depth = 8;
+  let palette: Uint8Array = new Uint8Array();
+  let trns: Uint8Array = new Uint8Array();
+  const idat: Uint8Array[] = [];
+  for (let o = 8; o + 8 <= bytes.length; ) {
+    const len = dv.getUint32(o);
+    const name = String.fromCharCode(...bytes.subarray(o + 4, o + 8));
+    const body = bytes.subarray(o + 8, o + 8 + len);
+    if (name === 'IHDR') {
+      width = dv.getUint32(o + 8);
+      height = dv.getUint32(o + 12);
+      type = body[9] ?? -1;
+      depth = body[8] ?? 0;
+      if (depth !== 8 && !(depth === 16 && type !== 3))
+        bad(`bit depth ${depth} (8, or 16 for non-palette images, is supported)`);
+      if (body[12] !== 0) bad('interlaced');
+    } else if (name === 'PLTE') palette = body;
+    else if (name === 'tRNS') trns = body;
+    else if (name === 'IDAT') idat.push(body);
+    else if (name === 'IEND') break;
+    o += 12 + len;
+  }
+  const ch = CHANNELS[type];
+  if (!ch || width === 0 || height === 0) bad(`colour type ${type} or empty image`);
+  const raw = new Uint8Array(inflateSync(Buffer.concat(idat)));
+  const B = depth / 8;
+  const bpp = ch * B;
+  const stride = width * bpp;
+  if (raw.length < height * (stride + 1)) bad('truncated image data');
+  const px = new Uint8Array(height * stride);
+  for (let y = 0; y < height; y++) {
+    const f = raw[y * (stride + 1)] ?? 0;
+    const src = y * (stride + 1) + 1;
+    const row = y * stride;
+    for (let x = 0; x < stride; x++) {
+      const a = x >= bpp ? (px[row + x - bpp] ?? 0) : 0;
+      const b = y > 0 ? (px[row - stride + x] ?? 0) : 0;
+      const c = x >= bpp && y > 0 ? (px[row - stride + x - bpp] ?? 0) : 0;
+      const v = raw[src + x] ?? 0;
+      const pred =
+        f === 1 ? a : f === 2 ? b : f === 3 ? (a + b) >> 1 : f === 4 ? paeth(a, b, c) : 0;
+      px[row + x] = (v + pred) & 255;
+    }
+  }
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0; i < width * height; i++) {
+    const s = i * bpp;
+    const at = (k: number): number => px[s + k * B] ?? 0;
+    const g = at(0);
+    const o = i * 4;
+    if (type === 3) {
+      data[o] = palette[g * 3] ?? 0;
+      data[o + 1] = palette[g * 3 + 1] ?? 0;
+      data[o + 2] = palette[g * 3 + 2] ?? 0;
+      data[o + 3] = trns[g] ?? 255;
+    } else if (ch >= 3) {
+      data[o] = g;
+      data[o + 1] = at(1);
+      data[o + 2] = at(2);
+      data[o + 3] = ch === 4 ? at(3) : 255;
+    } else {
+      data[o] = g;
+      data[o + 1] = g;
+      data[o + 2] = g;
+      data[o + 3] = ch === 2 ? at(1) : 255;
+    }
+  }
+  return { width, height, data };
+}

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

@@ -0,0 +1,73 @@
+// 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 };
+
+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 } },
+  ...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 },
+    clock: { kind: 'noise', scaleMetres: 1, roughness: 0.3 },
+    smokebox: {
+      kind: 'plates',
+      scaleMetres: 1,
+      roughness: 0.6,
+      metalness: 0.2,
+      params: { rust: 0.3 },
+    },
+    sign: { kind: 'noise', scaleMetres: 1, roughness: 0.5 },
+    porthole: { kind: 'plates', scaleMetres: 1, roughness: 0.5 },
+    foliage_broadleaf: leaf,
+    foliage_maple: leaf,
+    foliage_maple_autumn: leaf,
+    foliage_birch: leaf,
+    foliage_acacia: leaf,
+    foliage_palm: leaf,
+    foliage_spruce: leaf,
+    foliage_spruce_snow: leaf,
+    foliage_willow: leaf,
+    foliage_reeds: leaf,
+    foliage_needles: leaf,
+  },
+};

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/foliage-broad.ts

@@ -0,0 +1,126 @@
+// Broadleaf foliage cells: a twig grows from the bottom-centre anchor toward +V, side twigs
+// alternate off it, leaves sit at the nodes. A darker back layer of leaves fills the crown first
+// for depth. Variants: beech/oak cluster (ovate, fine teeth), palmate maple, autumn maple
+// (red/orange/yellow per leaf), birch (small serrated leaves on thin drooping twigs).
+
+import { createRng, type Rng } from '../../core/index.ts';
+import type { Canvas } from './canvas.ts';
+import { AUTUMN, at, curve, dim, drawStem, LEAF, vary } from './foliage-common.ts';
+import { Foliage, type LeafShape, type Rgb } from './foliage-raster.ts';
+
+interface ClusterSpec {
+  readonly shape: LeafShape;
+  readonly len: number;
+  readonly wid: number;
+  readonly serrate: number;
+  readonly twigs: number;
+  readonly perTwig: number;
+  readonly back: number;
+  /** Side-twig droop: 0 = straight out, 1 = bends back down. */
+  readonly droop: number;
+  readonly colour: (rng: Rng) => Rgb;
+}
+
+function cluster(c: Canvas, seed: number, s: ClusterSpec): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  const leafAt = (x: number, y: number, a: number, k: number, lift: number): void => {
+    const len = s.len * rng.range(0.8, 1.15) * k;
+    f.leaf(s.shape, x, y, a, len, s.wid * (len / s.len), s.colour(rng), s.serrate, lift);
+  };
+  // Back layer: darker, unattached leaves filling the crown silhouette.
+  for (let i = 0; i < s.back; i++) {
+    const x = 0.5 + rng.range(-0.33, 0.33);
+    const y = rng.range(0.3, 0.85);
+    const col = dim(s.colour(rng), 0.5);
+    const len = s.len * rng.range(0.8, 1.1);
+    f.leaf(s.shape, x, y, rng.range(-1.4, 1.4), len, s.wid * (len / s.len), col, s.serrate);
+  }
+  const main = curve(
+    0.5,
+    0.02,
+    0.5 + rng.range(-0.1, 0.1),
+    0.45,
+    0.5 + rng.range(-0.08, 0.08),
+    0.8,
+  );
+  drawStem(f, main, 0.016, 0.004, LEAF.twig);
+  for (let k = 0; k < s.twigs; k++) {
+    const t = 0.22 + (k / Math.max(1, s.twigs - 1)) * 0.6;
+    const side = k % 2 === 0 ? 1 : -1;
+    const i = at(main, t);
+    const bx = main.x[i] ?? 0.5;
+    const by = main.y[i] ?? 0.5;
+    const a = (main.a[i] ?? 0) + side * rng.range(0.7, 1.1);
+    const len = 0.3 * (1 - t * 0.45);
+    const ex = bx + Math.sin(a) * len;
+    const ey = by + Math.cos(a) * len - s.droop * len * 0.4;
+    const twig = curve(bx, by, (bx + ex) / 2, (by + ey) / 2 + len * 0.15, ex, ey, 8);
+    drawStem(f, twig, 0.007, 0.002, LEAF.twig);
+    for (let q = 1; q <= s.perTwig; q++) {
+      const j = at(twig, q / s.perTwig);
+      const alt = q % 2 === 0 ? 1 : -1;
+      const ta = (twig.a[j] ?? 0) + (q === s.perTwig ? 0 : alt * rng.range(0.5, 0.9));
+      leafAt(twig.x[j] ?? 0, twig.y[j] ?? 0, ta, 1 - 0.15 * (1 - q / s.perTwig), 0.002);
+    }
+  }
+  const tip = main.x.length - 1;
+  leafAt(main.x[tip] ?? 0.5, main.y[tip] ?? 0.8, main.a[tip] ?? 0, 1.1, 0.003);
+  f.finish(0.5, 0.35);
+}
+
+export function paintBroadleaf(c: Canvas, seed: number): void {
+  cluster(c, seed, {
+    shape: 'ovate',
+    len: 0.15,
+    wid: 0.085,
+    serrate: 0.03,
+    twigs: 6,
+    perTwig: 3,
+    back: 16,
+    droop: 0.1,
+    colour: (rng) => vary(rng, LEAF.beech, 0.18),
+  });
+}
+
+export function paintMaple(c: Canvas, seed: number): void {
+  cluster(c, seed, {
+    shape: 'palmate',
+    len: 0.24,
+    wid: 0.24,
+    serrate: 0.04,
+    twigs: 4,
+    perTwig: 2,
+    back: 7,
+    droop: 0,
+    colour: (rng) => vary(rng, LEAF.maple, 0.15),
+  });
+}
+
+export function paintMapleAutumn(c: Canvas, seed: number): void {
+  cluster(c, seed, {
+    shape: 'palmate',
+    len: 0.24,
+    wid: 0.24,
+    serrate: 0.04,
+    twigs: 4,
+    perTwig: 2,
+    back: 7,
+    droop: 0,
+    colour: (rng) => vary(rng, rng.pick(AUTUMN), 0.12),
+  });
+}
+
+export function paintBirch(c: Canvas, seed: number): void {
+  cluster(c, seed, {
+    shape: 'ovate',
+    len: 0.085,
+    wid: 0.06,
+    serrate: 0.12,
+    twigs: 8,
+    perTwig: 5,
+    back: 22,
+    droop: 0.6,
+    colour: (rng) => vary(rng, LEAF.birch, 0.2),
+  });
+}