@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/scene/playbook.ts

@@ -0,0 +1,121 @@
+// What to do about each error a place can end a build with: the fixes to try, cheapest first, and the
+// step the place is rebuilt from after them. The build report and the agent's repair brief both read it,
+// so a failed gate says how to get past it instead of only that it failed.
+import type { Finding } from './verify.ts';
+
+export type Play = {
+  /** Where to look first. */
+  look: string;
+  /** Fix tools in the order to try them: each is a Studio action and keeps its fix in corrections.json. */
+  tools: string[];
+  /** Only when the tools did not help: it costs a model call or changes the place a lot. */
+  last?: string;
+};
+
+const FLOOR_GAP: Play = {
+  look: 'place_view: the red patches are floor the hero cannot reach; each yellow dashed gap names the cells to bridge and the things standing in it. '
+    + 'A red patch that is no floor at all (a wall, the sky, water) is taken back, not bridged: when corrections_get shows a brush stroke or added cells there, '
+    + 'corrections_clear that floor (or mask_brush erase over it); floor_cells remove does not undo a brush stroke, strokes are painted after the cells',
+  tools: [
+    'floor_cells: add the cells that bridge the gap (stairs, a gangway, a jetty edge)',
+    'mask_fix kind: a thing drawn over the join that people walk on becomes walk-on',
+    'mask_fix phrase: name the floor better for SAM ("wooden jetty planks")',
+  ],
+  last: 'repaint_region: paint steps or a plank across the gap (one Muse edit); when water or a drop parts the floors, or a standing thing is laid across the only way, the layout needs a floor that joins them or the thing moved (relayout and repaint: ask first)',
+};
+
+/** The camera stands too close: the hero would be taller than the frame at the front. */
+const CLOSE_UP: Play = {
+  look: 'place_status: the blue rulers on walk.png show how tall the hero is at the front; a DERIVE flag "too near the camera" counts the front cells shut for it',
+  tools: [
+    'run_step derive: shuts the front cells where the hero would be too tall; often enough on its own',
+    'floor_cells remove: floor cells at the very bottom edge that stretch the scale',
+  ],
+  last: 'relayout and repaint the place with the camera farther back (layout now refuses a close camera; ask first)',
+};
+
+export const PLAYBOOK: Record<string, Play> = {
+  PAINT_LAYOUT_MISMATCH: {
+    look: 'place_status.paintingLayout: measured composition problems; place_view layers blockin, first and painting compare the plan with the art',
+    tools: ['paint_retry: new take with the current plan, followed by composition checks and rebuilding this place'],
+    last: 'layout_fix: simplify the plan with concrete camera, floor joins and object-position guidance, then rebuild this place; allowed for an observed composition rejection',
+  },
+  FLOOR_UNREACHABLE: FLOOR_GAP,
+  UNREACHABLE: FLOOR_GAP,
+  NO_FLOOR: {
+    look: 'place_status: the floors list says how each floor mask was found; walk.png shows what is walkable',
+    tools: ['mask_fix phrase: a better name for the floor', 'floor_cells: add the cells people walk on'],
+    last: 'repaint_region: make the floor read as floor (one Muse edit)',
+  },
+  START_BLOCKED: {
+    look: 'place_view: the start (green dot) sits off the green floor',
+    tools: ['floor_cells: open the cells under the start', 'mask_brush: erase the thing mask that covers the start'],
+  },
+  SPOT_UNREACHABLE: {
+    look: 'place_view: the spot is a red dot, with a dashed line to the nearest reachable point',
+    tools: ['stand_set: a spot on reachable floor next to the thing', 'mask_fix box: the box where the thing really is'],
+  },
+  MASK_MISSING: {
+    look: 'place_status: the thing has no mask; masks/overlay.png shows what SAM found',
+    tools: ['mask_fix phrase: a name SAM can find', 'mask_fix box: the box where it is', 'mask_brush: paint its mask'],
+    last: 'repaint_region: make the thing visible (one Muse edit)',
+  },
+  MASK_WRONG: {
+    look: 'place_view layer masks: the thing\'s mask against the box it should be in; the error gives the box where Spark sees the thing',
+    tools: ['mask_fix box: the box from the error (or the one you see)', 'mask_fix phrase: a name SAM tells apart from its neighbour'],
+    last: 'repaint_region: when the thing is not painted at all (one Muse edit)',
+  },
+  CARD_CUT: {
+    look: 'place_view layer masks: the thing\'s mask leaves out a part of it (what is in or on it: fish over a bucket\'s rim, a lamp on its post); the flag\'s box is where its outline cuts through that part',
+    tools: ['mask_fix box: a box around the whole thing with the part; masks asks SAM by that box and joins what it finds to the mask, then derive and backdrop follow', 'mask_brush: paint the part onto its mask'],
+  },
+  THING_NOT_PAINTED: {
+    look: 'place_view layer painting: the thing\'s box shows something else, and Spark found the thing nowhere in the painting',
+    tools: ['mask_fix box: when you do see it painted somewhere else'],
+    last: 'repaint_region: paint the thing in at its box with its looks (one Muse edit), then rebuild the place from masks; the build already tried this once at the layout box (corrections_get shows it), so look at where it landed first',
+  },
+  FLOOR_LOST: {
+    look: 'place_view layer walk: the floor (stairs, a trail) is painted somewhere else than the layout put it, or not as floor at all, so nothing on it can be walked to; the build already asked for one new take of the painting',
+    tools: ['floor_cells add: the cells where the floor is painted, when it is painted as floor somewhere', 'mask_fix phrase: a name SAM finds the painted floor by'],
+    last: 'paint with a new take (run_step paint --take N for the place), then rebuild the place from masks',
+  },
+  THING_MISSING: {
+    look: 'world_status: the place lost the thing between layout and derive',
+    tools: ['run_step masks, then derive, for the world'],
+  },
+  HORIZON_LOW: {
+    look: 'place_status: walk.png draws the horizon as a dashed blue line and the hero as blue rulers',
+    tools: ['mask_fix phrase: the floor mask may reach into the sky', 'floor_cells remove: cells high up that are not floor'],
+  },
+  SCALE_NEAR: CLOSE_UP,
+  SCALE_FALLBACK: {
+    look: 'place_status: the DERIVE flags say why Spark gave no scale ("the asks failed": a hiccup; "N usable points": its answers did not fit); walk.png\'s blue rulers show how tall the hero is where',
+    tools: ['run_step derive with the place: Spark judges a person\'s height again (3 Spark calls), the walk floor and fixes stay'],
+  },
+  SCALE_FAR: {
+    look: 'place_status: the blue rulers on walk.png show how tall the hero is at the back',
+    tools: ['floor_cells remove: far floor cells near the horizon that no one should walk to'],
+  },
+  STEP_FAILED: {
+    look: 'job_wait or job_list: the last lines of the failed job say why the step broke',
+    tools: [
+      'layout_fix: when layout failed, save concrete camera, size or floor guidance and rebuild; works before any place files exist',
+      'job_retry: when it was a network or model hiccup (it starts at the step where the place broke)',
+      'paint_words: when paint was refused by the image safety filter (content_policy_violation) even after Spark reworded it: calm, plain words for the scene and the looks it names',
+      'PAINT_LAYOUT_MISMATCH: read place_status.paintingLayout and place_view layers blockin/first/painting; paint already tried a composition repair. Use paint_retry for a new take or layout_fix for a simpler connected plan; after 2 rejected plans in a row layout_fix waits for a paint_retry. Do not bridge displaced objects with floor_cells',
+      'the fix tool for what the error names, then rebuild the place',
+    ],
+  },
+};
+
+const NEAR_CAMERA = /too near the camera/;
+
+/**
+ * A finding with what to do about it, when the playbook knows. flags: the place's verify flags; a floor cut off
+ * right after derive shut the front rows for a close camera is a close-up, not a gap to bridge.
+ */
+export function withPlay(f: Finding, flags: Finding[] = []): Finding & { play?: Play } {
+  const closeUp = (f.code === 'UNREACHABLE' || f.code === 'FLOOR_UNREACHABLE') && flags.some((x) => x.code === 'DERIVE' && NEAR_CAMERA.test(x.detail));
+  const play = closeUp ? CLOSE_UP : PLAYBOOK[f.code];
+  return play ? { ...f, play } : f;
+}

package/app/src/scene/preview.ts

@@ -0,0 +1,23 @@
+// A drawing brought to life at once, while the children are still drawing: a character as the figure the game
+// will use (same prompt, same drawing, so cast finds it in the memo), a place or a thing as a quick painting.
+import sharp from 'sharp';
+import type { Memo } from '../meta/memo.ts';
+import { museEdit } from '../meta/muse.ts';
+import { KIDS_STYLE, type Drawn } from '../world/drawings.ts';
+import type { World } from '../world/schema.ts';
+import { paintFigure } from './cast.ts';
+import { FRAME } from './layout.ts';
+
+export async function previewDrawing(memo: Memo, drawn: Drawn, drawing: Buffer): Promise<Buffer> {
+  if (drawn.kind === 'hero' || drawn.kind === 'npc' || drawn.kind === 'player') {
+    const { figure } = await paintFigure(memo, { style: KIDS_STYLE } as World, { key: drawn.key, looks: drawn.looks }, 0, { drawing });
+    return figure;
+  }
+  const prompt = drawn.kind === 'place'
+    ? `This is a child's drawing on paper of a place. Paint it as a finished background of a 2D adventure game, so the child knows it at once: the same things where they drew them, their colours and shapes, only whole and alive, with depth and light. No paper, no table, no written names, no people, no text.\n\nPlace: ${drawn.looks}\nStyle: ${KIDS_STYLE}`
+    : `This is a child's drawing on paper. Paint the thing in it alone, whole and centred on a plain pale background, as the child drew it: the same colours and shapes, only cleaner and alive. No paper, no table, no written names, no text.\n\nThing: ${drawn.looks}\nStyle: ${KIDS_STYLE}`;
+  const painted = await museEdit(memo, { label: `preview:${drawn.key}`, prompt, images: [drawing] });
+  return drawn.kind === 'place'
+    ? sharp(painted).resize(FRAME.width, FRAME.height, { fit: 'fill' }).png().toBuffer()
+    : sharp(painted).resize(900, 900, { fit: 'inside' }).png().toBuffer();
+}

package/app/src/scene/reactions.ts

@@ -0,0 +1,118 @@
+// One vision-language plan per place. Bind proposals to reachable walk cells and exact story actions.
+import { z } from 'zod';
+import { Burst, Reactions } from '../play/reactions.ts';
+import { When, type Story } from '../story/schema.ts';
+import type { Geometry } from '../play/geometry.ts';
+import type { Layout } from './layout.ts';
+import type { Place, World } from '../world/schema.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { inputHash, type Memo } from '../meta/memo.ts';
+import { gridOf } from './verify.ts';
+import { reach } from './walk.ts';
+
+const XY = z.tuple([z.number(), z.number()]);
+export const ReactionPlan = z.object({
+  scene: z.string().min(1),
+  areas: z.array(z.object({
+    key: z.string().min(1), floor: z.string(),
+    polygon: z.array(XY).min(3).max(12).optional(),
+    step: Burst.optional(), enter: Burst.optional(), when: When,
+    once: z.boolean().default(false), cooldown: z.number().min(0.2).max(30).default(1.5),
+  })).max(8),
+  interactions: z.array(z.object({
+    key: z.string(), interaction: z.number().int().nonnegative(),
+    at: z.tuple([z.number().min(0).max(1), z.number().min(0).max(1)]),
+    burst: Burst, cooldown: z.number().min(0.2).max(30).default(1),
+  })).max(12),
+});
+export type ReactionPlan = z.infer<typeof ReactionPlan>;
+export type ReactionInput = { world: World; place: Place; layout: Layout; geometry: Geometry; story: Story | null; weather?: unknown; hint?: string; painting: Buffer };
+export function reactionSource(i: ReactionInput): string {
+  return inputHash('reactions-planner-2', JSON.stringify({ style: i.world.style, place: i.place, layout: i.layout, geometry: i.geometry, story: i.story, weather: i.weather, hint: i.hint }), i.painting);
+}
+function contains(p: number[][], x: number, y: number) {
+  let inside = false;
+  for (let i = 0, j = p.length - 1; i < p.length; j = i++) {
+    const [a, b] = p[i], [c, d] = p[j];
+    if ((b > y) !== (d > y) && x < (c - a) * (y - b) / (d - b) + a) inside = !inside;
+  }
+  return inside;
+}
+export function bindReactions(plan: ReactionPlan, input: ReactionInput): Reactions {
+  const { geometry: g, layout, story, place } = input;
+  const grid = gridOf(g);
+  const cellOf = (x: number, y: number) => grid.at(Math.floor(x / g.cell), Math.floor(y / g.cell));
+  const reachable = reach(grid, cellOf(...g.start));
+  const seen = new Set<string>();
+  const key = (k: string) => { if (seen.has(k)) throw new Error(`duplicate reaction key ${k}`); seen.add(k); };
+  const facts = new Set(story?.interactions.flatMap((it) => it.do.flatMap((e) => 'set' in e ? [e.set] : [])) ?? []);
+  for (const d of story?.dialogues ?? []) for (const l of d.lines) for (const c of l.choices) for (const e of c.do) if ('set' in e) facts.add(e.set);
+  const areas = plan.areas.map((a) => {
+    key(a.key);
+    if (!a.step && !a.enter) throw new Error(`${a.key}: needs step or enter`);
+    for (const f of a.when) {
+      const fact = f.replace(/^!/, '');
+      if (!(fact.startsWith('has:') ? story?.items.some((i) => i.key === fact.slice(4)) : fact.startsWith('at:') ? input.world.places.some((p) => p.key === fact.slice(3)) : facts.has(fact))) throw new Error(`${a.key}: unknown condition ${f}`);
+    }
+    const floor = layout.floors.findIndex((f) => f.key === a.floor);
+    if (floor < 0) throw new Error(`${a.key}: unknown floor ${a.floor}`);
+    if (a.polygon?.some(([x, y]) => x < 0 || y < 0 || x > g.frame.width || y > g.frame.height)) throw new Error(`${a.key}: polygon outside painting`);
+    const cells = g.walk.map((row, r) => [...row].map((ch, c) => ch === '#' && reachable[grid.at(c, r)] && g.zone?.[r]?.[c] === String(floor) && (!a.polygon || contains(a.polygon, (c + .5) * g.cell, (r + .5) * g.cell)) ? '#' : '.').join(''));
+    if (!cells.some((row) => row.includes('#'))) throw new Error(`${a.key}: no reachable cells on ${a.floor}`);
+    const { floor: _, polygon: __, ...rule } = a;
+    return { ...rule, cells };
+  });
+  // Two step recipes in one cell double every footstep; local patches must partition the floor.
+  const steps = new Set<number>();
+  for (const a of areas.filter((a) => a.step)) a.cells.forEach((row, r) => [...row].forEach((v, c) => {
+    if (v !== '#') return;
+    const i = grid.at(c, r);
+    if (steps.has(i)) throw new Error('step areas overlap: partition the polygons or use one recipe per floor');
+    steps.add(i);
+  }));
+  const assigned = new Set<number>();
+  const interactions = plan.interactions.map((r) => {
+    key(r.key);
+    if (assigned.has(r.interaction)) throw new Error(`${r.key}: duplicate interaction recipe`);
+    assigned.add(r.interaction);
+    const it = story?.interactions[r.interaction];
+    if (!it || it.place !== place.key || !['use', 'take'].includes(it.verb)) throw new Error(`${r.key}: interaction must be a use or take in this place`);
+    const thing = g.things.find((t) => t.key === it.thing);
+    if (!thing || !reachable[cellOf(...thing.stand)]) throw new Error(`${r.key}: no reachable target ${it.thing}`);
+    const { interaction: _, ...rule } = r;
+    return { ...rule, thing: it.thing, action: JSON.stringify(it) };
+  });
+  return Reactions.parse({ version: 1, source: reactionSource(input), scene: plan.scene, areas, interactions });
+}
+
+export async function planReactions(memo: Memo, input: ReactionInput): Promise<{ plan: ReactionPlan; reactions: Reactions }> {
+  const { world, place, layout, geometry: g, story } = input;
+  const actions = story?.interactions.flatMap((it, index) => it.place === place.key && ['use', 'take'].includes(it.verb) ? [{ index, ...it }] : []) ?? [];
+  const prompt = `Plan subtle physical reactions for this painted point-and-click scene. Return JSON only.
+Style: ${world.style}
+Place: ${JSON.stringify(place)}
+Frame pixels: ${g.frame.width} x ${g.frame.height}. Floors, in zone order: ${JSON.stringify(layout.floors)}
+Actual objects and their boxes/stand points: ${JSON.stringify(g.things)}
+Weather: ${JSON.stringify(input.weather ?? {})}
+Available story interactions, with global indexes: ${JSON.stringify(actions)}
+Author's preference: ${input.hint ?? 'Choose restrained, natural effects automatically.'}
+
+Return {scene: short explanation of material, wetness and style choices, areas: [], interactions: []}.
+An area: {key, floor: exact floor key, polygon?: [[pixelX,pixelY],...], step?: burst, enter?: burst, when: [], once: false, cooldown: 1.5}.
+Omit polygon for the whole floor; use it only for a clearly visible local patch (leaves, snow, dust, puddle) and keep it on that floor. The compiler clips it to reachable floor cells. No overlapping step areas: use a single recipe per floor or non-overlapping polygons. Enter means crossing into an area, not spawning there; use it only where entry really stirs something, not as a second effect on every ordinary floor. Conditions use story facts (!flag, has:item); normally [].
+Look specifically for localized loose material on reachable ground, such as scattered straw near a hay cart, leaves beneath a tree, or a small puddle. When present, an enter-only polygon can add one small burst on crossing its boundary, with a cooldown. It may overlap a general step area. Do not place it on the solid cart/tree itself. Straw/chaff can use pale-gold leaves or dust. When there is no convincing patch, omit it.
+A burst: {kind: dust|splash|snow|leaves|sparks, colour: #rrggbb, strength: 0.1..1}. Prefer 0.25..0.5. Dry loose soil/sand/dust: dust. Wet floors/puddles: splash. Lying snow: snow. Visible loose leaves: leaves. Sparks only for actual fire/magic/metal impact supported by the story. Clean wood, clean stone, indoor tiles: no effect. Rain in the air alone does not prove a floor is wet. Do not invent dusty surfaces to fill the lists; empty lists are valid.
+An interaction: {key, interaction: global index above, at: [0..1,0..1] within that object's box, burst, cooldown: 1}.
+Choose only physical use/take actions: dust dislodged from a dusty object, droplets shaken off a wet object, leaves stirred from vegetation, a supported magical response. Never attach a reaction to a refusal, looking, conversation, or a failed prerequisite. Do not add generic success glitter to clean items. Match the actual action outcome and object material. No more than 8 areas and 12 interactions.`;
+  let problem = '';
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const plan = ReactionPlan.parse(await askSparkJson(memo, { schema: ReactionPlan, label: `reactions:${place.key}`, images: [input.painting], prompt: prompt + problem }));
+      return { plan, reactions: bindReactions(plan, input) };
+    } catch (e) {
+      if (attempt === 2) throw e;
+      problem = `\nCorrect the previous plan: ${e instanceof Error ? e.message : String(e)}. Use only the provided floors, objects and actions.`;
+    }
+  }
+  throw new Error('reaction planning failed');
+}

package/app/src/scene/restyle.ts

@@ -0,0 +1,53 @@
+// restyle: a place or a character painted in one style, repainted in another by one Muse edit that keeps
+// every outline where it is, so what was measured on the old picture still fits the new one.
+import sharp from 'sharp';
+import type { Memo } from '../meta/memo.ts';
+import { museEdit } from '../meta/muse.ts';
+import type { Place } from '../world/schema.ts';
+import type { Brief } from './brief.ts';
+import { FRAME } from './layout.ts';
+import type { Drawing } from './paint.ts';
+
+const KEEP = 'Keep the composition exactly: the camera, and every object, wall, door, floor and path where it is, at its size and in its shape, so an outline traced on the old picture still fits the new one. Only the medium changes: brushwork, rendering, palette and how light and shadow are painted.';
+/** Muse keeps too much of the old look by itself (a cartoon keeps its black outlines under oil paint): say what goes. */
+const CHANGE = 'It must look truly painted in the new style, not the old picture with a filter over it: whatever the old style has and the new one does not (black outlines, flat fills, cel shading) goes, and the forms are painted the new way.';
+
+export function restylePlacePrompt(place: Place, was: string, style: string, brief?: Brief, drawings: Drawing[] = []): string {
+  const looks = place.things.filter((t) => t.role !== 'npc').map((t) => `- ${t.key}: ${brief?.looks[t.key] ?? t.looks}`);
+  const which = drawings.map((d, i) => `image ${i + 2} is ${d.key === place.key ? 'this place' : `the ${d.key}`}`);
+  return `Repaint this background of a 2D point-and-click adventure game in a new style. ${KEEP}
+
+It is painted now as: ${was}
+Paint it as: ${style}
+${CHANGE}
+
+Place: ${place.shows}
+Mood: ${place.mood}
+Things to keep recognisable, each where it is:
+${looks.join('\n')}
+
+Keep the floor clear to walk on. No people, no animals, no text or letters, no border.${which.length ? `
+
+The other images are children's drawings on paper the game was made from: ${which.join(', ')}. Keep what they drew recognisable in the new style: their colours, shapes and ideas. The composition comes only from the first image; leave out the paper and any written names.` : ''}`;
+}
+
+/** The place's painting in the new style, at the layout frame. */
+export async function restylePlace(memo: Memo, place: Place, painting: Buffer, was: string, style: string, brief?: Brief, take = 0, drawings: Drawing[] = []): Promise<Buffer> {
+  const prompt = restylePlacePrompt(place, was, style, brief, drawings);
+  // Muse traces crisp lines it is given, so a cartoon kept its black outlines under the oil paint: it gets the
+  // painting a little soft, which keeps every shape where it is and leaves the edges for the new style to paint.
+  const soft = await sharp(painting).blur(2.5).png().toBuffer();
+  const painted = await museEdit(memo, { label: `restyle:${place.key}`, prompt, images: [soft, ...drawings.map((d) => d.image)], take });
+  return sharp(painted).resize(FRAME.width, FRAME.height, { fit: 'fill' }).png().toBuffer();
+}
+
+export function restyleFigurePrompt(looks: string, was: string, style: string, drawn: boolean): string {
+  return `Repaint this character of a 2D point-and-click adventure game in a new style. Keep the same character: face, hair, clothes, colours, body proportions and the exact pose, at the same place and size in the frame, so the outline matches the picture. Show the whole figure from head to feet. Only the medium changes.
+
+Character: ${looks}
+It is painted now as: ${was}
+Paint it as: ${style}
+${CHANGE}
+${drawn ? '\nThe second image is the child\'s drawing the character came from: keep it recognisable to them in the new style, its colours, shapes and proportions.\n' : ''}
+Plain flat light grey background, no floor, no shadow, no other people, no text.`;
+}

package/app/src/scene/rig-check.ts

@@ -0,0 +1,68 @@
+// Judges a walk sheet: a walk that tears open (holes in a coat, a boot floating free, an arm off the shoulder) is
+// marked, and the runtime slides the painted figure as one piece instead.
+import sharp from 'sharp';
+import { emptyMask, maskArea, type Mask } from '../image/mask.ts';
+import { components } from '../image/raster.ts';
+import type { Rig } from '../play/rig.ts';
+
+type Raw = { width: number; height: number; data: Buffer };
+
+const opaque = (r: Raw, min = 128): Mask => {
+  const m = emptyMask(r.width, r.height);
+  for (let i = 0; i < m.bits.length; i++) m.bits[i] = r.data[i * 4 + 3] >= min ? 1 : 0;
+  return m;
+};
+
+/** See-through pixels the figure closes round: background pieces that do not reach the picture's edge. */
+function holes(fig: Mask): number {
+  const bg = emptyMask(fig.width, fig.height);
+  fig.bits.forEach((b, i) => (bg.bits[i] = b ? 0 : 1));
+  let n = 0;
+  for (const c of components(bg)) {
+    let edge = false;
+    for (let i = 0; i < c.bits.length && !edge; i++) {
+      if (!c.bits[i]) continue;
+      const x = i % c.width;
+      const y = Math.floor(i / c.width);
+      edge = x === 0 || y === 0 || x === c.width - 1 || y === c.height - 1;
+    }
+    if (!edge) n += maskArea(c);
+  }
+  return n;
+}
+
+export type RigCheck = {
+  ok: boolean;
+  /** Worst walk frame: see-through holes, and pixels in pieces cut off from the body, as shares of the figure. */
+  holes: number;
+  loose: number;
+  /** Why it fails, in a few words. */
+  why?: string;
+};
+
+/** Holes above this share of the figure, or loose pieces above LOOSE, and the walk is torn. */
+export const HOLES = 0.004;
+export const LOOSE = 0.002;
+
+
+
+/** The same measure on a walk sheet (src/scene/warp.ts): holes and loose pieces in each walk cell. */
+export async function checkSheet(rig: Rig, png: Buffer): Promise<RigCheck> {
+  const sheet = rig.sheet!;
+  const [cw, ch] = sheet.cell;
+  let worstHoles = 0;
+  let worstLoose = 0;
+  const cell = async (f: number) => opaque({ width: cw, height: ch, data: (await sharp(png).extract({ left: (f % sheet.cols) * cw, top: Math.floor(f / sheet.cols) * ch, width: cw, height: ch }).raw().toBuffer()) });
+  // Gaps the painting itself closes round (a hand on the hip) are not tears: only what the walk opens counts.
+  const painted = holes(await cell(sheet.frames));
+  for (let f = 0; f < sheet.frames; f++) {
+    const fig = await cell(f);
+    const area = maskArea(fig) || 1;
+    // Specks of a few pixels (a stray hair) do not count as a loose part.
+    const loose = components(fig).slice(1).reduce((s, c) => s + (maskArea(c) > area * 0.0005 ? maskArea(c) : 0), 0);
+    worstHoles = Math.max(worstHoles, Math.max(0, holes(fig) - painted) / area);
+    worstLoose = Math.max(worstLoose, loose / area);
+  }
+  const why = [worstHoles > HOLES && `opens holes (${(worstHoles * 100).toFixed(1)}% of the figure)`, worstLoose > LOOSE && `parts come loose (${(worstLoose * 100).toFixed(1)}%)`].filter(Boolean).join(', ');
+  return { ok: !why, holes: Math.round(worstHoles * 1e4) / 1e4, loose: Math.round(worstLoose * 1e4) / 1e4, ...(why && { why }) };
+}