@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/scene/carry.ts

@@ -0,0 +1,177 @@
+// carry: after a small repaint, what the repaint did not reach keeps what was measured on it.
+// Each place step keeps the painting it last ran on (places/<p>/.ran/<step>.png). On the next run the painting
+// is compared with it, tile by tile. A question whose region no changed tile reaches is asked about the old
+// painting again, which the memo answers with the old answer for nothing; only what the change reaches goes
+// to the models. A big change (a new painting) carries nothing, and the step runs as before.
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import type { Mask } from '../image/mask.ts';
+import type { Rect } from '../image/raster.ts';
+import { FRAME } from './layout.ts';
+
+const { width: W, height: H } = FRAME;
+/** Tiles of the comparison: a changed pixel marks its whole tile. */
+const TILE = 24;
+/** A pixel changed when a channel moved more than this: a repaint pastes exactly, untouched pixels match, and a feathered edge is part of the change. */
+const NOISE = 0;
+/** Past this share of the frame the painting is taken as new: nothing is carried. */
+export const MOST = 0.35;
+
+export type Carry = {
+  /** The painting the step last ran on. */
+  old: Buffer;
+  /** The changed tiles, as rects. */
+  tiles: Rect[];
+  /** The share of the frame they cover. */
+  share: number;
+};
+
+const rgb = (png: Buffer) => sharp(png).resize(W, H, { fit: 'fill' }).removeAlpha().raw().toBuffer();
+
+/** The tiles where `b` differs from `a`. */
+export async function changedTiles(a: Buffer, b: Buffer): Promise<Rect[]> {
+  const [pa, pb] = await Promise.all([rgb(a), rgb(b)]);
+  const tiles: Rect[] = [];
+  for (let ty = 0; ty < H; ty += TILE) {
+    for (let tx = 0; tx < W; tx += TILE) {
+      let hit = false;
+      for (let y = ty; y < Math.min(H, ty + TILE) && !hit; y++) {
+        for (let x = tx, i = (y * W + tx) * 3; x < Math.min(W, tx + TILE); x++, i += 3) {
+          if (Math.abs(pa[i] - pb[i]) > NOISE || Math.abs(pa[i + 1] - pb[i + 1]) > NOISE || Math.abs(pa[i + 2] - pb[i + 2]) > NOISE) {
+            hit = true;
+            break;
+          }
+        }
+      }
+      if (hit) tiles.push([tx, ty, Math.min(W, tx + TILE), Math.min(H, ty + TILE)]);
+    }
+  }
+  return tiles;
+}
+
+const ranFile = (dir: string, step: string) => path.join(dir, '.ran', `${step}.png`);
+
+/** What `step` can carry over from its last run in this place, or nothing (first run, same painting, a new painting). */
+export async function carryFrom(dir: string, step: string, painting: Buffer): Promise<Carry | undefined> {
+  const file = ranFile(dir, step);
+  if (!fs.existsSync(file)) return undefined;
+  return carryBetween(fs.readFileSync(file), painting);
+}
+
+/** What can be carried from `old` to `now`, any two pictures of the place (two backdrops), or nothing. */
+export async function carryBetween(old: Buffer, now: Buffer): Promise<Carry | undefined> {
+  // The same picture: the memo answers every question as it is.
+  if (old.equals(now)) return undefined;
+  const tiles = await changedTiles(old, now);
+  const share = tiles.reduce((s, [x0, y0, x1, y1]) => s + (x1 - x0) * (y1 - y0), 0) / (W * H);
+  return share > MOST ? undefined : { old, tiles, share };
+}
+
+/** Keeps the painting `step` ran on in this place. Steps that ran on the same painting share one file. */
+export function ran(dir: string, step: string, painting: Buffer) {
+  const file = ranFile(dir, step);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const twin = fs.readdirSync(path.dirname(file)).map((f) => path.join(path.dirname(file), f))
+    .find((f) => f !== file && f.endsWith('.png') && fs.statSync(f).size === painting.length && fs.readFileSync(f).equals(painting));
+  fs.rmSync(file, { force: true });
+  if (twin) {
+    try {
+      fs.linkSync(twin, file);
+      return;
+    } catch {
+      // No hard links here: a copy will do.
+    }
+  }
+  fs.writeFileSync(file, painting);
+}
+
+/** What each place step leaves. */
+const MADE: Record<string, string> = { masks: 'masks.json', plates: 'plates.json', derive: 'geometry.json', backdrop: 'backdrop.png' };
+
+/**
+ * For a place whose steps have not kept their painting (built before .ran/, or put back by an Undo that predates it):
+ * each step that left its output takes the painting on disk as the one it ran on. File times say nothing here (an
+ * Undo writes every file anew), and they need not: the carried questions are asked about this painting, a real one,
+ * so the worst a wrong guess costs is the model calls it would have cost anyway. Called before a repaint replaces it.
+ */
+export function seedRan(dir: string): string[] {
+  const file = path.join(dir, 'painting.png');
+  if (!fs.existsSync(file)) return [];
+  let painting: Buffer | undefined;
+  const seeded: string[] = [];
+  for (const [step, made] of Object.entries(MADE)) {
+    if (fs.existsSync(ranFile(dir, step)) || !fs.existsSync(path.join(dir, made))) continue;
+    ran(dir, step, (painting ??= fs.readFileSync(file)));
+    seeded.push(step);
+  }
+  // The far flats and the water were cut from the backdrop on disk.
+  if (fs.existsSync(ranFile(dir, 'backdrop')) && !fs.existsSync(ranFile(dir, 'backdrop-made')) && fs.existsSync(path.join(dir, 'backdrop.png'))) {
+    ran(dir, 'backdrop-made', fs.readFileSync(path.join(dir, 'backdrop.png')));
+  }
+  return seeded;
+}
+
+/** Whether the change reaches a region (a mask, a box, or several), grown by `margin` px. No region is never reached. */
+export function reaches(carry: Carry, region: Mask | Rect | Array<Mask | Rect | undefined> | undefined, margin = 16): boolean {
+  if (!region) return false;
+  if (Array.isArray(region) && (region.length === 0 || typeof region[0] !== 'number')) return (region as Array<Mask | Rect | undefined>).some((r) => reaches(carry, r, margin));
+  for (const [tx0, ty0, tx1, ty1] of carry.tiles) {
+    const [x0, y0, x1, y1] = [Math.max(0, tx0 - margin), Math.max(0, ty0 - margin), Math.min(W, tx1 + margin), Math.min(H, ty1 + margin)];
+    if (Array.isArray(region)) {
+      const [rx0, ry0, rx1, ry1] = region as Rect;
+      if (rx0 < x1 && rx1 > x0 && ry0 < y1 && ry1 > y0) return true;
+      continue;
+    }
+    const m = region as Mask;
+    for (let y = y0; y < y1; y++) {
+      for (let x = x0, i = y * m.width + x0; x < x1; x++, i++) if (m.bits[i]) return true;
+    }
+  }
+  return false;
+}
+
+/** A thing or floor this big (px) is masked again only when the change covers a good part of it. */
+const BIG = 20_000;
+const GRAZE = 0.3;
+
+/**
+ * Whether a repaint changes a mask's outline: it lies on the changed tiles (grown by 8 px), and it is small or a good
+ * part of it changed. A thermos repainted on a jetty changes the thermos, not where the jetty is.
+ */
+export function remakes(carry: Carry, mask: Mask): boolean {
+  let total = 0;
+  for (let i = 0; i < mask.bits.length; i++) total += mask.bits[i];
+  let on = 0;
+  const seen = new Uint8Array(mask.bits.length);
+  for (const [tx0, ty0, tx1, ty1] of carry.tiles) {
+    for (let y = Math.max(0, ty0 - 8); y < Math.min(mask.height, ty1 + 8); y++) {
+      for (let x = Math.max(0, tx0 - 8), i = y * mask.width + x; x < Math.min(mask.width, tx1 + 8); x++, i++) {
+        if (mask.bits[i] && !seen[i]) (seen[i] = 1, on++);
+      }
+    }
+  }
+  return on > 0 && (total < BIG || on / total > GRAZE);
+}
+
+/** The painting to ask a question about a region with: the old one when the change does not reach the region. */
+export function paintingFor(carry: Carry | undefined, painting: Buffer, region: Parameters<typeof reaches>[1], margin?: number): Buffer {
+  return carry && !reaches(carry, region, margin) ? carry.old : painting;
+}
+
+/** `made` (built from the old painting) with the changed tiles taken from the new painting, except inside `keep`. */
+export async function withChange(made: Buffer, painting: Buffer, carry: Carry, keep?: Mask): Promise<Buffer> {
+  const [out, now] = await Promise.all([rgb(made), rgb(painting)]);
+  for (const [x0, y0, x1, y1] of carry.tiles) {
+    for (let y = y0; y < y1; y++) {
+      if (!keep) {
+        now.copy(out, (y * W + x0) * 3, (y * W + x0) * 3, (y * W + x1) * 3);
+        continue;
+      }
+      for (let x = x0, i = y * W + x0; x < x1; x++, i++) if (!keep.bits[i]) now.copy(out, i * 3, i * 3, i * 3 + 3);
+    }
+  }
+  return sharp(out, { raw: { width: W, height: H, channels: 3 } }).png().toBuffer();
+}
+
+export const tilesLine = (carry: Carry) => `${Math.round(carry.share * 100)}% of the painting changed (${carry.tiles.length} tiles)`;

package/app/src/scene/cast-fixes.ts

@@ -0,0 +1,33 @@
+// The person's fixes to the cast, kept in cast/fixes.json and applied by every rebuild: how a character
+// looks (cast, model, sprites paint from it), which take to keep, and which voice speaks their lines.
+import fs from 'node:fs';
+import { z } from 'zod';
+import type { WorldFiles } from '../world/files.ts';
+
+export const CastFixes = z.record(z.string(), z.object({
+  looks: z.string().min(10).optional(),
+  /** What they hold, as short SAM phrases ("slice of toast"), kept on the cut-out whatever its size (cast_holds); [] keeps nothing. */
+  holds: z.array(z.string().min(2)).max(4).optional(),
+  take: z.number().int().min(0).optional(),
+  /** The person asked for a 3D model (cast_animate) though the story would not build one: the model step builds it every time. */
+  animate: z.boolean().optional(),
+  voice: z.object({ voice: z.string().min(1), design: z.string().min(10).optional(), why: z.string().default('chosen by the person'), stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional() }).optional(),
+  /** Rounds of walk and talk sheets asked for again (sprites_redo): each round paints new takes instead of the cached ones. */
+  spriteTake: z.number().int().min(0).optional(),
+  /** This character's own painting style over world.json's (style_set with scope cast). */
+  style: z.string().min(10).optional(),
+}));
+export type CastFixes = z.infer<typeof CastFixes>;
+
+export const castFixesFile = (files: WorldFiles) => files.path('cast', 'fixes.json');
+
+export function readCastFixes(files: WorldFiles): CastFixes {
+  const file = castFixesFile(files);
+  return fs.existsSync(file) ? CastFixes.parse(files.readJson(file)) : {};
+}
+
+/** A character with the person's description in place of the world's. */
+export function fixedLooks<T extends { key: string; looks: string }>(files: WorldFiles, who: T): T & { holds?: string[] } {
+  const { looks, holds } = readCastFixes(files)[who.key] ?? {};
+  return { ...who, ...(looks && { looks }), ...(holds && { holds }) };
+}

package/app/src/scene/cast.ts

@@ -0,0 +1,199 @@
+import { STYLE_REFERENCE_PROMPT } from '../world/style-reference.ts';
+// The hero and every NPC as one painted figure each: Muse paints them alone on a plain ground, SAM cuts them out.
+import sharp from 'sharp';
+import type { Mask } from '../image/mask.ts';
+import { maskBox, union } from '../image/raster.ts';
+import { bodyShare, groundGaps, heldMask, heldThings } from './held.ts';
+import { companions, silhouette } from './warp.ts';
+import type { Memo } from '../meta/memo.ts';
+import { museEdit, musePaint } from '../meta/muse.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { samFind } from '../meta/sam.ts';
+import type { World } from '../world/schema.ts';
+import { restyleFigurePrompt } from './restyle.ts';
+
+export const HERO_PX = 600;
+
+/** `holds`: what they hold, as SAM phrases, when the person named it (cast/fixes.json); else read from `looks`. */
+export type Who = { key: string; looks: string; holds?: string[] };
+
+export function figurePrompt(world: World, who: Who): string {
+  return `A single full-body character for a 2D point-and-click adventure game, standing in a relaxed walking-ready pose, seen from the side in three-quarter view, facing to the right. The whole figure is visible from the top of the head down to both feet, centred, about two thirds of the image tall.
+
+Character: ${who.looks}
+Style: ${world.style}
+
+Plain flat light grey background, no floor, no shadow, no other people, no props around, no text.`;
+}
+
+/** The biggest instance SAM finds of the hero, as an RGBA PNG cropped to the figure and HERO_PX tall. */
+export async function cutHero(painting: Buffer, mask: Mask, held?: Mask): Promise<Buffer> {
+  return (await cutOut(painting, mask, held)).figure;
+}
+
+/**
+ * The cut-out, and the share of its height the body takes (`share`, 1 unless something held stands above the head):
+ * `held` (scene/held.ts) is what SAM found of the things the description has in their hands, kept whatever its size.
+ */
+export async function cutOut(painting: Buffer, mask: Mask, held?: Mask): Promise<{ figure: Buffer; share: number }> {
+  if (!maskBox(mask)) throw new Error('figure: the mask is empty');
+  const { data, info } = await sharp(painting).resize(mask.width, mask.height, { fit: 'fill' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  // SAM's person leaves out what they hold (a lantern, a net of fish) and leaves holes where it hangs over them.
+  // ... and what floats beside them as part of who they are (a heart, the bubble they are in).
+  const body = held ? union(mask, held) : mask;
+  const whole = companions(data, silhouette(data, body));
+  // Held up in both hands, the thing closes a window of plain ground with the arms and head: it stays see-through.
+  if (held) for (const gap of groundGaps(data, whole, body)) gap.bits.forEach((b, i) => b && (whole.bits[i] = 0));
+  for (let i = 0; i < whole.bits.length; i++) if (!whole.bits[i]) data[i * info.channels + 3] = 0;
+  const [x0, y0, x1, y1] = maskBox(whole)!;
+  const figure = await sharp(data, { raw: { width: info.width, height: info.height, channels: 4 } })
+    .extract({ left: x0, top: y0, width: x1 - x0, height: y1 - y0 })
+    .resize({ height: HERO_PX })
+    .png()
+    .toBuffer();
+  return { figure, share: bodyShare(mask, whole) };
+}
+
+/** For a photo of a real person standing whole in frame: same person, same pose and outline, so live footage can dissolve into the figure. */
+export function photoPrompt(world: World): string {
+  return `Repaint this photo of a person as a character of a 2D point-and-click adventure game. Keep the same person, face, hair, clothes, body proportions and exact pose, at the same place and size in the frame, so the outline matches the photo. Show the whole figure from head to feet.
+
+Style: ${world.style}
+
+Plain flat light grey background, no floor, no shadow, no other people, no text.`;
+}
+
+/**
+ * For a photo of a person sitting, lying or cut off by the frame: the same person, standing. Their pose is not
+ * theirs to keep: a hero painted sitting against a headboard walks as a sitting cut-out, and the 3D model is
+ * built from that painting, headboard and all.
+ */
+export function photoStandPrompt(world: World, who: Who): string {
+  return `Paint the person in this photo as a single full-body character for a 2D point-and-click adventure game: the same person, so anyone who knows them sees it at once (same face, hair, beard, build and clothes), but standing upright on both feet in a relaxed walking-ready pose, seen from the side in three-quarter view, facing to the right. In the photo they may be sitting, lying or cut off by the frame; here the whole figure is visible from the top of the head down to both feet, centred, about two thirds of the image tall. What the photo does not show (legs, trousers, shoes) is as described: ${who.looks}
+
+Style: ${world.style}
+
+Nothing they sat or lay on: no bed, headboard, pillow, chair or blanket. Plain flat light grey background, no floor, no shadow, no other people, no props around, no text.`;
+}
+
+/** For a child's drawing: the character they drew, as they drew it, made whole enough to walk. */
+export function drawingPrompt(world: World, who: Who): string {
+  return `This is a child's drawing on paper. Paint the character in it as a single full-body character for a 2D point-and-click adventure game, so the child who drew it knows it at once: the same colours, the same clothes and features, the same shapes and proportions (a big head stays big), only cleaner and whole: every part coloured in solidly, with clear outlines and no white paper showing through, a finished character, not a sketch. Standing in a relaxed walking-ready pose, seen from the side in three-quarter view, facing to the right, the whole figure visible from the top of the head down to both feet (or paws), centred, about two thirds of the image tall.
+
+Character: ${who.looks}
+Style: ${world.style}
+
+Plain flat light grey background, no paper, no table, no written name, no floor, no shadow, no other characters, no text.`;
+}
+
+/**
+ * `from` is a photo of a real person (`standing`: whole and on their feet in it, so the pose is kept), or a child's
+ * drawing of the character; `restyle` is the character as painted before in another style (`was`), repainted in the
+ * world's style with the same face, clothes and pose. `upright` (a person on two legs, cast/figures.json): a figure
+ * that comes out sitting, lying or cut off is painted once more, as a seated painting makes a seated walker and a
+ * 3D model with the chair grown into it.
+ */
+export async function paintFigure(memo: Memo, world: World, who: Who, take = 0, from?: { photo?: Buffer; standing?: boolean; drawing?: Buffer; concept?: Buffer; styleReference?: Buffer; restyle?: { painting: Buffer; was: string } }, upright = false): Promise<{ painting: Buffer; figure: Buffer; share: number; holds: string[] }> {
+  const edit = (args: Parameters<typeof museEdit>[1]) => museEdit(memo, from?.styleReference ? {
+    ...args, prompt: args.prompt.replace('The LAST image is the creator-approved', 'The second-to-last image is the creator-approved') + '\nThe LAST image: ' + STYLE_REFERENCE_PROMPT,
+    images: [...args.images, from.styleReference],
+  } : args);
+  let fallback: { painting: Buffer; figure: Buffer; share: number; holds: string[]; why: string } | undefined;
+  const holds = await heldThings(memo, who);
+  // A take SAM finds no one in (a drawing painted back as loose scribble) is painted once more before giving up.
+  for (const t of [take, take + 1]) {
+    const painting = from?.restyle
+      ? await edit({ label: `figure:${who.key}:restyle`, prompt: restyleFigurePrompt(who.looks, from.restyle.was, world.style, !!from.drawing), images: [from.restyle.painting, ...(from.drawing ? [from.drawing] : [])], take: t })
+      : from?.concept
+      ? await edit({ label: `figure:${who.key}:approved`, prompt: (from.photo ? from.standing ? photoPrompt(world) : photoStandPrompt(world, who) : from.drawing ? drawingPrompt(world, who) : figurePrompt(world, who)) + '\nThe LAST image is the creator-approved character concept. Keep that identity: face, silhouette, proportions, clothing, markings and colours. Any earlier image is the original source drawing or photo: keep the person or drawn character recognizable. Adapt pose and background only as instructed above. The current written style and any explicit appearance edits take precedence over the old concept.', images: [...(from.photo ? [from.photo] : from.drawing ? [from.drawing] : []), from.concept], take: t })
+      : from?.photo
+      ? from.standing
+        ? await edit({ label: `figure:${who.key}:photo`, prompt: photoPrompt(world), images: [await sharp(from.photo).rotate().png().toBuffer()], take: t })
+        : await edit({ label: `figure:${who.key}:photo-stand`, prompt: photoStandPrompt(world, who), images: [await sharp(from.photo).rotate().png().toBuffer()], take: t })
+      : from?.drawing
+        ? await edit({ label: `figure:${who.key}:drawing`, prompt: drawingPrompt(world, who), images: [from.drawing], take: t })
+        : (from?.styleReference ? await edit({ label: `figure:${who.key}`, prompt: figurePrompt(world, who), images: [], take: t }) : await musePaint(memo, { label: `figure:${who.key}`, prompt: figurePrompt(world, who), take: t }));
+    const png = await sharp(painting).png().toBuffer();
+    // Not every character is a person (a flock of pigeons, a cat): SAM is asked by their own description next.
+    const biggest = await findFigure(memo, who, png);
+    if (!biggest) continue;
+    const made = { painting: png, ...(await cutOut(png, biggest.mask, await heldMask(memo, who.key, png, biggest.mask, holds))), holds };
+    const why = (await boxed(made.figure)) ?? (upright ? await notStanding(memo, who.key, made.figure, t) : undefined);
+    if (!why) return made;
+    console.log(`  ${who.key} take ${t}: the figure is not standing whole (${why}); painting it once more`);
+    fallback ??= { ...made, why };
+  }
+  if (fallback) {
+    console.log(`  ${who.key}: kept a figure that is not standing whole (${fallback.why}); try another take (cast_redo anotherTake)`);
+    return { painting: fallback.painting, figure: fallback.figure, share: fallback.share, holds };
+  }
+  throw new Error(`${who.key}: SAM found no one in the painting, two takes; try another take (cast_redo anotherTake)`);
+}
+
+/** The biggest one SAM finds of the character: as a person, else by its own description (a flock of pigeons, a cat), else as an animal. */
+export async function findFigure(memo: Memo, who: Who, png: Buffer) {
+  for (const prompt of ['person', who.looks.split(/[,.;]/)[0].trim().split(/\s+/).slice(0, 6).join(' '), 'animal']) {
+    const found = await samFind(memo, { label: `figure:${who.key}`, image: png, prompt });
+    if (found.length) return found.reduce((a, b) => (area(b.mask) > area(a.mask) ? b : a));
+  }
+  return undefined;
+}
+
+/**
+ * Why a cut-out of a person on two legs is not one standing whole, or undefined when it is. A standing figure is
+ * about twice as tall as wide (robots and big-headed drawn children down to about 1.4), so only a squatter one is
+ * looked at by Spark: sitting with knees up comes out about as wide as tall.
+ */
+export async function notStanding(memo: Memo, key: string, figure: Buffer, take = 0): Promise<string | undefined> {
+  const { width = 1, height = 1 } = await sharp(figure).metadata();
+  if (height / width >= 1.6) return undefined;
+  const flat = await sharp(figure).flatten({ background: '#cccccc' }).png().toBuffer();
+  const a = await askSparkJson<{ standing?: unknown; why?: unknown }>(memo, {
+    label: `figure-standing:${key}#${take}`, images: [flat],
+    prompt: 'This is a character cut out for a 2D adventure game, where it has to walk. Is it standing upright on its own feet, with the whole body from head to feet shown, and nothing it sits or leans on? Sitting, lying, kneeling, crouching, or legs or feet cut off is no. A character that has no legs by nature (a ghost, a blob) is yes.\n\nReply with JSON only: {"standing": true or false, "why": "a few words"}',
+  });
+  return a.standing === false ? String(a.why ?? 'not standing') || 'not standing' : undefined;
+}
+
+const area = (m: Mask) => m.bits.reduce((s, b) => s + b, 0);
+
+/**
+ * Why a cut-out is a box and not a figure, or undefined: one that fills nearly all of its box kept the scene it
+ * was painted standing in (a framed picture of stormy sea), and the game would draw that patch around them.
+ */
+export async function boxed(figure: Buffer): Promise<string | undefined> {
+  const { data, info } = await sharp(figure).ensureAlpha().extractChannel(3).raw().toBuffer({ resolveWithObject: true });
+  let solid = 0;
+  for (let i = 0; i < info.width * info.height; i++) if (data[i] > 128) solid++;
+  return solid > 0.85 * info.width * info.height ? 'cut out with the scene behind them, a box' : undefined;
+}
+
+/** A grown-up's height, the scale's unit (PERSON_M in src/scene/scale.ts). */
+export const PERSON_M = 1.62;
+
+/** How a character stands: metres tall, and whether upright on two legs like a person (a cat is not). */
+export type Body = { height: number; upright: boolean };
+
+/**
+ * How tall each character stands, in metres (a cat about 0.3, a child about 1.1, a grown-up 1.62), so the
+ * runtime draws an animal or a child at its own size, and whether it walks upright like a person: only those
+ * get a walking rig, a 3D model and sprite sheets, the rest stay their painted figure. One Spark call for the cast.
+ */
+export async function castBodies(memo: Memo, world: World, cast: Who[]): Promise<Record<string, Body>> {
+  if (!cast.length) return {};
+  const prompt = `These are the characters of a 2D adventure game (${world.pitch}):
+${cast.map((w) => `- ${w.key}: ${w.looks}`).join('\n')}
+For each one: how tall does it stand, in metres, from the ground to the top of the head (for an animal on four legs, to the top of its head as it stands)? An ordinary grown-up is ${PERSON_M}. And does it stand and walk upright on two legs like a person (a person, a robot, a talking bear in a coat: yes; a cat, a dog, a horse, a bird, a fish: no)?
+Reply with JSON only: {${cast.map((w) => `"${w.key}": {"m": <metres>, "upright": true or false}`).join(', ')}}`;
+  const a = await askSparkJson<Record<string, { m?: unknown; upright?: unknown }>>(memo, { label: 'cast-bodies', prompt });
+  return Object.fromEntries(cast.flatMap((w) => {
+    const m = Number(a[w.key]?.m);
+    return Number.isFinite(m) && m > 0 ? [[w.key, { height: Math.round(Math.min(3, Math.max(0.08, m)) * 100) / 100, upright: a[w.key]?.upright !== false }]] : [];
+  }));
+}
+
+/** cast/figures.json (diorama cast): each character's body; absent, everyone is an upright grown-up. */
+export function readBodies(files: { path(...p: string[]): string; readJson(p: string): unknown }, exists: (p: string) => boolean): Record<string, Body> {
+  const at = files.path('cast', 'figures.json');
+  return exists(at) ? (files.readJson(at) as Record<string, Body>) : {};
+}

package/app/src/scene/corrections.ts

@@ -0,0 +1,164 @@
+// The person's fixes to a place, kept in places/<place>/corrections.json and applied again by every
+// rebuild: paint repaints their regions, masks takes their names, boxes, kinds, floor cells and
+// brush strokes, derive their stand spots. A fix is never an edit to a generated file, which the
+// next build would overwrite.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { maskArea, type Mask } from '../image/mask.ts';
+import { clampRect, maskBox, type Rect } from '../image/raster.ts';
+import { FRAME } from './layout.ts';
+import { KINDS, type Spots } from './locate.ts';
+
+const XY = z.tuple([z.number(), z.number()]);
+export const RectIn = z.tuple([z.number(), z.number(), z.number(), z.number()]).describe('x0, y0, x1, y1 in painting pixels (1200x896)');
+
+export const Stroke = z.object({
+  mode: z.enum(['add', 'erase']),
+  radius: z.number().min(1).max(200),
+  points: z.array(XY).min(1).max(2000),
+});
+export type Stroke = z.infer<typeof Stroke>;
+
+export const Corrections = z.object({
+  /** Persistent instructions for repairing an unfinished layout. */
+  layout: z.object({
+    guidance: z.string().min(10).max(4000),
+    /** layout_fix rounds after a composition rejection since the last new painting take. */
+    replans: z.number().int().min(0).optional(),
+  }).optional(),
+  things: z.record(z.string(), z.object({
+    /** What to ask SAM for instead of Spark's phrase. */
+    phrase: z.string().min(2).optional(),
+    /** Where it really is, instead of Spark's box. */
+    box: RectIn.optional(),
+    /** How it meets the floor, instead of Spark's reading. */
+    kind: z.enum(KINDS).optional(),
+    strokes: z.array(Stroke).default([]),
+    /** Where the hero stands to use it. */
+    stand: XY.optional(),
+    /** Where an NPC stands (its feet), instead of the layout's spot. */
+    at: XY.optional(),
+    /** Not a thing of its own any more (a prop the person took off the list): it stays painted, or is painted out. */
+    removed: z.boolean().optional(),
+  })).default({}),
+  /** Props the person added to the place's things, by key: what it is, in words (it must be in the painting). */
+  added: z.record(z.string(), z.object({ looks: z.string().min(3) })).default({}),
+  floors: z.record(z.string(), z.object({
+    add: z.array(z.string()).default([]),
+    remove: z.array(z.string()).default([]),
+    strokes: z.array(Stroke).default([]),
+  })).default({}),
+  repaint: z.array(z.object({ region: RectIn, fix: z.string().min(3) })).default([]),
+  /**
+   * How the place is worded for the painter, instead of world.json and Spark's brief: set by paint_words, or by
+   * paint itself when the image safety filter refused the painting and Spark reworded it.
+   */
+  words: z.object({
+    shows: z.string().min(10).optional(),
+    mood: z.string().min(2).optional(),
+    /** One sentence per thing or floor key, used as its look as it is (Spark does not expand it again). */
+    looks: z.record(z.string(), z.string().min(10)).default({}),
+    by: z.enum(['filter', 'person']).default('person'),
+    /** Spark's rewords so far: each asks anew, so a rebuild after refused rewords does not get the same words back. */
+    tries: z.number().int().min(0).optional(),
+  }).optional(),
+  /** Which take of the painting (paint --take): the build asks for a new one when the painting left the layout (FLOOR_LOST). */
+  take: z.number().int().min(0).optional(),
+  /** Where the hero begins in this place (hero_start_set), instead of the front middle of the biggest floor. */
+  start: XY.optional(),
+  /** This place's own painting style over world.json's (style_set with scope place). */
+  style: z.string().min(10).optional(),
+});
+export type Corrections = z.infer<typeof Corrections>;
+
+export const correctionsFile = (placeDir: string) => path.join(placeDir, 'corrections.json');
+
+export function readCorrections(placeDir: string): Corrections {
+  const file = correctionsFile(placeDir);
+  if (!fs.existsSync(file)) return Corrections.parse({});
+  return Corrections.parse(JSON.parse(fs.readFileSync(file, 'utf8')));
+}
+
+export function writeCorrections(placeDir: string, c: Corrections) {
+  fs.writeFileSync(correctionsFile(placeDir), `${JSON.stringify(c, null, 2)}\n`);
+}
+
+/** Spark's spots with the person's names, boxes and kinds in their place. */
+export function correctSpots(spots: Spots, c: Corrections): Spots {
+  const out: Spots = { ...spots };
+  for (const [key, fix] of Object.entries(c.things)) {
+    const spot = out[key];
+    if (!spot) continue;
+    out[key] = {
+      ...spot,
+      ...(fix.phrase && { phrase: fix.phrase, also: undefined }),
+      ...(fix.box && { box: clampRect(fix.box, FRAME.width, FRAME.height) }),
+      ...(fix.kind && { kind: fix.kind }),
+    };
+  }
+  return out;
+}
+
+/** Spark's floor cells with the person's added and removed. */
+export function correctCells(marked: Record<string, string[]>, c: Corrections): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(marked).map(([key, cells]) => {
+    const fix = c.floors[key];
+    if (!fix) return [key, cells];
+    const removed = new Set(fix.remove.map((s) => s.toUpperCase()));
+    return [key, [...new Set([...cells, ...fix.add.map((s) => s.toUpperCase())])].filter((s) => !removed.has(s))];
+  }));
+}
+
+/** Paints brush strokes into a mask: round dabs along each line, added or erased. */
+export function brush(mask: Mask, strokes: Stroke[]): Mask {
+  if (strokes.length === 0) return mask;
+  const out: Mask = { ...mask, bits: mask.bits.slice() };
+  const { width: W, height: H } = out;
+  for (const s of strokes) {
+    const v = s.mode === 'add' ? 1 : 0;
+    const r = s.radius;
+    const dab = (cx: number, cy: number) => {
+      for (let y = Math.max(0, Math.floor(cy - r)); y <= Math.min(H - 1, Math.ceil(cy + r)); y++) {
+        for (let x = Math.max(0, Math.floor(cx - r)); x <= Math.min(W - 1, Math.ceil(cx + r)); x++) {
+          if ((x - cx) ** 2 + (y - cy) ** 2 <= r * r) out.bits[y * W + x] = v;
+        }
+      }
+    };
+    s.points.forEach(([x, y], i) => {
+      const [px, py] = i ? s.points[i - 1] : [x, y];
+      const n = Math.max(1, Math.ceil(Math.hypot(x - px, y - py) / Math.max(1, r / 2)));
+      for (let k = 1; k <= n; k++) dab(px + ((x - px) * k) / n, py + ((y - py) * k) / n);
+    });
+  }
+  return out;
+}
+
+/** A mask after the person's strokes, with its size and box measured again. */
+export function brushed<T extends { mask: Mask; px: number }>(m: T, strokes: Stroke[] | undefined): T & { brushed?: true } {
+  if (!strokes?.length) return m;
+  const mask = brush(m.mask, strokes);
+  const box = maskBox(mask) ?? ([0, 0, 0, 0] as Rect);
+  return { ...m, mask, px: maskArea(mask), ...('box' in m && { box }), brushed: true };
+}
+
+export const isEmpty = (c: Corrections) => Object.keys(c.things).length === 0 && Object.keys(c.floors).length === 0 && c.repaint.length === 0;
+
+
+/**
+ * The layout with each moved NPC standing where the person put it: feet at the new spot, and as much bigger or
+ * smaller as the depth there asks (height grows with the distance below the horizon).
+ */
+export function placeNpcs<L extends { horizon: number; things: Array<{ key: string; x: number; footY: number; width: number; height: number }> }>(layout: L, npcs: ReadonlySet<string>, c: Corrections): L {
+  return {
+    ...layout,
+    things: layout.things.map((t) => {
+      const at = npcs.has(t.key) ? c.things[t.key]?.at : undefined;
+      if (!at) return t;
+      const before = t.footY - layout.horizon;
+      const after = at[1] - layout.horizon;
+      const k = before > 0 && after > 0 ? after / before : 1;
+      return { ...t, x: at[0], footY: at[1], width: t.width * k, height: t.height * k };
+    }),
+  };
+}