@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/render/scene.ts

@@ -0,0 +1,119 @@
+// Flatten a compiled asset into one packed, world-space triangle soup for the beauty renderer:
+// positions, normals, UVs, colours per vertex; surface code + tangent frame per triangle.
+// Packed typed arrays keep the per-pixel loops monomorphic and allocation-free.
+
+import { type CompiledAsset, type Surface, worldMeshes } from '../core/index.ts';
+
+export const SURFACE_CODE: Readonly<Record<Surface, number>> = {
+  opaque: 0,
+  cutout: 1,
+  glass: 2,
+  translucent: 3,
+};
+
+export interface Scene {
+  readonly positions: Float32Array;
+  readonly normals: Float32Array;
+  readonly uvs: Float32Array;
+  readonly colors: Float32Array;
+  /** Three global vertex indices per triangle. */
+  readonly indices: Uint32Array;
+  /** SURFACE_CODE per triangle. */
+  readonly surface: Uint8Array;
+  /** Per-triangle tangent frame for the normal map, 6 floats: T = dP/dU, B = −dP/dV (glTF +Y). */
+  readonly tangents: Float32Array;
+  readonly min: readonly [number, number, number];
+  readonly max: readonly [number, number, number];
+  readonly triangles: number;
+}
+
+export function sceneOf(asset: CompiledAsset): Scene {
+  const meshes = worldMeshes(asset.parts);
+  const surfOf = new Map(asset.parts.map((p) => [p.name, SURFACE_CODE[p.surface ?? 'opaque']]));
+  let nv = 0;
+  let nt = 0;
+  for (const m of meshes.values()) {
+    nv += m.positions.length / 3;
+    nt += m.indices.length / 3;
+  }
+  const positions = new Float32Array(nv * 3);
+  const normals = new Float32Array(nv * 3);
+  const uvs = new Float32Array(nv * 2);
+  const colors = new Float32Array(nv * 3);
+  const indices = new Uint32Array(nt * 3);
+  const surface = new Uint8Array(nt);
+  let vo = 0;
+  let to = 0;
+  for (const [name, m] of meshes) {
+    positions.set(m.positions, vo * 3);
+    normals.set(m.normals, vo * 3);
+    uvs.set(m.uvs, vo * 2);
+    colors.set(m.colors, vo * 3);
+    for (let i = 0; i < m.indices.length; i++) indices[to * 3 + i] = (m.indices[i] ?? 0) + vo;
+    surface.fill(surfOf.get(name) ?? 0, to, to + m.indices.length / 3);
+    vo += m.positions.length / 3;
+    to += m.indices.length / 3;
+  }
+  const min: [number, number, number] = [Infinity, Infinity, Infinity];
+  const max: [number, number, number] = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < positions.length; i++) {
+    const v = positions[i] ?? 0;
+    const k = i % 3;
+    if (v < (min[k] ?? 0)) min[k] = v;
+    if (v > (max[k] ?? 0)) max[k] = v;
+  }
+  if (nv === 0) {
+    min.fill(-0.5);
+    max.fill(0.5);
+  }
+  return {
+    positions,
+    normals,
+    uvs,
+    colors,
+    indices,
+    surface,
+    tangents: tangentsOf(positions, uvs, indices),
+    min,
+    max,
+    triangles: nt,
+  };
+}
+
+/** Per-triangle dP/dU and −dP/dV from the UV parameterisation; zero frame when UVs degenerate. */
+function tangentsOf(p: Float32Array, uv: Float32Array, idx: Uint32Array): Float32Array {
+  const out = new Float32Array(idx.length * 2);
+  for (let t = 0; t < idx.length; t += 3) {
+    const a = idx[t] ?? 0;
+    const b = idx[t + 1] ?? 0;
+    const c = idx[t + 2] ?? 0;
+    const e1x = (p[b * 3] ?? 0) - (p[a * 3] ?? 0);
+    const e1y = (p[b * 3 + 1] ?? 0) - (p[a * 3 + 1] ?? 0);
+    const e1z = (p[b * 3 + 2] ?? 0) - (p[a * 3 + 2] ?? 0);
+    const e2x = (p[c * 3] ?? 0) - (p[a * 3] ?? 0);
+    const e2y = (p[c * 3 + 1] ?? 0) - (p[a * 3 + 1] ?? 0);
+    const e2z = (p[c * 3 + 2] ?? 0) - (p[a * 3 + 2] ?? 0);
+    const du1 = (uv[b * 2] ?? 0) - (uv[a * 2] ?? 0);
+    const dv1 = (uv[b * 2 + 1] ?? 0) - (uv[a * 2 + 1] ?? 0);
+    const du2 = (uv[c * 2] ?? 0) - (uv[a * 2] ?? 0);
+    const dv2 = (uv[c * 2 + 1] ?? 0) - (uv[a * 2 + 1] ?? 0);
+    const det = du1 * dv2 - du2 * dv1;
+    if (Math.abs(det) < 1e-12) continue;
+    const tx = (e1x * dv2 - e2x * dv1) / det;
+    const ty = (e1y * dv2 - e2y * dv1) / det;
+    const tz = (e1z * dv2 - e2z * dv1) / det;
+    const bx = (e2x * du1 - e1x * du2) / det;
+    const by = (e2y * du1 - e1y * du2) / det;
+    const bz = (e2z * du1 - e1z * du2) / det;
+    const lt = Math.hypot(tx, ty, tz) || 1;
+    const lb = -(Math.hypot(bx, by, bz) || 1);
+    const o = t * 2;
+    out[o] = tx / lt;
+    out[o + 1] = ty / lt;
+    out[o + 2] = tz / lt;
+    out[o + 3] = bx / lb;
+    out[o + 4] = by / lb;
+    out[o + 5] = bz / lb;
+  }
+  return out;
+}

package/src/render/shade.ts

@@ -0,0 +1,204 @@
+// Per-pixel shading of the visibility buffer: reconstruct position, normal, UV and vertex colour
+// from (triangle, barycentrics), perturb by the trim sheet's normal map, then light it — key sun
+// with a PCF shadow, sky/bounce hemisphere × multi-direction AO × the sheet's baked occlusion,
+// a roughness-driven sun specular (normalised Blinn–Phong + Schlick Fresnel) and a studio
+// environment reflection (envRadiance) per texel from the sheet's ORM, so metal reads as metal.
+
+import type { PerspectiveCamera } from './camera.ts';
+import { type DepthMap, openness, visibility } from './depth-map.ts';
+import { envRadiance, type Rig } from './lighting.ts';
+import type { Scene } from './scene.ts';
+import { type SheetTextures, sample } from './texture.ts';
+
+export interface ShadeContext {
+  readonly scene: Scene;
+  readonly cam: PerspectiveCamera;
+  readonly tex: SheetTextures;
+  readonly rig: Rig;
+  readonly sunMap: DepthMap;
+  readonly aoMaps: readonly DepthMap[];
+  readonly pcf: readonly Float32Array[];
+  /** AO falloff distance, metres: occluders farther than this along a sky direction don't count. */
+  readonly reach: number;
+}
+
+const ONE_TAP = new Float32Array([0, 0]);
+const hyp = (x: number, y: number, z: number): number => Math.sqrt(x * x + y * y + z * z);
+const texel = new Float32Array(4);
+
+/** Sky openness at p for a surface facing n: cosine-weighted share of unoccluded sky directions. */
+export function skyOpen(c: ShadeContext, p: readonly number[], n: readonly number[]): number {
+  let open = 0;
+  let total = 0;
+  const dirs = c.rig.skyDirs;
+  for (let k = 0; k < dirs.length; k++) {
+    const d = dirs[k];
+    const m = c.aoMaps[k];
+    if (!d || !m) continue;
+    const w = 0.5 + 0.5 * ((n[0] ?? 0) * d[0] + (n[1] ?? 0) * d[1] + (n[2] ?? 0) * d[2]);
+    if (w <= 0) continue;
+    const off = 1.5 / m.k;
+    const v = openness(
+      m,
+      (p[0] ?? 0) + (n[0] ?? 0) * off,
+      (p[1] ?? 0) + (n[1] ?? 0) * off,
+      (p[2] ?? 0) + (n[2] ?? 0) * off,
+      2 / m.k,
+      c.reach,
+    );
+    open += w * v;
+    total += w;
+  }
+  return total > 0 ? open / total : 1;
+}
+
+/** Sun visibility at p (geometric normal n), PCF with one of four rotated tap sets. */
+export function sunVisible(
+  c: ShadeContext,
+  p: readonly number[],
+  n: readonly number[],
+  set: number,
+): number {
+  const m = c.sunMap;
+  const off = 1.2 / m.k;
+  return visibility(
+    m,
+    (p[0] ?? 0) + (n[0] ?? 0) * off,
+    (p[1] ?? 0) + (n[1] ?? 0) * off,
+    (p[2] ?? 0) + (n[2] ?? 0) * off,
+    1.5 / m.k,
+    c.pcf[set & 3] ?? ONE_TAP,
+  );
+}
+
+const pos = [0, 0, 0];
+const nrm = [0, 0, 0];
+const geo = [0, 0, 0];
+
+/** Linear radiance of triangle `t` at barycentrics (b1, b2) into out[0..2]. */
+export function shadeSample(
+  c: ShadeContext,
+  t: number,
+  b1: number,
+  b2: number,
+  mip: number,
+  set: number,
+  out: Float32Array,
+): void {
+  const s = c.scene;
+  const ia = (s.indices[t * 3] ?? 0) * 3;
+  const ib = (s.indices[t * 3 + 1] ?? 0) * 3;
+  const ic = (s.indices[t * 3 + 2] ?? 0) * 3;
+  const b0 = 1 - b1 - b2;
+  const P = s.positions;
+  const N = s.normals;
+  const C = s.colors;
+  for (let k = 0; k < 3; k++) {
+    pos[k] = (P[ia + k] ?? 0) * b0 + (P[ib + k] ?? 0) * b1 + (P[ic + k] ?? 0) * b2;
+    nrm[k] = (N[ia + k] ?? 0) * b0 + (N[ib + k] ?? 0) * b1 + (N[ic + k] ?? 0) * b2;
+  }
+  const ua = (ia / 3) * 2;
+  const ub = (ib / 3) * 2;
+  const uc = (ic / 3) * 2;
+  const U = s.uvs;
+  const u = (U[ua] ?? 0) * b0 + (U[ub] ?? 0) * b1 + (U[uc] ?? 0) * b2;
+  const v = (U[ua + 1] ?? 0) * b0 + (U[ub + 1] ?? 0) * b1 + (U[uc + 1] ?? 0) * b2;
+  const e = c.cam.eye;
+  let vx = e[0] - (pos[0] ?? 0);
+  let vy = e[1] - (pos[1] ?? 0);
+  let vz = e[2] - (pos[2] ?? 0);
+  const vl = hyp(vx, vy, vz) || 1;
+  vx /= vl;
+  vy /= vl;
+  vz /= vl;
+  let nl = hyp(nrm[0] ?? 0, nrm[1] ?? 0, nrm[2] ?? 1) || 1;
+  // Double-sided view: a normal facing away from the eye is lit as its back face.
+  if ((nrm[0] ?? 0) * vx + (nrm[1] ?? 0) * vy + (nrm[2] ?? 0) * vz < 0) nl = -nl;
+  for (let k = 0; k < 3; k++) {
+    nrm[k] = (nrm[k] ?? 0) / nl;
+    geo[k] = nrm[k] ?? 0;
+  }
+  // Normal map through the triangle's tangent frame (skipped where UVs are degenerate).
+  const T = s.tangents;
+  const to = t * 6;
+  const tx = T[to] ?? 0;
+  const ty = T[to + 1] ?? 0;
+  const tz = T[to + 2] ?? 0;
+  if (tx !== 0 || ty !== 0 || tz !== 0) {
+    sample(c.tex.normal, mip, u, v, texel);
+    const mx = texel[0] ?? 0;
+    const my = texel[1] ?? 0;
+    const mz = texel[2] ?? 1;
+    const n0 = nrm[0] ?? 0;
+    const n1 = nrm[1] ?? 0;
+    const n2 = nrm[2] ?? 0;
+    const bx = T[to + 3] ?? 0;
+    const by = T[to + 4] ?? 0;
+    const bz = T[to + 5] ?? 0;
+    const px = tx * mx + bx * my + n0 * mz;
+    const py = ty * mx + by * my + n1 * mz;
+    const pz = tz * mx + bz * my + n2 * mz;
+    const pl = hyp(px, py, pz) || 1;
+    nrm[0] = px / pl;
+    nrm[1] = py / pl;
+    nrm[2] = pz / pl;
+  }
+  sample(c.tex.albedo, mip, u, v, texel);
+  const surf = s.surface[t] ?? 0;
+  const glass = surf === 2;
+  let ar = (texel[0] ?? 1) * ((C[ia] ?? 1) * b0 + (C[ib] ?? 1) * b1 + (C[ic] ?? 1) * b2);
+  let ag =
+    (texel[1] ?? 1) * ((C[ia + 1] ?? 1) * b0 + (C[ib + 1] ?? 1) * b1 + (C[ic + 1] ?? 1) * b2);
+  let ab =
+    (texel[2] ?? 1) * ((C[ia + 2] ?? 1) * b0 + (C[ib + 2] ?? 1) * b1 + (C[ic + 2] ?? 1) * b2);
+  sample(c.tex.orm, mip, u, v, texel);
+  const occ = texel[0] ?? 1;
+  const rough = glass ? 0.06 : Math.max(0.08, texel[1] ?? 0.8);
+  const metal = glass ? 0 : (texel[2] ?? 0);
+  if (glass) {
+    ar *= 0.12;
+    ag *= 0.14;
+    ab *= 0.16;
+  }
+  const r = c.rig;
+  const n0 = nrm[0] ?? 0;
+  const n1 = nrm[1] ?? 0;
+  const n2 = nrm[2] ?? 1;
+  const ndl = n0 * r.sun[0] + n1 * r.sun[1] + n2 * r.sun[2];
+  const gdl = (geo[0] ?? 0) * r.sun[0] + (geo[1] ?? 0) * r.sun[1] + (geo[2] ?? 0) * r.sun[2];
+  const lit = ndl > 0 && gdl > -0.05 ? sunVisible(c, pos, geo, set) * ndl : 0;
+  const open = skyOpen(c, pos, geo);
+  const hemi = 0.5 + 0.5 * n2;
+  const amb = open * (0.35 + 0.65 * occ);
+  const dk = 1 - metal;
+  // Specular: half vector, normalised Blinn–Phong lobe, Schlick Fresnel against F0.
+  let hx = r.sun[0] + vx;
+  let hy = r.sun[1] + vy;
+  let hz = r.sun[2] + vz;
+  const hl = hyp(hx, hy, hz) || 1;
+  hx /= hl;
+  hy /= hl;
+  hz /= hl;
+  const ndh = Math.max(0, n0 * hx + n1 * hy + n2 * hz);
+  const vdh = Math.max(0, vx * hx + vy * hy + vz * hz);
+  const ndv = Math.max(0, n0 * vx + n1 * vy + n2 * vz);
+  const shin = Math.min(2048, 2 / (rough * rough * rough * rough) - 2);
+  const lobe = ((shin + 8) / 25.13) * ndh ** shin;
+  const fr = (1 - vdh) ** 5;
+  const fv = (1 - ndv) ** 5;
+  // Image-based term: the studio seen along the reflection, occluded like the sky (+ cavity AO).
+  const rz = 2 * ndv * n2 - vz;
+  const specOcc = open * (0.4 + 0.6 * occ);
+  const ch = [ar, ag, ab];
+  for (let k = 0; k < 3; k++) {
+    const al = ch[k] ?? 0;
+    const f0 = 0.04 * dk + al * metal;
+    const sky = (r.bounce[k] ?? 0) * (1 - hemi) + (r.sky[k] ?? 0) * hemi;
+    const diffuse = al * dk * ((r.sunColor[k] ?? 0) * lit + sky * amb);
+    const spec = (f0 + (1 - f0) * fr) * lobe * lit * (r.sunColor[k] ?? 0) * 0.8;
+    const env = glass
+      ? (f0 + (1 - f0) * fv * (1 - rough) * (1 - rough)) * (r.sky[k] ?? 0) * open * 2.5
+      : (f0 + (Math.max(1 - rough, f0) - f0) * fv) * envRadiance(rz, rough, k) * specOcc;
+    out[k] = (diffuse + spec + env) * r.exposure;
+  }
+}

package/src/render/sheet.ts

@@ -0,0 +1,88 @@
+// Contact sheet: ONE PNG, six labelled orthographic views on a metre grid. Built for an agent's
+// eyes — one image read shows proportions from every side, so it fixes the right thing first.
+//   row 1: 3/4 FRONT · FRONT (+X) · SIDE (-Y)
+//   row 2: TOP · 3/4 REAR · FAR LOD (LOD2, 3/4 front)
+
+import { type CompiledAsset, encodePng, type Vec3 } from '../core/index.ts';
+import { drawText } from './font.ts';
+import { drawAsset, line, orthoCamera, type Target, type View, worldParts } from './raster.ts';
+
+export const VIEWS: readonly View[] = [
+  { label: '3/4 FRONT', dir: [-1, 0.8, -0.6], up: [0, 0, 1] },
+  { label: 'FRONT +X', dir: [-1, 0, 0], up: [0, 0, 1] },
+  { label: 'SIDE -Y', dir: [0, 1, 0], up: [0, 0, 1] },
+  { label: 'TOP', dir: [0, 0, -1], up: [1, 0, 0] },
+  { label: '3/4 REAR', dir: [1, -0.8, -0.6], up: [0, 0, 1] },
+  { label: 'FAR LOD2', dir: [-1, 0.8, -0.6], up: [0, 0, 1] },
+];
+
+export function bounds(asset: CompiledAsset): {
+  centre: Vec3;
+  extent: number;
+  min: Vec3;
+  max: Vec3;
+} {
+  const min = [Infinity, Infinity, Infinity];
+  const max = [-Infinity, -Infinity, -Infinity];
+  for (const m of worldParts(asset)) {
+    for (let i = 0; i < m.positions.length; i += 3) {
+      for (let k = 0; k < 3; k++) {
+        const v = m.positions[i + k] ?? 0;
+        min[k] = Math.min(min[k] ?? 0, v);
+        max[k] = Math.max(max[k] ?? 0, v);
+      }
+    }
+  }
+  const lo: Vec3 = [min[0] ?? 0, min[1] ?? 0, min[2] ?? 0];
+  const hi: Vec3 = [max[0] ?? 0, max[1] ?? 0, max[2] ?? 0];
+  const extent = Math.max(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2], 0.1);
+  return {
+    centre: [(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, (lo[2] + hi[2]) / 2],
+    extent,
+    min: lo,
+    max: hi,
+  };
+}
+
+const gridStep = (extent: number): number =>
+  [0.1, 0.5, 1, 5, 10, 50, 100].find((s) => extent / s <= 24) ?? 100;
+
+export interface SheetOptions {
+  readonly cell?: number;
+  /** The far view's asset — compile the same recipe at LOD 2 and pass it here. */
+  readonly far?: CompiledAsset;
+}
+
+export function contactSheet(asset: CompiledAsset, o: SheetOptions = {}): Uint8Array {
+  const cell = o.cell ?? 400;
+  const width = cell * 3;
+  const height = cell * 2 + 40;
+  const px = new Uint8Array(width * height * 4).fill(255);
+  const b = bounds(asset);
+  const step = gridStep(b.extent);
+  VIEWS.forEach((view, i) => {
+    const t: Target = {
+      px: new Uint8Array(cell * cell * 4),
+      depth: new Float32Array(cell * cell).fill(Infinity),
+      width: cell,
+      height: cell,
+    };
+    for (let k = 0; k < cell * cell; k++) t.px.set([238, 240, 243, 255], k * 4);
+    const cam = orthoCamera(view, b.centre, b.extent, cell);
+    drawAsset(t, cam, i === 5 && o.far ? o.far : asset);
+    const g0 = Math.floor(Math.min(b.min[0], b.min[1]) / step - 1) * step;
+    const g1 = Math.ceil(Math.max(b.max[0], b.max[1]) / step + 1) * step;
+    for (let g = g0; g <= g1 + 1e-9; g += step) {
+      line(t, cam.project([g, g0, 0]), cam.project([g, g1, 0]), [190, 196, 204]);
+      line(t, cam.project([g0, g, 0]), cam.project([g1, g, 0]), [190, 196, 204]);
+    }
+    const ox = (i % 3) * cell;
+    const oy = 40 + Math.floor(i / 3) * cell;
+    for (let y = 0; y < cell; y++)
+      px.set(t.px.subarray(y * cell * 4, (y + 1) * cell * 4), ((oy + y) * width + ox) * 4);
+    drawText(px, width, ox + 8, oy + 8, view.label, 3, [40, 44, 52]);
+  });
+  const dims = `${asset.name}  ${(b.max[0] - b.min[0]).toFixed(1)}X${(b.max[1] - b.min[1]).toFixed(1)}X${(b.max[2] - b.min[2]).toFixed(1)}M  GRID ${step}M  LOD${asset.lod}`;
+  drawText(px, width, 10, 10, dims, 4, [20, 22, 26]);
+  return encodePng(width, height, px);
+}

package/src/render/texture.ts

@@ -0,0 +1,97 @@
+// The trim sheet as the beauty renderer samples it: albedo (linear, alpha), tangent-space normal
+// and ORM, each as a box-filtered mip chain, sampled bilinearly — U repeats (strips tile), V clamps
+// (rows never bleed). The mip level is chosen per triangle by the caller (texel ÷ pixel footprint).
+
+import type { PaintedSheet } from '../material/index.ts';
+
+export interface Mip {
+  readonly size: number;
+  /** 4 floats per texel. */
+  readonly data: Float32Array;
+}
+
+export interface SheetTextures {
+  readonly size: number;
+  readonly albedo: readonly Mip[];
+  readonly normal: readonly Mip[];
+  readonly orm: readonly Mip[];
+}
+
+const SRGB = new Float32Array(256).map((_, i) => {
+  const v = i / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+});
+
+function chain(src: Uint8Array, size: number, decode: (c: number, v: number) => number): Mip[] {
+  const top = new Float32Array(size * size * 4);
+  for (let i = 0; i < top.length; i++) top[i] = decode(i & 3, src[i] ?? 0);
+  const out: Mip[] = [{ size, data: top }];
+  let cur = out[0];
+  while (cur && cur.size > 4) {
+    const s = cur.size / 2;
+    const d = new Float32Array(s * s * 4);
+    const p = cur.data;
+    const w = cur.size;
+    for (let y = 0; y < s; y++)
+      for (let x = 0; x < s; x++)
+        for (let c = 0; c < 4; c++) {
+          const a = ((2 * y * w + 2 * x) << 2) + c;
+          const b = a + w * 4;
+          d[((y * s + x) << 2) + c] =
+            ((p[a] ?? 0) + (p[a + 4] ?? 0) + (p[b] ?? 0) + (p[b + 4] ?? 0)) * 0.25;
+        }
+    cur = { size: s, data: d };
+    out.push(cur);
+  }
+  return out;
+}
+
+const cache = new WeakMap<PaintedSheet, SheetTextures>();
+
+export function sheetTextures(sheet: PaintedSheet): SheetTextures {
+  const hit = cache.get(sheet);
+  if (hit) return hit;
+  const t: SheetTextures = {
+    size: sheet.size,
+    albedo: chain(sheet.albedo, sheet.size, (c, v) => (c === 3 ? v / 255 : (SRGB[v] ?? 0))),
+    normal: chain(sheet.normal, sheet.size, (c, v) => (c === 3 ? 1 : v / 127.5 - 1)),
+    orm: chain(sheet.orm, sheet.size, (_c, v) => v / 255),
+  };
+  cache.set(sheet, t);
+  return t;
+}
+
+/** Bilinear sample of mip `level` at (u, v) into out[0..3]. */
+export function sample(
+  mips: readonly Mip[],
+  level: number,
+  u: number,
+  v: number,
+  out: Float32Array,
+): void {
+  const m = mips[Math.min(mips.length - 1, Math.max(0, level))] ?? mips[0];
+  if (!m) return;
+  const s = m.size;
+  const x = u * s - 0.5;
+  const y = Math.min(s - 1, Math.max(0, v * s - 0.5));
+  const xf = Math.floor(x);
+  const yf = Math.floor(y);
+  const fx = x - xf;
+  const fy = y - yf;
+  const x0 = ((xf % s) + s) % s;
+  const x1 = (x0 + 1) % s;
+  const y0 = yf;
+  const y1 = Math.min(s - 1, yf + 1);
+  const d = m.data;
+  const a = (y0 * s + x0) << 2;
+  const b = (y0 * s + x1) << 2;
+  const c = (y1 * s + x0) << 2;
+  const e = (y1 * s + x1) << 2;
+  const w0 = (1 - fx) * (1 - fy);
+  const w1 = fx * (1 - fy);
+  const w2 = (1 - fx) * fy;
+  const w3 = fx * fy;
+  for (let k = 0; k < 4; k++)
+    out[k] =
+      (d[a + k] ?? 0) * w0 + (d[b + k] ?? 0) * w1 + (d[c + k] ?? 0) * w2 + (d[e + k] ?? 0) * w3;
+}

package/src/render/thumbnail.ts

@@ -0,0 +1,75 @@
+// Thumbnail: ONE hero view (3/4 front, slightly from above) on a transparent background, for
+// gallery cards and asset browsers. Rendered at 3×, cropped to the asset, filtered down: smooth edges.
+// Same zero-GPU rasteriser as the contact sheet — deterministic bytes, runs in CI.
+
+import { type CompiledAsset, encodePng } from '../core/index.ts';
+import { drawAsset, orthoCamera, type Target, type View } from './raster.ts';
+import { bounds } from './sheet.ts';
+
+export interface ThumbnailOptions {
+  /** Output edge in pixels (square). Default 512. */
+  readonly size?: number;
+  readonly view?: View;
+}
+
+const HERO: View = { label: 'HERO', dir: [-1, 0.75, -0.45], up: [0, 0, 1] };
+
+export function thumbnail(asset: CompiledAsset, o: ThumbnailOptions = {}): Uint8Array {
+  const size = o.size ?? 512;
+  const big = size * 3;
+  const t: Target = {
+    px: new Uint8Array(big * big * 4),
+    depth: new Float32Array(big * big).fill(Infinity),
+    width: big,
+    height: big,
+  };
+  const b = bounds(asset);
+  drawAsset(t, orthoCamera(o.view ?? HERO, b.centre, b.extent * 0.92, big), asset);
+  // Crop to the drawn pixels (square, 6% margin) so every card is filled the same way.
+  let x0 = big;
+  let y0 = big;
+  let x1 = -1;
+  let y1 = -1;
+  for (let y = 0; y < big; y++)
+    for (let x = 0; x < big; x++)
+      if ((t.px[(y * big + x) * 4 + 3] ?? 0) > 0) {
+        x0 = Math.min(x0, x);
+        y0 = Math.min(y0, y);
+        x1 = Math.max(x1, x);
+        y1 = Math.max(y1, y);
+      }
+  const side = x1 < 0 ? big : Math.max(x1 - x0, y1 - y0) * 1.12 + 1;
+  const ox = x1 < 0 ? 0 : (x0 + x1) / 2 - side / 2;
+  const oy = x1 < 0 ? 0 : (y0 + y1) / 2 - side / 2;
+  const step = side / size;
+  // Supersampled box filter over each output pixel's footprint; alpha-weighted colour so
+  // silhouettes stay clean against any page background.
+  const out = new Uint8Array(size * size * 4);
+  const taps = [0.25, 0.75];
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      let r = 0;
+      let g = 0;
+      let bl = 0;
+      let a = 0;
+      for (const fy of taps)
+        for (const fx of taps) {
+          const sx = Math.floor(ox + (x + fx) * step);
+          const sy = Math.floor(oy + (y + fy) * step);
+          if (sx < 0 || sy < 0 || sx >= big || sy >= big) continue;
+          const i = (sy * big + sx) * 4;
+          const w = t.px[i + 3] ?? 0;
+          r += (t.px[i] ?? 0) * w;
+          g += (t.px[i + 1] ?? 0) * w;
+          bl += (t.px[i + 2] ?? 0) * w;
+          a += w;
+        }
+      if (a > 0)
+        out.set(
+          [Math.round(r / a), Math.round(g / a), Math.round(bl / a), Math.round(a / 4)],
+          (y * size + x) * 4,
+        );
+    }
+  }
+  return encodePng(size, size, out);
+}