@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/qa/measures.ts

@@ -0,0 +1,67 @@
+// Gate: the model matches its spec sheet. Each `real.measures` entry (driver diameter, gauge,
+// wheelbase, turret width…) is measured on the LOD0 model and must land within tolerance (2%
+// default — tighter than the overall box, because these are the numbers players notice).
+
+import {
+  type Bounds,
+  boundsOf,
+  type CompiledAsset,
+  type Measure,
+  worldMeshes,
+} from '../core/index.ts';
+import type { Finding, Gate } from './types.ts';
+
+const AXIS = { x: 0, y: 1, z: 2 } as const;
+
+function union(bounds: readonly Bounds[]): Bounds | null {
+  if (bounds.length === 0) return null;
+  const k = [0, 1, 2] as const;
+  return {
+    min: k.map((i) => Math.min(...bounds.map((b) => b.min[i]))) as unknown as Bounds['min'],
+    max: k.map((i) => Math.max(...bounds.map((b) => b.max[i]))) as unknown as Bounds['max'],
+  };
+}
+
+export function measure(asset: CompiledAsset, m: Measure): number | null {
+  const meshes = worldMeshes(asset.parts);
+  const of = (prefix: string): Bounds | null =>
+    union(
+      [...meshes]
+        .filter(([n]) => n === prefix || n.startsWith(`${prefix}_`))
+        .map(([, mesh]) => boundsOf(mesh)),
+    );
+  const k = AXIS[m.axis];
+  if (m.between) {
+    const [a, b] = [of(m.between[0]), of(m.between[1])];
+    if (!a || !b) return null;
+    return Math.abs((a.min[k] + a.max[k]) / 2 - (b.min[k] + b.max[k]) / 2);
+  }
+  const u = union((m.parts ?? []).map(of).filter((b): b is Bounds => b !== null));
+  return u ? u.max[k] - u.min[k] : null;
+}
+
+export const measures: Gate = (asset): Finding[] => {
+  if (asset.lod !== 0 || !asset.real?.measures) return [];
+  return asset.real.measures.flatMap((m): Finding[] => {
+    const got = measure(asset, m);
+    const tol = m.tolerance ?? 0.02;
+    if (got === null) {
+      return [
+        {
+          gate: 'measures',
+          message: `'${m.label}': no part matches ${JSON.stringify(m.parts ?? m.between)}`,
+          fix: 'name the parts the measure refers to, or fix the names in the measure',
+        },
+      ];
+    }
+    return Math.abs(got - m.value) / m.value > tol
+      ? [
+          {
+            gate: 'measures',
+            message: `${m.label}: ${got.toFixed(3)} m on ${m.axis.toUpperCase()}, spec ${m.value} m (±${tol * 100}%)${m.source ? ` — ${m.source}` : ''}`,
+            fix: 'rebuild the part from the spec number; never edit the spec to match the model',
+          },
+        ]
+      : [];
+  });
+};

package/src/qa/occlusion.ts

@@ -0,0 +1,166 @@
+// Gates: surfaces a viewer either can't see or can't see cleanly. `zFighting` — a face lying in
+// another part's face, both facing the same way, flickers in every engine. `hiddenParts` — a part
+// entirely inside another closed solid is budget nobody ever sees. Both need a closed partner
+// (point-in-solid); open sheets are skipped, never guessed.
+
+import {
+  type Bounds,
+  boundsOf,
+  type CompiledAsset,
+  type Mesh,
+  type Vec3,
+  worldMeshes,
+} from '../core/index.ts';
+import { TriangleGrid } from './geometry.ts';
+import { SolidIndex } from './inside.ts';
+import type { Finding, Gate } from './types.ts';
+
+const overlaps = (a: Bounds, b: Bounds, eps: number): boolean =>
+  [0, 1, 2].every(
+    (k) => (a.min[k] ?? 0) <= (b.max[k] ?? 0) + eps && (b.min[k] ?? 0) <= (a.max[k] ?? 0) + eps,
+  );
+const contains = (outer: Bounds, inner: Bounds): boolean =>
+  [0, 1, 2].every(
+    (k) => (outer.min[k] ?? 0) <= (inner.min[k] ?? 0) && (inner.max[k] ?? 0) <= (outer.max[k] ?? 0),
+  );
+
+/** Up to `cap` triangle centroids with unit face normals, evenly strided (deterministic). */
+function faceSamples(m: Mesh, cap: number): Array<{ p: Vec3; n: Vec3 }> {
+  const tris = m.indices.length / 3;
+  const step = Math.max(1, Math.floor(tris / cap));
+  const out: Array<{ p: Vec3; n: Vec3 }> = [];
+  const P = m.positions;
+  const v = (i: number): Vec3 => [P[i * 3] ?? 0, P[i * 3 + 1] ?? 0, P[i * 3 + 2] ?? 0];
+  for (let t = 0; t < tris; t += step) {
+    const a = v(m.indices[t * 3] ?? 0);
+    const b = v(m.indices[t * 3 + 1] ?? 0);
+    const c = v(m.indices[t * 3 + 2] ?? 0);
+    const u: Vec3 = [b[0] - a[0], b[1] - a[1], b[2] - a[2]];
+    const w: Vec3 = [c[0] - a[0], c[1] - a[1], c[2] - a[2]];
+    const g: Vec3 = [
+      u[1] * w[2] - u[2] * w[1],
+      u[2] * w[0] - u[0] * w[2],
+      u[0] * w[1] - u[1] * w[0],
+    ];
+    const len = Math.hypot(...g);
+    if (len < 1e-10) continue;
+    out.push({
+      p: [(a[0] + b[0] + c[0]) / 3, (a[1] + b[1] + c[1]) / 3, (a[2] + b[2] + c[2]) / 3],
+      n: [g[0] / len, g[1] / len, g[2] / len],
+    });
+  }
+  return out;
+}
+
+interface Scene {
+  readonly names: string[];
+  readonly mesh: Map<string, Mesh>;
+  readonly bounds: Map<string, Bounds>;
+  grid(name: string): TriangleGrid;
+  solid(name: string): SolidIndex;
+}
+
+function scene(asset: CompiledAsset): Scene {
+  const mesh = worldMeshes(asset.parts);
+  const bounds = new Map([...mesh].map(([n, m]) => [n, boundsOf(m)]));
+  const grids = new Map<string, TriangleGrid>();
+  const solids = new Map<string, SolidIndex>();
+  const lazy =
+    <T>(cache: Map<string, T>, make: (m: Mesh) => T) =>
+    (name: string): T => {
+      const hit = cache.get(name);
+      if (hit) return hit;
+      const made = make(
+        mesh.get(name) ?? {
+          positions: new Float32Array(),
+          normals: new Float32Array(),
+          uvs: new Float32Array(),
+          colors: new Float32Array(),
+          indices: new Uint32Array(),
+        },
+      );
+      cache.set(name, made);
+      return made;
+    };
+  return {
+    names: [...mesh.keys()],
+    mesh,
+    bounds,
+    grid: lazy(grids, (m) => new TriangleGrid(m)),
+    solid: lazy(solids, (m) => new SolidIndex(m)),
+  };
+}
+
+const ON = 2e-4;
+const PROBE = 2e-3;
+
+export const zFighting: Gate = (asset) => {
+  const s = scene(asset);
+  const out: Finding[] = [];
+  for (const a of s.names) {
+    const ba = s.bounds.get(a);
+    const ma = s.mesh.get(a);
+    if (!ba || !ma) continue;
+    const samples = faceSamples(ma, 256);
+    for (const b of s.names) {
+      const bb = s.bounds.get(b);
+      if (a === b || !bb || !overlaps(ba, bb, ON)) continue;
+      let hits = 0;
+      for (const { p, n } of samples) {
+        if (!overlaps({ min: p, max: p }, bb, ON) || s.grid(b).nearest(p, ON) > ON) continue;
+        const solid = s.solid(b);
+        const behind = solid.inside([
+          p[0] - n[0] * PROBE,
+          p[1] - n[1] * PROBE,
+          p[2] - n[2] * PROBE,
+        ]);
+        const front = solid.inside([p[0] + n[0] * PROBE, p[1] + n[1] * PROBE, p[2] + n[2] * PROBE]);
+        if (behind && !front) hits++;
+      }
+      if (hits >= 2)
+        out.push({
+          gate: 'z-fighting',
+          part: a,
+          message: `'${a}' has ${hits} face sample(s) lying in '${b}''s surface, facing the same way — it flickers`,
+          fix: `stand '${a}' proud of '${b}' by ≥ 2 mm, or inset it, or cut it from '${b}'; coplanar faces never render cleanly`,
+        });
+    }
+  }
+  return out;
+};
+
+export const hiddenParts: Gate = (asset) => {
+  const s = scene(asset);
+  return s.names.flatMap((a): Finding[] => {
+    const ba = s.bounds.get(a);
+    const ma = s.mesh.get(a);
+    if (!ba || !ma) return [];
+    const pts = faceSamples(ma, 64).map((x) => x.p);
+    const stride = Math.max(1, Math.floor(ma.positions.length / 192));
+    for (let i = 0; i < ma.positions.length / 3; i += stride)
+      pts.push([
+        ma.positions[i * 3] ?? 0,
+        ma.positions[i * 3 + 1] ?? 0,
+        ma.positions[i * 3 + 2] ?? 0,
+      ]);
+    const host = s.names.find((b) => {
+      const bb = s.bounds.get(b);
+      if (b === a || !bb || !contains(bb, ba)) return false;
+      // Inside, and not merely flush with the host's skin (that is seating, not hiding).
+      return (
+        pts.every((p) => s.solid(b).inside(p)) &&
+        pts.every((p) => s.grid(b).nearest(p, PROBE) > PROBE)
+      );
+    });
+    return host
+      ? [
+          {
+            gate: 'hidden-parts',
+            part: a,
+            message: `'${a}' (${ma.indices.length / 3} tris) is entirely inside '${host}' — nobody can see it`,
+            fix: `delete it, gate it behind ctx.lod, or move it out of '${host}'; hidden triangles are wasted budget`,
+          },
+        ]
+      : [];
+  });
+};

package/src/qa/sanity.ts

@@ -0,0 +1,137 @@
+// Gates: per-part mesh sanity a reviewer would spot at once — non-finite numbers (NaN from a
+// zero-length normalize), vertex colours outside [0,1], shading normals that point against the
+// face winding (black or inside-out lighting), and wasted zero-area triangles.
+
+import type { CompiledAsset, Mesh, Part } from '../core/index.ts';
+import type { Finding, Gate } from './types.ts';
+
+const parts = (asset: CompiledAsset): Array<[Part, Mesh]> =>
+  asset.parts.flatMap((p): Array<[Part, Mesh]> => (p.mesh ? [[p, p.mesh]] : []));
+
+const finite = (a: Float32Array): boolean => {
+  for (let i = 0; i < a.length; i++) if (!Number.isFinite(a[i] ?? 0)) return false;
+  return true;
+};
+
+export const nonFinite: Gate = (asset) =>
+  parts(asset).flatMap(([p, m]): Finding[] => {
+    const bad = (
+      [
+        ['positions', m.positions],
+        ['normals', m.normals],
+        ['uvs', m.uvs],
+        ['colors', m.colors],
+      ] as const
+    )
+      .filter(([, a]) => !finite(a))
+      .map(([n]) => n);
+    const maxIndex = m.positions.length / 3;
+    const outOfRange = m.indices.some((i) => i >= maxIndex);
+    if (outOfRange) bad.push('indices' as never);
+    return bad.length
+      ? [
+          {
+            gate: 'non-finite',
+            part: p.name,
+            message: `'${p.name}' has NaN/Infinity or out-of-range data in ${bad.join(', ')}`,
+            fix: 'look for a zero-length normalize, a divide by a zero count or segment, or an index past the vertex count',
+          },
+        ]
+      : [];
+  });
+
+export const vertexColors: Gate = (asset) =>
+  parts(asset).flatMap(([p, m]): Finding[] => {
+    let lo = Infinity;
+    let hi = -Infinity;
+    for (const c of m.colors) {
+      if (c < lo) lo = c;
+      if (c > hi) hi = c;
+    }
+    return lo < -1e-6 || hi > 1 + 1e-6
+      ? [
+          {
+            gate: 'vertex-colors',
+            part: p.name,
+            message: `'${p.name}' vertex colour spans ${lo.toFixed(3)}…${hi.toFixed(3)}, outside linear [0,1]`,
+            fix: 'colours are linear 0–1 (use the palette / material helpers); clamp after grime or livery maths',
+          },
+        ]
+      : [];
+  });
+
+/** Per triangle: geometric normal (from winding) vs the mean of its three vertex normals. */
+function windingStats(m: Mesh): {
+  flipped: number;
+  area: number;
+  flippedArea: number;
+  counted: number;
+} {
+  const P = m.positions;
+  const N = m.normals;
+  let flipped = 0;
+  let area = 0;
+  let flippedArea = 0;
+  let counted = 0;
+  for (let t = 0; t < m.indices.length; t += 3) {
+    const a = (m.indices[t] ?? 0) * 3;
+    const b = (m.indices[t + 1] ?? 0) * 3;
+    const c = (m.indices[t + 2] ?? 0) * 3;
+    const ux = (P[b] ?? 0) - (P[a] ?? 0);
+    const uy = (P[b + 1] ?? 0) - (P[a + 1] ?? 0);
+    const uz = (P[b + 2] ?? 0) - (P[a + 2] ?? 0);
+    const vx = (P[c] ?? 0) - (P[a] ?? 0);
+    const vy = (P[c + 1] ?? 0) - (P[a + 1] ?? 0);
+    const vz = (P[c + 2] ?? 0) - (P[a + 2] ?? 0);
+    const gx = uy * vz - uz * vy;
+    const gy = uz * vx - ux * vz;
+    const gz = ux * vy - uy * vx;
+    const len = Math.hypot(gx, gy, gz);
+    if (len < 1e-12) continue;
+    counted++;
+    const nx = (N[a] ?? 0) + (N[b] ?? 0) + (N[c] ?? 0);
+    const ny = (N[a + 1] ?? 0) + (N[b + 1] ?? 0) + (N[c + 1] ?? 0);
+    const nz = (N[a + 2] ?? 0) + (N[b + 2] ?? 0) + (N[c + 2] ?? 0);
+    area += len;
+    // Against the face by more than ~95°: the lighting is inside out, not just smoothed.
+    if ((gx * nx + gy * ny + gz * nz) / (len * (Math.hypot(nx, ny, nz) || 1)) < -0.1) {
+      flipped++;
+      flippedArea += len;
+    }
+  }
+  return { flipped, area, flippedArea, counted };
+}
+
+/** Shading normals must agree with the winding (the side a renderer culls/lights). */
+export const normalsMatchWinding: Gate = (asset) =>
+  parts(asset).flatMap(([p, m]): Finding[] => {
+    const s = windingStats(m);
+    // 1% of a part's area tolerates a few pinched poles on smooth caps.
+    return s.flipped > 0 && s.flippedArea > s.area * 0.01
+      ? [
+          {
+            gate: 'normals-winding',
+            part: p.name,
+            message: `'${p.name}': ${s.flipped} triangle(s) (${((100 * s.flippedArea) / s.area).toFixed(1)}% of its area) have vertex normals opposing their face — inverted winding, or normals smoothed across a hard crease`,
+            fix: 'split normals at creases (lathe crease angle / weightedNormals hardAngle), or fix the mirrored piece: a negative-scale place() flips winding but not normals',
+          },
+        ]
+      : [];
+  });
+
+/** Zero-area triangles: invisible, but they cost index bandwidth and skew QA sampling. */
+export const degenerateTriangles: Gate = (asset) =>
+  parts(asset).flatMap(([p, m]): Finding[] => {
+    const tris = m.indices.length / 3;
+    const zero = tris - windingStats(m).counted;
+    return zero > tris * 0.05
+      ? [
+          {
+            gate: 'degenerate-triangles',
+            part: p.name,
+            message: `'${p.name}': ${zero} of ${tris} triangles have zero area`,
+            fix: 'a ring/lathe with a zero radius emits fans of slivers: cap it with a point instead, or skip the segment',
+          },
+        ]
+      : [];
+  });

package/src/qa/types.ts

@@ -0,0 +1,17 @@
+// QA vocabulary shared by every gate.
+
+import type { CompiledAsset } from '../core/index.ts';
+
+export interface Finding {
+  readonly gate: string;
+  readonly part?: string;
+  readonly message: string;
+  readonly fix: string;
+}
+
+export type Gate = (asset: CompiledAsset) => Finding[];
+
+/** Contact tolerance: surfaces closer than this touch (metres). */
+export const CONTACT_EPS = 0.02;
+/** Clash tolerance: penetration deeper than this is a clash (metres). */
+export const CLASH_EPS = 0.01;

package/src/render/beauty.ts

@@ -0,0 +1,115 @@
+// Beauty render: the zero-GPU product shot for READMEs, gallery cards and the review pack.
+// Perspective 3/4 hero camera, trim-sheet textures × vertex colour with normal + ORM maps, a key
+// sun with soft PCF shadows, sky fill with multi-direction ambient occlusion, a seamless studio
+// floor that only shows the shadows, 2× supersampling. Deterministic: same asset → same bytes.
+
+import { type CompiledAsset, encodePng } from '../core/index.ts';
+import type { PaintedSheet } from '../material/index.ts';
+import { DEFAULT_SHEET, paintTrimSheet } from '../material/index.ts';
+import { frameOrbit, type PerspectiveCamera, scaled, zoomWindow } from './camera.ts';
+import { depthMap } from './depth-map.ts';
+import { floorGrid } from './ground.ts';
+import { pcfTaps, studioRig } from './lighting.ts';
+import { checkBeautyOptions } from './options.ts';
+import { resolve } from './resolve.ts';
+import { sceneOf } from './scene.ts';
+import type { ShadeContext } from './shade.ts';
+import { sample, sheetTextures } from './texture.ts';
+import { rasteriseVis } from './vis-buffer.ts';
+
+export interface BeautyOptions {
+  /** Output size in pixels. Default 1600 × 900. */
+  readonly width?: number;
+  readonly height?: number;
+  /** Camera orbit, degrees: azimuth about Z from the front (+X), −35 = front-left 3/4. */
+  readonly azDeg?: number;
+  /** Elevation above the horizon, degrees (−10…89). Default 18. */
+  readonly elDeg?: number;
+  /** Vertical field of view, degrees. Default 30. */
+  readonly fovDeg?: number;
+  /** Samples per pixel edge (1–4). Default 2 (4 samples per pixel). */
+  readonly supersample?: number;
+  /** The painted trim sheet; default paints `DEFAULT_SHEET` at 1024² once per process. */
+  readonly sheet?: PaintedSheet;
+  /** Zoom into the default framing: window centre (0–1, 0–1) of the full shot and a zoom ≥ 1. */
+  readonly window?: { readonly x: number; readonly y: number; readonly zoom: number };
+  /** Frame with this asset instead (e.g. LOD0's framing for a LOD2 render, so they line up). */
+  readonly frameFrom?: CompiledAsset;
+}
+
+export interface BeautyRender {
+  readonly width: number;
+  readonly height: number;
+  /** RGBA8, sRGB, opaque. */
+  readonly rgba: Uint8Array;
+  /** Asset coverage per pixel, 0–255 (the silhouette, antialiased). */
+  readonly mask: Uint8Array;
+  /** Distinct triangles visible per cell of a 16 × 9 grid — where the detail is. */
+  readonly detail: Uint32Array;
+}
+
+let defaultSheet: PaintedSheet | undefined;
+const sheetOf = (o: BeautyOptions): PaintedSheet => {
+  if (o.sheet) return o.sheet;
+  defaultSheet ??= paintTrimSheet({ ...DEFAULT_SHEET, size: 1024 });
+  return defaultSheet;
+};
+
+export function cameraFor(asset: CompiledAsset, o: BeautyOptions = {}): PerspectiveCamera {
+  const v = checkBeautyOptions(o);
+  const cam = frameOrbit(
+    sceneOf(o.frameFrom ?? asset).positions,
+    { azDeg: v.azDeg, elDeg: v.elDeg, fovDeg: v.fovDeg, fill: 0.8 },
+    v.width,
+    v.height,
+  );
+  return o.window ? zoomWindow(cam, o.window.x, o.window.y, o.window.zoom) : cam;
+}
+
+export function renderBeauty(asset: CompiledAsset, o: BeautyOptions = {}): BeautyRender {
+  const v = checkBeautyOptions(o);
+  const ss = v.supersample;
+  const scene = sceneOf(asset);
+  const tex = sheetTextures(sheetOf(o));
+  const rig = studioRig(v.azDeg);
+  const texel = new Float32Array(4);
+  const alpha = (t: number, b1: number, b2: number, mip = 2): boolean => {
+    const I = scene.indices;
+    const U = scene.uvs;
+    const b0 = 1 - b1 - b2;
+    const a = (I[t * 3] ?? 0) * 2;
+    const b = (I[t * 3 + 1] ?? 0) * 2;
+    const c = (I[t * 3 + 2] ?? 0) * 2;
+    const u = (U[a] ?? 0) * b0 + (U[b] ?? 0) * b1 + (U[c] ?? 0) * b2;
+    const w = (U[a + 1] ?? 0) * b0 + (U[b + 1] ?? 0) * b1 + (U[c + 1] ?? 0) * b2;
+    sample(tex.albedo, mip, u, w, texel);
+    return (texel[3] ?? 1) >= 0.5;
+  };
+  const cam = scaled(cameraFor(asset, o), ss);
+  const vis = rasteriseVis(scene, cam, tex.size, alpha);
+  const extent = Math.max(...scene.max.map((m, k) => m - (scene.min[k] ?? 0)));
+  // Map resolutions follow the output: full quality at hero sizes, cheap for thumbnails/tests.
+  const px = Math.max(v.width, v.height) * ss;
+  const res = (lo: number, hi: number, f: number): number =>
+    Math.max(lo, Math.min(hi, Math.round(px * f)));
+  const sunMap = depthMap(scene, rig.sun, res(256, 2048, 1), undefined, alpha);
+  const ctx: ShadeContext = {
+    scene,
+    cam,
+    tex,
+    rig,
+    sunMap,
+    aoMaps: rig.skyDirs.map((d) => depthMap(scene, d, res(96, 384, 0.25), undefined, alpha)),
+    // Penumbra ~0.4% of the asset's size: soft enough to read as a studio key, never mushy.
+    pcf: pcfTaps(Math.max(1.2, 0.004 * extent * sunMap.k)),
+    reach: 0.12 * extent,
+  };
+  const floor = floorGrid(ctx, res(96, 512, 0.25));
+  return resolve(ctx, vis, floor, v.width, v.height, ss);
+}
+
+/** The beauty render as PNG bytes. */
+export function beauty(asset: CompiledAsset, o: BeautyOptions = {}): Uint8Array {
+  const r = renderBeauty(asset, o);
+  return encodePng(r.width, r.height, r.rgba);
+}

package/src/render/camera.ts

@@ -0,0 +1,142 @@
+// Perspective camera for beauty renders: orbit (azimuth/elevation about the asset), auto-framed so
+// the asset fills the frame, with an optional zoomed sub-window (a true high-res crop of the same
+// shot, used for detail close-ups). Z up, +X front; azimuth 0 looks at the front, −35° is a 3/4.
+
+export interface PerspectiveCamera {
+  readonly eye: readonly [number, number, number];
+  /** Unit right, up, forward (view direction). */
+  readonly r: readonly [number, number, number];
+  readonly u: readonly [number, number, number];
+  readonly f: readonly [number, number, number];
+  /** Pixels per unit of tan(angle) — the focal length in pixels. */
+  readonly focal: number;
+  readonly cx: number;
+  readonly cy: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface Orbit {
+  readonly azDeg: number;
+  readonly elDeg: number;
+  readonly fovDeg: number;
+  /** Fraction of the frame the asset may fill (0–1). */
+  readonly fill: number;
+}
+
+type V3 = [number, number, number];
+
+function basis(azDeg: number, elDeg: number): { dir: V3; r: V3; u: V3; f: V3 } {
+  const az = (azDeg * Math.PI) / 180;
+  const el = (elDeg * Math.PI) / 180;
+  const dir: V3 = [Math.cos(el) * Math.cos(az), Math.cos(el) * Math.sin(az), Math.sin(el)];
+  const f: V3 = [-dir[0], -dir[1], -dir[2]];
+  const rl = Math.hypot(f[1], f[0]) || 1;
+  const r: V3 = [f[1] / rl, -f[0] / rl, 0];
+  const u: V3 = [r[1] * f[2] - r[2] * f[1], r[2] * f[0] - r[0] * f[2], r[0] * f[1] - r[1] * f[0]];
+  return { dir, r, u, f };
+}
+
+/** Project world xyz → [screen x, screen y, view depth]. Depth ≤ 0 means behind the eye. */
+export function project(c: PerspectiveCamera, x: number, y: number, z: number): V3 {
+  const dx = x - c.eye[0];
+  const dy = y - c.eye[1];
+  const dz = z - c.eye[2];
+  const w = dx * c.f[0] + dy * c.f[1] + dz * c.f[2];
+  const sx = dx * c.r[0] + dy * c.r[1] + dz * c.r[2];
+  const sy = dx * c.u[0] + dy * c.u[1] + dz * c.u[2];
+  return [c.cx + (sx / w) * c.focal, c.cy - (sy / w) * c.focal, w];
+}
+
+/**
+ * Orbit camera framing `points` (xyz triples, world) in a width × height image. Iterates a few
+ * times: re-centre on the projected extent, then dolly so the larger axis fills `fill`.
+ */
+export function frameOrbit(
+  points: Float32Array,
+  o: Orbit,
+  width: number,
+  height: number,
+): PerspectiveCamera {
+  const { dir, r, u, f } = basis(o.azDeg, o.elDeg);
+  const stride = Math.max(1, Math.floor(points.length / 3 / 20000)) * 3;
+  let lo: V3 = [Infinity, Infinity, Infinity];
+  let hi: V3 = [-Infinity, -Infinity, -Infinity];
+  for (let i = 0; i < points.length; i += 3)
+    for (let k = 0; k < 3; k++) {
+      const v = points[i + k] ?? 0;
+      lo[k] = Math.min(lo[k] ?? 0, v);
+      hi[k] = Math.max(hi[k] ?? 0, v);
+    }
+  if (points.length === 0) {
+    lo = [-0.5, -0.5, -0.5];
+    hi = [0.5, 0.5, 0.5];
+  }
+  const target: V3 = [(lo[0] + hi[0]) / 2, (lo[1] + hi[1]) / 2, (lo[2] + hi[2]) / 2];
+  const radius = Math.max(Math.hypot(hi[0] - lo[0], hi[1] - lo[1], hi[2] - lo[2]) / 2, 0.05);
+  const tanY = Math.tan((o.fovDeg * Math.PI) / 360);
+  const focal = height / 2 / tanY;
+  let dist = radius / Math.sin(Math.atan(tanY)) + radius;
+  const at = (d: number): PerspectiveCamera => ({
+    eye: [target[0] + dir[0] * d, target[1] + dir[1] * d, target[2] + dir[2] * d],
+    r,
+    u,
+    f,
+    focal,
+    cx: width / 2,
+    cy: height / 2,
+    width,
+    height,
+  });
+  for (let iter = 0; iter < 6; iter++) {
+    const cam = at(dist);
+    let x0 = Infinity;
+    let x1 = -Infinity;
+    let y0 = Infinity;
+    let y1 = -Infinity;
+    for (let i = 0; i < points.length; i += stride) {
+      const p = project(cam, points[i] ?? 0, points[i + 1] ?? 0, points[i + 2] ?? 0);
+      x0 = Math.min(x0, p[0]);
+      x1 = Math.max(x1, p[0]);
+      y0 = Math.min(y0, p[1]);
+      y1 = Math.max(y1, p[1]);
+    }
+    if (!Number.isFinite(x0)) break;
+    // Shift the target by the screen-space offset of the extent's centre, at the target's depth.
+    const k = dist / focal;
+    const ox = ((x0 + x1) / 2 - width / 2) * k;
+    const oy = -((y0 + y1) / 2 - height / 2) * k;
+    for (let a = 0; a < 3; a++) target[a] = (target[a] ?? 0) + (r[a] ?? 0) * ox + (u[a] ?? 0) * oy;
+    const need = Math.max((x1 - x0) / (width * o.fill), (y1 - y0) / (height * o.fill));
+    // Perspective: dolly on the part of the distance in front of the target, not through it.
+    dist = Math.max(dist * need ** 0.85, radius * 1.05);
+  }
+  return at(dist);
+}
+
+/** The same shot through a zoomed window: (nx, ny) ∈ [0,1]² is the window centre, k the zoom. */
+export function zoomWindow(
+  c: PerspectiveCamera,
+  nx: number,
+  ny: number,
+  k: number,
+): PerspectiveCamera {
+  return {
+    ...c,
+    focal: c.focal * k,
+    cx: c.width / 2 - (nx * c.width - c.cx) * k,
+    cy: c.height / 2 - (ny * c.height - c.cy) * k,
+  };
+}
+
+/** Same camera at another resolution (supersampling): every pixel quantity scales by s. */
+export function scaled(c: PerspectiveCamera, s: number): PerspectiveCamera {
+  return {
+    ...c,
+    focal: c.focal * s,
+    cx: c.cx * s,
+    cy: c.cy * s,
+    width: c.width * s,
+    height: c.height * s,
+  };
+}