@developerz.ai/ts23d 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,93 @@
+// Shared growth helpers for foliage cells: quadratic stem curves sampled into points, per-leaf
+// colour jitter and the leaf palettes (linear RGB). Allocation is per leaf/stem, never per pixel.
+
+import type { Rng } from '../../core/index.ts';
+import type { Foliage, Rgb } from './foliage-raster.ts';
+
+/** A quadratic Bézier from p0 via p1 to p2, metres in the cell (anchor usually 0.5, 0.02). */
+export interface Curve {
+  readonly x: readonly number[];
+  readonly y: readonly number[];
+  /** Tangent angle per sample (0 = +V, + toward +U), the convention `Foliage.leaf` takes. */
+  readonly a: readonly number[];
+}
+
+export function curve(
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  n = 16,
+): Curve {
+  const x: number[] = [];
+  const y: number[] = [];
+  const a: number[] = [];
+  for (let i = 0; i <= n; i++) {
+    const t = i / n;
+    const u = 1 - t;
+    x.push(u * u * x0 + 2 * u * t * x1 + t * t * x2);
+    y.push(u * u * y0 + 2 * u * t * y1 + t * t * y2);
+    const dx = 2 * u * (x1 - x0) + 2 * t * (x2 - x1);
+    const dy = 2 * u * (y1 - y0) + 2 * t * (y2 - y1);
+    a.push(Math.atan2(dx, dy));
+  }
+  return { x, y, a };
+}
+
+/** Sample index nearest parameter t ∈ [0, 1]. */
+export const at = (c: Curve, t: number): number => Math.round(t * (c.x.length - 1));
+
+/** Draw a curve as a tapered stem. */
+export function drawStem(f: Foliage, c: Curve, w0: number, w1: number, col: Rgb): void {
+  const n = c.x.length - 1;
+  for (let i = 0; i < n; i++) {
+    const t0 = i / n;
+    const t1 = (i + 1) / n;
+    f.stem(
+      c.x[i] ?? 0,
+      c.y[i] ?? 0,
+      c.x[i + 1] ?? 0,
+      c.y[i + 1] ?? 0,
+      w0 + (w1 - w0) * t0,
+      w0 + (w1 - w0) * t1,
+      col,
+    );
+  }
+}
+
+/** Jitter a colour per leaf: brightness ±amt and a small hue drift between R and G. */
+export function vary(rng: Rng, col: Rgb, amt: number): Rgb {
+  const k = 1 + amt * (rng.next() * 2 - 1);
+  const drift = 1 + amt * 0.6 * (rng.next() * 2 - 1);
+  return [col[0] * k * drift, col[1] * k, (col[2] * k) / drift];
+}
+
+export const dim = (col: Rgb, k: number): Rgb => [col[0] * k, col[1] * k, col[2] * k];
+
+/** Leaf palettes, linear RGB (multiply by a near-white vertex colour on the card). */
+export const LEAF = {
+  beech: [0.09, 0.2, 0.035] as Rgb,
+  maple: [0.1, 0.24, 0.04] as Rgb,
+  birch: [0.16, 0.3, 0.05] as Rgb,
+  acacia: [0.11, 0.2, 0.06] as Rgb,
+  palm: [0.12, 0.22, 0.05] as Rgb,
+  dry: [0.3, 0.2, 0.08] as Rgb,
+  spruce: [0.035, 0.09, 0.04] as Rgb,
+  pine: [0.06, 0.13, 0.04] as Rgb,
+  willow: [0.2, 0.3, 0.08] as Rgb,
+  reed: [0.2, 0.28, 0.08] as Rgb,
+  snow: [0.85, 0.88, 0.92] as Rgb,
+  bark: [0.08, 0.055, 0.035] as Rgb,
+  twig: [0.12, 0.09, 0.05] as Rgb,
+} as const;
+
+/** Autumn maple: each leaf picks one of these, then gets jittered. */
+export const AUTUMN: readonly Rgb[] = [
+  [0.6, 0.08, 0.02],
+  [0.75, 0.25, 0.02],
+  [0.8, 0.45, 0.03],
+  [0.45, 0.04, 0.03],
+  [0.55, 0.35, 0.05],
+];

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

@@ -0,0 +1,135 @@
+// Compound and strand foliage cells, all growing from the bottom-centre anchor toward +V:
+// pinnate acacia (rachis, paired pinnae, tiny leaflets), palm frond (arched rachis, lance
+// leaflets both sides, some dry brown tips), willow curtain (long fine strands of narrow leaves;
+// hang it by mapping the card with V down). A dimmed back layer goes down first.
+
+import { createRng } from '../../core/index.ts';
+import type { Canvas } from './canvas.ts';
+import { at, curve, dim, drawStem, LEAF, vary } from './foliage-common.ts';
+import { Foliage } from './foliage-raster.ts';
+
+export function paintAcacia(c: Canvas, seed: number): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  const rachis = curve(0.5, 0.02, 0.48 + rng.range(-0.05, 0.05), 0.5, 0.5, 0.95);
+  for (let layer = 0; layer < 2; layer++) {
+    const k = layer === 0 ? 0.5 : 1;
+    if (layer === 1) drawStem(f, rachis, 0.01, 0.003, LEAF.twig);
+    const pairs = layer === 0 ? 6 : 8;
+    for (let p = 0; p < pairs; p++) {
+      const t = 0.15 + (p / pairs) * 0.8 + (layer === 0 ? 0.05 : 0);
+      const i = at(rachis, t);
+      for (const side of [-1, 1]) {
+        const a = (rachis.a[i] ?? 0) + side * rng.range(0.9, 1.2);
+        const len = 0.22 * (1 - t * 0.5);
+        const bx = rachis.x[i] ?? 0.5;
+        const by = rachis.y[i] ?? 0.5;
+        const pinna = curve(
+          bx,
+          by,
+          bx + Math.sin(a) * len * 0.5,
+          by + Math.cos(a) * len * 0.5 + 0.02,
+          bx + Math.sin(a) * len,
+          by + Math.cos(a) * len,
+          6,
+        );
+        drawStem(f, pinna, 0.003, 0.0015, dim(LEAF.twig, k));
+        for (let q = 1; q <= 12; q++) {
+          const j = at(pinna, q / 12.5);
+          const col = dim(vary(rng, LEAF.acacia, 0.15), k);
+          for (const s2 of [-1, 1])
+            f.leaf(
+              'ovate',
+              pinna.x[j] ?? 0,
+              pinna.y[j] ?? 0,
+              (pinna.a[j] ?? 0) + s2 * 1.1,
+              0.03,
+              0.011,
+              col,
+              0,
+              layer * 0.002,
+            );
+        }
+      }
+    }
+  }
+  f.finish(0.5, 0.25);
+}
+
+export function paintPalm(c: Canvas, seed: number): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  const rachis = curve(0.5, 0.02, 0.3, 0.7, 0.78, 0.96, 24);
+  for (let layer = 0; layer < 2; layer++) {
+    const k = layer === 0 ? 0.55 : 1;
+    const n = 26;
+    for (let q = 0; q < n; q++) {
+      const t = 0.1 + (q / n) * 0.9 + (layer === 0 ? 0.015 : 0);
+      const i = at(rachis, Math.min(1, t));
+      const bx = rachis.x[i] ?? 0.5;
+      const by = rachis.y[i] ?? 0.5;
+      for (const side of [-1, 1]) {
+        const a = (rachis.a[i] ?? 0) + side * rng.range(0.75, 1.0);
+        const len = 0.3 * Math.sin(Math.PI * (0.2 + 0.75 * t)) * rng.range(0.85, 1.05);
+        const wid = 0.03;
+        f.leaf('lance', bx, by, a, len, wid, dim(vary(rng, LEAF.palm, 0.15), k), 0, layer * 0.002);
+        if (rng.next() < 0.3) {
+          const tx = bx + Math.sin(a) * len * 0.72;
+          const ty = by + Math.cos(a) * len * 0.72;
+          f.leaf(
+            'blade',
+            tx,
+            ty,
+            a,
+            len * 0.28,
+            wid * 0.55,
+            dim(vary(rng, LEAF.dry, 0.2), k),
+            0,
+            layer * 0.002 + 0.0002,
+          );
+        }
+      }
+    }
+    if (layer === 0) drawStem(f, rachis, 0.018, 0.004, dim(LEAF.palm, 0.8));
+  }
+  f.finish(0.5, 0.2);
+}
+
+export function paintWillow(c: Canvas, seed: number): void {
+  const rng = createRng(seed);
+  const f = new Foliage(c);
+  const strands = 9;
+  for (let s = 0; s < strands; s++) {
+    const back = s < 3;
+    const k = back ? 0.55 : 1;
+    const ex = 0.5 + rng.range(-0.4, 0.4);
+    const strand = curve(
+      0.5 + rng.range(-0.03, 0.03),
+      0.02,
+      (0.5 + ex) / 2 + rng.range(-0.1, 0.1),
+      0.5,
+      ex,
+      rng.range(0.85, 0.97),
+      24,
+    );
+    drawStem(f, strand, 0.006, 0.0015, dim(LEAF.twig, k));
+    for (let q = 2; q < 30; q++) {
+      const j = at(strand, q / 30);
+      const side = q % 2 === 0 ? 1 : -1;
+      const a = (strand.a[j] ?? 0) + side * rng.range(0.2, 0.45);
+      const col = dim(vary(rng, LEAF.willow, 0.18), k);
+      f.leaf(
+        'lance',
+        strand.x[j] ?? 0,
+        strand.y[j] ?? 0,
+        a,
+        rng.range(0.07, 0.1),
+        0.014,
+        col,
+        0,
+        back ? 0 : 0.002,
+      );
+    }
+  }
+  f.finish(0.5, 0.2);
+}

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/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);
+  }
+}