@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/commands/build.ts

@@ -0,0 +1,503 @@
+// diorama build <slug> ["<idea>"]: runs the steps, each as soon as what it needs is made (src/world/schedule.ts):
+// every place on its own, the cast, voices and sound alongside. Keeps a build.json of what happened.
+import { facesState } from '../scene/faces-settings.ts';
+import { inStep } from '../meta/step.ts';
+import fs from 'node:fs';
+import { defineCommand, emit, registry, takeOption } from '../registry.ts';
+import { Geometry } from '../play/geometry.ts';
+import { maskFromPng, type Mask } from '../image/mask.ts';
+import { autoFixes } from '../scene/autofix.ts';
+import { Corrections, readCorrections, writeCorrections } from '../scene/corrections.ts';
+import { Layout } from '../scene/layout.ts';
+import { withPlay, type Play } from '../scene/playbook.ts';
+import { gridOf, type Finding, type Verdict } from '../scene/verify.ts';
+import { WorldFiles } from '../world/files.ts';
+import { drawingFiles } from '../world/drawings.ts';
+import { toldFiles } from '../world/told.ts';
+import { NEEDS, needs, PLACE_STEPS, STEPS, type Step } from '../world/schedule.ts';
+import { itemSources } from '../scene/icons.ts';
+import { Story } from '../story/schema.ts';
+import { assetReport } from '../scene/assets.ts';
+import { FacePreparationError } from '../scene/face-work.ts';
+
+/** How the build's own repaints of a missing thing start, so a new take can drop them. */
+const BUILD_REPAINT = 'Paint the';
+
+export { PLACE_STEPS, STEPS } from '../world/schedule.ts';
+
+/** What each place step leaves that later steps read; a place missing one never got past that step. */
+const MADE: Partial<Record<Step, string>> = { layout: 'blockin.png', paint: 'painting.png', masks: 'masks.json', derive: 'geometry.json' };
+
+/**
+ * The earliest step before `step` whose file the place lacks, with that file; null when it has them all. Steps this
+ * build ran itself (`ran`) are not looked at: they made the file or set the place aside already.
+ */
+export function placeGap(placeDir: string, step: Step, ran: readonly Step[] = []): { step: Step; file: string } | null {
+  for (const s of PLACE_STEPS.slice(0, PLACE_STEPS.indexOf(step)).filter((x) => !ran.includes(x))) {
+    const file = MADE[s];
+    if (file && !fs.existsSync(`${placeDir}/${file}`)) return { step: s, file };
+  }
+  return null;
+}
+
+export const gapError = (place: string, gap: { step: string; file: string }) =>
+  `${place} never got past ${gap.step} (no ${gap.file}): fix why ${gap.step} failed there (place_status, the job log) and rebuild the place from ${gap.step}`;
+
+type Report = { place: string; ok: boolean; errors: string[]; flagged: string[]; issues: Array<Finding & { play?: Play }>; from?: Step };
+type Repair = { place: string; by: 'auto'; fixes: string[]; ok: boolean };
+const line = (f: Finding) => `${f.code}${f.key ? ` ${f.key}` : ''}: ${f.detail}`;
+
+/**
+ * Model calls `step` sent (not answered from the memo) since `since`, and what they cost, read from the memo's call
+ * log. Only calls tagged with this step count: steps run side by side, and counting every call since the step
+ * began gave each step the others' calls too (the 3D step showed 137 Spark calls where it made about 25).
+ */
+export function stepCalls(files: WorldFiles, step: string, since: string): { sent: Record<string, number>; usd: number } {
+  const log = files.path('memo', 'calls.jsonl');
+  const sent: Record<string, number> = { spark: 0, muse: 0, sam: 0, sound: 0, music: 0, voice: 0, space: 0 };
+  let usd = 0;
+  if (!fs.existsSync(log)) return { sent, usd };
+  for (const line of fs.readFileSync(log, 'utf8').split('\n')) {
+    if (!line) continue;
+    const call = JSON.parse(line) as { at: string; model: string; hit: boolean; step?: string; usd?: number };
+    if (call.at < since || call.hit || call.step !== step) continue;
+    sent[call.model] = (sent[call.model] ?? 0) + 1;
+    usd += call.usd ?? 0;
+  }
+  return { sent, usd: Math.round(usd * 1000) / 1000 };
+}
+
+defineCommand({
+  name: 'build',
+  usage: 'build <slug> ["<idea>"] run every step, world to verify, in order [--from STEP] [--to STEP] [--places N] [--photo room.jpg] [--hero-photo me.jpg] [--drawings DIR] [--told DIR] [--kids] [--language L] [--place KEY: only the place steps, for one place] [--repair off: leave errors for the agent and the person, no free fixes] [--max-take N: new paintings the build may ask for, default 2, 0 keeps them]',
+  async run(args) {
+    const from = takeOption(args, 'from', STEPS[0]) as Step;
+    const to = takeOption(args, 'to', STEPS[STEPS.length - 1]) as Step;
+    const places = takeOption(args, 'places', '4');
+    const photo = takeOption(args, 'photo', '');
+    const heroPhoto = takeOption(args, 'hero-photo', '');
+    // Children's drawings and recordings of their story, and the game's language, go to the world step as they are.
+    const told = takeOption(args, 'told', '');
+    const worldArgs = ['drawings', 'told', 'language'].flatMap((o) => {
+      const value = o === 'told' ? told : takeOption(args, o, '');
+      return value ? [`--${o}`, value] : [];
+    });
+    const kids = args.indexOf('--kids');
+    if (kids >= 0) (args.splice(kids, 1), worldArgs.push('--kids'));
+    const only = takeOption(args, 'place', '');
+    const repair = takeOption(args, 'repair', 'auto');
+    // The highest take of a painting the build may ask for by itself (FLOOR_LOST); 0 keeps every painting as it is.
+    const maxTake = Number(takeOption(args, 'max-take', '2'));
+    const [slug, idea] = args;
+    if (!slug) throw new Error('usage: diorama build <slug> ["<idea>"] [--from STEP] [--to STEP]');
+    const range = STEPS.slice(STEPS.indexOf(from), STEPS.indexOf(to) + 1).filter((s) => !only || PLACE_STEPS.includes(s));
+    if (range.length === 0) throw new Error(`steps run ${STEPS.join(' > ')}; --from ${from} --to ${to} selects none`);
+    const files = new WorldFiles(slug);
+    if (range[0] === 'world' && !idea && !told && toldFiles(files).length === 0 && drawingFiles(files).length === 0) throw new Error('the world step needs an idea: diorama build <slug> "<idea>" (or --told DIR, recordings of the story)');
+
+    if (only && !files.world().places.some((p) => p.key === only)) throw new Error(`${slug} has no place ${only}`);
+    const logFile = files.path('build.json');
+    const log = (fs.existsSync(logFile) ? files.readJson(logFile) : { steps: {} }) as { steps: Record<string, unknown>; places?: Report[]; repairs?: Array<Repair & { at: string }> };
+    // A place whose step threw is set aside with why; the other places go on, and so do the world's own steps.
+    const broken = new Map<string, { step: Step; error: string }>();
+    const placeStep = async (step: Step, place: string) => {
+      // A place step that lost the network (every retry of a request failed: "fetch failed") gets the step
+      // again after a pause, twice, before the place is set aside: an outage of a few minutes costs time, not a place.
+      for (let again = 0; ; again++) {
+        try {
+          await inStep(step, () => registry.get(step)!.run([slug, place]));
+          return;
+        } catch (reason) {
+          const error = reason instanceof Error ? reason.message : String(reason);
+          if (again < 2 && /fetch failed|ECONNRESET|ENOTFOUND|EAI_AGAIN|socket hang up/i.test(error)) {
+            console.log(`${place}: ${step} lost the network (${error.slice(0, 80)}); trying the step again in ${60 * (again + 1)} s`);
+            await new Promise((r) => setTimeout(r, 60_000 * (again + 1)));
+            continue;
+          }
+          throw reason;
+        }
+      }
+    };
+    /** Runs a place step for one place; a place that throws is set aside, the others go on. */
+    const runPlace = async (step: Step, place: string) => {
+      // A place an earlier job left unfinished (its paint refused, say) is set aside at the step it never got past,
+      // not failed here with a missing file, so the report and job_retry point at the step to redo.
+      const gap = placeGap(files.place(place), step, range);
+      if (gap) {
+        broken.set(place, { step: gap.step, error: gapError(place, gap) });
+        console.log(`${place}: ${step} skipped: ${gapError(place, gap)}`);
+        emit('place.fail', { place, step: gap.step, error: gapError(place, gap) });
+        return;
+      }
+      try {
+        await placeStep(step, place);
+      } catch (reason) {
+        const error = reason instanceof Error ? reason.message : String(reason);
+        broken.set(place, { step, error });
+        console.log(`${place}: ${step} failed, set aside: ${error}`);
+        emit('place.fail', { place, step, error });
+      }
+    };
+    /** Per place: whether it is playable, everything flagged and let through, and for each error what to try (the playbook). */
+    const reportOf = (place: string): Report | null => {
+      const gone = broken.get(place);
+      if (gone) {
+        const issue = withPlay({ code: 'STEP_FAILED', key: gone.step, detail: gone.error });
+        return { place, ok: false, errors: [line(issue)], flagged: [], issues: [issue], from: gone.step };
+      }
+      const file = files.place(place, 'verify.json');
+      if (!range.includes('verify') || !fs.existsSync(file)) return null;
+      const v = files.readJson(file) as Verdict;
+      return { place, ok: v.ok, errors: v.errors.map(line), flagged: v.flags.map(line), issues: v.errors.map((e) => withPlay(e, v.flags)) };
+    };
+
+    emit('build.start', { slug, steps: range });
+    const saved = process.exitCode;
+    const optionalWarnings = new Map<Step,string[]>();
+    const run = (step: Step) => range.includes(step);
+    /** Each step's run: when it began, its longest single run (one place, or the world), what is still to do. */
+    const runs = new Map<Step, { at: string; started: number; longest: number; left: number; done: Promise<void>; end: () => void; fail: (error: unknown) => void }>();
+    for (const step of range) {
+      let end!: () => void;
+      let fail!: (error: unknown) => void;
+      const done = new Promise<void>((resolve, reject) => ((end = resolve), (fail = reject)));
+      // Whoever waits on it hears of a failure; nobody waiting is fine.
+      done.catch(() => {});
+      runs.set(step, { at: '', started: 0, longest: 0, left: 1, done, end, fail });
+    }
+    /** A world step failed: nothing waiting on an unfinished step starts, so the build ends with that failure. */
+    const abort = (error: unknown) => {
+      for (const r of runs.values()) r.fail(error);
+    };
+    /** How many runs make the step: one for the world's, one per place (known once world.json is). */
+    const open = (step: Step, units: number) => {
+      const r = runs.get(step)!;
+      r.left = units;
+      if (units === 0) r.end();
+    };
+    const begin = (step: Step) => {
+      const r = runs.get(step)!;
+      if (r.started) return Date.now();
+      r.started = Date.now();
+      r.at = new Date().toISOString();
+      console.log(`\n# ${step}`);
+      emit('step.start', { step });
+      return r.started;
+    };
+    /** One unit of a step finished (a place, or the world's own run); the last one ends the step. */
+    const finish = (step: Step, since?: number) => {
+      const r = runs.get(step)!;
+      if (since) r.longest = Math.max(r.longest, Date.now() - since);
+      if (--r.left > 0) return;
+      r.end();
+      if (!r.started) return;
+      // A step's time is what one place (or the world) took with it, so it adds up along the web, not the clock.
+      const done = { at: r.at, seconds: Math.round(r.longest / 100) / 10, ...stepCalls(files, step, r.at), ...(optionalWarnings.has(step) && { status: 'incomplete', warnings: optionalWarnings.get(step) }) };
+      // A one-place rerun does not stand for the whole step.
+      if (!only) {
+        log.steps[step] = done;
+        files.write(logFile, log);
+      }
+      emit('step.end', { step, ...done, ...(only && { place: only }) });
+    };
+    /** Resolves when `step` is done everywhere (every place has finished it or was set aside); at once when not run. */
+    const ready = (step: Step) => (run(step) ? runs.get(step)!.done : Promise.resolve());
+    const worldStep = async (step: Step, args: string[]) => {
+      await Promise.all(needs(step).map(ready));
+      const since = begin(step);
+      if (step === 'faces' && !facesState().enabled) {
+        console.log('Talking mouths are off (Setup): characters speak with voice and gestures.');
+        finish(step, since); return;
+      }
+      try {
+        await inStep(step, () => registry.get(step)!.run(args));
+      } catch (error) {
+        // Speaking faces never fail a build: whatever went wrong, the game plays with gestures.
+        if (step === 'faces') {
+          optionalWarnings.set(step,error instanceof FacePreparationError ? error.failures : [error instanceof Error ? error.message : String(error)]);
+          console.log(`Speaking animation incomplete; game build continues: ${optionalWarnings.get(step)!.join('; ')}`);
+          finish(step,since);return;
+        }
+        emit('step.fail', { step, error: error instanceof Error ? error.message : String(error) });
+        abort(error);
+        throw error;
+      }
+      finish(step, since);
+    };
+
+    const worldSteps = STEPS.filter((s) => run(s) && !PLACE_STEPS.includes(s) && s !== 'icons');
+    const tasks: Array<Promise<void>> = [];
+    const go = (step: Step, args: string[]) => {
+      const task = worldStep(step, args);
+      // Every world step is awaited at the end; this only keeps a failure from being reported twice as unhandled.
+      task.catch(() => {});
+      tasks.push(task);
+    };
+    if (run('world')) go('world', [slug, ...(idea ? [idea] : []), '--places', places, ...worldArgs, ...(photo ? ['--photo', photo] : []), ...(heroPhoto ? ['--hero-photo', heroPhoto] : [])]);
+    // Speaking faces in a build: the portrait (what a conversation shows) and the 2D rig only. Talk sheets and 3D
+    // surfaces cost a Muse atlas and many vision checks each, about 20 minutes a character, for lips nobody watches.
+    for (const s of worldSteps.filter((s) => s !== 'world')) go(s, s === 'faces' ? [slug, '--image-only'] : [slug]);
+
+    // The places start once world.json says which there are; each goes through its steps on its own.
+    const reports: Report[] = [];
+    const repairs: Repair[] = [];
+    let keys: string[] = [];
+    const placesDone = ready('world').then(async () => {
+      keys = files.world().places.map((p) => p.key).filter((p) => !only || p === only);
+      for (const s of PLACE_STEPS.filter(run)) open(s, keys.length);
+      // Icons, per place once its things are cut out; items picked up nowhere once the story is there.
+      const story = () => (fs.existsSync(files.path('story.json')) ? Story.parse(files.readJson(files.path('story.json'))) : null);
+      if (run('icons')) open('icons', keys.length + 1);
+      let iconsQueue = Promise.resolve();
+      const iconTasks: Array<Promise<void>> = [];
+      /** items/items.json is read and written by each run, so icons runs one after another. */
+      const icons = (items: () => string[] | null) => {
+        const next = iconsQueue.then(async () => {
+          await ready('story');
+          const keys = items();
+          // null: no story to say which items, so icons is run as a whole (it says there is nothing to do).
+          if (keys && keys.length === 0) return finish('icons');
+          const since = begin('icons');
+          try {
+            await inStep('icons', () => registry.get('icons')!.run([slug, ...(keys ?? [])]));
+          } catch (error) {
+            emit('step.fail', { step: 'icons', error: error instanceof Error ? error.message : String(error) });
+            abort(error);
+            throw error;
+          }
+          finish('icons', since);
+        });
+        iconsQueue = next.catch(() => {});
+        iconTasks.push(next);
+      };
+      const itemsFrom = (place: string | null) => () => {
+        const s = story();
+        if (!s) return place === null ? null : [];
+        const placed = new Set(keys);
+        return Object.entries(itemSources(s)).filter(([, from]) => (place === null ? !from || !placed.has(from.place) : from?.place === place)).map(([item]) => item);
+      };
+      if (run('icons')) icons(itemsFrom(null));
+
+      const chains = await Promise.allSettled(keys.map(async (place) => {
+        for (const step of PLACE_STEPS.filter(run)) {
+          await Promise.all(NEEDS[step].map(ready));
+          if (!broken.has(place)) {
+            const since = begin(step);
+            emit('place.step', { place, step });
+            await runPlace(step, place);
+            // Said per place, so Studio can tell a place between steps (waiting on another one) from one being worked on.
+            emit('place.step', { place, step, done: true });
+            finish(step, since);
+          } else finish(step);
+          if (step === 'masks' && run('icons')) icons(itemsFrom(place));
+        }
+        const report = await repairPlace(place);
+        if (report) {
+          reports.push(report);
+          // Said as soon as the place is done, so it can be played while the others are still being made.
+          emit('place.verdict', report);
+        }
+      }));
+      if (run('icons') && !run('masks')) for (const p of keys) icons(itemsFrom(p));
+      for (const settled of [...chains, ...(await Promise.allSettled(iconTasks))]) if (settled.status === 'rejected') throw settled.reason;
+    });
+    placesDone.catch(abort);
+    tasks.push(placesDone);
+    // Everything runs to the end before a failure is told, so no step is cut off half written.
+    const settled = await Promise.allSettled(tasks);
+    process.exitCode = saved;
+    const failure = settled.find((s): s is PromiseRejectedResult => s.status === 'rejected');
+    if (failure) throw failure.reason;
+    if (keys.length && keys.every((p) => broken.has(p))) {
+      const last = [...broken.values()].sort((a, b) => STEPS.indexOf(b.step) - STEPS.indexOf(a.step))[0].step;
+      const error = `${last} failed for every place: ${[...broken].map(([p, b]) => `${p}: ${b.error}`).join('; ')}`;
+      emit('step.fail', { step: last, error });
+      throw new Error(error);
+    }
+    if (reports.length) {
+      const report = keys.map((p) => reports.find((r) => r.place === p)).filter((r): r is Report => !!r);
+      if (repairs.length) log.repairs = [...(log.repairs ?? []), ...repairs.map((x) => ({ at: new Date().toISOString(), ...x }))].slice(-50);
+      log.places = [...(log.places ?? []).filter((r) => !report.some((n) => n.place === r.place)), ...report];
+      files.write(logFile, log);
+      console.log('\n# report');
+      for (const r of report) {
+        console.log(`${r.place}: ${r.ok ? 'playable' : 'NOT playable'}${r.flagged.length ? `, flagged and continued: ${r.flagged.length}` : ''}`);
+        for (const i of r.issues) {
+          console.log(`  error  ${line(i)}`);
+          if (i.play) console.log(`         try: ${i.play.tools.join(' | ')}`);
+        }
+        for (const f of r.flagged) console.log(`  flag   ${f}`);
+      }
+      if (report.some((r) => !r.ok)) process.exitCode = 1;
+    }
+    // The cast and the sound, which verify does not look at: a character with no walk, a sound that stayed silent.
+    if (['cast', 'model', 'sprites', 'sound', 'voices'].some((s) => run(s as Step))) {
+      try {
+        const assets = assetReport(files);
+        if (assets.length) console.log(`\n# made\n${assets.map((l) => `  ${l}`).join('\n')}`);
+      } catch { /* a report only */ }
+    }
+
+    /**
+     * The place's verdict once its steps are done, after the free tier of repair: fixes the build can make itself
+     * with no model call (src/scene/autofix.ts), then the place is rebuilt from the step they feed. Whatever is
+     * left goes to the agent, then the person. Null when verify did not run and the place did not break.
+     */
+    async function repairPlace(place: string): Promise<Report | null> {
+      let r = reportOf(place);
+      if (!r || repair === 'off') return r;
+      // Two passes: a bridge to one patch can bring the next patch within reach of a second bridge.
+      for (let pass = 0; pass < 2 && !r.ok && !r.from; pass++) {
+        const dir = files.place(place);
+        let fixes: ReturnType<typeof autoFixes>;
+        try {
+          const geometry = Geometry.parse(files.readJson(files.place(place, 'geometry.json')));
+          const floors = Layout.parse(files.readJson(files.place(place, 'layout.json'))).floors.map((f) => f.key);
+          // Walk-on masks: a bridge is drawn along stairs only when they reach both floors.
+          const masks: Record<string, Mask> = {};
+          for (const t of geometry.things) {
+            if (t.kind === 'walk-on' && t.mask && fs.existsSync(files.place(place, t.mask))) masks[t.key] = await maskFromPng(fs.readFileSync(files.place(place, t.mask)));
+          }
+          fixes = autoFixes(geometry, floors, r.issues, masks);
+        } catch (error) {
+          fixes = [];
+          console.log(`${place}: could not look for a free fix: ${error instanceof Error ? error.message : error}`);
+        }
+        const before = readCorrections(dir);
+        const after = Corrections.parse(JSON.parse(JSON.stringify(before)));
+        for (const f of fixes) f.apply(after);
+        if (fixes.length === 0 || JSON.stringify(after) === JSON.stringify(before)) {
+          console.log(`\n# repair ${place}: no free fix for ${[...new Set(r.issues.map((i) => i.code))].join(', ')}; left for the agent`);
+          break;
+        }
+        writeCorrections(dir, after);
+        const start = fixes.some((f) => f.from === 'masks') ? 'masks' : 'derive';
+        console.log(`\n# repair ${place}: ${fixes.map((f) => f.what).join('; ')}`);
+        emit('repair.start', { place, by: 'auto', fixes: fixes.map((f) => f.what) });
+        for (const step of PLACE_STEPS.slice(PLACE_STEPS.indexOf(start))) {
+          if (!broken.has(place)) await runPlace(step, place);
+        }
+        r = reportOf(place)!;
+        repairs.push({ place, by: 'auto', fixes: fixes.map((f) => f.what), ok: r.ok });
+        emit('repair.end', { place, by: 'auto', ok: r.ok });
+      }
+      return recutCards(place, await paintMissing(place, await newTake(place, r)));
+    }
+
+    // Do not paint a bridge to a snapped interaction spot and brush it open without measuring it.
+    // Paint now restores the plan's composition before masks; remaining gaps need observed floor evidence.
+
+    /**
+     * A card whose mask leaves out a painted part of its thing (CARD_CUT: the boat's bow, a lamp on its post) leaves
+     * that part smeared on the backdrop when the card slides. The flag's box says where; the thing's box is widened
+     * to take it in (as mask_fix box does), so masks asks SAM by the wider box and joins what it finds there that
+     * touches the thing; the card carries it and the backdrop is made again without it. Once per cut. A round dab
+     * brushed over the part instead took the sky round it too: a disc on the card, and a hover outline looping round it.
+     */
+    async function recutCards(place: string, r: Report | null): Promise<Report | null> {
+      if (!r || r.from || repair === 'off') return r;
+      const file = files.place(place, 'verify.json');
+      if (!fs.existsSync(file)) return r;
+      const cuts = (files.readJson(file) as Verdict).flags.filter((f) => f.code === 'CARD_CUT' && f.key && f.box);
+      if (!cuts.length) return r;
+      const dir = files.place(place);
+      const before = readCorrections(dir);
+      const after = Corrections.parse(JSON.parse(JSON.stringify(before)));
+      const geometry = fs.existsSync(files.place(place, 'geometry.json')) ? Geometry.parse(files.readJson(files.place(place, 'geometry.json'))) : undefined;
+      const what: string[] = [];
+      for (const f of cuts) {
+        const was = after.things[f.key!]?.box ?? geometry?.things.find((t) => t.key === f.key)?.box;
+        if (!was) continue;
+        const [x0, y0, x1, y1] = f.box!;
+        const box: [number, number, number, number] = [Math.min(was[0], x0), Math.min(was[1], y0), Math.max(was[2], x1), Math.max(was[3], y1)].map(Math.round) as [number, number, number, number];
+        if (box.every((v, i) => v === Math.round(was[i]))) continue;
+        (after.things[f.key!] ??= { strokes: [] }).box = box;
+        what.push(`widened ${f.key}'s box to [${box.join(', ')}] to take in the part its card cut through at [${f.box!.join(', ')}]`);
+      }
+      if (!what.length) return r;
+      writeCorrections(dir, after);
+      console.log(`\n# repair ${place}: ${what.join('; ')}`);
+      emit('repair.start', { place, by: 'auto', fixes: what });
+      for (const step of PLACE_STEPS.slice(PLACE_STEPS.indexOf('masks'))) {
+        if (!broken.has(place)) await runPlace(step, place);
+      }
+      const next = reportOf(place) ?? r;
+      repairs.push({ place, by: 'auto', fixes: what, ok: next.ok });
+      emit('repair.end', { place, by: 'auto', ok: next.ok });
+      return next;
+    }
+
+    async function newTake(place: string, r: Report | null): Promise<Report | null> {
+      if (!r || r.ok || r.from || !r.issues.some((i) => i.code === 'FLOOR_LOST')) return r;
+      const dir = files.place(place);
+      const before = readCorrections(dir);
+      const take = (before.take ?? 0) + 1;
+      if (take > maxTake) return r;
+      const after = Corrections.parse(JSON.parse(JSON.stringify(before)));
+      after.take = take;
+      after.repaint = after.repaint.filter((x) => !x.fix.startsWith(BUILD_REPAINT));
+      writeCorrections(dir, after);
+      const lost = r.issues.filter((i) => i.code === 'FLOOR_LOST').map((i) => i.key).join(', ');
+      const what = [`painted take ${take}: floor ${lost} was painted away from its layout (one Muse painting)`];
+      console.log(`\n# repair ${place}: ${what[0]}`);
+      emit('repair.start', { place, by: 'auto', fixes: what });
+      for (const step of PLACE_STEPS.slice(PLACE_STEPS.indexOf('paint'))) {
+        if (!broken.has(place)) await runPlace(step, place);
+      }
+      const next = reportOf(place) ?? r;
+      repairs.push({ place, by: 'auto', fixes: what, ok: next.ok });
+      emit('repair.end', { place, by: 'auto', ok: next.ok });
+      return next;
+    }
+
+    /**
+     * A thing the story needs that Spark finds nowhere in the painting: no mask fix can find what was never painted,
+     * so it gets one Muse edit at its layout box (the one repaint_region per place the agent may make unasked), and
+     * the place is rebuilt from paint. Once per thing: a repaint already asked for it is not asked again.
+     */
+    async function paintMissing(place: string, r: Report | null): Promise<Report | null> {
+      if (!r || r.ok || r.from) return r;
+      const keys = [...new Set(r.issues.filter((i) => i.code === 'THING_NOT_PAINTED' && i.key).map((i) => i.key!))];
+      if (!keys.length) return r;
+      const dir = files.place(place);
+      const before = readCorrections(dir);
+      const after = Corrections.parse(JSON.parse(JSON.stringify(before)));
+      const asked: string[] = [];
+      try {
+        const layout = Layout.parse(files.readJson(files.place(place, 'layout.json')));
+        const listed = files.world().places.find((p) => p.key === place)?.things ?? [];
+        for (const key of keys) {
+          const t = layout.things.find((x) => x.key === key);
+          if (!t) continue;
+          const looks = (listed.find((x) => x.key === key)?.looks ?? key.replace(/-/g, ' ')).replace(/^(a|an|the)\s+/i, '');
+          const fix = `${BUILD_REPAINT} ${looks} here, clearly visible and whole, standing where it meets the floor, in the painting's own style and light; keep everything around it`;
+          if (after.repaint.some((x) => x.fix === fix)) continue;
+          // The layout box with room round it, so Muse can fit the thing in, at least 120 px each way.
+          const w = Math.max(120, t.width * 1.4), h = Math.max(120, t.height * 1.3);
+          const region: [number, number, number, number] = [
+            Math.max(0, Math.round(t.x - w / 2)), Math.max(0, Math.round(t.footY - h + 12)),
+            Math.min(1200, Math.round(t.x + w / 2)), Math.min(896, Math.round(t.footY + 24)),
+          ];
+          after.repaint.push({ region, fix });
+          asked.push(key);
+        }
+      } catch (error) {
+        console.log(`${place}: could not ask for a repaint: ${error instanceof Error ? error.message : error}`);
+        return r;
+      }
+      if (!asked.length) return r;
+      writeCorrections(dir, after);
+      const what = asked.map((k) => `repainted ${k} at its layout box (one Muse edit)`);
+      console.log(`\n# repair ${place}: ${what.join('; ')}`);
+      emit('repair.start', { place, by: 'auto', fixes: what });
+      for (const step of PLACE_STEPS.slice(PLACE_STEPS.indexOf('paint'))) {
+        if (!broken.has(place)) await runPlace(step, place);
+      }
+      const next = reportOf(place) ?? r;
+      repairs.push({ place, by: 'auto', fixes: what, ok: next.ok });
+      emit('repair.end', { place, by: 'auto', ok: next.ok });
+      return next;
+    }
+    console.log(`\nbuild ${slug}: ${range.join(' > ')} done · ${files.path('build.json')}`);
+  },
+});

package/app/src/commands/cast.ts

@@ -0,0 +1,142 @@
+import { worldStyleReference } from '../world/style-reference.ts';
+// diorama cast <slug>: the hero and every NPC of world.json as cut-out figures the runtime walks around.
+import fs from 'node:fs';
+import { bindExistingAnimation, bindAnimation } from '../scene/animation-source.ts';
+import { museEdit } from '../meta/muse.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { z } from 'zod';
+import { defineCommand, takeOption } from '../registry.ts';
+import { castBodies, cutHero, paintFigure, readBodies, type Who } from '../scene/cast.ts';
+import { samFind } from '../meta/sam.ts';
+import { photoStanding } from '../scene/photo.ts';
+import { rigFigure } from '../scene/rig.ts';
+import { checkSheet } from '../scene/rig-check.ts';
+import { PART_NAMES } from '../play/rig.ts';
+import { fixedLooks, readCastFixes } from '../scene/cast-fixes.ts';
+import { drawingFor, players, readDrawn } from '../world/drawings.ts';
+import { WorldFiles } from '../world/files.ts';
+import { approvedConcept } from '../world/sketch.ts';
+import { castStyle, markStyled, readStyled } from '../world/styled.ts';
+
+defineCommand({
+  name: 'cast',
+  usage: 'cast <slug> [key...]     paint the hero, NPCs and players (heroes for more gamepads, drawings marked player) with Muse, cut them out with SAM 3.1 (cast/<key>.png) [--take N] [--photo me.jpg: paint the hero from a photo, standing even if they sit in it] (a character a child drew, drawings.json, is painted from the drawing)',
+  async run(args) {
+    const take = Number(takeOption(args, 'take', '0'));
+    const photoPath = takeOption(args, 'photo', '');
+    const [slug, ...only] = args;
+    if (!slug) throw new Error('usage: diorama cast <slug> [key...] [--take N]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const styled = readStyled(files);
+    // world --hero-photo keeps the photo next to the cast, so a plain `cast` uses it too.
+    const kept = files.path('cast', `${world.hero.key}-photo.png`);
+    const photo = photoPath ? fs.readFileSync(photoPath) : fs.existsSync(kept) ? fs.readFileSync(kept) : undefined;
+    // Only a person standing whole in the photo keeps the photo's pose; anyone sitting, lying or cut off is painted standing.
+    const standing = photo ? await photoStanding(files.memo, photo) : false;
+    if (photo && !standing) console.log(`${world.hero.key}: the photo does not show them standing whole; painted standing`);
+    // A character a child drew is painted from what was read off the drawing, as its preview was, so the preview is the figure.
+    const drawn = readDrawn(files);
+    const drawnLooks = (w: Who): Who => ({ ...w, looks: drawn.find((d) => d.key === w.key && (d.kind === 'hero' || d.kind === 'npc' || d.kind === 'player'))?.looks ?? w.looks });
+    const npcs = world.places.flatMap((p) => p.things.filter((t) => t.role === 'npc'));
+    const fixes = readCastFixes(files);
+    const cast: Who[] = [world.hero, ...new Map(npcs.map((n) => [n.key, n])).values(), ...players(files)].filter((w) => !only.length || only.includes(w.key)).map((w) => fixedLooks(files, drawnLooks(w)));
+    const missing: string[] = [];
+    // cast/figures.json: how tall each one stands and whether upright, so a cat or a child is drawn at its own
+    // size and only those walking like a person get a rig (and later a model and sprites).
+    const bodies = { ...readBodies(files, fs.existsSync), ...(await castBodies(files.memo, world, cast)) };
+    files.write(files.path('cast', 'figures.json'), bodies);
+    const odd = Object.entries(bodies).filter(([, b]) => Math.abs(b.height - 1.62) > 0.25 || !b.upright);
+    if (odd.length) console.log(`bodies: ${odd.map(([k, b]) => `${k} ${b.height} m${b.upright ? '' : ', not upright'}`).join(', ')}`);
+    await Promise.all(cast.map(async (who) => {
+      // The person's description and chosen take (cast/fixes.json) win over the world's.
+      // An NPC that cannot be cut out is set aside (the game draws a stand-in) so the rest of the cast is made.
+      // A character painted before in another style (style_set) is repainted from that painting, so they stay who
+      // they were; the hero from a photo is painted from the photo again, in the new style.
+      const style = castStyle(files, world, who.key);
+      const was = styled.cast[who.key];
+      const before = files.path('cast', `${who.key}-painting.png`);
+      const heroPhoto = who.key === world.hero.key ? photo : undefined;
+      const restyle = was && was !== style && !heroPhoto && fs.existsSync(before) ? { painting: fs.readFileSync(before), was } : undefined;
+      const made = await paintFigure(files.memo, { ...world, style }, who, fixes[who.key]?.take ?? take, { photo: heroPhoto, standing, drawing: drawingFor(files, who.key), concept: approvedConcept(files, 'character', who.key), styleReference: worldStyleReference(files, style), restyle }, bodies[who.key]?.upright !== false).catch((error: Error) => {
+        if (who.key === world.hero.key) throw error;
+        missing.push(`${who.key}: ${error.message}`);
+        return null;
+      });
+      if (!made) return;
+      const { painting, figure } = made;
+      bindExistingAnimation(files, who.key);
+      files.write(files.path('cast', `${who.key}-painting.png`), painting);
+      files.write(files.path('cast', `${who.key}.png`), figure);
+      markStyled(files, 'cast', who.key, style);
+      // The same painting cut into parts, so the runtime can walk the figure.
+      if (bodies[who.key]?.upright === false) return console.log(`${who.key}: ${files.path('cast', `${who.key}.png`)} · not upright: drawn as painted`);
+      await rigCast(files, who.key, painting);
+    }));
+    for (const m of missing) console.log(`set aside, shown as a stand-in: ${m}`);
+    console.log(`calls sent: muse ${files.memo.sent.muse}, sam ${files.memo.sent.sam}`);
+  },
+});
+
+/**
+ * The painting made walkable: the whole figure warped by its bones into a walk sheet (cast/<key>/walk.png) and
+ * rig.json with the joints and how the walk measured. A walk that tears is kept but marked, and the game slides
+ * the painted figure as one piece instead. Parts of an older cut-out rig are removed.
+ */
+export async function rigCast(files: WorldFiles, key: string, painting: Buffer) {
+  try {
+    let { rig, parts, issues } = await rigFigure(files.memo, key, painting);
+    rig.check = rig.sheet ? await checkSheet(rig, parts[rig.sheet.file]) : undefined;
+    if (rig.check && !rig.check.ok) {
+      // Try a separate neutral source for the warp; never overwrite the creator's painting.
+      try {
+        const neutral = await museEdit(files.memo, { label: `rig-neutral:${key}`, images: [painting], size: '1024x1024',
+          prompt: 'The same character, identity, face, clothes, colours, proportions and every object they hold. Show the whole character standing still in a relaxed neutral walk-ready pose: both feet on the ground, legs slightly apart and visible, no stepping, no overlapping legs. Keep any carried object firmly in the same hand, complete and not touching the ground. No other objects. Plain flat background, no shadow, no text.' });
+        const schema = z.object({ matches: z.boolean(), neutral: z.boolean(), heldPreserved: z.boolean(), reason: z.string() });
+        const verdict = schema.parse(await askSparkJson(files.memo, { label: `rig-neutral-check:${key}`, schema, images: [painting,neutral], personal: true,
+          prompt: 'Compare the original and proposed neutral standing character. Check identity, clothing, colours and proportions match; legs are visible and not already walking; every object held in the original remains complete and held in the same hand. If none is held, heldPreserved is true. Reply JSON {"matches":true,"neutral":true,"heldPreserved":true,"reason":"short explanation"}.' }));
+        if (!verdict.matches || !verdict.neutral || !verdict.heldPreserved) throw new Error(verdict.reason || 'neutral pose did not preserve the original');
+        const candidate = await rigFigure(files.memo, key, neutral);
+        candidate.rig.check = candidate.rig.sheet ? await checkSheet(candidate.rig, candidate.parts[candidate.rig.sheet.file]) : undefined;
+        if (!candidate.rig.check?.ok) throw new Error(candidate.rig.check?.why ?? 'neutral walk did not pass');
+        rig = candidate.rig; parts = candidate.parts; issues = [...issues, 'walk prepared from a verified neutral pose'];
+      } catch (error) {
+        issues.push(`neutral walk could not be prepared: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    for (const name of PART_NAMES) fs.rmSync(files.path('cast', key, `${name}.png`), { force: true });
+    for (const [file, png] of Object.entries(parts)) files.write(files.path('cast', key, file), png);
+    files.write(files.path('cast', key, 'rig.json'), rig);
+    bindAnimation(files, key, 'rig');
+    files.write(rigAttemptFile(files, key), { ok: true, reason: issues.length ? issues.join('; ') : null, at: new Date().toISOString() });
+    const verdict = rig.check && !rig.check.ok ? ` · walk torn (${rig.check.why}): slides as one piece` : '';
+    console.log(`${key}: ${files.path('cast', `${key}.png`)} · walk sheet ${rig.sheet?.frames ?? 0} frames${verdict}${issues.map((i) => ` · ${i}`).join('')}`);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    // Kept for cast_status (rigIssue): the figure still shows, sliding as one piece, and the person sees why.
+    files.write(rigAttemptFile(files, key), { ok: false, reason, at: new Date().toISOString() });
+    console.log(`${key}: ${files.path('cast', `${key}.png`)} · no rig: ${reason}; moves as one cut-out (cast_animate gives it a 3D model)`);
+  }
+}
+
+export const rigAttemptFile = (files: WorldFiles, key: string) => files.path('cast', key, 'rig-attempt.json');
+
+defineCommand({
+  name: 'rig',
+  usage: 'rig <slug> [key...]     make the walk again from the cast paintings already painted (no Muse; SAM answers are kept), and cut the figure out again so what it holds stays on',
+  async run(args) {
+    const [slug, ...only] = args;
+    if (!slug) throw new Error('usage: diorama rig <slug> [key...]');
+    const files = new WorldFiles(slug);
+    const bodies = readBodies(files, fs.existsSync);
+    const keys = fs.readdirSync(files.path('cast')).filter((f) => f.endsWith('-painting.png')).map((f) => f.slice(0, -'-painting.png'.length)).filter((k) => !only.length || only.includes(k));
+    for (const key of keys) {
+      if (bodies[key]?.upright === false) continue;
+      const painting = fs.readFileSync(files.path('cast', `${key}-painting.png`));
+      const person = (await samFind(files.memo, { label: `figure:${key}`, image: painting, prompt: 'person' })).sort((a, b) => b.mask.bits.reduce((s, x) => s + x, 0) - a.mask.bits.reduce((s, x) => s + x, 0))[0];
+      if (person) files.write(files.path('cast', `${key}.png`), await cutHero(painting, person.mask));
+      await rigCast(files, key, painting);
+    }
+    console.log(`calls sent: sam ${files.memo.sent.sam}`);
+  },
+});