@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/commands/model.ts

@@ -0,0 +1,284 @@
+// diorama model <slug> [key]: a character as a rigged 3D model, painted by Muse from four sides. Without a
+// key, everyone the sprites plan needs (the hero, NPCs who speak): the model is where their poses come from.
+import { castLanes, mapLimit } from '../world/pool.ts';
+import fs from 'node:fs';
+import { bindExistingAnimation, bindAnimation } from '../scene/animation-source.ts';
+import { refusedByFilter } from '../scene/words.ts';
+import { defineCommand, registry, takeOption } from '../registry.ts';
+import { autoRig, reconstruct } from '../model/build.ts';
+import { fitViews, refitIfOld } from '../model/fit.ts';
+import { badModel, lean, readShape, rigProblem, standUp } from '../model/glb.ts';
+import { findBlender, relaxPose, type RelaxReport } from '../model/blender.ts';
+import { paintViews } from '../model/views.ts';
+import { planSprites } from '../model/plan.ts';
+import { animationSettings, animationOptions, saveAnimationSettings } from '../model/animation.ts';
+import { Story } from '../story/schema.ts';
+import { fixedLooks, readCastFixes } from '../scene/cast-fixes.ts';
+import { readBodies } from '../scene/cast.ts';
+import { WorldFiles } from '../world/files.ts';
+
+defineCommand({
+  name: 'model',
+  usage: 'model <slug> [key]       with [key], also finishes its required sprites; Muse paints each character who needs sprites (or [key]) from 4 sides, TRELLIS + auto-rig make a 3D model (cast/<key>/model/) [--texture model|views: saved per character] [--glb rigged.glb: skip TRELLIS and the rig] [--coat-correction on|off: off for trousers] [--sprites: finish the character animation, used by Studio] [--take N] [--refit: only fit the views onto the model again, no calls] [--relax: only put existing models into a calm rest pose with a local Blender, no calls]',
+  async run(args) {
+    const options = animationOptions(takeOption(args, 'texture', ''), '', takeOption(args, 'coat-correction', ''));
+    const take = Number(takeOption(args, 'take', '0'));
+    const given = takeOption(args, 'glb', '');
+    const refit = args.includes('--refit');
+    const relaxOnly = args.includes('--relax');
+    const [slug, keyArg] = args.filter((a) => a !== '--refit' && a !== '--sprites' && a !== '--relax');
+    // An individual Animate request includes its sprites, including older Studio clients.
+    const withSprites = !!keyArg || args.includes('--sprites');
+    if (!slug) throw new Error('usage: diorama model <slug> [key] [--glb rigged.glb] [--refit]');
+    if (refit) {
+      if (Object.keys(options).length) throw new Error('--texture cannot be combined with --refit');
+      const files = new WorldFiles(slug);
+      const castDir = files.path('cast');
+      for (const key of keyArg ? [keyArg] : fs.readdirSync(castDir).filter((k) => fs.existsSync(files.path('cast', k, 'model', 'model.json')))) {
+        await refitIfOld(files.path('cast', key, 'model'), true);
+        console.log(`${key}: views fitted again, slice by slice`);
+      }
+      return;
+    }
+    if (relaxOnly) {
+      const blender = await findBlender();
+      if (!blender) throw new Error('--relax needs Blender 3.6+ (install it, or set DIORAMA_BLENDER to its path)');
+      const files = new WorldFiles(slug);
+      const castDir = files.path('cast');
+      const keys = keyArg ? [keyArg] : fs.readdirSync(castDir).filter((k) => fs.existsSync(files.path('cast', k, 'model', 'model.json')));
+      for (const key of keys) console.log(`${key}: ${await relaxModel(files, key, true)}`);
+      // Renders of the model itself follow it; painted sprites are redrawn by diorama sprites (Muse).
+      for (const key of keys) if (animationSettings(files, key).texture === 'model') await registry.get('sprites')!.run([slug, key]);
+      return;
+    }
+    if (given && !keyArg) throw new Error('--glb needs the key of the character it is');
+    const files = new WorldFiles(slug);
+    const story = fs.existsSync(files.path('story.json')) ? Story.parse(files.readJson(files.path('story.json'))) : undefined;
+    // Everyone the sprites plan needs, and whoever the person asked to animate (cast_animate, cast/fixes.json).
+    const asked = Object.entries(readCastFixes(files)).filter(([, f]) => f.animate).map(([k]) => k);
+    const keys = keyArg ? [keyArg] : [...new Set([...(await planSprites(files, story)).map((p) => p.key), ...asked])];
+    for (const key of keys) if (Object.keys(options).length) saveAnimationSettings(files, key, animationSettings(files, key, options));
+    await buildModels(files, keys, take, given, !!keyArg);
+    console.log(`calls sent: muse ${files.memo.sent.muse}, space ${files.memo.sent.space}`);
+    // UV sprites are renders of the model itself (no Muse): a new model without them leaves the game walking
+    // the old body's sheets (a pole the new sides left out, an old face), so they are always rendered again.
+    const uvSprites = (key: string) => {
+      try {
+        return animationSettings(files, key).texture === 'model' && fs.existsSync(files.path('cast', key, 'model', 'model.json'));
+      } catch {
+        return false;
+      }
+    };
+    if (withSprites || keys.some(uvSprites)) {
+      const plans = await planSprites(files, story);
+      for (const key of keys) if ((withSprites || uvSprites(key)) && plans.some((p) => p.key === key && !p.creature)) await registry.get('sprites')!.run([slug, key]);
+    }
+  },
+});
+
+/** Said when a character is left in 2D because the 3D service did not answer: cast_animate tries it again. */
+export const SERVICE_DOWN = 'the 3D service did not answer';
+/** Pauses before asking TRELLIS again after an error; tests shorten them. */
+export const SERVICE_PAUSES = { ms: [10_000, 30_000, 60_000] };
+/** Errors that asking again will not mend: no quota left, no access, a refused picture. */
+const lasting = (message: string) => /quota|\b40[13]\b|unauthori[sz]ed|forbidden|NSFW|not allowed/i.test(message);
+
+/** An unavailable service for one character must not prevent the rest of the cast being attempted. */
+export async function buildModels(files: WorldFiles, keys: string[], take: number, given: string, requireModel = false) {
+  const failures: string[] = [];
+  // Characters side by side (a few at once): each waits on Muse, Claude and the Spaces, never on another character.
+  // The Spaces keep their own small lanes (model/build.ts), so a busy GPU queue is not asked twice as hard.
+  await mapLimit(keys, castLanes(), async (key) => {
+    try {
+      const made = await buildModel(files, key, take, given);
+      if (!made && requireModel) failures.push(`${key}: no usable 3D model (${attemptReason(files, key)}); see cast status`);
+    } catch (error) {
+      const reason = `${key}: ${error instanceof Error ? error.message : String(error)}`;
+      console.error(reason);
+      failures.push(reason);
+    }
+  });
+  if (failures.length) throw new Error(`3D models failed: ${failures.join('; ')}`);
+}
+
+function attemptReason(files: WorldFiles, key: string): string {
+  try {
+    return String((files.readJson(files.path('cast', key, 'model', 'attempt.json')) as { reason?: unknown }).reason ?? 'unknown');
+  } catch {
+    return 'unknown';
+  }
+}
+
+export async function buildModel(files: WorldFiles, key: string, take: number, given: string): Promise<boolean> {
+  const attempt = files.path('cast', key, 'model', 'attempt.json');
+  bindExistingAnimation(files, key);
+  try {
+    const reason = await makeModel(files, key, take, given);
+    if (!reason) bindAnimation(files, key, 'model');
+    files.write(attempt, { state: reason ? 'fallback' : 'ready', reason, at: new Date().toISOString() });
+    return !reason;
+  } catch (error) {
+    files.write(attempt, { state: 'failed', reason: error instanceof Error ? error.message : String(error), at: new Date().toISOString() });
+    throw error;
+  }
+}
+
+async function makeModel(files: WorldFiles, key: string, take: number, given: string): Promise<string | null> {
+  const finishSettings = (mesh: Buffer) => {
+    const settings = animationSettings(files, key, {}, mesh);
+    saveAnimationSettings(files, key, settings);
+    return { ...(settings.texture === 'model' && { texture: 'model' as const }), ...(settings.coatCorrection !== undefined && { coatCorrection: settings.coatCorrection }) };
+  };
+  const world = files.world();
+  const found = [world.hero, ...world.places.flatMap((p) => p.things)].find((w) => w.key === key);
+  if (!found) throw new Error(`no hero or NPC called ${key}`);
+  const supplied = given ? fs.readFileSync(given) : undefined;
+  if (supplied) {
+    const bad = badModel(readShape(supplied));
+    if (bad) throw new Error(`${key}: supplied 3D model rejected: ${bad}`);
+  }
+  const who = fixedLooks(files, found);
+  const painting = fs.readFileSync(files.path('cast', `${key}-painting.png`));
+  const out = (name: string) => files.path('cast', key, 'model', name);
+
+  // Not a person on two legs (cast/figures.json): painted as it is, no skeleton; it hops and squashes as one body.
+  const creature = readBodies(files, fs.existsSync)[key]?.upright === false;
+  // Each stage says its name ("<key>: ..."), and each side is written as it lands: Studio follows both live.
+  console.log(`${key}: painting 4 sides`);
+  let views: Awaited<ReturnType<typeof paintViews>>;
+  try {
+    views = await paintViews(files.memo, key, who.looks ?? '', painting, take, creature, (name, png) => files.write(out(`${name}.png`), png));
+  } catch (error) {
+    // Refused even in calm words: the model made before stays (a changed prompt reran it), else the 2D rig walks.
+    if (!refusedByFilter(error)) throw error;
+    if (fs.existsSync(out('model.json')) && fs.existsSync(out('model.glb'))) {
+      console.log(`${key}: the image safety filter refused its 4 sides; the 3D model made before stays`);
+      return null;
+    }
+    console.log(`${key}: no 3D model: the image safety filter refused its 4 sides; ${creature ? 'the painted figure hops as it is' : 'the game walks the 2D rig'}`);
+    return 'the image safety filter refused its 4 sides';
+  }
+  // TRELLIS sometimes makes a flat card of a flat drawing: other seeds, then the front alone (depth guessed),
+  // and with none of them a body, no model: the character walks with its 2D rig.
+  const all = [views.front, views.back, views.left, views.right];
+  const tries = [[1, all], [2, all], [3, all], [1, [views.front]]] as const;
+  let shell: Buffer | undefined;
+  // A Space that answers with an error (busy, restarting, a lost file) is asked again after a pause, on the next try;
+  // one that keeps failing leaves the character in 2D, so the world is still built and playable.
+  let unavailable: string | undefined;
+  let failures = 0;
+  let built: Buffer | undefined;
+  let rigDown: string | undefined;
+  let misplaced: string | undefined;
+  for (const [seed, from] of tries) {
+    if (given) break;
+    console.log(`${key}: TRELLIS builds the body${seed > 1 || from.length === 1 ? ` (try ${seed + (from.length === 1 ? 3 : 0)})` : ''}`);
+    let made: Buffer;
+    try {
+      made = await reconstruct(files.memo, key, [...from], seed);
+    } catch (error) {
+      unavailable = error instanceof Error ? error.message : String(error);
+      console.log(`${key}: TRELLIS failed: ${unavailable}`);
+      if (lasting(unavailable) || ++failures > SERVICE_PAUSES.ms.length) break;
+      const pause = SERVICE_PAUSES.ms[failures - 1];
+      console.log(`${key}: asking TRELLIS again in ${Math.round(pause / 1000)} s`);
+      await new Promise((resolve) => setTimeout(resolve, pause));
+      continue;
+    }
+    unavailable = undefined;
+    const bad = badModel(readShape(made));
+    if (bad) {
+      console.log(`${key}: TRELLIS (seed ${seed}${from.length === 1 ? ', front only' : ''}) made a model that is ${bad}`);
+      continue;
+    }
+    if (creature) { shell = made; break; }
+    // The auto-rig guesses joints from the shape alone and is deterministic: a skeleton it misplaces (a long
+    // robe hides the legs) comes back the same for the same body, so the next TRELLIS body gets the next try.
+    console.log(`${key}: rigging the skeleton`);
+    let skinned: Buffer;
+    try {
+      skinned = await autoRig(files.memo, key, made);
+    } catch (error) {
+      rigDown = error instanceof Error ? error.message : String(error);
+      break;
+    }
+    misplaced = rigProblem(skinned) ?? undefined;
+    if (!misplaced) { shell = made; built = skinned; break; }
+    console.log(`${key}: auto-rig on TRELLIS seed ${seed}${from.length === 1 ? ', front only' : ''}: ${misplaced}`);
+  }
+  const rejected = out('model.json');
+  const reject = (why: string) => {
+    if (fs.existsSync(rejected)) fs.renameSync(rejected, out('model-rejected.json'));
+    console.log(`${key}: no 3D model: ${why}; ${creature ? 'the painted figure hops as it is' : 'the game walks the 2D rig'}`);
+    return why;
+  };
+  if (rigDown) return reject(`${SERVICE_DOWN}: ${rigDown}`);
+  if (!given && !shell) {
+    // An older model of this character (a flat one, kept before this gate) must not stay in the game.
+    return reject(unavailable ? `${SERVICE_DOWN}: ${unavailable}` : misplaced ? `every skeleton the auto-rig made was misplaced (${misplaced})` : 'every reconstruction was flat or invalid');
+  }
+  if (creature) {
+    // Make-It-Animatable rigs a person's skeleton only; a creature keeps TRELLIS's mesh as it came (no standing up:
+    // a cat or a frog is not meant to be straight up and down).
+    const mesh = supplied ?? shell!;
+    files.write(out('model.glb'), mesh);
+    const fits = await fitViews(mesh, views);
+    files.write(out('model.json'), { glb: 'model.glb', creature: true, views: fits, ...finishSettings(mesh) });
+    console.log(`${key}: ${out('model.glb')} · a creature, no skeleton: hops, squashes and blinks as one body · views ${Object.entries(fits).map(([v, f]) => `${v} ${f.iou}`).join(', ')}`);
+    return null;
+  }
+  built ??= supplied!;
+  const misrigged = rigProblem(built);
+  if (misrigged) return reject(`rigged body rejected: ${misrigged}`);
+  const bad = badModel(readShape(built));
+  if (bad) return reject(`rigged body rejected: ${bad}`);
+  const tilt = lean(readShape(built));
+  const rigged = standUp(built);
+  const standingProblem = badModel(readShape(rigged));
+  if (standingProblem) return reject(`standing body rejected: ${standingProblem}`);
+  files.write(out('model.glb'), rigged);
+
+  const fits = await fitViews(rigged, views);
+  files.write(out('model.json'), { glb: 'model.glb', views: fits, ...finishSettings(rigged) });
+  console.log(`${key}: ${await relaxModel(files, key)}`);
+  const degrees = (slope: number) => Math.round(Math.atan(slope) * 180 / Math.PI * 10) / 10;
+  console.log(`${key}: ${out('model.glb')} · stood up ${degrees(tilt.z)}° forward, ${degrees(tilt.x)}° sideways · views ${Object.entries(fits).map(([v, f]) => `${v} ${f.iou}`).join(', ')}`);
+  return null;
+}
+
+/**
+ * What the Blender round trip broke, or null. The face is painted onto the surface from the views, so a head
+ * that moved, or a mesh whose corners came apart (flat shading splits every triangle on export: faceted
+ * normals, a blotchy torn face on the talk sprites), must not replace the rig that worked.
+ */
+export function relaxDamage(source: Buffer, relaxed: Buffer, report: RelaxReport): string | null {
+  if ((report.headMove ?? 0) > 0.002) return `the head moved ${(report.headMove! * 100).toFixed(2)}% of the height`;
+  const before = readShape(source).positions.length / 3, after = readShape(relaxed).positions.length / 3;
+  if (after > before * 1.3) return `the mesh came apart on export (${before} -> ${after} corners)`;
+  return null;
+}
+
+/**
+ * With a local Blender, the model's rest pose becomes calm (arms down, feet under the hips): the game's walk
+ * then turns bones a little from rest instead of 100 degrees from TRELLIS's raised arms, which pinched the
+ * shoulders, glued sleeves to the chest and splayed the hands. model.source.glb keeps the rig as it came, so
+ * this can run again; model.json says relaxed. Says what happened, in a line.
+ */
+export async function relaxModel(files: WorldFiles, key: string, again = false): Promise<string> {
+  const out = (name: string) => files.path('cast', key, 'model', name);
+  const info = files.readJson(out('model.json')) as { glb: string; relaxed?: boolean; creature?: boolean };
+  if (info.creature) return 'a creature has no skeleton to relax';
+  if (info.relaxed && !again) return 'rest pose already relaxed';
+  const blender = await findBlender();
+  if (!blender) return 'rest pose as TRELLIS built it (no local Blender; install Blender 3.6+ for calmer walks)';
+  const source = fs.existsSync(out('model.source.glb')) ? fs.readFileSync(out('model.source.glb')) : fs.readFileSync(out(info.glb));
+  const done = await relaxPose(source, (line) => console.log(`${key}: ${line}`));
+  if (!done) return 'rest pose as TRELLIS built it (Blender could not relax it)';
+  const problem = rigProblem(done.glb) ?? badModel(readShape(done.glb)) ?? relaxDamage(source, done.glb, done.report);
+  if (problem) return `rest pose as TRELLIS built it (relaxed body rejected: ${problem})`;
+  if (!fs.existsSync(out('model.source.glb'))) files.write(out('model.source.glb'), source);
+  files.write(out('model.glb'), done.glb);
+  files.write(out('model.json'), { ...info, glb: 'model.glb', relaxed: true });
+  const arms = Object.values(done.report.armTurn ?? {}).map(Math.round).join('/');
+  return `Blender ${blender.version} relaxed the rest pose (arms turned ${arms}° down, feet under the hips)`;
+}

package/app/src/commands/paint.ts

@@ -0,0 +1,182 @@
+import { worldStyleReference } from '../world/style-reference.ts';
+// diorama paint <slug> [place...]: painting.png for each laid-out place.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { writeBrief } from '../scene/brief.ts';
+import { seedRan } from '../scene/carry.ts';
+import { addsPerson, critique, paintedPeople, repaint } from '../scene/critic.ts';
+import { readCorrections, writeCorrections } from '../scene/corrections.ts';
+import { Layout } from '../scene/layout.ts';
+import { paintPlace } from '../scene/paint.ts';
+import { alignPainting, PaintingLayoutError, paintingLayoutHash } from '../scene/paint-layout.ts';
+import { paintPhoto } from '../scene/photo.ts';
+import { restylePlace } from '../scene/restyle.ts';
+import { refusedByFilter, reword, withWords, worded, type Words } from '../scene/words.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { drawingsIn } from '../world/drawings.ts';
+import { WorldFiles } from '../world/files.ts';
+import { approvedConcept } from '../world/sketch.ts';
+import { markStyled, placeStyle, readStyled } from '../world/styled.ts';
+
+/** Rewords Spark may try after the image safety filter refuses a painting, before the place is set aside. */
+const REWORDS = 2;
+
+defineCommand({
+  name: 'paint',
+  usage: 'paint <slug> [place...]  brief, paint, critique and repaint laid-out places [--take N]',
+  async run(args) {
+    const takeArg = takeOption(args, 'take', '');
+    const [slug, ...only] = args;
+    if (!slug) throw new Error('usage: diorama paint <slug> [place...] [--take N]');
+    const files = new WorldFiles(slug);
+    const base = files.world();
+    const places = base.places.filter((p) => only.length === 0 || only.includes(p.key));
+    await Promise.all(places.map(async (place) => {
+      // The place's own style, when the person gave it one, is the world's style for everything painted here.
+      const style = placeStyle(files, base, place.key);
+      // --take wins; else the take the place's corrections keep (a new take the build asked for stays across rebuilds).
+      const take = takeArg ? Number(takeArg) : readCorrections(files.place(place.key)).take ?? 0;
+      const world = { ...base, style };
+      const layout = Layout.parse(files.readJson(files.place(place.key, 'layout.json')));
+      const blockin = fs.readFileSync(files.place(place.key, 'blockin.png'));
+      const fromPhoto = fs.existsSync(files.place(place.key, 'photo.png'));
+      const concept = approvedConcept(files, 'place', place.key);
+      const styleReference = worldStyleReference(files, style);
+      // The first painting is kept while its block-in, layout and take stay the same, even without the model
+      // cache (a world copied without memo/): a person's region repaint must not repaint the whole place.
+      const hash = (words?: Words) => {
+        const h = createHash('sha256').update(blockin).update(JSON.stringify(layout)).update(String(take));
+        // A new wording paints the place anew; a place never reworded keeps the inputs it had.
+        if (words) h.update(JSON.stringify(words));
+        if (concept) h.update(concept);
+        if (styleReference) h.update(styleReference);
+        return h.digest('hex');
+      };
+      let words = readCorrections(files.place(place.key)).words;
+      let inputs = hash(words);
+      const kept = files.place(place.key, 'painting-first.json');
+      const mtime = (f: string) => fs.statSync(files.place(place.key, f)).mtimeMs;
+      const have = ['painting-first.png', 'brief.json', 'critique.json'].every((f) => fs.existsSync(files.place(place.key, f)));
+      // Worlds painted before this record: the first painting counts when it is newer than what it was painted from.
+      const same = fs.existsSync(kept)
+        ? (files.readJson(kept) as { inputs?: string }).inputs === inputs
+        : have && take === 0 && mtime('painting-first.png') >= Math.max(mtime('blockin.png'), mtime('layout.json'));
+      const reuse = have && same;
+      const record = (fs.existsSync(kept) ? files.readJson(kept) : {}) as { inputs?: string; applied?: string[] };
+      let first: Buffer;
+      let found: Awaited<ReturnType<typeof critique>>;
+      // The style changed since this place was painted (style_set): Muse repaints the painting as it is, every
+      // fix in it, in the new style, keeping the composition, so masks, stand spots and the person's fixes still fit.
+      const was = readStyled(files).places[place.key];
+      const restyled = reuse && !!was && was !== style && fs.existsSync(files.place(place.key, 'painting.png'));
+      if (restyled) {
+        const brief = files.readJson(files.place(place.key, 'brief.json')) as Awaited<ReturnType<typeof writeBrief>>;
+        const told = worded(place, words);
+        first = await restylePlace(files.memo, told, fs.readFileSync(files.place(place.key, 'painting.png')), was, style, brief, take, drawingsIn(files, place));
+        console.log(`  ${place.key}: repainted in the new style, composition kept`);
+        files.write(files.place(place.key, 'painting-first.png'), first);
+        found = await critique(files.memo, told, brief, first);
+        files.write(files.place(place.key, 'critique.json'), found);
+      } else if (reuse) {
+        first = fs.readFileSync(files.place(place.key, 'painting-first.png'));
+        found = files.readJson(files.place(place.key, 'critique.json')) as typeof found;
+        // The critic is asked again (a memo hit while its prompt stays the same): what it now finds unwanted (a person
+        // painted in, a double of the place's NPC) is painted out over the painting as it is; the rest stays.
+        const brief = files.readJson(files.place(place.key, 'brief.json')) as Awaited<ReturnType<typeof writeBrief>>;
+        // A person the critic itself once asked for ("a child kneeling at the dock edge") is taken out of its fixes,
+        // so the painting is made again from the first one without them.
+        const before = found.issues.length;
+        found = { issues: found.issues.filter((i) => !addsPerson(i)) };
+        const again = await critique(files.memo, worded(place, words), brief, first);
+        // People are looked for on the painting as the game shows it, with every fix in, not only the first one.
+        const shown = fs.existsSync(files.place(place.key, 'painting.png')) ? fs.readFileSync(files.place(place.key, 'painting.png')) : first;
+        for (const p of shown === first ? [] : await paintedPeople(files.memo, place.key, shown)) {
+          again.issues.push({ key: 'person', problem: 'unwanted', region: p.box, fix: `Paint out the ${p.what}: continue what is behind them (planks, water, wall), add nothing new` });
+        }
+        const had = new Set(found.issues.map((i) => JSON.stringify([i.region, i.fix])));
+        const unwanted = again.issues.filter((i) => i.problem === 'unwanted' && !had.has(JSON.stringify([i.region, i.fix])));
+        if (unwanted.length || found.issues.length !== before) {
+          found = { issues: [...found.issues, ...unwanted].slice(0, 8) };
+          files.write(files.place(place.key, 'critique.json'), found);
+        }
+      } else {
+        let brief: Awaited<ReturnType<typeof writeBrief>>;
+        // When the image safety filter refuses the painting, Spark rewords the place and it is painted again;
+        // the wording is kept in corrections.json, so every later paint asks with it and no rebuild repeats the refusal.
+        // A wording Spark made in an earlier run counts its rewords, so the next one is a new ask.
+        const before = words?.tries ?? 0;
+        for (let refusals = 0; ; refusals++) {
+          const told = worded(place, words);
+          brief = withWords(await writeBrief(files.memo, world, told, layout), words);
+          files.write(files.place(place.key, 'brief.json'), brief);
+          try {
+            first = fromPhoto
+              ? await paintPhoto(files.memo, world, told, blockin, brief, take, concept, styleReference)
+              : await paintPlace(files.memo, world, told, layout, blockin, brief, take, drawingsIn(files, place), concept, styleReference);
+            break;
+          } catch (error) {
+            if (!refusedByFilter(error)) throw error;
+            if (refusals >= REWORDS) {
+              throw new Error(`the image safety filter refused to paint ${place.key} ${refusals + 1} times, also after ${refusals} reword(s) by Spark: `
+                + `reword its scene and looks with paint_words (calm, plain words), which paints it again (${error instanceof Error ? error.message.slice(0, 160) : error})`);
+            }
+            words = await reword(files.memo, told, layout, brief, before + refusals);
+            const fixes = readCorrections(files.place(place.key));
+            fixes.words = words;
+            writeCorrections(files.place(place.key), fixes);
+            console.log(`  ${place.key}: the image safety filter refused the painting; Spark reworded it (kept in corrections.json), painting again: ${words.shows ?? place.shows}`);
+          }
+        }
+        inputs = hash(words);
+        files.write(files.place(place.key, 'painting-first.png'), first);
+        found = await critique(files.memo, worded(place, words), brief, first);
+        files.write(files.place(place.key, 'critique.json'), found);
+      }
+      // The person's repaints join the critic's. When the painting already has every earlier fix, only the new
+      // ones are painted over it, so the rest of the place stays exactly as the person saw it.
+      const asked = readCorrections(files.place(place.key)).repaint.map((r) => ({ key: 'person', problem: 'wrong' as const, region: r.region, fix: r.fix }));
+      const fixes = { issues: [...found.issues, ...asked] };
+      const id = (i: (typeof fixes.issues)[number]) => JSON.stringify([i.region, i.fix]);
+      // After a restyle the person's repaints are in the picture already; only the critic's new findings are painted.
+      const done = restyled ? asked.map(id) : reuse && fs.existsSync(files.place(place.key, 'painting.png')) ? record.applied ?? (have && !fs.existsSync(kept) ? found.issues.map(id) : null) : null;
+      const onTop = done && done.every((d) => fixes.issues.some((i) => id(i) === d));
+      const fresh = onTop ? fixes.issues.filter((i) => !done.includes(id(i))) : fixes.issues;
+      const from = onTop && !restyled ? fs.readFileSync(files.place(place.key, 'painting.png')) : first;
+      // A place built before the steps kept their painting (.ran/) gets it now, so this first repaint carries too.
+      const seeded = seedRan(files.place(place.key));
+      if (seeded.length) console.log(`  ${place.key}: ${seeded.join(', ')} take the painting before this repaint as the one they ran on`);
+      let painting: Buffer;
+      try {
+        painting = await repaint(files.memo, place, from, { issues: fresh });
+      } catch (error) {
+        // The critic's own fixes are nice to have: a refused repaint leaves the painting as it is. The person's are not.
+        if (!refusedByFilter(error) || asked.length) throw error;
+        console.log(`  ${place.key}: the image safety filter refused the critic's repaint; the painting is kept without it`);
+        painting = from;
+      }
+      // Inspect the FINAL candidate, including region fixes and restyles. Only a passing composition may
+      // become the input to masks/derive. Old paid art stays on disk until a replacement passes.
+      if (!fromPhoto) {
+        const report = files.place(place.key, 'painting-layout.json');
+        const previous = fs.existsSync(report) ? files.readJson(report) as { ok?: boolean; inputs?: string } : undefined;
+        if (!previous?.ok || previous.inputs !== paintingLayoutHash(place, layout, blockin, painting)) {
+          files.write(report, { ok: false, pending: true });
+          try {
+            const brief = files.readJson(files.place(place.key, 'brief.json')) as Awaited<ReturnType<typeof writeBrief>>;
+            const aligned = await alignPainting(files.memo, worded(place, words), layout, blockin, painting, brief, take, fixes.issues.map((i) => i.fix));
+            painting = aligned.painting;
+            files.write(report, { ok: true, inputs: paintingLayoutHash(place, layout, blockin, painting), attempts: aligned.attempts });
+          } catch (error) {
+            files.write(report, { ok: false, attempts: error instanceof PaintingLayoutError ? error.attempts : [], error: String(error) });
+            throw error;
+          }
+        }
+      }
+      files.write(files.place(place.key, 'painting.png'), painting);
+      files.write(kept, { inputs, applied: fixes.issues.map(id) });
+      markStyled(files, 'places', place.key, style);
+      console.log(`${place.key}: painted, ${fresh.length} fix(es)${onTop ? ' over the last painting' : ''}${fresh.map((i) => ` · ${i.key} ${i.problem}`).join('')}`);
+    }));
+    console.log(`calls sent: spark ${files.memo.sent.spark}, muse ${files.memo.sent.muse}`);
+  },
+});

package/app/src/commands/plates.ts

@@ -0,0 +1,97 @@
+// diorama plates <slug> [place...]: plates/<thing>.png for every thing the story lets the hero carry off.
+import fs from 'node:fs';
+import { maskFromPng, maskArea, maskToPng, type Mask } from '../image/mask.ts';
+import { dilate, intersect } from '../image/raster.ts';
+import { defineCommand } from '../registry.ts';
+import { Brief } from '../scene/brief.ts';
+import { Layout } from '../scene/layout.ts';
+import { carryFrom, paintingFor, ran } from '../scene/carry.ts';
+import { changePlate, changeShape, plateFor } from '../scene/plates.ts';
+import { removableThings } from '../story/engine.ts';
+import { Story } from '../story/schema.ts';
+import { WorldFiles } from '../world/files.ts';
+
+/** How far from its thing a plate looks at the painting: its grown area, the ring it is matched to, a close view's crop. */
+const PLATE_REACH = 96;
+
+defineCommand({
+  name: 'plates',
+  usage: 'plates <slug> [place...]  paint each place without the things the hero can take, and with the things the story changes (needs story.json)',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: diorama plates <slug> [place...]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    if (!fs.existsSync(files.path('story.json'))) {
+      console.log('no story.json: nothing is carried off, no plates needed');
+      return;
+    }
+    const story = Story.parse(files.readJson(files.path('story.json')));
+    const removable = removableThings(story);
+    const places = world.places.filter((p) => only.length === 0 || only.includes(p.key));
+    await Promise.all(places.map(async (place) => {
+      const at = (...parts: string[]) => files.place(place.key, ...parts);
+      const painted = fs.readFileSync(at('painting.png'));
+      // After a small repaint a plate the change does not reach is the one made last time (the memo keeps it).
+      const carry = await carryFrom(at(), 'plates', painted);
+      fs.rmSync(at('plates'), { recursive: true, force: true });
+      fs.rmSync(at('changes'), { recursive: true, force: true });
+      const keys = removable.filter((r) => r.place === place.key).map((r) => r.thing);
+      const changes = story.changes.map((c, i) => ({ ...c, i })).filter((c) => c.place === place.key);
+      if (!keys.length && !changes.length) return ran(at(), 'plates', carry?.old ?? painted);
+      const notes = (files.readJson(at('masks.json')) as { things: Record<string, { phrase: string }> }).things;
+      // A plate is painted around its thing and matched to a ring around it.
+      const around = (mask: Mask) => paintingFor(carry, painted, mask, PLATE_REACH);
+      // changes/<i>.png: the place once story.changes[i] holds, drawn by the runtime over the painting.
+      // Every plate is its own Muse edit: they are painted side by side.
+      const changed = Promise.all(changes.map(async (c) => {
+        if (!notes[c.thing]) {
+          console.log(`  ${place.key}: ${c.thing} has no mask, no change plate`);
+          return;
+        }
+        const mask = await maskFromPng(fs.readFileSync(at('masks', `${c.thing}.png`)));
+        // What the hero can take keeps its own pixels: Muse redraws all it sees, and a ticket it moved would lie
+        // beside the one the player clicks (its outline off), and stay when the hero takes it. Props may be
+        // overgrown: a basket that grew a rope may reach over the door beside it.
+        const others = await Promise.all(keys.filter((k) => k !== c.thing && fs.existsSync(at('masks', `${k}.png`)))
+          .map(async (k) => maskFromPng(fs.readFileSync(at('masks', `${k}.png`)))));
+        const plate = await changePlate(files.memo, place, { key: c.thing, phrase: notes[c.thing].phrase, mask }, around(mask), c.looks, others);
+        files.write(at('changes', `${c.i}.png`), plate);
+        // changes/<i>-shape.png: the thing as the plate draws it, for its hover outline while the change holds.
+        const shape = await changeShape(files.memo, place, { key: c.thing, mask }, plate, c.looks).catch((error) => {
+          console.log(`  ${place.key}: ${c.thing}: no shape for its change (${error instanceof Error ? error.message : error})`);
+          return undefined;
+        });
+        if (shape) files.write(at('changes', `${c.i}-shape.png`), await maskToPng(shape));
+        else console.log(`  ${place.key}: ${c.thing}: SAM found no clear shape in its change plate; the outline keeps the painted one`);
+        console.log(`${place.key}: ${c.thing} once ${c.when.join(', ')}: ${c.looks}`);
+      }));
+      if (!keys.length) {
+        await changed;
+        return ran(at(), 'plates', carry?.old ?? painted);
+      }
+      const layout = Layout.parse(files.readJson(at('layout.json')));
+      const brief = Brief.parse(files.readJson(at('brief.json')));
+      const floors = await Promise.all(layout.floors.map(async (f) => ({ f, mask: await maskFromPng(fs.readFileSync(at('masks', 'floors', `${f.key}.png`))) })));
+      const made = await Promise.all(keys.map(async (key) => {
+        if (!notes[key]) {
+          console.log(`  ${place.key}: ${key} has no mask, no plate`);
+          return [];
+        }
+        const mask = await maskFromPng(fs.readFileSync(at('masks', `${key}.png`)));
+        // The floor around it says what to paint where it stood.
+        const ring = dilate(mask, 16);
+        const under = floors.map(({ f, mask: m }) => ({ f, px: maskArea(intersect(m, ring)) })).sort((a, b) => b.px - a.px)[0];
+        const ground = under?.px ? (brief.looks[under.f.key] ?? under.f.is) : 'the ground around it';
+        const plate = await plateFor(files.memo, place, { key, phrase: notes[key].phrase, mask }, around(mask), ground);
+        files.write(at('plates', `${key}.png`), plate.png);
+        console.log(`${place.key}: plate for ${key} (seam ${plate.ringError.toFixed(1)}, stain ${Math.round(plate.stain * 100)}%)${plate.stillThere ? ' (SAM still finds it: check the plate)' : ''}`);
+        return [[key, { stillThere: plate.stillThere, iou: Math.round(plate.iou * 100) / 100, ringError: Math.round(plate.ringError * 10) / 10, stain: Math.round(plate.stain * 100) / 100 }] as const];
+      }));
+      await changed;
+      const report = Object.fromEntries(made.flat());
+      files.write(at('plates.json'), report);
+      ran(at(), 'plates', carry?.old ?? painted);
+    }));
+    console.log(`calls sent: muse ${files.memo.sent.muse}, sam ${files.memo.sent.sam}`);
+  },
+});