@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/commands/masks.ts

@@ -0,0 +1,117 @@
+// diorama masks <slug> [place...]: masks/<thing>.png, masks/floors/<floor>.png and masks.json per place.
+import fs from 'node:fs';
+import { maskFromPng, maskToPng, type Mask } from '../image/mask.ts';
+import { PALETTE, svgLabel, tintOver } from '../image/overlay.ts';
+import { defineCommand } from '../registry.ts';
+import { Brief } from '../scene/brief.ts';
+import { carryFrom, ran, remakes, tilesLine } from '../scene/carry.ts';
+import { brushed, correctCells, correctSpots, readCorrections } from '../scene/corrections.ts';
+import { Layout } from '../scene/layout.ts';
+import { locateThings, markFloors } from '../scene/locate.ts';
+import { checkMasks, type MaskCheck } from '../scene/maskcheck.ts';
+import { maskFloors, maskThings } from '../scene/masks.ts';
+import { paintingLayoutHash } from '../scene/paint-layout.ts';
+import { maskBox, type Rect } from '../image/raster.ts';
+import { WorldFiles } from '../world/files.ts';
+
+defineCommand({
+  name: 'masks',
+  usage: 'masks <slug> [place...]  find each thing and floor in the painting with Spark and SAM 3.1',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: diorama masks <slug> [place...]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    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);
+      fs.rmSync(at('verify.json'), { force: true });
+      const layout = Layout.parse(files.readJson(at('layout.json')));
+      const brief = Brief.parse(files.readJson(at('brief.json')));
+      const painting = fs.readFileSync(at('painting.png'));
+      // A rejected/stale checked painting must not be rescued by masks and invented floor strokes.
+      // Legacy worlds without a report remain editable; rebuilding from paint checks them too.
+      if (!fs.existsSync(at('photo.png')) && fs.existsSync(at('painting-layout.json'))) {
+        const report = files.readJson(at('painting-layout.json')) as { ok?: boolean; inputs?: string };
+        if (!report.ok || report.inputs !== paintingLayoutHash(place, layout, fs.readFileSync(at('blockin.png')), painting)) {
+          throw new Error(`PAINT_LAYOUT_MISMATCH ${place.key}: painting/layout changed or its composition check failed; rebuild this place from paint to inspect and repair it before masks`);
+        }
+      }
+      const flagged: string[] = [];
+      const log = (line: string) => {
+        flagged.push(line);
+        console.log(`  ${place.key}: ${line}`);
+      };
+
+      // After a small repaint, what it did not reach is found again on the old painting: the memo has those answers.
+      const carry = await carryFrom(at(), 'masks', painting);
+      if (carry) console.log(`  ${place.key}: ${tilesLine(carry)}; only what it reaches is asked again`);
+      const seen = carry?.old ?? painting;
+      const [found, marked] = await Promise.all([
+        locateThings(files.memo, place, brief, seen),
+        markFloors(files.memo, place, layout, brief, seen),
+      ]);
+      files.write(at('locate.json'), { things: found, floors: marked });
+      // The person's fixes go in before SAM is asked and their brush strokes after, every time.
+      const fixes = readCorrections(at());
+      const spots = correctSpots(found, fixes);
+      const cells = correctCells(marked, fixes);
+      const before = async (file: string): Promise<Mask | undefined> => (carry && fs.existsSync(at('masks', file)) ? maskFromPng(fs.readFileSync(at('masks', file))) : undefined);
+      // A thing or floor keeps its mask when the change does not reach it, or only grazes a big one.
+      const keptThing = new Set<string>();
+      const keptFloor = new Set<string>();
+      for (const t of place.things) {
+        const last = await before(`${t.key}.png`);
+        if (carry && last && !remakes(carry, last)) keptThing.add(t.key);
+      }
+      for (const f of layout.floors) {
+        const last = await before(`floors/${f.key}.png`);
+        if (carry && last && !remakes(carry, last)) keptFloor.add(f.key);
+      }
+      const split = <T>(all: T[], kept: (x: T) => boolean) => [all.filter(kept), all.filter((x) => !kept(x))];
+      const [oldThings, newThings] = split(place.things, (t) => keptThing.has(t.key));
+      const [oldFloors, newFloors] = split(layout.floors, (f) => keptFloor.has(f.key));
+      const [thingsOld, thingsNew, floorsOld, floorsNew] = await Promise.all([
+        oldThings.some((t) => t.role !== 'npc') ? maskThings(files.memo, { ...place, things: oldThings }, layout, spots, carry!.old, log) : [],
+        newThings.some((t) => t.role !== 'npc') ? maskThings(files.memo, { ...place, things: newThings }, layout, spots, painting, log) : [],
+        oldFloors.length ? maskFloors(files.memo, place, { ...layout, floors: oldFloors }, cells, carry!.old, log) : [],
+        newFloors.length ? maskFloors(files.memo, place, { ...layout, floors: newFloors }, cells, painting, log) : [],
+      ]);
+      const inOrder = <T extends { key: string }>(keys: string[], got: T[]) => keys.flatMap((k) => got.filter((g) => g.key === k));
+      const things = inOrder(place.things.map((t) => t.key), [...thingsOld, ...thingsNew]).map((t) => brushed(t, fixes.things[t.key]?.strokes));
+      const floors = inOrder(layout.floors.map((f) => f.key), [...floorsOld, ...floorsNew]).map((f) => brushed(f, fixes.floors[f.key]?.strokes));
+      if (carry) console.log(`  ${place.key}: kept ${thingsOld.length}/${things.length} things and ${floorsOld.length}/${floors.length} floors as they were; masked again: ${[...thingsNew, ...floorsNew].map((m) => m.key).join(', ') || 'nothing'}`);
+      const lastChecks = carry && fs.existsSync(at('masks.json')) ? ((files.readJson(at('masks.json')) as { things?: Record<string, { box?: Rect; check?: MaskCheck }> }).things ?? {}) : {};
+
+      fs.rmSync(at('masks'), { recursive: true, force: true });
+      for (const t of things) files.write(at('masks', `${t.key}.png`), await maskToPng(t.mask));
+      for (const f of floors) files.write(at('masks', 'floors', `${f.key}.png`), await maskToPng(f.mask));
+      const layers = [...floors.map((f) => ({ key: f.key, mask: f.mask, alpha: 0.25 })), ...things.map((t) => ({ key: t.key, mask: t.mask, alpha: 0.45 }))];
+      const tints = layers.map((l, i) => ({ mask: l.mask, alpha: l.alpha, rgb: PALETTE[i % PALETTE.length] }));
+      const labels = [...floors.map((f) => ({ key: f.key, box: maskBox(f.mask) })), ...things.map((t) => ({ key: t.key, box: t.box as Rect | undefined }))]
+        .map((l, i) => (l.box ? svgLabel(l.box[0] + 4, l.box[1] + 18, l.key, PALETTE[i % PALETTE.length]) : ''));
+      files.write(at('masks', 'overlay.png'), await tintOver(painting, tints, labels.join('')));
+      // A corrected box guides SAM; it does not prove what SAM cut out. Kept masks retain their check.
+      let checks: Record<string, MaskCheck> = Object.fromEntries(things.flatMap((t) => (keptThing.has(t.key) && lastChecks[t.key]?.check && JSON.stringify(t.box) === JSON.stringify(lastChecks[t.key].box) ? [[t.key, lastChecks[t.key].check!]] : [])));
+      try {
+        const look = things.filter((t) => !checks[t.key]);
+        // Asked by what the thing is (the world's words), not by how the brief dressed it: a brief that described
+        // "the empty stall the cow uses" let a mask on an empty stall pass.
+        if (look.length) checks = { ...checks, ...await checkMasks(files.memo, place.key, painting, look.map((t) => ({ key: t.key, looks: place.things.find((x) => x.key === t.key)?.looks ?? brief.looks[t.key] ?? t.key, box: t.box as Rect | undefined }))) };
+        for (const [key, c] of Object.entries(checks)) if (!c.ok) log(`${key}: Spark sees ${c.seen ?? 'something else'} in its mask`);
+      } catch (error) {
+        throw new Error(`mask check failed: ${error instanceof Error ? error.message : error}`);
+      }
+      const round = (v: number) => Math.round(v * 100) / 100;
+      files.write(at('masks.json'), {
+        things: Object.fromEntries(things.map(({ key, mask: _, ...t }) => [key, { ...t, ...(checks[key] && { check: checks[key] }) }])),
+        floors: Object.fromEntries(floors.map(({ key, mask: _, iouCells, iouLayout, ...f }) => [key, { ...f, iouCells: round(iouCells), iouLayout: round(iouLayout) }])),
+        flagged,
+      });
+      // After a carry the old painting stays the one the answers belong to, so a rerun on this painting asks nothing new.
+      ran(at(), 'masks', carry?.old ?? painting);
+      const coarse = [...things, ...floors].filter((m) => m.coarse).map((m) => m.key);
+      console.log(`${place.key}: ${things.length} things, ${floors.length} floors${coarse.length ? `, coarse: ${coarse.join(', ')}` : ''}`);
+    }));
+    console.log(`calls sent: spark ${files.memo.sent.spark}, sam ${files.memo.sent.sam}`);
+  },
+});

package/app/src/commands/mcp.ts

@@ -0,0 +1,52 @@
+// diorama mcp: the Studio's actions as an MCP server over stdio, for Muse Code (or any MCP client) started
+// by hand. With a Studio running for this folder it forwards every call there, so the page shows the agent's
+// work live; without one it runs the actions itself.
+import path from 'node:path';
+import readline from 'node:readline';
+import '../actions/index.ts';
+import { defineCommand } from '../registry.ts';
+import { Events } from '../studio/events.ts';
+import { snapshotBeforeJob } from '../studio/history.ts';
+import { Jobs } from '../studio/jobs.ts';
+import { handleMcp, type Reply } from '../studio/mcp.ts';
+import { readStudioFile } from '../studio/discovery.ts';
+
+defineCommand({
+  name: 'mcp',
+  usage: 'mcp                     serve the Studio actions as MCP tools on stdio (forwards to a running diorama studio)',
+  async run() {
+    const studio = readStudioFile(process.cwd());
+    const events = new Events();
+    const root = path.resolve('worlds');
+    const ctx = { by: 'agent' as const, root, events, jobs: new Jobs(events, { beforeStart: snapshotBeforeJob(root, events) }) };
+    const out = (reply: Reply | Reply[] | null) => reply && process.stdout.write(`${JSON.stringify(reply)}\n`);
+    // Logs go to stderr: stdout carries only protocol messages.
+    console.error(studio ? `diorama mcp: forwarding to the Studio at ${studio.url}` : 'diorama mcp: no Studio running here, running actions in this process');
+    const lines = readline.createInterface({ input: process.stdin });
+    for await (const line of lines) {
+      if (!line.trim()) continue;
+      let message: unknown;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        out({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+        continue;
+      }
+      if (studio) {
+        const res = await fetch(`${studio.url}mcp`, {
+          method: 'POST',
+          headers: { authorization: `Bearer ${studio.agentToken}`, 'content-type': 'application/json' },
+          body: line,
+        }).catch((error: Error) => ({ ok: false, status: 0, text: async () => error.message }));
+        if (res.status === 202) continue;
+        const text = await res.text();
+        if (res.ok) process.stdout.write(`${text}\n`);
+        else out({ jsonrpc: '2.0', id: (message as { id?: string | number }).id ?? null, error: { code: -32603, message: `the Studio answered ${res.status}: ${text.slice(0, 200)}` } });
+        continue;
+      }
+      if (Array.isArray(message)) out((await Promise.all(message.map((m) => handleMcp(m, ctx)))).filter((r): r is Reply => !!r));
+      else out(await handleMcp(message as Parameters<typeof handleMcp>[0], ctx));
+    }
+    ctx.jobs.stopAll();
+  },
+});

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}`);
+  },
+});