@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/render/options.ts

@@ -0,0 +1,81 @@
+// Validate beauty-render options up front: a bad size or angle fails with a code and the exact
+// fix instead of a blank or giant image. The CLI's --size/--az/--el/--fov flags land here too.
+
+import { Ts23dError } from '../core/index.ts';
+
+export interface CheckedBeauty {
+  readonly width: number;
+  readonly height: number;
+  readonly azDeg: number;
+  readonly elDeg: number;
+  readonly fovDeg: number;
+  readonly supersample: number;
+}
+
+interface Raw {
+  readonly width?: number;
+  readonly height?: number;
+  readonly azDeg?: number;
+  readonly elDeg?: number;
+  readonly fovDeg?: number;
+  readonly supersample?: number;
+  readonly window?: { readonly x: number; readonly y: number; readonly zoom: number };
+}
+
+function need(ok: boolean, cause: string, fix: string): void {
+  if (!ok) throw new Ts23dError('T3D_RENDER_OPTIONS', { cause, fix });
+}
+
+export function checkBeautyOptions(o: Raw): CheckedBeauty {
+  const v = {
+    width: o.width ?? 1600,
+    height: o.height ?? 900,
+    azDeg: o.azDeg ?? -35,
+    elDeg: o.elDeg ?? 18,
+    fovDeg: o.fovDeg ?? 30,
+    supersample: o.supersample ?? 2,
+  };
+  for (const k of ['width', 'height'] as const)
+    need(
+      Number.isInteger(v[k]) && v[k] >= 16 && v[k] <= 8192,
+      `${k} ${v[k]} is not an integer in 16…8192 pixels`,
+      'pass a size like 1600x900 (--size WxH), each side 16–8192',
+    );
+  need(
+    Number.isFinite(v.azDeg),
+    `azimuth ${v.azDeg} is not a number`,
+    'pass degrees, e.g. --az -35',
+  );
+  need(
+    Number.isFinite(v.elDeg) && v.elDeg >= -10 && v.elDeg <= 89,
+    `elevation ${v.elDeg} is outside −10…89°`,
+    'pass degrees above the horizon, e.g. --el 18 (89 = straight down)',
+  );
+  need(
+    Number.isFinite(v.fovDeg) && v.fovDeg >= 5 && v.fovDeg <= 120,
+    `field of view ${v.fovDeg} is outside 5…120°`,
+    'pass a vertical FOV in degrees, e.g. --fov 30',
+  );
+  need(
+    Number.isInteger(v.supersample) && v.supersample >= 1 && v.supersample <= 4,
+    `supersample ${v.supersample} is not 1, 2, 3 or 4`,
+    'use supersample: 2 (4 samples per pixel)',
+  );
+  if (o.window)
+    need(
+      Number.isFinite(o.window.zoom) && o.window.zoom >= 1 && o.window.zoom <= 64,
+      `window zoom ${o.window.zoom} is outside 1…64`,
+      'zoom into the shot with window: { x, y, zoom } and 1 ≤ zoom ≤ 64',
+    );
+  return v;
+}
+
+/** Parse a `WxH` size flag ("1600x900"). */
+export function parseSize(text: string): { width: number; height: number } {
+  const m = /^(\d+)[x×](\d+)$/i.exec(text.trim());
+  need(m !== null, `size "${text}" is not WIDTHxHEIGHT`, 'pass --size 1600x900');
+  const width = Number(m?.[1]);
+  const height = Number(m?.[2]);
+  checkBeautyOptions({ width, height });
+  return { width, height };
+}

package/src/render/photo-match.ts

@@ -0,0 +1,28 @@
+// Photo match: render the asset from the camera that took a reference photo and stack
+// photo · model · 50% overlay in ONE image. The strongest check an agent has — silhouette,
+// proportions and colour against reality at a glance. Planned: M2 (docs/plans/roadmap.md).
+
+import { type CompiledAsset, notImplemented, type Vec3 } from '../core/index.ts';
+
+export interface PhotoCamera {
+  /** Camera position and look-at target in asset space (metres, Z up). */
+  readonly eye: Vec3;
+  readonly target: Vec3;
+  /** Vertical field of view, degrees. */
+  readonly fovDeg: number;
+}
+
+export interface PhotoMatchOptions {
+  readonly photo: Uint8Array;
+  /** Solve the camera from ≥ 4 marked correspondences instead of passing it (planned with it). */
+  readonly camera: PhotoCamera;
+  readonly width?: number;
+}
+
+/** Returns a PNG: photo on top, model in the middle, overlay at the bottom; plus silhouette IoU. */
+export function photoMatch(
+  _asset: CompiledAsset,
+  _o: PhotoMatchOptions,
+): { png: Uint8Array; iou: number } {
+  return notImplemented('photoMatch (photo · model · overlay sheet + silhouette IoU)');
+}

package/src/render/raster.ts

@@ -0,0 +1,143 @@
+// CPU rasteriser: orthographic, z-buffered, Lambert-shaded triangles plus depth-tested lines.
+// Slow by GPU standards and fast enough for 6 × 400² views of a game asset in well under a second.
+
+import type { CompiledAsset, Vec3 } from '../core/index.ts';
+import { cross, dot, normalize, rotateZ, sub, toWorld, worldTransforms } from '../core/index.ts';
+
+export interface View {
+  readonly label: string;
+  /** Direction the camera looks along (world, Z up). */
+  readonly dir: Vec3;
+  readonly up: Vec3;
+}
+
+export interface Target {
+  readonly px: Uint8Array;
+  readonly depth: Float32Array;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface Camera {
+  project(p: Vec3): Vec3;
+}
+
+export function orthoCamera(view: View, centre: Vec3, extent: number, size: number): Camera {
+  const f = normalize(view.dir);
+  const r = normalize(cross(f, view.up));
+  const u = cross(r, f);
+  const k = size / (extent * 1.15);
+  return {
+    project: (p) => {
+      const d = sub(p, centre);
+      return [size / 2 + dot(d, r) * k, size / 2 - dot(d, u) * k, dot(d, f)];
+    },
+  };
+}
+
+const LIGHT = normalize([0.4, -0.6, 0.8]);
+
+export function worldParts(asset: CompiledAsset): {
+  positions: Float32Array;
+  normals: Float32Array;
+  colors: Float32Array;
+  indices: Uint32Array;
+}[] {
+  const xf = worldTransforms(asset.parts);
+  const out = [];
+  for (const p of asset.parts) {
+    const t = xf.get(p.name);
+    if (!p.mesh || !t) continue;
+    const positions = new Float32Array(p.mesh.positions.length);
+    const normals = new Float32Array(p.mesh.normals.length);
+    for (let i = 0; i < positions.length; i += 3) {
+      positions.set(
+        toWorld(t, [
+          p.mesh.positions[i] ?? 0,
+          p.mesh.positions[i + 1] ?? 0,
+          p.mesh.positions[i + 2] ?? 0,
+        ]),
+        i,
+      );
+      normals.set(
+        rotateZ(
+          [p.mesh.normals[i] ?? 0, p.mesh.normals[i + 1] ?? 0, p.mesh.normals[i + 2] ?? 0],
+          t.yaw,
+        ),
+        i,
+      );
+    }
+    out.push({ positions, normals, colors: p.mesh.colors, indices: p.mesh.indices });
+  }
+  return out;
+}
+
+function tri(t: Target, a: Vec3, b: Vec3, c: Vec3, rgb: Vec3): void {
+  const minX = Math.max(0, Math.floor(Math.min(a[0], b[0], c[0])));
+  const maxX = Math.min(t.width - 1, Math.ceil(Math.max(a[0], b[0], c[0])));
+  const minY = Math.max(0, Math.floor(Math.min(a[1], b[1], c[1])));
+  const maxY = Math.min(t.height - 1, Math.ceil(Math.max(a[1], b[1], c[1])));
+  const area = (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0]);
+  if (Math.abs(area) < 1e-9) return;
+  for (let y = minY; y <= maxY; y++) {
+    for (let x = minX; x <= maxX; x++) {
+      const px = x + 0.5;
+      const py = y + 0.5;
+      const w0 = ((b[0] - px) * (c[1] - py) - (b[1] - py) * (c[0] - px)) / area;
+      const w1 = ((c[0] - px) * (a[1] - py) - (c[1] - py) * (a[0] - px)) / area;
+      const w2 = 1 - w0 - w1;
+      if (w0 < 0 || w1 < 0 || w2 < 0) continue;
+      const z = w0 * a[2] + w1 * b[2] + w2 * c[2];
+      const i = y * t.width + x;
+      if (z >= (t.depth[i] ?? Infinity)) continue;
+      t.depth[i] = z;
+      t.px.set([rgb[0], rgb[1], rgb[2], 255], i * 4);
+    }
+  }
+}
+
+const toSrgb = (v: number): number =>
+  Math.round(255 * Math.min(1, v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055));
+
+export function drawAsset(t: Target, cam: Camera, asset: CompiledAsset): void {
+  for (const m of worldParts(asset)) {
+    for (let i = 0; i < m.indices.length; i += 3) {
+      const ids = [m.indices[i] ?? 0, m.indices[i + 1] ?? 0, m.indices[i + 2] ?? 0];
+      const pts = ids.map((v) =>
+        cam.project([
+          m.positions[v * 3] ?? 0,
+          m.positions[v * 3 + 1] ?? 0,
+          m.positions[v * 3 + 2] ?? 0,
+        ]),
+      );
+      const v0 = ids[0] ?? 0;
+      const n: Vec3 = [
+        m.normals[v0 * 3] ?? 0,
+        m.normals[v0 * 3 + 1] ?? 0,
+        m.normals[v0 * 3 + 2] ?? 1,
+      ];
+      const shade = 0.35 + 0.65 * Math.max(0, dot(n, LIGHT));
+      const rgb: Vec3 = [
+        toSrgb((m.colors[v0 * 3] ?? 1) * shade),
+        toSrgb((m.colors[v0 * 3 + 1] ?? 1) * shade),
+        toSrgb((m.colors[v0 * 3 + 2] ?? 1) * shade),
+      ];
+      const [a, b, c] = pts;
+      if (a && b && c) tri(t, a, b, c, rgb);
+    }
+  }
+}
+
+export function line(t: Target, a: Vec3, b: Vec3, rgb: Vec3): void {
+  const steps = Math.ceil(Math.max(Math.abs(b[0] - a[0]), Math.abs(b[1] - a[1]), 1));
+  for (let s = 0; s <= steps; s++) {
+    const k = s / steps;
+    const x = Math.round(a[0] + (b[0] - a[0]) * k);
+    const y = Math.round(a[1] + (b[1] - a[1]) * k);
+    if (x < 0 || y < 0 || x >= t.width || y >= t.height) continue;
+    const z = a[2] + (b[2] - a[2]) * k;
+    const i = y * t.width + x;
+    if (z > (t.depth[i] ?? Infinity) + 1e-3) continue;
+    t.px.set([rgb[0], rgb[1], rgb[2], 255], i * 4);
+  }
+}

package/src/render/resolve.ts

@@ -0,0 +1,109 @@
+// Resolve the supersampled visibility buffer to output pixels, MSAA-style: samples in a pixel
+// that hit the same triangle are shaded ONCE at their mean barycentrics and weighted by count, so
+// edges get ss² coverage samples while interiors cost one shade. Background samples show the
+// studio backdrop × the floor's shadow light. Also yields the coverage mask and a detail grid.
+
+import type { FloorGrid } from './ground.ts';
+import { floorLight } from './ground.ts';
+import { fromSrgb, tone, toSrgb8 } from './lighting.ts';
+import { type ShadeContext, shadeSample } from './shade.ts';
+import type { VisBuffer } from './vis-buffer.ts';
+
+export interface Resolved {
+  readonly width: number;
+  readonly height: number;
+  readonly rgba: Uint8Array;
+  readonly mask: Uint8Array;
+  readonly detail: Uint32Array;
+}
+
+/** Backdrop colour (linear) at normalised screen (nx, ny): soft radial falloff below centre. */
+function backdrop(nx: number, ny: number, out: Float32Array): void {
+  const dx = (nx - 0.5) * 1.1;
+  const dy = ny - 0.62;
+  const fall = Math.min(1, dx * dx + dy * dy * 1.6);
+  out[0] = fromSrgb(0.93 - 0.17 * fall);
+  out[1] = fromSrgb(0.935 - 0.15 * fall);
+  out[2] = fromSrgb(0.94 - 0.12 * fall);
+}
+
+export function resolve(
+  ctx: ShadeContext,
+  vis: VisBuffer,
+  floor: FloorGrid,
+  width: number,
+  height: number,
+  ss: number,
+): Resolved {
+  const rgba = new Uint8Array(width * height * 4);
+  const mask = new Uint8Array(width * height);
+  // Last detail cell each triangle was counted in: ≈ distinct triangles per cell, no hash set.
+  const counted = new Int32Array(ctx.scene.triangles).fill(-1);
+  const detail = new Uint32Array(16 * 9);
+  const lin = new Float32Array(3);
+  const bg = new Float32Array(3);
+  const n = ss * ss;
+  const ids = new Int32Array(n);
+  const cnt = new Int32Array(n);
+  const sb1 = new Float64Array(n);
+  const sb2 = new Float64Array(n);
+  const W = vis.width;
+  const inv = 1 / n;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      backdrop(x / width, y / height, bg);
+      let r = 0;
+      let g = 0;
+      let b = 0;
+      let groups = 0;
+      let hits = 0;
+      for (let sy = 0; sy < ss; sy++)
+        for (let sx = 0; sx < ss; sx++) {
+          const X = x * ss + sx;
+          const Y = y * ss + sy;
+          const i = Y * W + X;
+          const t = vis.tri[i] ?? -1;
+          if (t < 0) {
+            const l = floorLight(floor, ctx.cam, X + 0.5, Y + 0.5);
+            r += (bg[0] ?? 0) * l;
+            g += (bg[1] ?? 0) * l;
+            b += (bg[2] ?? 0) * l;
+            continue;
+          }
+          hits++;
+          let k = 0;
+          while (k < groups && ids[k] !== t) k++;
+          if (k === groups) {
+            ids[k] = t;
+            cnt[k] = 0;
+            sb1[k] = 0;
+            sb2[k] = 0;
+            groups++;
+          }
+          cnt[k] = (cnt[k] ?? 0) + 1;
+          sb1[k] = (sb1[k] ?? 0) + (vis.b1[i] ?? 0);
+          sb2[k] = (sb2[k] ?? 0) + (vis.b2[i] ?? 0);
+        }
+      const cell = Math.floor((y * 9) / height) * 16 + Math.floor((x * 16) / width);
+      for (let k = 0; k < groups; k++) {
+        const t = ids[k] ?? 0;
+        const c = cnt[k] ?? 1;
+        if (counted[t] !== cell) {
+          counted[t] = cell;
+          detail[cell] = (detail[cell] ?? 0) + 1;
+        }
+        shadeSample(ctx, t, (sb1[k] ?? 0) / c, (sb2[k] ?? 0) / c, vis.mip[t] ?? 0, x + y * 2, lin);
+        r += tone(lin[0] ?? 0) * c;
+        g += tone(lin[1] ?? 0) * c;
+        b += tone(lin[2] ?? 0) * c;
+      }
+      const o = (y * width + x) * 4;
+      rgba[o] = toSrgb8(r * inv);
+      rgba[o + 1] = toSrgb8(g * inv);
+      rgba[o + 2] = toSrgb8(b * inv);
+      rgba[o + 3] = 255;
+      mask[y * width + x] = Math.round(hits * inv * 255);
+    }
+  }
+  return { width, height, rgba, mask, detail };
+}

package/src/render/review-prompt.ts

@@ -0,0 +1,59 @@
+// review.md: the checklist prompt a vision-capable agent follows over the review pack. Mined from
+// years of rejected assets (railroads procgen AGENT_BRIEF "review checklist"), plus the metrics
+// and warnings this pack computed, so the reviewer starts from evidence, not from scratch.
+
+import type { ReviewMetrics } from './review-warnings.ts';
+
+const CHECKLIST = [
+  '**Floating bits** — every bar, bracket, lamp, rod, handle touches what holds it. Look at the close-ups and the TOP view.',
+  '**Clipping** — wheels through frames or fenders, rods through guides, brackets through roofs, branches through trunks.',
+  '**Proportions vs reality** — compare overall length/width/height ratios and signature features with the reference dossier and its photos.',
+  '**Open stacks and throats** — chimneys, funnels, exhausts, muzzles and pipes are OPEN (rim + dark inner throat), never capped.',
+  '**Hidden detail** — detail buried inside another mass (a clock behind a roof, a hatch under a turret) is wasted triangles.',
+  '**Silhouette at LOD2** — in lods.png, LOD2 keeps the outline and the big colour blocks; nothing pops, vanishes or shifts colour.',
+  '**Texture stretching** — trim-sheet strips run along faces at a sensible scale: no smeared bricks, giant planks or streaked rivets.',
+  '**Colour / value contrast** — materials separate (paint vs rubber vs metal vs glass); not one flat tone; no pure black or white.',
+  '**Lettering and decals** — numbers and signs are legible in the close-ups and read the right way round.',
+  '**Organic forms** — foliage, snow and terrain read as volume from the 3/4 hero, not as blotches, slabs or cards edge-on.',
+  '**Grounding** — the asset stands on the floor (contact shadow under every wheel, foot or base), not sunk or hovering.',
+];
+
+export function reviewPrompt(m: ReviewMetrics, files: readonly string[], refs?: string): string {
+  const pct = (v: number): string => `${(v * 100).toFixed(1)}%`;
+  const views = m.views
+    .map(
+      (v) =>
+        `| ${v.view} | ${pct(v.lod0.coverage)} | ${pct(v.lod0.bboxFill)} | ${v.lodIoU.toFixed(3)} | ${v.lodIoUExact.toFixed(3)} |`,
+    )
+    .join('\n');
+  const warnings = m.warnings.length
+    ? m.warnings.map((w) => `- **${w.code}**: ${w.message}\n  fix: ${w.fix}`).join('\n')
+    : '- none — the metrics are proxies, so still run the checklist.';
+  return `# Visual review: ${m.asset}
+
+You are reviewing a game asset generated from code. READ every image in this folder before
+answering: ${files.filter((f) => f.endsWith('.png')).join(', ')}.
+${refs ? `Reference dossier (specs, measures, photo links): \`${refs}\` — read it first.\n` : 'No reference dossier was found (expected recipes/<name>/README.md): judge against well-known photos of the real thing.\n'}
+- \`hero.png\` — 3/4 product shot, LOD0. · \`sheet.png\` — six orthographic views on a metre grid.
+- \`detail_*.png\` — 3× close-ups where the triangles are. · \`lods.png\` — LOD0 · LOD1 · LOD2, same camera.
+
+Triangles per LOD: ${m.triangles.join(' / ')}.
+
+## Checklist — answer each with PASS or FAIL + where + the fix
+${CHECKLIST.map((c, i) => `${i + 1}. ${c}`).join('\n')}
+
+## Automatic metrics (review.json)
+Hero: coverage ${pct(m.hero.coverage)}, span ${pct(m.hero.span)}, mean luminance ${m.hero.mean.toFixed(3)}, contrast ${m.hero.contrast.toFixed(3)}, near-black ${pct(m.hero.nearBlack)}, near-white ${pct(m.hero.nearWhite)}.
+
+| view | LOD0 coverage | bbox fill | LOD0↔LOD2 IoU (far) | IoU (exact) |
+|---|---|---|---|---|
+${views}
+
+## Warnings
+${warnings}
+
+## Output
+A list of findings, worst first: \`[FAIL] <check> — <where, which view/image> — <fix in the recipe>\`,
+then one line: \`VERDICT: SHIP\` or \`VERDICT: ITERATE\`.
+`;
+}

package/src/render/review-warnings.ts

@@ -0,0 +1,92 @@
+// Threshold checks over the review metrics: each warning names the metric, the value, the limit
+// and the fix. Warnings, not failures — the image metrics are proxies; the vision pass decides.
+
+import type { ExposureStats, MaskStats } from './metrics.ts';
+
+export interface ViewMetrics {
+  readonly view: string;
+  readonly lod0: MaskStats;
+  readonly lod2: MaskStats;
+  /** Silhouette IoU LOD0 ↔ LOD2 as seen from afar (64² max-pooled masks, same frame). Low = popping. */
+  readonly lodIoU: number;
+  /** The same at full mask resolution (256²): lattices and foliage score low here by nature. */
+  readonly lodIoUExact: number;
+}
+
+export interface ReviewWarning {
+  readonly code: string;
+  readonly message: string;
+  readonly fix: string;
+}
+
+export interface ReviewMetrics {
+  readonly asset: string;
+  readonly triangles: readonly number[];
+  readonly hero: ExposureStats;
+  readonly views: readonly ViewMetrics[];
+  readonly warnings: readonly ReviewWarning[];
+}
+
+export const REVIEW_THRESHOLDS = {
+  /** LOD0 ↔ LOD2 silhouette IoU below this in any view = visible popping. */
+  lodIoU: 0.8,
+  heroMeanMin: 0.18,
+  heroMeanMax: 0.85,
+  heroContrastMin: 0.06,
+  nearBlackMax: 0.2,
+  nearWhiteMax: 0.1,
+  /** Asset spanning less of the hero frame than this: something stretches the bounds. */
+  heroSpanMin: 0.5,
+} as const;
+
+const f = (v: number): string => v.toFixed(3);
+
+export function warningsOf(m: Omit<ReviewMetrics, 'warnings'>): ReviewWarning[] {
+  const t = REVIEW_THRESHOLDS;
+  const out: ReviewWarning[] = [];
+  for (const v of m.views)
+    if (v.lodIoU < t.lodIoU)
+      out.push({
+        code: 'lod-popping',
+        message: `${v.view}: LOD0↔LOD2 silhouette IoU ${f(v.lodIoU)} < ${t.lodIoU}`,
+        fix: 'keep the LOD2 massing on the LOD0 silhouette — same outer envelope, fewer cuts (see lods.png)',
+      });
+  const h = m.hero;
+  if (h.span < t.heroSpanMin)
+    out.push({
+      code: 'tiny-in-frame',
+      message: `asset spans ${f(h.span)} of the hero frame (< ${t.heroSpanMin})`,
+      fix: 'a stray or far-off part is stretching the bounds — find it in sheet.png and attach or remove it',
+    });
+  if (h.mean < t.heroMeanMin)
+    out.push({
+      code: 'too-dark',
+      message: `hero mean luminance ${f(h.mean)} < ${t.heroMeanMin}`,
+      fix: 'raise vertex colours (dark paint ≈ 0.05–0.1 linear, never 0) or check for inward-facing normals',
+    });
+  if (h.mean > t.heroMeanMax)
+    out.push({
+      code: 'washed-out',
+      message: `hero mean luminance ${f(h.mean)} > ${t.heroMeanMax}`,
+      fix: 'lower vertex colours: real paint and stone rarely exceed ~0.7 linear albedo',
+    });
+  if (h.contrast < t.heroContrastMin)
+    out.push({
+      code: 'low-contrast',
+      message: `hero luminance contrast ${f(h.contrast)} < ${t.heroContrastMin}`,
+      fix: 'add value contrast between materials (trim, rubber, metal, glass) and grime in crevices',
+    });
+  if (h.nearBlack > t.nearBlackMax)
+    out.push({
+      code: 'crushed-blacks',
+      message: `${f(h.nearBlack)} of asset pixels are near black (> ${t.nearBlackMax})`,
+      fix: 'lift near-black colours to ≥ 0.03 linear and check normals point outward',
+    });
+  if (h.nearWhite > t.nearWhiteMax)
+    out.push({
+      code: 'blown-whites',
+      message: `${f(h.nearWhite)} of asset pixels are near white (> ${t.nearWhiteMax})`,
+      fix: 'bring white paint down to ~0.8 linear so texture and shading stay readable',
+    });
+  return out;
+}

package/src/render/review.ts

@@ -0,0 +1,103 @@
+// AI review pack: everything a vision-capable agent needs to judge an asset in one folder — hero,
+// contact sheet, two detail close-ups (where the triangles are), the LOD strip, review.md (the
+// checklist prompt) and review.json (model-free image metrics with threshold warnings).
+
+import { type Asset, type CompiledAsset, compile, encodePng, type Lod } from '../core/index.ts';
+import type { PaintedSheet } from '../material/index.ts';
+import { type BeautyOptions, renderBeauty } from './beauty.ts';
+import { lodStrip } from './lod-strip.ts';
+import { exposure, maskIoU, maskStats, poolMask, silhouette, viewFrame } from './metrics.ts';
+import { reviewPrompt } from './review-prompt.ts';
+import { type ReviewMetrics, warningsOf } from './review-warnings.ts';
+import { contactSheet, VIEWS } from './sheet.ts';
+
+export interface ReviewOptions {
+  readonly sheet?: PaintedSheet;
+  readonly width?: number;
+  readonly height?: number;
+  readonly azDeg?: number;
+  readonly elDeg?: number;
+  readonly fovDeg?: number;
+  /** Path of the reference dossier (recipes/<name>/README.md) the prompt points the reviewer at. */
+  readonly refs?: string;
+}
+
+export interface ReviewPack {
+  /** File name (inside the review folder) → contents. */
+  readonly files: ReadonlyMap<string, Uint8Array | string>;
+  readonly metrics: ReviewMetrics;
+}
+
+const tris = (a: CompiledAsset): number =>
+  a.parts.reduce((s, p) => s + (p.mesh ? p.mesh.indices.length / 3 : 0), 0);
+
+/** Two zoom windows centred on the densest cells of the hero's 16 × 9 detail grid, ≥ 4 cells apart. */
+export function detailWindows(detail: Uint32Array): { x: number; y: number }[] {
+  const order = [...detail.keys()].sort((a, b) => (detail[b] ?? 0) - (detail[a] ?? 0) || a - b);
+  const picked: number[] = [];
+  for (const c of order) {
+    if ((detail[c] ?? 0) === 0 || picked.length === 2) break;
+    if (
+      picked.every(
+        (p) => Math.hypot((p % 16) - (c % 16), Math.floor(p / 16) - Math.floor(c / 16)) >= 4,
+      )
+    )
+      picked.push(c);
+  }
+  const clamp = (v: number): number => Math.min(5 / 6, Math.max(1 / 6, v));
+  return picked.map((c) => ({
+    x: clamp(((c % 16) + 0.5) / 16),
+    y: clamp((Math.floor(c / 16) + 0.5) / 9),
+  }));
+}
+
+export function reviewPack(asset: Asset, o: ReviewOptions = {}): ReviewPack {
+  const lods = ([0, 1, 2] as Lod[]).map((lod) => compile(asset, { lod }));
+  const lod0 = lods[0] ?? compile(asset);
+  const lod2 = lods[2] ?? lod0;
+  const base: BeautyOptions = {
+    ...(o.sheet ? { sheet: o.sheet } : {}),
+    ...(o.width ? { width: o.width } : {}),
+    ...(o.height ? { height: o.height } : {}),
+    ...(o.azDeg !== undefined ? { azDeg: o.azDeg } : {}),
+    ...(o.elDeg !== undefined ? { elDeg: o.elDeg } : {}),
+    ...(o.fovDeg !== undefined ? { fovDeg: o.fovDeg } : {}),
+  };
+  const files = new Map<string, Uint8Array | string>();
+  const hero = renderBeauty(lod0, base);
+  files.set('hero.png', encodePng(hero.width, hero.height, hero.rgba));
+  files.set('sheet.png', contactSheet(lod0, { far: lod2 }));
+  detailWindows(hero.detail).forEach((w, i) => {
+    const r = renderBeauty(lod0, { ...base, window: { ...w, zoom: 3 } });
+    files.set(`detail_${i + 1}.png`, encodePng(r.width, r.height, r.rgba));
+  });
+  // Each LOD panel at most 640 × 480 (smaller when the pack itself is rendered small).
+  const k = Math.min(1, (o.width ?? 1600) / 640);
+  const panel = {
+    width: Math.max(16, Math.round(640 * k)),
+    height: Math.max(16, Math.round(480 * k)),
+  };
+  files.set('lods.png', lodStrip(lods, { ...base, ...panel }));
+  const views = VIEWS.slice(0, 5).map((view) => {
+    const frame = viewFrame(lod0, view);
+    const a = silhouette(lod0, view, 256, frame);
+    const b = silhouette(lod2, view, 256, frame);
+    return {
+      view: view.label,
+      lod0: maskStats(a),
+      lod2: maskStats(b),
+      lodIoU: maskIoU(poolMask(a, 4).mask, poolMask(b, 4).mask),
+      lodIoUExact: maskIoU(a.mask, b.mask),
+    };
+  });
+  const partial = {
+    asset: asset.name,
+    triangles: lods.map(tris),
+    hero: exposure(hero.rgba, hero.mask, hero.width),
+    views,
+  };
+  const metrics: ReviewMetrics = { ...partial, warnings: warningsOf(partial) };
+  files.set('review.json', `${JSON.stringify(metrics, null, 2)}\n`);
+  files.set('review.md', reviewPrompt(metrics, [...files.keys()], o.refs));
+  return { files, metrics };
+}