@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/scene/shadows.ts

@@ -0,0 +1,207 @@
+// shadows: the painted cast shadows on the floor, and the light they tell of, so the hero casts a
+// shadow the same way and darkens when standing in one. SAM finds no shadows in a painting (asked
+// "shadow", "cast shadow", "shade": nothing), so they are cut by brightness: floor clearly darker
+// than the lit floor around it, touching the base of a standing thing. The shape of each thing's
+// shadow gives the direction and length. Spark says whether there is sun at all (fog darkens wet
+// planks too). No thing with a shadow of its own: no light, so the hero casts none either.
+import sharp from 'sharp';
+import { z } from 'zod';
+import { emptyMask, maskArea, type Mask } from '../image/mask.ts';
+import { components, dilate, intersect, subtract, unionAll } from '../image/raster.ts';
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { FRAME } from './layout.ts';
+import type { Blob } from './occluders.ts';
+
+const { width: W, height: H } = FRAME;
+
+/** Light as the runtime takes it: where shadows fall on screen (+y toward the viewer), how long they are
+ * per px of the caster's height, and how much darker the floor is in shadow (0 none, 1 black). */
+export type Light = { dir: [number, number]; length: number; strength: number; at?: [number, number]; also?: Array<[number, number]> };
+export type CasterShadow = { thing: string; px: number; dir?: [number, number]; length?: number };
+export type Shadows = { mask: Mask; light?: Light; casters: CasterShadow[]; source: 'casters' | 'spark' | 'none' };
+
+/** Darker than this share of the lit floor around it is shadow. */
+export const SHADOW_DARK = 0.74;
+const REF_CELL = 16;
+const REF_RADIUS = 6;
+
+/** The painting's luma, lightly blurred so plank grain and pebbles don't count. */
+export async function lumaOf(painting: Buffer): Promise<Uint8Array> {
+  const raw = await sharp(painting).resize(W, H, { fit: 'fill' }).removeAlpha().blur(3).toColourspace('b-w').raw().toBuffer();
+  return new Uint8Array(raw.buffer, raw.byteOffset, W * H);
+}
+
+/** How bright lit floor is around each pixel: a high percentile of the floor cells nearby. */
+export function litFloor(luma: Uint8Array, floor: Mask): Float32Array {
+  const cw = Math.ceil(W / REF_CELL), ch = Math.ceil(H / REF_CELL);
+  const mean = new Float32Array(cw * ch).fill(-1);
+  for (let cy = 0; cy < ch; cy++) for (let cx = 0; cx < cw; cx++) {
+    let sum = 0, n = 0;
+    for (let y = cy * REF_CELL; y < Math.min(H, (cy + 1) * REF_CELL); y++) for (let x = cx * REF_CELL; x < Math.min(W, (cx + 1) * REF_CELL); x++) {
+      if (floor.bits[y * W + x]) { sum += luma[y * W + x]; n++; }
+    }
+    if (n > 0.3 * REF_CELL * REF_CELL) mean[cy * cw + cx] = sum / n;
+  }
+  const ref = new Float32Array(cw * ch);
+  for (let cy = 0; cy < ch; cy++) for (let cx = 0; cx < cw; cx++) {
+    const near: number[] = [];
+    for (let dy = -REF_RADIUS; dy <= REF_RADIUS; dy++) for (let dx = -REF_RADIUS; dx <= REF_RADIUS; dx++) {
+      const x = cx + dx, y = cy + dy;
+      if (x >= 0 && y >= 0 && x < cw && y < ch && mean[y * cw + x] >= 0) near.push(mean[y * cw + x]);
+    }
+    near.sort((a, b) => a - b);
+    ref[cy * cw + cx] = near.length ? near[Math.floor(0.8 * (near.length - 1))] : 0;
+  }
+  const out = new Float32Array(W * H);
+  for (let y = 0; y < H; y++) for (let x = 0; x < W; x++) out[y * W + x] = ref[Math.floor(y / REF_CELL) * cw + Math.floor(x / REF_CELL)];
+  return out;
+}
+
+/** Floor clearly darker than the lit floor around it, without thin cracks between planks. */
+export function darkFloor(luma: Uint8Array, lit: Float32Array, floor: Mask): Mask {
+  const dark = emptyMask(W, H);
+  for (let i = 0; i < W * H; i++) if (floor.bits[i] && luma[i] < SHADOW_DARK * lit[i]) dark.bits[i] = 1;
+  return intersect(dilate(dilate(dark, -2), 2), floor);
+}
+
+function centroid(m: Mask): [number, number] | undefined {
+  let sx = 0, sy = 0, n = 0;
+  for (let i = 0; i < m.bits.length; i++) if (m.bits[i]) { sx += i % W; sy += Math.floor(i / W); n++; }
+  return n ? [sx / n, sy / n] : undefined;
+}
+
+/** A thing's shadow measured from its base: where its middle points, and how far its far end is. */
+export function measure(shadow: Mask, base: [number, number], height: number): { dir: [number, number]; length: number } | undefined {
+  const mid = centroid(shadow);
+  if (!mid) return undefined;
+  const vx = mid[0] - base[0], vy = mid[1] - base[1];
+  const reach = Math.hypot(vx, vy);
+  // A dark ring around the foot is contact shade, not a cast shadow: it says nothing of the light.
+  if (reach < 0.15 * height) return undefined;
+  const dir: [number, number] = [vx / reach, vy / reach];
+  const along: number[] = [];
+  for (let i = 0; i < W * H; i++) if (shadow.bits[i]) along.push((i % W - base[0]) * dir[0] + (Math.floor(i / W) - base[1]) * dir[1]);
+  along.sort((a, b) => a - b);
+  return { dir, length: along[Math.floor(0.95 * (along.length - 1))] / height };
+}
+
+// Without sun Spark often leaves the direction out.
+const SparkLight = z.object({ sunlit: z.boolean(), dx: z.number().default(0), dy: z.number().default(0), length: z.number().default(1) });
+
+/** Is there sun? (Its direction is not used: painted shadows are measured, not guessed.) */
+async function sparkLight(memo: Memo, label: string, painting: Buffer): Promise<Light | undefined> {
+  const prompt = `This is a painted background for a 2D adventure game (${W}x${H} px, x right, y down). A person will be walking on its floor.
+Is the scene lit by direct sun or another strong light that casts clear shadows (not fog, overcast or night without a lamp)? If it is, which way on the screen would a person's shadow fall from their feet, and how long would it be compared with their height?
+Reply with JSON only: {"sunlit": true, "dx": 0.5, "dy": 0.5, "length": 0.8}  (dx, dy: direction on screen, +dy toward the viewer)`;
+  const a = SparkLight.parse(await askSparkJson(memo, { schema: SparkLight, label, prompt, images: [painting] }));
+  const d = Math.hypot(a.dx, a.dy);
+  if (!a.sunlit || d < 1e-3) return undefined;
+  const r = (v: number) => Math.round(v * 1000) / 1000;
+  return { dir: [r(a.dx / d), r(a.dy / d)], length: r(Math.min(3, Math.max(0.2, a.length))), strength: 0.35 };
+}
+
+/** The painted shadows on `floor` (ground the hero walks on, minus things) and the light behind them.
+ * `casters` are the sharp standing blobs on the floor. */
+/** `askWith`: the painting to ask Spark where the sun is (after a small repaint, the one before it). */
+export async function findShadows(memo: Memo, label: string, painting: Buffer, floor: Mask, casters: Blob[], askWith = painting): Promise<Shadows> {
+  const luma = await lumaOf(painting);
+  const lit = litFloor(luma, floor);
+  const blobs = components(darkFloor(luma, lit, floor)).filter((c) => maskArea(c) >= 120);
+  const kept: Mask[] = [];
+  const measured: CasterShadow[] = [];
+  for (const b of casters) {
+    const height = b.baseY - b.box[1];
+    if (height < 24) continue;
+    // Only shadow at the thing's foot is its own: a lamp post rising through dark pebbles casts no pebbles.
+    const foot = emptyMask(W, H);
+    const from = Math.max(0, Math.round(b.baseY - Math.max(8, 0.1 * height)));
+    for (let i = from * W; i < Math.min(H, b.baseY + 1) * W; i++) foot.bits[i] = b.mask.bits[i];
+    const touch = dilate(foot, 8);
+    const own = blobs.filter((c) => maskArea(intersect(c, touch)) >= 20);
+    if (!own.length) continue;
+    // A long shadow can run into the next one: only the part within a few heights of the base is this thing's.
+    const near = emptyMask(W, H);
+    const r = 4 * height, cx = (b.box[0] + b.box[2]) / 2;
+    for (let y = Math.max(0, Math.round(b.baseY - r)); y < Math.min(H, b.baseY + r); y++) for (let x = Math.max(0, Math.round(cx - r)); x < Math.min(W, cx + r); x++) near.bits[y * W + x] = 1;
+    const shadow = intersect(unionAll(W, H, own), near);
+    // A shadow many times the thing's size is shade it stands in (the risers of stairs, a tree), not its own.
+    if (maskArea(shadow) > 3 * maskArea(b.mask)) {
+      measured.push({ thing: b.key, px: maskArea(shadow) });
+      continue;
+    }
+    kept.push(...own);
+    // Measured from where the shadow meets the foot: a wide thing's base is a line, not its box's corner.
+    const contact = centroid(intersect(shadow, touch)) ?? [cx, b.baseY];
+    measured.push({ thing: b.key, px: maskArea(shadow), ...measure(shadow, contact, height) });
+  }
+  const mask = unionAll(W, H, kept);
+  const directed = measured.filter((m) => m.dir);
+  // Dark wet planks next to a teapot look like a shadow too: Spark says whether there is sun at all.
+  const sun = await sparkLight(memo, `light:${label}`, askWith);
+  if (!sun) return { mask: emptyMask(W, H), casters: measured, source: 'none' };
+  // Sun, but no thing whose own shadow could be measured: the hero casts the shadow Spark sees, and no
+  // painted shadow is masked (nothing says which dark patches are shadows).
+  if (!directed.length) return { mask: emptyMask(W, H), light: sun, casters: measured, source: 'spark' };
+  // The things agree on the light when their directions add up; if they don't, the biggest shadow wins.
+  const weight = (m: CasterShadow) => Math.sqrt(m.px);
+  const total = directed.reduce((s, m) => s + weight(m), 0);
+  const sum = directed.reduce(([x, y], m) => [x + weight(m) * m.dir![0], y + weight(m) * m.dir![1]], [0, 0]);
+  const agree = Math.hypot(sum[0], sum[1]) / total;
+  const biggest = directed.reduce((a, b) => (b.px > a.px ? b : a));
+  const dir: [number, number] = agree >= 0.8 ? [sum[0] / (agree * total), sum[1] / (agree * total)] : biggest.dir!;
+  const lengths = directed.map((m) => m.length!).sort((a, b) => a - b);
+  const length = agree >= 0.8 ? lengths[Math.floor(lengths.length / 2)] : biggest.length!;
+  // Strength: how much darker the shadow is than the lit floor right around it.
+  const ring = subtract(intersect(dilate(mask, 20), floor), mask);
+  const median = (m: Mask, of: (i: number) => number) => {
+    const v: number[] = [];
+    for (let i = 0; i < W * H; i++) if (m.bits[i]) v.push(of(i));
+    v.sort((a, b) => a - b);
+    return v.length ? v[Math.floor(v.length / 2)] : 0;
+  };
+  const inShadow = median(mask, (i) => luma[i]);
+  const around = Math.max(median(ring, (i) => luma[i]), median(mask, (i) => lit[i]));
+  const strength = around > 0 ? Math.min(0.85, Math.max(0.1, 1 - inShadow / around)) : 0.35;
+  const round = (v: number) => Math.round(v * 1000) / 1000;
+  return { mask, light: { dir: [round(dir[0]), round(dir[1])], length: round(Math.min(4, length)), strength: round(strength) }, casters: measured, source: 'casters' };
+}
+
+const SparkSource = z.object({ source: z.string(), flame: z.boolean().optional() });
+
+/**
+ * A fire or a lamp that lights the scene more than the sky does (a camp at dusk, a lamp-lit room): Spark
+ * names the main light among the place's own `lights`. Asked only where the layout has lights. The light
+ * stands where its thing does: the foot of a tall one (a lamp post), the middle of a low one (a fire ring).
+ */
+export async function localLight(memo: Memo, label: string, painting: Buffer, lights: Array<{ key: string; box?: [number, number, number, number] }>): Promise<{ key: string; at: [number, number]; flame: boolean; also?: Array<[number, number]> } | undefined> {
+  const placed = lights.filter((l) => l.box);
+  if (!placed.length) return undefined;
+  const prompt = `This is a painted background for a 2D adventure game (${W}x${H} px). It shows these light sources: ${placed.map((l) => `"${l.key}"`).join(', ')}.
+What mainly lights the ground where people walk, and so decides which way their shadows fall: the sun or daylight, or one of those light sources (at dusk or at night a fire or a lamp usually does)?
+Reply with JSON only: {"source": "sun"} or {"source": "<one of the names above>", "flame": true if that light is a living flame (a fire, a torch, a candle, an oil lamp), false if not (an electric lamp, a glowing window)}`;
+  const a = SparkSource.parse(await askSparkJson(memo, { schema: SparkSource, label, prompt, images: [painting] }));
+  const hit = placed.find((l) => l.key === a.source);
+  if (!hit?.box) return undefined;
+  const also = placed.filter((l) => l !== hit && alikeLights(l.key, hit.key)).map((l) => lightAt(l.box!));
+  return { key: hit.key, at: lightAt(hit.box), flame: a.flame === true, ...(also.length && { also }) };
+}
+
+/** Where a light stands: the foot of a tall one (a lamp post), the middle of a low one (a fire ring). */
+function lightAt([x0, y0, x1, y1]: [number, number, number, number]): [number, number] {
+  const tall = y1 - y0 > 1.5 * (x1 - x0);
+  return [Math.round((x0 + x1) / 2), Math.round(tall ? y1 : (y0 + y1) / 2)];
+}
+
+/** Words that tell twins apart, not what they are. */
+const WHERE = new Set(['near', 'far', 'left', 'right', 'front', 'back', 'middle', 'centre', 'center', 'big', 'small', 'one', 'two', 'other', 'first', 'second']);
+
+/**
+ * Whether two lights are the same kind of thing (lamp-post-near and lamp-post-far): they share a word that
+ * says what they are. Two alike lamps around the walk area leave no single key light.
+ */
+export function alikeLights(a: string, b: string): boolean {
+  const words = (k: string) => k.toLowerCase().split(/[^a-z]+/).filter((w) => w.length > 2 && !WHERE.has(w));
+  const theirs = words(b);
+  return words(a).some((w) => theirs.includes(w));
+}

package/app/src/scene/stairs.ts

@@ -0,0 +1,183 @@
+// stairs: the steps of a staircase, so people's feet stay on a tread and step over each riser instead
+// of gliding up a ramp. Only places whose walk-on things or floors are stairs ask (one SAM call): SAM
+// "stair step" returns one instance per step, tread and riser together, which is exactly the band a
+// foot belongs to. Kept: wide, flat bands inside the stairs, at least two of them, stacked top to bottom.
+import { emptyMask, maskArea, type Mask } from '../image/mask.ts';
+import sharp from 'sharp';
+import { dilate, intersect, maskBox, rectMask } from '../image/raster.ts';
+import type { Memo } from '../meta/memo.ts';
+import { samFind } from '../meta/sam.ts';
+import type { Geometry } from '../play/geometry.ts';
+import { FRAME } from './layout.ts';
+
+const { width: W, height: H } = FRAME;
+/** Column spacing of the stored step edges, px. */
+export const STEP_EVERY = 8;
+
+/** Words that make a floor or walk-on thing a staircase (English and Polish, as worlds are written in both). */
+export const STAIRS = /stair|step|staircase|schod|stopn|stopień/i;
+
+/** A mask at frame size (SAM may answer at the painting's own size). */
+export function atFrame(m: Mask): Mask {
+  if (m.width === W && m.height === H) return m;
+  const out = emptyMask(W, H);
+  for (let y = 0; y < H; y++) {
+    const sy = Math.min(m.height - 1, Math.floor((y * m.height) / H));
+    for (let x = 0; x < W; x++) out.bits[y * W + x] = m.bits[sy * m.width + Math.min(m.width - 1, Math.floor((x * m.width) / W))];
+  }
+  return out;
+}
+
+/** One step's band per column: its first and last pixel, every STEP_EVERY px. */
+export function stepEdges(m: Mask): NonNullable<Geometry['steps']>[number] | undefined {
+  const box = maskBox(m);
+  if (!box) return undefined;
+  const x0 = Math.floor(box[0] / STEP_EVERY) * STEP_EVERY;
+  const top: number[] = [];
+  const bottom: number[] = [];
+  for (let x = x0; x <= box[2]; x += STEP_EVERY) {
+    let t = -1;
+    let b = -1;
+    for (let y = box[1]; y <= box[3] && y < H; y++) {
+      if (!m.bits[y * W + Math.min(W - 1, x)]) continue;
+      if (t < 0) t = y;
+      b = y;
+    }
+    top.push(t);
+    bottom.push(b);
+  }
+  return { x0, every: STEP_EVERY, top, bottom };
+}
+
+/** Least squares y = a + b x + c x² through the points, or undefined when there are too few. */
+function quadratic(xs: number[], ys: number[]): ((x: number) => number) | undefined {
+  if (xs.length < 4) return undefined;
+  // Centred and scaled, so the normal equations stay well conditioned.
+  const m = xs.reduce((a, b) => a + b, 0) / xs.length;
+  const u = xs.map((x) => (x - m) / 100);
+  const S = (f: (i: number) => number) => u.reduce((acc, _, i) => acc + f(i), 0);
+  const [s0, s1, s2, s3, s4] = [0, 1, 2, 3, 4].map((k) => S((i) => u[i] ** k));
+  const [t0, t1, t2] = [0, 1, 2].map((k) => S((i) => ys[i] * u[i] ** k));
+  const det = (a: number[][]) => a[0][0] * (a[1][1] * a[2][2] - a[1][2] * a[2][1]) - a[0][1] * (a[1][0] * a[2][2] - a[1][2] * a[2][0]) + a[0][2] * (a[1][0] * a[2][1] - a[1][1] * a[2][0]);
+  const A = [[s0, s1, s2], [s1, s2, s3], [s2, s3, s4]];
+  const D = det(A);
+  if (Math.abs(D) < 1e-9) return undefined;
+  const col = (k: number) => det(A.map((row, r) => row.map((v, c) => (c === k ? [t0, t1, t2][r] : v))));
+  const [a, b, c] = [col(0) / D, col(1) / D, col(2) / D];
+  return (x: number) => { const v = (x - m) / 100; return a + b * v + c * v * v; };
+}
+
+/**
+ * A step partly hidden by something on or in front of it (a basket on the tread, a boat at its end) is
+ * mended: the back edge of a flight's step is a smooth line or arc, so columns far off that curve get the
+ * curve instead, and a band much shallower than the step's usual depth gets its depth back.
+ */
+export function mendStep(s: NonNullable<Geometry['steps']>[number]): NonNullable<Geometry['steps']>[number] {
+  const cols = s.top.flatMap((t, i) => (t >= 0 && s.bottom[i] > t ? [i] : []));
+  const depths = cols.map((i) => s.bottom[i] - s.top[i]).sort((a, b) => a - b);
+  if (!depths.length) return s;
+  const usual = depths[Math.floor(depths.length / 2)];
+  // Fit the back edge, dropping the worst columns until everything left lies close to it.
+  let keep = cols;
+  let curve = quadratic(keep.map((i) => i), keep.map((i) => s.top[i]));
+  for (let round = 0; curve && round < 6; round++) {
+    const fit = curve;
+    const near = keep.filter((i) => Math.abs(s.top[i] - fit(i)) <= Math.max(6, 0.15 * usual));
+    if (near.length === keep.length || near.length < 0.5 * cols.length) break;
+    keep = near;
+    curve = quadratic(keep.map((i) => i), keep.map((i) => s.top[i]));
+  }
+  const top = [...s.top];
+  const bottom = [...s.bottom];
+  for (const i of cols) {
+    if (curve && Math.abs(top[i] - curve(i)) > Math.max(6, 0.15 * usual)) {
+      top[i] = Math.round(curve(i));
+      bottom[i] = Math.min(H - 1, top[i] + usual);
+    } else if (bottom[i] - top[i] < 0.75 * usual) bottom[i] = Math.min(H - 1, top[i] + usual);
+  }
+  return { ...s, top, bottom };
+}
+
+/**
+ * The steps of `stairs` read off the painting: a tread is lit from above, so its front edge is a row where the
+ * picture turns from dark (the riser above's shadow) to light, all the way across the stairs. Rows like that,
+ * evenly spaced, split the stairs into its steps, each from one tread's edge to the next. Empty when there is no
+ * such run of at least three edges (a slope, a ladder, one big block): the stairs stay a ramp.
+ */
+export async function treadBands(painting: Buffer, stairs: Mask): Promise<Mask[]> {
+  const box = maskBox(stairs);
+  if (!box) return [];
+  const L = await sharp(painting).resize(W, H, { fit: 'fill' }).greyscale().raw().toBuffer();
+  // Per row: how much lighter the row below is than the row above, across the stairs' columns there.
+  const rows: number[] = [];
+  const width: number[] = [];
+  for (let y = 0; y < H; y++) {
+    if (y < box[1] + 2 || y > box[3] - 3) {
+      rows.push(0);
+      width.push(0);
+      continue;
+    }
+    let n = 0;
+    let sum = 0;
+    for (let x = box[0]; x < box[2]; x++) {
+      if (!stairs.bits[(y - 2) * W + x] || !stairs.bits[(y + 2) * W + x]) continue;
+      n++;
+      sum += L[(y + 1) * W + x] - L[(y - 1) * W + x];
+    }
+    rows.push(n ? sum / n : 0);
+    width.push(n);
+  }
+  const widest = Math.max(...width);
+  const edge = rows.map((v, y) => (y + 1 < H && Math.max(width[y], width[y + 1]) >= 0.4 * widest ? v + rows[y + 1] : 0));
+  const strongest = Math.max(...edge);
+  if (strongest < 40) return [];
+  // Peaks: the lightest turn within 6 px either way, at least 60% of the strongest.
+  const peaks = edge.flatMap((v, y) => (v >= 0.6 * strongest && edge.slice(Math.max(0, y - 6), y + 7).every((u, k) => u < v || (u === v && Math.max(0, y - 6) + k >= y)) ? [y] : []));
+  if (peaks.length < 3) return [];
+  const gaps = peaks.slice(1).map((y, i) => y - peaks[i]).sort((a, b) => a - b);
+  const usual = gaps[Math.floor(gaps.length / 2)];
+  if (usual < 8 || gaps.some((g) => g < 0.65 * usual || g > 1.5 * usual)) return [];
+  // The top step's lit edge is the stairs' own top when there is a whole step above the first edge found.
+  const cuts = [...(peaks[0] - box[1] >= 0.65 * usual ? [box[1]] : []), ...peaks, Math.min(box[3], peaks[peaks.length - 1] + usual)];
+  return cuts.slice(1).map((y1, i) => intersect(stairs, rectMask(W, H, [box[0], cuts[i], box[2], y1]))).filter((m) => maskArea(m) > 0);
+}
+
+/**
+ * The steps inside `stairs` (the walk-on things and floors named as stairs), top step first. Empty when
+ * SAM finds no clear run of steps there: the stairs then stay a ramp, as before.
+ */
+export async function findSteps(memo: Memo, placeKey: string, painting: Buffer, stairs: Mask, log: (line: string) => void): Promise<NonNullable<Geometry['steps']>> {
+  if (!maskArea(stairs)) return [];
+  const found = await samFind(memo, { label: `steps:${placeKey}`, image: painting, prompt: 'stair step' });
+  const region = dilate(stairs, 6);
+  const bands: Mask[] = [];
+  for (const f of found) {
+    const m = atFrame(f.mask);
+    const area = maskArea(m);
+    const inside = intersect(m, region);
+    const box = maskBox(inside);
+    // A step is a wide, flat band, mostly inside the stairs.
+    if (!box || maskArea(inside) < 0.6 * area || box[2] - box[0] < 1.5 * (box[3] - box[1])) continue;
+    bands.push(inside);
+  }
+  if (bands.length < 2) {
+    // SAM sees no single step on many painted stairs (a stack of cardboard boards, steps drawn in a few strokes):
+    // the treads' lit edges, row after row, split the stairs instead.
+    const lit = await treadBands(painting, stairs);
+    if (lit.length < 2) {
+      log(`stairs: ${bands.length} step(s) found, kept as a ramp`);
+      return [];
+    }
+    log(`stairs: SAM found ${bands.length} step(s); ${lit.length} read off the treads' painted edges`);
+    bands.length = 0;
+    bands.push(...lit);
+  }
+  const steps = bands.map(stepEdges).filter((s): s is NonNullable<typeof s> => !!s).map(mendStep);
+  const mid = (s: (typeof steps)[number]) => {
+    const tops = s.top.filter((t) => t >= 0);
+    return tops.reduce((a, b) => a + b, 0) / tops.length;
+  };
+  steps.sort((a, b) => mid(a) - mid(b));
+  log(`stairs: ${steps.length} steps`);
+  return steps;
+}

package/app/src/scene/status.ts

@@ -0,0 +1,32 @@
+// Recheck stored reports against the current scene without writing or calling a model.
+import fs from 'node:fs';
+import path from 'node:path';
+import { Geometry } from '../play/geometry.ts';
+import { withThingEdits } from '../world/files.ts';
+import { World, type Place } from '../world/schema.ts';
+import { verifyPlace, type BackdropNotes, type MaskNotes, type PlateNotes, type Verdict } from './verify.ts';
+import { Layout } from './layout.ts';
+import { paintingLayoutHash } from './paint-layout.ts';
+
+export function currentVerdict(worldDir: string, key: string, place?: Place): Verdict | null {
+  const dir = path.join(worldDir, 'places', key);
+  if (!fs.existsSync(path.join(dir, 'verify.json'))) return null;
+  let stored: Verdict | undefined;
+  try {
+    stored = JSON.parse(fs.readFileSync(path.join(dir, 'verify.json'), 'utf8')) as Verdict;
+    place ??= withThingEdits(World.parse(JSON.parse(fs.readFileSync(path.join(worldDir, 'world.json'), 'utf8'))), worldDir).places.find((p) => p.key === key);
+    if (!place) throw new Error(`no place ${key}`);
+    const read = (file: string) => JSON.parse(fs.readFileSync(path.join(dir, file), 'utf8'));
+    const optional = <T>(file: string) => (fs.existsSync(path.join(dir, file)) ? read(file) as T : {} as T);
+    if (!fs.existsSync(path.join(dir, 'photo.png')) && fs.existsSync(path.join(dir, 'painting-layout.json'))) {
+      const r = read('painting-layout.json') as { ok?: boolean; inputs?: string; attempts?: Array<{ issues: string[] }> };
+      if (!r.ok || r.inputs !== paintingLayoutHash(place, Layout.parse(read('layout.json')), fs.readFileSync(path.join(dir, 'blockin.png')), fs.readFileSync(path.join(dir, 'painting.png')))) {
+        return { ok: false, errors: [{ code: 'PAINT_LAYOUT_MISMATCH', detail: r.attempts?.at(-1)?.issues.join('; ') || 'Composition check is pending or stale: rebuild from paint.' }], flags: [] };
+      }
+    }
+    return verifyPlace(place, Geometry.parse(read('geometry.json')), read('masks.json') as MaskNotes, optional<PlateNotes>('plates.json'), optional<BackdropNotes>('backdrop.json'));
+  } catch {
+    if (stored?.ok === false) return stored;
+    return { ok: false, errors: [{ code: 'VERIFY_INPUTS', detail: 'Current geometry or mask data is missing or invalid: rebuild this place and verify it again.' }], flags: [] };
+  }
+}

package/app/src/scene/verify.ts

@@ -0,0 +1,156 @@
+// verify: checks a place's geometry before anyone walks it. An error means the place is not
+// playable as is; a flag is something a person should look at, listed in the build report.
+// Nothing is flagged and passed silently: every finding is in verify.json with a code.
+import type { Geometry } from '../play/geometry.ts';
+import { personPx } from '../play/geometry.ts';
+import type { Place } from '../world/schema.ts';
+import { Grid, reach, roomy } from './walk.ts';
+import { rectIou } from '../image/raster.ts';
+
+export type Finding = { code: string; key?: string; detail: string; /** Where the thing really is, when a check found it elsewhere. */ box?: [number, number, number, number] };
+export type Verdict = { ok: boolean; errors: Finding[]; flags: Finding[] };
+
+/** What masks.json says about each mask. */
+export type MaskNotes = {
+  things: Record<string, { coarse: boolean; source: string; check?: { ok: boolean; seen?: string; box?: [number, number, number, number] | null } }>;
+  floors: Record<string, { coarse: boolean; source: string; iouLayout: number }>;
+};
+
+export function gridOf(g: Pick<Geometry, 'walk' | 'zone'>): Grid {
+  const grid = new Grid(Math.max(...g.walk.map((r) => r.length)), g.walk.length);
+  g.walk.forEach((row, r) => [...row].forEach((ch, c) => {
+    const i = grid.at(c, r);
+    grid.open[i] = ch === '#' ? 1 : 0;
+    const z = g.zone?.[r]?.[c];
+    grid.zone[i] = z && z !== '.' ? Number(z) : -1;
+  }));
+  return grid;
+}
+
+/** plates.json: whether SAM still finds the thing on its plate. */
+export type PlateNotes = Record<string, { stillThere: boolean }>;
+
+/** backdrop.json: per card, whether its outline cuts through a painted part of its thing. */
+export type BackdropNotes = Record<string, { cut?: { px: number; box: [number, number, number, number] | null } }>;
+
+const words = (text: string) => text.toLowerCase().match(/[a-z]{3,}/g)?.map((w) => w.replace(/(es|s)$/, '')) ?? [];
+
+/** What a thing is, in a word or two: its key's words and the head noun of its looks ("a chestnut horse in its stall" -> horse). */
+function kindWords(key: string, looks = ''): Set<string> {
+  const head = looks.toLowerCase().split(/\b(?:with|in|on|of|at|by|that|which|under|over|near|beside)\b|[,;(]/)[0];
+  return new Set([...words(key.replace(/[-_]/g, ' ')), ...words(head).slice(-1)]);
+}
+
+/** Does Spark's word for what it sees name the same kind of thing? */
+export function sameKind(seen: string, key: string, looks?: string): boolean {
+  const kind = kindWords(key, looks);
+  // What Spark says is not there does not count: "the hull of a rowboat, no can in its mask" saw no can.
+  const said = seen.replace(/\b(?:no|not|without|nor|missing)\s+(?:a|an|the|any)?\s*[a-z-]+/gi, ' ');
+  return words(said).some((w) => kind.has(w));
+}
+
+export function verifyPlace(place: Place, g: Geometry, notes: MaskNotes, plates: PlateNotes = {}, backdrop: BackdropNotes = {}): Verdict {
+  const errors: Finding[] = [];
+  const flags: Finding[] = [];
+  const grid = gridOf(g);
+  const cells = roomy(grid);
+  const open = grid.count();
+  const cell = (x: number, y: number) => grid.cellOf(x, y);
+
+  if (open < 200) errors.push({ code: 'NO_FLOOR', detail: `only ${open} walkable cells` });
+  const start = cell(...g.start);
+  if (!cells[start]) errors.push({ code: 'START_BLOCKED', detail: `start (${g.start.join(', ')}) is not on open floor` });
+  const reached = reach(grid, start, cells);
+  // Thin fringes next to reached floor are fine; a whole patch out of reach is not.
+  const cut = [...cells.keys()].filter((i) => cells[i] && !reached[i]).length;
+  if (cut >= 20) errors.push({ code: 'UNREACHABLE', detail: `${cut} walkable cells can't be reached from the start` });
+
+  // Every floor that has cells is reachable.
+  const zones = new Set<number>();
+  grid.zone.forEach((z, i) => grid.open[i] && z >= 0 && zones.add(z));
+  for (const z of zones) {
+    const any = [...grid.zone.keys()].some((i) => grid.zone[i] === z && reached[i]);
+    if (!any) errors.push({ code: 'FLOOR_UNREACHABLE', key: String(z), detail: `floor ${z} has walkable cells but none reachable` });
+  }
+
+  for (const thing of place.things) {
+    const t = g.things.find((x) => x.key === thing.key);
+    if (!t) {
+      errors.push({ code: 'THING_MISSING', key: thing.key, detail: 'not in geometry.json' });
+      continue;
+    }
+    if (thing.role !== 'npc' && !t.mask) errors.push({ code: 'MASK_MISSING', key: thing.key, detail: 'painted thing without a mask' });
+    const at = cell(...t.stand);
+    if (!reached[at]) {
+      const finding = { code: 'SPOT_UNREACHABLE', key: thing.key, detail: `its spot (${t.stand.map(Math.round).join(', ')}) can't be reached` };
+      // A prop can stay a thing to look at; exits, items and people must be usable.
+      (thing.role === 'prop' ? flags : errors).push(finding);
+    }
+    const check = notes.things[thing.key]?.check;
+    if (check && !check.ok) {
+      const seen = check.seen ?? 'something else';
+      // Spark points to where the thing really is, and it is where the mask is, and what it sees there is that kind
+      // of thing: a doubt about details ("but no long rays in its mask", when the painting has none), not a wrong
+      // mask. Brushing a disc of sky onto the mask to please it only gave the thing a round outline.
+      if (check.box && check.seen && rectIou(check.box, t.box) >= 0.6 && sameKind(check.seen, thing.key, thing.looks)) flags.push({ code: 'MASK_DOUBT', key: thing.key, detail: `Spark sees ${seen} in its mask, where the mask is` });
+      // Spark points to where the thing really is: the mask is wrong for sure, whatever the thing's role.
+      else if (check.box) errors.push({ code: 'MASK_WRONG', key: thing.key, detail: `Spark sees ${seen} in its mask; it is at [${check.box.join(', ')}]`, box: check.box });
+      // Spark sees no such thing anywhere, and what it sees is not even the same kind of thing: it was never
+      // painted. A doubt about details ("a bronze bell" for "a small brass bell") stays a flag to look at.
+      else if (check.seen && !sameKind(check.seen, thing.key, thing.looks)) errors.push({ code: 'THING_NOT_PAINTED', key: thing.key, detail: `Spark sees ${seen} where it should be, and no ${thing.key} anywhere` });
+      else flags.push({ code: 'MASK_DOUBT', key: thing.key, detail: `Spark sees ${seen} in its mask` });
+    }
+    if (notes.things[thing.key]?.source === 'colour-cut') flags.push({ code: 'COLOUR_CUT', key: thing.key, detail: 'SAM missed it; its mask was cut out of its box by colour' });
+    if (notes.things[thing.key]?.source === 'sketch-colour') flags.push({ code: 'COLOUR_CUT', key: thing.key, detail: 'SAM missed it; its mask is the pixels of its sketch colour in its box' });
+    if (t.coarse && thing.role !== 'npc') flags.push({ code: 'COARSE_MASK', key: thing.key, detail: `mask is a ${notes.things[thing.key]?.source ?? 'box'}, so it hides no one` });
+  }
+
+  // A floor painted nowhere near its layout that the hero cannot walk on at all: the painting left the plan (stairs
+  // or a trail drawn somewhere else, or not drawn as floor), and whatever exit leads off it is only a click at an edge.
+  Object.entries(notes.floors).forEach(([key, f], z) => {
+    if (!g.zone || f.coarse || f.iouLayout >= 0.05) return;
+    if ([...grid.zone.keys()].some((i) => grid.zone[i] === z && reached[i])) return;
+    // When every exit, item and person can still be reached, the lost floor costs the game nothing (a boat's deck
+    // the hero never needs to step into): a flag to look at, not a reason the place cannot be played.
+    const needed = g.things.filter((t) => t.role === 'exit' || t.role === 'item' || t.role === 'npc');
+    const spare = needed.length > 0 && needed.every((t) => reached[cell(...t.stand)]);
+    (spare ? flags : errors).push({ code: 'FLOOR_LOST', key, detail: `painted floor overlaps its layout only ${f.iouLayout.toFixed(2)} and none of it can be walked on${spare ? '; every exit, item and person is reached without it' : ''}` });
+  });
+  for (const [key, f] of Object.entries(notes.floors)) {
+    if (f.coarse) flags.push({ code: 'FLOOR_COARSE', key, detail: `floor taken from ${f.source}` });
+    else if (f.iouLayout < 0.3) flags.push({ code: 'FLOOR_MOVED', key, detail: `painted floor overlaps its layout only ${f.iouLayout.toFixed(2)} (the painting wins)` });
+  }
+
+  // Scale: the horizon above every floor, the hero neither a dot at the back nor a giant at the front.
+  const rows = g.walk.map((row, r) => (row.includes('#') ? r : -1)).filter((r) => r >= 0);
+  if (rows.length) {
+    const topY = rows[0] * g.cell;
+    const bottomY = (rows[rows.length - 1] + 1) * g.cell;
+    if (g.scale.horizonY >= topY) errors.push({ code: 'HORIZON_LOW', detail: `horizon ${g.scale.horizonY} is not above the floor top ${topY}` });
+    const near = personPx(g, bottomY);
+    const far = personPx(g, topY + g.cell);
+    if (near < 60 || near > 760) errors.push({ code: 'SCALE_NEAR', detail: `a person at the front is ${Math.round(near)} px tall` });
+    if (far < 14) errors.push({ code: 'SCALE_FAR', detail: `a person at the back is ${Math.round(far)} px tall` });
+    if (g.scale.source !== 'spark') flags.push({ code: 'SCALE_FALLBACK', detail: `scale from ${g.scale.source}` });
+    // Where his head would leave the frame.
+    let clipped = 0;
+    grid.open.forEach((v, i) => {
+      if (!v) return;
+      const [, y] = grid.centre(i);
+      if (y - personPx(g, y) < -0.3 * personPx(g, y)) clipped++;
+    });
+    if (clipped > 0.05 * open) flags.push({ code: 'HEAD_OFF_FRAME', detail: `${clipped} cells put over 30% of the hero above the frame` });
+  }
+
+  for (const [key, p] of Object.entries(plates)) {
+    if (p.stillThere) flags.push({ code: 'PLATE_NOT_CLEAN', key, detail: 'SAM still finds it on its plate; taking it may leave it painted' });
+  }
+
+  // With parallax a card slides against the backdrop: a part its mask left out stays behind and splits off.
+  for (const [key, b] of Object.entries(backdrop)) {
+    if (b.cut) flags.push({ code: 'CARD_CUT', key, detail: `its mask leaves out a painted part of it (${b.cut.px} px of its outline cut through it), which stays on the backdrop when the card slides; mask it again with a box around the whole thing`, ...(b.cut.box && { box: b.cut.box }) });
+  }
+
+  for (const line of g.flagged ?? []) flags.push({ code: 'DERIVE', detail: line });
+  return { ok: errors.length === 0, errors, flags };
+}