@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/qa/explore.ts

@@ -0,0 +1,136 @@
+// The explorer: puts the hero on every part of the floor in the real play page and checks each
+// frame for what players notice: standing inside things, drawn over things he is behind, hidden
+// by things he is in front of, cut off by the frame. Spark looks at a contact sheet of the worst.
+import sharp from 'sharp';
+import { z } from 'zod';
+import { emptyMask } from '../image/mask.ts';
+import { PALETTE, svgLabel, tintOver } from '../image/overlay.ts';
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import type { Geometry } from '../play/geometry.ts';
+import { gridOf } from '../scene/verify.ts';
+import { reach, roomy } from '../scene/walk.ts';
+import type { ProbeHit } from './probe.ts';
+
+export const ISSUES = ['feet-inside', 'drawn-over', 'over-box', 'hidden-in-front', 'clipped', 'invisible'] as const;
+export type Issue = (typeof ISSUES)[number];
+export type Checked = ProbeHit & { issues: Issue[]; worst?: string };
+
+/** Up to `max` spots on walkable cells, on a coarser lattice for bigger floors, plus every thing's spot. */
+export function positions(g: Geometry, max = 600): [number, number][] {
+  const grid = gridOf(g);
+  const open = [...grid.open.keys()].filter((i) => grid.open[i]);
+  let step = 2;
+  while (open.length / (step * step) > max && step < 16) step++;
+  const out: [number, number][] = [];
+  for (const i of open) {
+    const c = i % grid.cols;
+    const r = Math.floor(i / grid.cols);
+    if (c % step === 0 && r % step === 0) out.push(grid.centre(i));
+  }
+  for (const t of g.things) out.push(t.stand);
+  return out;
+}
+
+/** The code checks: which issues a probe shows. Thresholds keep a few stray pixels from counting. */
+export function classify(hit: ProbeHit): Checked {
+  const issues: Issue[] = [];
+  const some = (n: number) => n >= Math.max(40, hit.drawn * 0.01);
+  const over = Object.entries(hit.overNearer).filter(([, n]) => some(n));
+  const hidden = Object.entries(hit.hiddenByFarther).filter(([, n]) => n >= Math.max(150, hit.drawn * 0.01));
+  if (hit.feetIn.length) issues.push('feet-inside');
+  if (over.length || some(hit.overDepth ?? 0)) issues.push('drawn-over');
+  // A box-only thing can't hide him, so standing where its box would overlap him looks wrong either way.
+  const boxed = Object.entries(hit.overBox ?? {}).filter(([, n]) => some(n));
+  if (boxed.length) issues.push('over-box');
+  if (hidden.length) issues.push('hidden-in-front');
+  if (hit.off > 0.3) issues.push('clipped');
+  if (hit.drawn > 0 && hit.hidden > 0.85 * hit.drawn) issues.push('invisible');
+  const worst = hit.feetIn[0] ?? over.sort((a, b) => b[1] - a[1])[0]?.[0] ?? (some(hit.overDepth ?? 0) ? 'depth' : undefined) ?? boxed.sort((a, b) => b[1] - a[1])[0]?.[0] ?? hidden.sort((a, b) => b[1] - a[1])[0]?.[0];
+  return { ...hit, issues, ...(worst && { worst }) };
+}
+
+/** Painting with each probed spot as a dot: green clean, red with issues, labelled by the thing involved. */
+export async function heatmap(painting: Buffer, g: Geometry, checked: Checked[]): Promise<Buffer> {
+  const walk = emptyMask(g.frame.width, g.frame.height);
+  g.walk.forEach((row, r) => [...row].forEach((ch, c) => {
+    if (ch !== '#') return;
+    for (let y = r * g.cell; y < Math.min(g.frame.height, (r + 1) * g.cell); y++) walk.bits.fill(1, y * g.frame.width + c * g.cell, y * g.frame.width + Math.min(g.frame.width, (c + 1) * g.cell));
+  }));
+  const dots = checked.map((h) => `<circle cx="${h.x}" cy="${h.y}" r="${h.issues.length ? 6 : 3}" fill="${h.issues.length ? '#ff3030' : '#30ff70'}" stroke="#000" stroke-width="1"/>`);
+  const labelled = new Set<string>();
+  const labels = checked.filter((h) => h.worst && !labelled.has(h.worst) && labelled.add(h.worst)).map((h) => svgLabel(h.x + 8, h.y - 6, `${h.issues[0]}: ${h.worst}`, [255, 120, 120]));
+  return tintOver(painting, [{ mask: walk, rgb: PALETTE[4], alpha: 0.18 }], [...dots, ...labels].join(''));
+}
+
+/** A 4x4 sheet of numbered crops. */
+export async function contactSheet(crops: Buffer[], size: number): Promise<Buffer> {
+  const cols = 4;
+  const rows = Math.ceil(crops.length / cols);
+  const tiles = await Promise.all(crops.map(async (crop, i) => ({
+    input: await sharp(crop).composite([{ input: Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}"><rect width="${size}" height="${size}" fill="none" stroke="#000" stroke-width="4"/>${svgLabel(8, 24, `#${i + 1}`, [255, 230, 0])}</svg>`) }]).png().toBuffer(),
+    left: (i % cols) * size,
+    top: Math.floor(i / cols) * size,
+  })));
+  return sharp({ create: { width: cols * size, height: rows * size, channels: 3, background: '#111' } }).composite(tiles).png().toBuffer();
+}
+
+const Judged = z.object({ wrong: z.array(z.object({ id: z.number(), why: z.string() })) });
+
+export async function judge(memo: Memo, label: string, sheet: Buffer, count: number): Promise<z.infer<typeof Judged>['wrong']> {
+  const prompt = `This contact sheet shows ${count} tiles from a 2D point-and-click adventure, each a crop around the player character (a simple dark figure), numbered #1 to #${count} in the corner. Which tiles look wrong, and why? Look for: the character standing inside an object, partly hidden by an object they should be in front of, drawn over an object they should be behind, floating above or sunk into the ground, or the wrong size for the things around them.
+Reply with JSON only: {"wrong": [{"id": 1, "why": "short reason"}]}, an empty list when all look right.`;
+  const { wrong } = Judged.parse(await askSparkJson(memo, { schema: Judged, label, prompt, images: [sheet] }));
+  return wrong.filter((w) => w.id >= 1 && w.id <= count);
+}
+
+/**
+ * Closes cells around spots with issues, never near the start or a thing's spot, and never more
+ * than `cap` of a floor's cells; a fix that would cut any floor off from the start is undone.
+ */
+export function fixGrid(g: Geometry, checked: Checked[], cap = 0.35): { geometry: Geometry; closed: number; undone: string[] } {
+  const grid = gridOf(g);
+  const keep = new Set<number>();
+  for (const [x, y] of [g.start, ...g.things.map((t) => t.stand)]) {
+    const c0 = Math.floor(x / g.cell);
+    const r0 = Math.floor(y / g.cell);
+    for (let r = r0 - 3; r <= r0 + 3; r++) for (let c = c0 - 3; c <= c0 + 3; c++) if (grid.inside(c, r)) keep.add(grid.at(c, r));
+  }
+  const byZone = new Map<number, number[]>();
+  for (const h of checked) {
+    if (!h.issues.some((i) => i !== 'invisible')) continue;
+    const c0 = Math.floor(h.x / g.cell);
+    const r0 = Math.floor(h.y / g.cell);
+    for (let r = r0 - 1; r <= r0 + 1; r++) {
+      for (let c = c0 - 1; c <= c0 + 1; c++) {
+        if (!grid.inside(c, r)) continue;
+        const i = grid.at(c, r);
+        if (!grid.open[i] || keep.has(i)) continue;
+        byZone.set(grid.zone[i], [...(byZone.get(grid.zone[i]) ?? []), i]);
+      }
+    }
+  }
+  const undone: string[] = [];
+  let closed = 0;
+  const startCell = grid.cellOf(...g.start);
+  for (const [zone, cells] of byZone) {
+    const unique = [...new Set(cells)];
+    const size = grid.zone.filter((z, i) => z === zone && grid.open[i]).length;
+    if (unique.length > cap * size) {
+      undone.push(`floor ${zone}: fixing would close ${unique.length} of ${size} cells`);
+      continue;
+    }
+    unique.forEach((i) => (grid.open[i] = 0));
+    const reached = reach(grid, startCell, roomy(grid));
+    const stillThere = [...grid.zone.keys()].some((i) => grid.zone[i] === zone && reached[i]);
+    const spotsOk = g.things.every((t) => reached[grid.cellOf(...t.stand)] || !reach(gridOf(g), startCell)[grid.cellOf(...t.stand)]);
+    if (!stillThere || !spotsOk) {
+      unique.forEach((i) => (grid.open[i] = 1));
+      undone.push(`floor ${zone}: fixing would cut it or a thing's spot off`);
+      continue;
+    }
+    closed += unique.length;
+  }
+  const { walk } = grid.rowsOut();
+  return { geometry: { ...g, walk }, closed, undone };
+}

package/app/src/qa/probe.ts

@@ -0,0 +1,139 @@
+// The in-page half of the explorer. It runs inside the play page (as a string, so no bundler
+// helpers leak in) and uses the page's own renderer: whatever the game draws is what gets checked.
+//
+// For each position it renders three frames over the hero's box: the place without him (once),
+// with him and occlusion, and with him but nothing put back. Drawn = differs from the empty
+// place without occlusion; hidden = drawn but the occluded frame shows the empty place there.
+
+export type ProbeHit = {
+  x: number;
+  y: number;
+  /** Hero pixels without occlusion, and how many of them occlusion put the painting back over. */
+  drawn: number;
+  hidden: number;
+  /** Visible hero pixels over a thing whose floor line is nearer than his feet: he should be behind it. */
+  overNearer: Record<string, number>;
+  /** Hidden hero pixels under a thing whose floor line is behind his feet: he should be in front of it. */
+  hiddenByFarther: Record<string, number>;
+  /** Visible hero pixels where the depth map says the painting stands nearer than his feet (a lamp post nobody masked). */
+  overDepth?: number;
+  /** Hero pixels inside the box of a thing with only a box for a mask, while his feet are behind its bottom. */
+  overBox: Record<string, number>;
+  /** Things whose floor footprint holds his feet: he would stand inside them. */
+  feetIn: string[];
+  /** Share of his height above the top of the frame or of his width outside its sides. */
+  off: number;
+};
+
+export const PROBE_JS = String.raw`async ({ placeKey, positions }) => {
+  const game = window.diorama;
+  if (!game.place || game.place.key !== placeKey) await game.enter(placeKey);
+  const place = game.place;
+  const g = place.g;
+  const W = g.frame.width, H = g.frame.height;
+  const canvas = document.getElementById('view');
+  const ctx = canvas.getContext('2d');
+  game.hero.path = []; game.speech = null; game.hover = undefined; game.grid = false; game.dark = 0;
+  if (typeof game.darkTarget === 'number') game.darkTarget = 0;
+
+  const lineAt = (line, x) => {
+    if (x <= line[0][0]) return line[0][1];
+    for (let i = 1; i < line.length; i++) {
+      if (x <= line[i][0]) {
+        const [x0, y0] = line[i - 1], [x1, y1] = line[i];
+        return x1 === x0 ? y1 : y0 + ((y1 - y0) * (x - x0)) / (x1 - x0);
+      }
+    }
+    return line[line.length - 1][1];
+  };
+  const occ = new Map(g.occluders.map((o) => [o.key, o]));
+  // Where each thing meets the floor at column x. Walls and water have no such line, and a coarse
+  // mask is a box around the thing, not its outline, so overlaps with it say nothing.
+  const things = place.hots.filter((h) => h.mask && !h.thing.coarse && h.thing.kind !== 'walk-on' && h.thing.kind !== 'wall' && h.thing.kind !== 'flat').map((h) => {
+    const own = g.occluders.filter((o) => (o.thing ?? o.key) === h.thing.key);
+    const base = (x) => {
+      const o = own.find((o) => x >= o.box[0] && x < o.box[2]) ?? own[0];
+      if (!o) return h.thing.box[3];
+      const under = o.on ? occ.get(o.on) : undefined;
+      const ref = under ?? o;
+      return ref.floor && ref.floor.length ? lineAt(ref.floor, x) : ref.baseY;
+    };
+    return { key: h.thing.key, bits: h.mask.bits, box: h.thing.box, base, solid: h.thing.kind === 'standing' };
+  });
+
+  // Standing things known only by a box: nobody should be drawn inside the box while behind its bottom.
+  const boxes = place.hots.filter((h) => h.thing.coarse && h.thing.kind === 'standing').map((h) => ({ key: h.thing.key, box: h.thing.box }));
+  const person = (y) => Math.max(8, g.scale.pxPerY * (y - g.scale.horizonY));
+  const region = (x0, y0, x1, y1) => ctx.getImageData(x0, y0, x1 - x0, y1 - y0).data;
+  game.hero.x = -5000; game.hero.y = H - 1;
+  game.render();
+  const empty = ctx.getImageData(0, 0, W, H).data;
+  const cuts = place.cuts;
+  const out = [];
+  for (const [x, y] of positions) {
+    const h = person(y);
+    const w = game.hero.img ? (h * game.hero.img.width) / game.hero.img.height : h * 0.36;
+    const off = Math.max(0, h - y) / h + (Math.max(0, w / 2 - x) + Math.max(0, x + w / 2 - W)) / w;
+    const x0 = Math.max(0, Math.floor(x - w / 2 - 3)), x1 = Math.min(W, Math.ceil(x + w / 2 + 3));
+    const y0 = Math.max(0, Math.floor(y - h - 3)), y1 = Math.min(H, Math.ceil(y + 4));
+    // foot: where the feet were drawn last (a stair's tread); a probe stands him afresh.
+    Object.assign(game.hero, { x, y, facing: 1, phase: 0, foot: undefined });
+    place.cuts = cuts; game.render();
+    const occluded = region(x0, y0, x1, y1);
+    place.cuts = []; game.depthOcclusion = false; game.render();
+    const bare = region(x0, y0, x1, y1);
+    place.cuts = cuts; game.depthOcclusion = true;
+    const front = game.frontOf ? game.frontOf([x0, y0, x1, y1], x, y) : null;
+    const hit = { x, y, drawn: 0, hidden: 0, overNearer: {}, overDepth: 0, hiddenByFarther: {}, overBox: {}, feetIn: [], off: Math.round(off * 100) / 100 };
+    const rw = x1 - x0;
+    for (let py = y0; py < y1; py++) {
+      // The shadow under his feet is not him.
+      if (py > y - Math.max(3, h * 0.04)) continue;
+      for (let px = x0; px < x1; px++) {
+        const r = ((py - y0) * rw + (px - x0)) * 4, f = (py * W + px) * 4;
+        const diff = Math.abs(bare[r] - empty[f]) + Math.abs(bare[r + 1] - empty[f + 1]) + Math.abs(bare[r + 2] - empty[f + 2]);
+        if (diff < 30) continue;
+        hit.drawn++;
+        const back = Math.abs(occluded[r] - empty[f]) + Math.abs(occluded[r + 1] - empty[f + 1]) + Math.abs(occluded[r + 2] - empty[f + 2]) < 12;
+        if (back) hit.hidden++;
+        // Still the hero as drawn with nothing put back: the depth map's work did not reach him there.
+        else if (front && front[(py - y0) * rw + (px - x0)] && Math.abs(occluded[r] - bare[r]) + Math.abs(occluded[r + 1] - bare[r + 1]) + Math.abs(occluded[r + 2] - bare[r + 2]) < 12) hit.overDepth++;
+        for (const b of boxes) {
+          if (px >= b.box[0] && px < b.box[2] && py >= b.box[1] && py < b.box[3] && y < b.box[3] - 4) hit.overBox[b.key] = (hit.overBox[b.key] ?? 0) + 1;
+        }
+        for (const t of things) {
+          if (px < t.box[0] || px >= t.box[2] || py < t.box[1] || py >= t.box[3] || !t.bits[py * W + px]) continue;
+          const base = t.base(px);
+          if (!back && base > y + 8) hit.overNearer[t.key] = (hit.overNearer[t.key] ?? 0) + 1;
+          if (back && base < y - 8) hit.hiddenByFarther[t.key] = (hit.hiddenByFarther[t.key] ?? 0) + 1;
+        }
+      }
+    }
+    // Inside a footprint: between where a thing meets the floor and a third of its width behind that.
+    for (const o of g.occluders) {
+      const cell = (o.foot ?? []).find(([fx]) => Math.abs(fx - x) <= 3);
+      if (cell && y > cell[1] + 2 && y < cell[2] - 2 && !hit.feetIn.includes(o.thing ?? o.key)) hit.feetIn.push(o.thing ?? o.key);
+    }
+    out.push(hit);
+  }
+  game.render();
+  return out;
+}`;
+
+/** Renders the hero at one spot and returns a PNG crop around him, for the juror's contact sheet. */
+export const CROP_JS = String.raw`async ({ placeKey, x, y, size }) => {
+  const game = window.diorama;
+  if (!game.place || game.place.key !== placeKey) await game.enter(placeKey);
+  const g = game.place.g;
+  Object.assign(game.hero, { x, y, facing: 1, phase: 0, path: [] });
+  game.speech = null; game.hover = undefined; game.grid = false;
+  game.render();
+  const h = Math.max(8, g.scale.pxPerY * (y - g.scale.horizonY));
+  const side = Math.max(size, Math.ceil(h * 1.5));
+  const cx = Math.round(Math.min(g.frame.width - side / 2, Math.max(side / 2, x)));
+  const cy = Math.round(Math.min(g.frame.height - side / 2, Math.max(side / 2, y - h / 2)));
+  const c = document.createElement('canvas');
+  c.width = size; c.height = size;
+  c.getContext('2d').drawImage(document.getElementById('view'), cx - side / 2, cy - side / 2, side, side, 0, 0, size, size);
+  return c.toDataURL('image/png');
+}`;

package/app/src/qa/route.ts

@@ -0,0 +1,118 @@
+import type { Page } from 'playwright';
+import type { Action } from '../story/engine.ts';
+
+type Step = { use: string; verb?: string; with?: string } | { act: Action } | { wait: number };
+
+/** Follow a route through the same pointer targets, inventory and answers as a person. */
+export async function playRoute(page: Page, steps: Step[]): Promise<{ ending: string | null; frames: number; time: number }> {
+  // Track async dialogue actions triggered by DOM buttons, without invoking them ourselves.
+  await trackPending(page);
+  const settled = () => waitSettled(page);
+  for (const step of steps) {
+    if ('wait' in step) {
+      await page.evaluate(`window.diorama.wait(${JSON.stringify(step.wait)})`);
+      continue;
+    }
+    await settled();
+    if ('act' in step) {
+      if (step.act.kind !== 'choose' && step.act.kind !== 'leave') throw new Error(`No pointer control for ${step.act.kind}`);
+      const action = step.act.kind === 'choose' ? `choose:${step.act.index}` : 'leave';
+      await page.locator(`#talk button[data-action=${JSON.stringify(action)}]`).click();
+    } else {
+      if (step.with) await page.locator(`#inventory button[data-item=${JSON.stringify(step.with)}]`).click();
+      const point = await aimPoint(page, step);
+      if (!point) throw new Error(`No clickable pixel for ${step.use}: its pointer target is hidden or covered`);
+      await page.mouse.click(point.x, point.y, { button: step.verb === 'look' ? 'right' : 'left' });
+    }
+    await settled();
+  }
+  return page.evaluate('({ ending: window.diorama.state.ending ?? null, frames: window.diorama.frame, time: window.diorama.time })');
+}
+
+/** The page is still: in a place, not walking a scripted action, nobody speaking, not faded out. */
+export const SETTLED = 'window.diorama.place && !window.diorama.busy && !window.diorama.pointerRoutePending && !window.diorama.speech && window.diorama.dark === 0';
+
+/**
+ * Waits until the page is settled. Settled is a game-clock matter: on a busy machine a long line takes minutes of
+ * wall time. Each minute the game clock moved on counts as progress; only a minute without a frame is a game that hangs.
+ */
+export async function waitSettled(page: Page): Promise<void> {
+  for (let last = -1; ;) {
+    try {
+      await page.waitForFunction(SETTLED, undefined, { timeout: 60_000 });
+      return;
+    } catch (error) {
+      const frame = await page.evaluate('window.diorama.frame') as number;
+      if (typeof frame !== 'number' || frame === last) throw error;
+      last = frame;
+    }
+  }
+}
+
+/** Counts the page's async dialogue actions started by DOM buttons (window.diorama.pointerRoutePending), once per page. */
+export async function trackPending(page: Page): Promise<void> {
+  await page.evaluate(`(() => {
+    const game = window.diorama;
+    if (game.pointerRouteInstalled) return;
+    game.pointerRouteInstalled = true;
+    game.pointerRoutePending = 0;
+    const act = game.act.bind(game);
+    game.act = async (...args) => {
+      game.pointerRoutePending++;
+      try { return await act(...args); }
+      finally { game.pointerRoutePending--; }
+    };
+  })()`);
+}
+
+/**
+ * Where on the page a person would click to use `step.use` (with the item in hand, when `step.with`): the middle of
+ * its box when that hits it, else inside the largest exposed patch. Null when no pixel of it can be clicked.
+ * Throws when the place has no such thing or the click would not do `step.verb`.
+ */
+export function aimPoint(page: Page, step: { use: string; verb?: string; with?: string }): Promise<{ x: number; y: number } | null> {
+  return page.evaluate<{ x: number; y: number } | null>(`(() => {
+    const step = ${JSON.stringify(step)};
+    const game = window.diorama;
+    const hot = game.hots().find(h => h.thing.key === step.use);
+    if (!hot) throw new Error(game.place.key + ' has no thing ' + step.use);
+    const action = game.actionFor(step.use, hot, step.verb === 'look' ? 'look' : undefined);
+    if (step.verb && (action.kind !== 'do' || action.verb !== step.verb || action.with !== step.with))
+      throw new Error('No pointer action ' + step.verb + ' for ' + step.use);
+    const canvas = document.querySelector('canvas');
+    const rect = canvas.getBoundingClientRect();
+    const box = game.pageRect(step.use) ?? rect;
+    const hits = (x, y) => {
+      const at = game.unzoom((x - rect.left) / rect.width * canvas.width, (y - rect.top) / rect.height * canvas.height);
+      return game.thingAt(...at)?.thing.key === step.use && document.elementFromPoint(x, y) === canvas;
+    };
+    const cx = box.left + box.width / 2, cy = box.top + box.height / 2;
+    if (hits(cx, cy)) return { x: cx, y: cy };
+    // Aim inside the largest exposed patch, not at its first edge pixel. An animated NPC can
+    // move between measuring and the actual pointer event, especially beside the inventory.
+    const left = Math.max(0, rect.left, box.left), top = Math.max(0, rect.top, box.top);
+    const right = Math.min(innerWidth, rect.right, box.right), bottom = Math.min(innerHeight, rect.bottom, box.bottom);
+    const stride = 4, cols = Math.ceil((right - left) / stride);
+    let previous = new Uint32Array(Math.max(0, cols) + 1), best = 0, aim = null;
+    for (let y = top + 0.5; y < bottom; y += stride) {
+      const row = new Uint32Array(previous.length);
+      for (let c = 1, x = left + 0.5; x < right; c++, x += stride) {
+        if (!hits(x, y)) continue;
+        row[c] = 1 + Math.min(row[c - 1], previous[c], previous[c - 1]);
+        if (row[c] > best) {
+          best = row[c];
+          aim = { x: x - (best - 1) * stride / 2, y: y - (best - 1) * stride / 2 };
+        }
+      }
+      previous = row;
+    }
+    if (aim && hits(aim.x, aim.y)) return aim;
+    // Preserve pixel-sized targets that the coarse search might step over.
+    for (let y = Math.max(0, rect.top, box.top) + 0.5; y < Math.min(innerHeight, rect.bottom, box.bottom); y++) {
+      for (let x = Math.max(0, rect.left, box.left) + 0.5; x < Math.min(innerWidth, rect.right, box.right); x++) {
+        if (hits(x, y)) return { x, y };
+      }
+    }
+    return null;
+  })()`);
+}

package/app/src/registry.ts

@@ -0,0 +1,23 @@
+// Every command module registers itself here on import.
+export type Command = { name: string; usage: string; run: (args: string[]) => Promise<void> };
+
+export const registry = new Map<string, Command>();
+
+export function defineCommand(cmd: Command) {
+  registry.set(cmd.name, cmd);
+}
+
+/** Removes `--name value` from args and returns the value, or `fallback`. */
+export function takeOption(args: string[], name: string, fallback: string): string {
+  const at = args.indexOf(`--${name}`);
+  if (at < 0) return fallback;
+  const [, value] = args.splice(at, 2);
+  return value ?? fallback;
+}
+
+/** With DIORAMA_EVENTS=1 (a job run by diorama studio), a line the studio reads as a live event; otherwise nothing. */
+export function emit(type: string, data: Record<string, unknown> = {}) {
+  // A staged extension is not the live world: do not report its provisional verdict as a live place or trigger auto-repair.
+  if (process.env.DIORAMA_STAGED_BUILD === '1' && type === 'place.verdict') return;
+  if (process.env.DIORAMA_EVENTS === '1') process.stdout.write(`@@diorama ${JSON.stringify({ type, ...data })}\n`);
+}

package/app/src/scene/animation-source.ts

@@ -0,0 +1,36 @@
+// Bind generated motion to the source painting and, for sprites, the model that made it.
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import type { WorldFiles } from '../world/files.ts';
+type Kind = 'rig' | 'model' | 'sprites';
+type Binding = { painting: string; model?: string };
+const hash = (file: string) => fs.existsSync(file) ? createHash('sha256').update(fs.readFileSync(file)).digest('hex') : undefined;
+const manifest = (files: WorldFiles, key: string) => files.path('cast', key, 'animation-source.json');
+const existing = (files: WorldFiles, key: string, kind: Kind) => files.path('cast', key, kind === 'rig' ? 'rig.json' : kind === 'model' ? 'model/model.json' : 'sprites/sprites.json');
+const read = (files: WorldFiles, key: string): Partial<Record<Kind, Binding>> => fs.existsSync(manifest(files,key)) ? files.readJson(manifest(files,key)) as Partial<Record<Kind, Binding>> : {};
+const current = (files: WorldFiles, key: string, kind: Kind): Binding | undefined => {
+  const painting = hash(files.path('cast',`${key}-painting.png`));
+  if (!painting) return;
+  const dir = files.path('cast', key, 'model');
+  const names = ['model.glb','model.json','front.png','back.png','left.png','right.png'];
+  const entries = kind === 'sprites' ? names.map(name => [name, hash(`${dir}/${name}`)] as const) : [];
+  const model = entries.some(([, value]) => value) ? createHash('sha256').update(JSON.stringify(entries)).digest('hex') : undefined;
+  return { painting, ...(model && {model}) };
+};
+/** Record legacy assets before replacing their source, without deleting paid work. */
+export function bindExistingAnimation(files: WorldFiles, key: string) {
+  const saved=read(files,key); let changed=false;
+  for(const kind of ['rig','model','sprites'] as const) if(!saved[kind] && fs.existsSync(existing(files,key,kind))) {
+    const source=current(files,key,kind); if(source) { saved[kind]=source; changed=true; }
+  }
+  if(changed)files.write(manifest(files,key),saved);
+}
+export function bindAnimation(files: WorldFiles,key:string,kind:Kind) {
+  const source=current(files,key,kind); if(!source)return;
+  const saved=read(files,key);saved[kind]=source;files.write(manifest(files,key),saved);
+}
+export function animationCurrent(files:WorldFiles,key:string,kind:Kind):boolean {
+  const binding=read(files,key)[kind]; if(!binding)return true; // legacy remains usable until its source is replaced
+  const source=current(files,key,kind);
+  return !!source && source.painting===binding.painting && (!binding.model || source.model===binding.model);
+}

package/app/src/scene/assets.ts

@@ -0,0 +1,37 @@
+// What the build made for the cast and the sound, apart from whether the places are playable: verify checks the
+// places' geometry, and says nothing of a character with no walk or a bed that stayed silent.
+import fs from 'node:fs';
+import { modelProblem } from '../model/glb.ts';
+import { liveVoiceFailures } from '../sound/data.ts';
+import { SoundManifest } from '../sound/make.ts';
+import { Voices } from '../sound/voices.ts';
+import type { WorldFiles } from '../world/files.ts';
+import { players } from '../world/drawings.ts';
+import { readBodies } from './cast.ts';
+
+export function assetReport(files: WorldFiles): string[] {
+  const world = files.world();
+  const keys = [world.hero.key, ...world.places.flatMap((p) => p.things.filter((t) => t.role === 'npc').map((t) => t.key)), ...players(files).map((p) => p.key)];
+  const has = (...f: string[]) => fs.existsSync(files.path(...f));
+  const model = (k: string) => has('cast', k, 'model', 'model.json') && !modelProblem(files.path('cast', k, 'model'));
+  const lines: string[] = [];
+  const count = (name: string, test: (k: string) => boolean, of = keys) => {
+    const missing = of.filter((k) => !test(k));
+    lines.push(`${name} ${of.length - missing.length}/${of.length}${missing.length ? ` (none: ${missing.join(', ')})` : ''}`);
+  };
+  count('figures', (k) => has('cast', `${k}.png`));
+  // A creature (not upright) moves as one body: it has no rig to miss.
+  const bodies = readBodies(files, fs.existsSync);
+  count('rig', (k) => has('cast', k, 'rig.json'), keys.filter((k) => has('cast', `${k}.png`) && bodies[k]?.upright !== false));
+  if (keys.some(model) || keys.some((k) => has('cast', k, 'model'))) count('3D model', model, keys.filter((k) => has('cast', k, 'model')));
+  if (has('voices.json')) {
+    const v = Voices.safeParse(files.readJson(files.path('voices.json')));
+    const failed = liveVoiceFailures(files);
+    if (v.success) lines.push(`voices ${v.data.lines.length} lines spoken${failed.length ? `, ${failed.length} not (${[...new Set(failed.map((f) => f.speaker))].join(', ')})` : ''}`);
+  }
+  if (has('sound', 'sounds.json')) {
+    const m = SoundManifest.safeParse(files.readJson(files.path('sound', 'sounds.json')));
+    if (m.success) lines.push(`sounds ${Object.keys(m.data.sounds).length} made${Object.keys(m.data.failures).length ? `, ${Object.keys(m.data.failures).length} silent (${Object.keys(m.data.failures).join(', ')}: sound_redo)` : ''}`);
+  }
+  return lines;
+}

package/app/src/scene/autofix.ts

@@ -0,0 +1,133 @@
+// The first, free tier of repair: fixes a build can make on its own, with no model call, before anyone is
+// asked. Each is an ordinary correction (the same ones the fix tools write), so it shows in corrections_get,
+// survives rebuilds and can be taken back with corrections_clear. Anything less certain is left to the agent.
+import type { Geometry } from '../play/geometry.ts';
+import type { Mask } from '../image/mask.ts';
+import type { Corrections } from './corrections.ts';
+import { diagnose } from './diagnose.ts';
+import { GRID } from './locate.ts';
+import type { Finding } from './verify.ts';
+import { gridOf } from './verify.ts';
+import { CELL, type Grid, islands, reach, roomy } from './walk.ts';
+
+export type AutoFix = {
+  /** What was done, in a line for the report and the agent. */
+  what: string;
+  /** The step the fix feeds: the place is rebuilt from there. */
+  from: 'masks' | 'derive';
+  apply(c: Corrections): void;
+};
+
+/** A gap longer than this is no slip of a mask: it needs someone to look. */
+const MAX_GAP = 3 * GRID;
+/** Through stairs or a gangway the painting itself shows the way, so a longer gap is bridged. */
+const MAX_GAP_WALK_ON = 6 * GRID;
+/** Things the hero walks around, not over: a gap through one is not bridged blindly. */
+const SOLID = new Set(['standing', 'wall']);
+
+/** How tall a person may be at the front after the floor is cut back (verify allows up to 760). */
+const NEAR_PX = 720;
+
+/** How far a walk-on mask may stop short of a floor and still be taken to join it. */
+const JOIN = 16;
+
+/** Walk cells within JOIN px of a mask pixel. */
+function nearMask(grid: Grid, m: Mask): Uint8Array {
+  const near = new Uint8Array(grid.open.length);
+  const reachCells = Math.ceil(JOIN / CELL);
+  for (let y = 0; y < m.height; y += 2) {
+    for (let x = 0; x < m.width; x += 2) {
+      if (!m.bits[y * m.width + x]) continue;
+      const c0 = Math.floor(x / CELL);
+      const r0 = Math.floor(y / CELL);
+      for (let r = r0 - reachCells; r <= r0 + reachCells; r++) {
+        for (let c = c0 - reachCells; c <= c0 + reachCells; c++) if (grid.inside(c, r)) near[grid.at(c, r)] = 1;
+      }
+    }
+  }
+  return near;
+}
+
+/**
+ * masks: the walk-on things' masks by key. Stairs only carry a bridge when their mask reaches both the patch
+ * and the reached floor: stairs that climb from the far side to somewhere else (water between the floors)
+ * join nothing, and a stroke across them would have the hero walk on water.
+ */
+export function autoFixes(g: Geometry, floorKeys: string[], errors: Finding[], masks: Record<string, Mask> = {}): AutoFix[] {
+  const codes = new Set(errors.map((e) => e.code));
+  const d = diagnose(g);
+  const fixes: AutoFix[] = [];
+  if (codes.has('FLOOR_UNREACHABLE') || codes.has('UNREACHABLE')) {
+    const grid = gridOf(g);
+    const cells = roomy(grid);
+    const reached = reach(grid, grid.cellOf(...g.start), cells);
+    const parts = islands(grid, cells);
+    const joins = (key: string, patch: number[]) => {
+      const m = masks[key];
+      if (!m) return false;
+      const near = nearMask(grid, m);
+      return patch.some((i) => near[i]) && [...reached.keys()].some((i) => reached[i] && near[i]);
+    };
+    for (const p of d.patches) {
+      const gap = p.gap;
+      if (!gap || gap.things.some((t) => SOLID.has(t.kind ?? ''))) continue;
+      // Stairs or a gangway (a walk-on thing) standing in the gap are what joins the two levels: bridge along
+      // them even when the gap is long, but only when their mask touches both sides. Without one, a long gap is
+      // a real wall (or water) and needs someone to look: a repaint or a floor in the layout.
+      const patch = parts.find((x) => x.includes(grid.cellOf(...gap.from))) ?? [];
+      const walkOn = gap.things.filter((t) => t.kind === 'walk-on' && joins(t.key, patch));
+      const along = walkOn.length > 0;
+      if (gap.px > (along ? MAX_GAP_WALK_ON : MAX_GAP)) continue;
+      // Brush the reached floor across the gap: a stroke wide enough for the hero (two walk cells and a margin).
+      const floor = floorKeys[grid.zone[grid.cellOf(...gap.to)]] ?? floorKeys[p.floors[0]];
+      if (!floor) continue;
+      const points: [number, number][] = [gap.to, gap.from];
+      fixes.push({
+        what: `bridged ${p.cells} cells of floor ${p.floors.join('+') || 'none'} to ${floor} across ${gap.px} px (${gap.cells.join(' ') || 'thin gap'})${along ? ` along ${walkOn.map((t) => t.key).join(', ')}` : ''}`,
+        from: 'masks',
+        apply: (c) => {
+          const f = (c.floors[floor] ??= { add: [], remove: [], strokes: [] });
+          // The same bridge twice is no new fix: a build that tried it once leaves it to the agent.
+          if (!f.strokes.some((s) => JSON.stringify(s.points) === JSON.stringify(points))) f.strokes.push({ mode: 'add', radius: 14, points });
+        },
+      });
+    }
+  }
+  if (codes.has('SPOT_UNREACHABLE')) {
+    const wanted = new Set(errors.filter((e) => e.code === 'SPOT_UNREACHABLE').map((e) => e.key));
+    for (const s of d.spots) {
+      if (!wanted.has(s.thing) || !s.nearest) continue;
+      const at = s.nearest;
+      fixes.push({ what: `moved the stand spot of ${s.thing} to (${at.join(', ')}), the nearest reachable floor`, from: 'derive', apply: (c) => void ((c.things[s.thing] ??= { strokes: [] }).stand = at) });
+    }
+  }
+  // The hero would be a giant at the very front (a close camera, a big thing in the foreground): the bottom of
+  // the floor goes, up to where a person is NEAR_PX tall, as long as most of the floor stays walkable.
+  if (codes.has('SCALE_NEAR') && g.scale.pxPerY > 0) {
+    const cut = Math.floor(g.scale.horizonY + NEAR_PX / g.scale.pxPerY);
+    const rows = g.walk.map((row, r) => (row.includes('#') ? r : -1)).filter((r) => r >= 0);
+    const kept = rows.filter((r) => (r + 1) * g.cell <= cut).length;
+    const bottom = rows.length ? (rows[rows.length - 1] + 1) * g.cell : 0;
+    if (cut < bottom && kept >= rows.length / 2) {
+      const width = g.walk[0].length * g.cell;
+      const lines: [number, number][][] = [];
+      for (let y = cut + 12; y < bottom + 12; y += 16) lines.push([[0, y], [width, y]]);
+      fixes.push({
+        what: `took the floor below y ${cut} out of the walk, where a person would be over ${NEAR_PX} px tall`,
+        from: 'masks',
+        apply: (c) => {
+          // Walk-on things (a path, a jetty) are walked on too, so they lose the same strip.
+          const all = [...floorKeys.map((k) => (c.floors[k] ??= { add: [], remove: [], strokes: [] })), ...Object.keys(masks).map((k) => (c.things[k] ??= { strokes: [] }))];
+          for (const f of all) for (const points of lines) if (!f.strokes.some((x) => JSON.stringify(x.points) === JSON.stringify(points))) f.strokes.push({ mode: 'erase', radius: 12, points });
+        },
+      });
+    }
+  }
+  // Spark found the thing in another box: give SAM that box (one SAM call when the place is rebuilt).
+  for (const e of errors.filter((x) => x.code === 'MASK_WRONG' && x.key)) {
+    const box = e.box;
+    if (!box) continue;
+    fixes.push({ what: `gave SAM the box Spark sees ${e.key} in: [${box.join(', ')}]`, from: 'masks', apply: (c) => void ((c.things[e.key!] ??= { strokes: [] }).box = box) });
+  }
+  return fixes;
+}