@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/commands/setup.ts

@@ -0,0 +1,85 @@
+// diorama setup: what this machine still needs, and the one place a key is typed in (hidden, in the terminal).
+import { defineCommand, takeOption } from '../registry.ts';
+import { findVault, NO_VAULT, SECRET_NAMES, SECRETS, SecretStore, type SecretName } from '../secrets.ts';
+import { runChecks, type Check } from '../setup/checks.ts';
+
+const MARK: Record<Check['state'], string> = { ok: '  ok      ', missing: '  MISSING ', optional: '  -       ', fail: '  FAIL    ' };
+
+export function printChecks(checks: Check[]) {
+  for (const c of checks) {
+    console.log(`${MARK[c.state]}${c.label}: ${c.detail}`);
+    for (const line of c.fix ?? []) console.log(`            $ ${line}`);
+  }
+}
+
+/** Reads a line without echoing it. Only from a terminal: a pasted key never lands in shell history or argv. */
+function askHidden(question: string): Promise<string> {
+  const stdin = process.stdin;
+  if (!stdin.isTTY) throw new Error('diorama setup reads keys from a terminal only; or set them as environment variables');
+  process.stdout.write(question);
+  return new Promise((resolve, reject) => {
+    let value = '';
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    const done = (error?: Error) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off('data', onData);
+      process.stdout.write('\n');
+      if (error) reject(error);
+      else resolve(value.trim());
+    };
+    const onData = (chunk: string) => {
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') return done();
+        if (ch === '\u0003') return done(new Error('cancelled'));
+        if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1);
+        else if (ch >= ' ') value += ch;
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+async function storeKey(name: SecretName, remove: boolean) {
+  const vault = await findVault();
+  if (!vault) throw new Error(NO_VAULT);
+  const store = new SecretStore(vault);
+  if (remove) {
+    await store.set(name, null);
+    return console.log(`removed ${name} from ${store.file}`);
+  }
+  const value = await askHidden(`${SECRETS[name].label} (${name}), hidden, Enter to skip: `);
+  if (!value) return console.log('skipped');
+  await store.set(name, value);
+  console.log(`stored ${name}: sealed in ${store.file}, its key in the ${vault.name}`);
+}
+
+defineCommand({
+  name: 'setup',
+  usage: 'setup                   check this machine and store keys, typed hidden [--key NAME] [--remove NAME] [--live]',
+  async run(args) {
+    const live = args.includes('--live');
+    const key = takeOption(args, 'key', '');
+    const remove = takeOption(args, 'remove', '');
+    for (const name of [key, remove].filter(Boolean)) {
+      if (!SECRET_NAMES.includes(name as SecretName)) throw new Error(`unknown key ${name}; diorama keeps ${SECRET_NAMES.join(', ')}`);
+    }
+    if (key || remove) return storeKey((key || remove) as SecretName, !!remove);
+
+    let checks = await runChecks({ live });
+    printChecks(checks);
+    // In a terminal, offer to store each missing key right away.
+    const missing = checks.filter((c) => SECRET_NAMES.includes(c.id as SecretName) && c.state !== 'ok');
+    if (process.stdin.isTTY && missing.length && (await findVault())) {
+      console.log('');
+      for (const c of missing) await storeKey(c.id as SecretName, false);
+      checks = await runChecks({ live });
+      console.log('');
+      printChecks(checks);
+    }
+    const blocking = checks.filter((c) => c.state === 'missing' || c.state === 'fail');
+    console.log(blocking.length ? `\n${blocking.length} to fix before a full build: ${blocking.map((c) => c.label).join(', ')}` : '\nready to build');
+  },
+});

package/app/src/commands/sound.ts

@@ -0,0 +1,90 @@
+// diorama sound <slug>: Spark plans what the world sounds like (sound.json), then every sound is generated,
+// checked and levelled into sound/<id>.mp3 with sound/sounds.json, which the play page mixes live.
+import fs from 'node:fs';
+import { defineCommand, takeOption } from '../registry.ts';
+import { Brief } from '../scene/brief.ts';
+import { Layout } from '../scene/layout.ts';
+import { Kind, makeSounds, seedLibrary, SoundManifest } from '../sound/make.ts';
+import { inputHash } from '../meta/memo.ts';
+import { planIssues, SoundPlan, withoutStrayLoops, withoutSilentLoops, writeSoundPlan, type PlaceSources } from '../sound/plan.ts';
+import { creditGuard, soundQuality } from '../sound/cost.ts';
+import { readSoundFixes } from '../sound/fixes.ts';
+import { elevenKey, musicgenPython } from '../sound/sources.ts';
+import { Story } from '../story/schema.ts';
+import { WorldFiles } from '../world/files.ts';
+
+defineCommand({
+  name: 'sound',
+  usage: 'sound <slug>             plan and generate ambience, loops, footsteps, one-shots and music [--replan] [--plan-only] [--only bed,loop,step,shot,music] [--redo <id,id>: make only these sounds again, with their hints from sound/fixes.json (sound_redo)] [--music auto|musicgen|eleven] [--draft: shorter loops and cheaper speech; final quality is the default]',
+  async run(args) {
+    // Keep this generation at one quality even if Setup changes while it runs.
+    process.env.DIORAMA_SOUND = soundQuality(args);
+    const replan = args.includes('--replan');
+    const planOnly = args.includes('--plan-only');
+    const only = takeOption(args, 'only', '');
+    const redo = takeOption(args, 'redo', '');
+    // auto: MusicGen when DIORAMA_PYTHON is set up for it, else ElevenLabs.
+    const musicFrom = takeOption(args, 'music', 'auto');
+    if (!['auto', 'musicgen', 'eleven'].includes(musicFrom)) throw new Error('--music takes auto, musicgen or eleven');
+    const [slug] = args.filter((a) => !a.startsWith('--'));
+    if (!slug) throw new Error('usage: diorama sound <slug>');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const story = fs.existsSync(files.path('story.json')) ? Story.parse(files.readJson(files.path('story.json'))) : null;
+    const sources: Record<string, PlaceSources> = {};
+    for (const place of world.places) {
+      const read = <T>(file: string, schema: { parse: (v: unknown) => T }) => (fs.existsSync(files.place(place.key, file)) ? schema.parse(files.readJson(files.place(place.key, file))) : undefined);
+      sources[place.key] = { brief: read('brief.json', Brief), layout: read('layout.json', Layout) };
+    }
+
+    // sound.json is the plan people may edit. It is made again with --replan, or when what it was made from
+    // (world, story, briefs, floors) has changed since, so its shots and loops keep matching the story's things.
+    const planFile = files.path('sound.json');
+    const from = inputHash(JSON.stringify(world), JSON.stringify(story), JSON.stringify(sources));
+    const old = fs.existsSync(planFile) ? SoundPlan.parse(files.readJson(planFile)) : undefined;
+    let plan: SoundPlan;
+    // A plan made before silent things lost their loops drops them here too, before anything is paid for.
+    if (old && !replan && old.from === from) plan = { ...old, ...withoutSilentLoops(old, sources) };
+    else {
+      if (old && !replan) console.log('the world, story or paintings changed since sound.json was planned: planning again (hand edits to it are replaced)');
+      plan = { from, ...withoutStrayLoops(await writeSoundPlan(files.memo, world, story, sources), world) };
+      files.write(planFile, plan);
+    }
+    const issues = planIssues(plan, world, sources);
+    const loops = Object.values(plan.places).reduce((n, p) => n + p.loops.length, 0);
+    console.log(`plan: music, ${Object.keys(plan.places).length} beds, ${loops} loops, ${Object.keys(plan.steps).length} surfaces, ${plan.shots.length} one-shots · ${planFile}`);
+    for (const issue of issues) console.log(`  flag   ${issue}`);
+    if (planOnly) return;
+    if (!elevenKey()) {
+      console.log('no ELEVENLABS_API_KEY: the plan is written, no sounds generated; the world plays silent');
+      return;
+    }
+
+    const guard = await creditGuard(elevenKey(), 'sound');
+    const python = musicFrom === 'eleven' ? undefined : musicgenPython();
+    if (musicFrom === 'musicgen' && !python) throw new Error('--music musicgen needs DIORAMA_PYTHON pointing at a Python with torch, transformers and scipy');
+    console.log(`music: ${python ? 'MusicGen (Meta open weights) on this machine' : 'ElevenLabs (set DIORAMA_PYTHON to a Python with torch + transformers for MusicGen)'}`);
+    const manifestFile = files.path('sound', 'sounds.json');
+    const made0: SoundManifest = fs.existsSync(manifestFile) ? SoundManifest.parse(files.readJson(manifestFile)) : { sounds: {}, failures: {} };
+    const kinds = only ? only.split(',').map((k) => Kind.parse(k.trim())) : undefined;
+    const ids = redo ? redo.split(',').map((id) => id.trim()).filter(Boolean) : undefined;
+    const fixes = readSoundFixes(files);
+    const made = await makeSounds(files.memo, plan, (id, mp3) => {
+      files.write(files.path('sound', `${id}.mp3`), mp3);
+      return `sound/${id}.mp3`;
+    }, { python, only: kinds, ids, fixes, log: (line) => console.log(line), old: made0.sounds, failedBefore: made0.failures, have: (e) => fs.existsSync(files.path(e.file)) });
+    const partial = !!(kinds || ids);
+    // A partial run keeps what it did not touch.
+    const sounds = { ...(partial ? made0.sounds : {}), ...made.sounds };
+    // Failed replacements cannot silently retain the rejected prior asset in a partial rebuild.
+    for (const id of Object.keys(made.failures)) delete sounds[id];
+    const failures = { ...(partial ? made0.failures : {}), ...made.failures };
+    for (const id of Object.keys(made.sounds)) delete failures[id];
+    files.write(manifestFile, { sounds, failures });
+    for (const [id, e] of Object.entries(sounds)) if (fs.existsSync(files.path(e.file))) seedLibrary(id, e, fs.readFileSync(files.path(e.file)));
+    const s = files.memo.sent;
+    console.log(`sound ${slug}: ${Object.keys(sounds).length} sounds · sent: spark ${s.spark}, sound ${s.sound}, music ${s.music} · ${await guard.report()} · ${manifestFile}`);
+    // A world plays without a sound: one that failed stays silent and the build goes on. Studio shows it with a retry.
+    if (Object.keys(failures).length) console.log(`warning: ${Object.keys(failures).length} sounds stay silent (failed quality or generation): ${Object.keys(failures).join(', ')}; see sound/sounds.json failures`);
+  },
+});

package/app/src/commands/sprites.ts

@@ -0,0 +1,232 @@
+// diorama sprites <slug> [key]: walk and talk sprite sheets drawn by Muse over the rigged model's poses,
+// only those the world and its story use (src/model/plan.ts).
+import fs from 'node:fs';
+import { bindExistingAnimation, bindAnimation } from '../scene/animation-source.ts';
+import path from 'node:path';
+import { gestureIndex } from '../play/gestures.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { planSprites, type CharacterPlan } from '../model/plan.ts';
+import { cutSheet, FACINGS, flatGuide, onGrey, paintSheet, POSE_OK, renderGuides, modelSheet, SHEET, TRACED, uvFaceLost, type Facing } from '../model/sprites.ts';
+import { animationSettings, animationOptions, saveAnimationSettings, type AnimationSettings } from '../model/animation.ts';
+import { Story } from '../story/schema.ts';
+import { fixedLooks, readCastFixes } from '../scene/cast-fixes.ts';
+import { refitIfOld } from '../model/fit.ts';
+import { modelProblem } from '../model/glb.ts';
+import { castStyle, readStyled } from '../world/styled.ts';
+import { WorldFiles } from '../world/files.ts';
+
+const LEGS_OK = 0.6;
+// Walk takes painted again at most, while the best one is traced or left the pose.
+const RETAKES = 4;
+const mean = (xs: number[]) => (xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0);
+
+defineCommand({
+  name: 'sprites',
+  usage: 'sprites <slug> [key]     walk and talk sheets for what the story uses: automatic UV/16 for new textured models, painted/8 fallback (cast/<key>/sprites/; needs `diorama model` first) [--texture model|views] [--coat-correction on|off] [--frames 8|16|32: model texture only; choices persist per character] [--plan: only print what would be drawn] [--take N] [--tries N: up to N takes per walk facing while a frame has its legs wrong]',
+  async run(args) {
+    const options = animationOptions(takeOption(args, 'texture', ''), takeOption(args, 'frames', ''), takeOption(args, 'coat-correction', ''));
+    const takeArg = takeOption(args, 'take', '');
+    const tries = Number(takeOption(args, 'tries', '1'));
+    const planOnly = args.includes('--plan');
+    const [slug, keyArg] = args.filter((a) => !a.startsWith('--'));
+    if (!slug) throw new Error('usage: diorama sprites <slug> [key]');
+    const files = new WorldFiles(slug);
+    const story = fs.existsSync(files.path('story.json')) ? Story.parse(files.readJson(files.path('story.json'))) : undefined;
+    const plans = (await planSprites(files, story)).filter((p) => !keyArg || p.key === keyArg);
+    if (!plans.length) throw new Error(keyArg ? `${keyArg} needs no sprites (not the hero, says no lines)` : 'nobody needs sprites');
+    const settings = new Map(plans.map((p) => [p.key, animationSettings(files, p.key, options)]));
+    if (!planOnly) files.write(files.path('cast', 'sprites-plan.json'), plans);
+    // Whether a usable 3D model is there: a creature without one (flat reconstructions) moves as its cut-out.
+    const modelled = (key: string) => fs.existsSync(files.path('cast', key, 'model', 'model.json')) && !modelProblem(files.path('cast', key, 'model'));
+    for (const p of plans) {
+      const talk = Object.entries(p.talk).map(([f, g]) => `${f} [${g.join(', ')}]`).join('; ');
+      console.log(p.creature ? `${p.key}: a creature · 0 Muse sheets (${modelled(p.key) ? 'its 3D model moves' : 'no usable 3D model: the cut-out moves as one piece'})` : `${p.key}: ${settings.get(p.key)!.texture === 'model' ? `UV ${settings.get(p.key)!.frames} frames` : 'painted 8 frames'} · walk ${p.walk.join(', ') || '-'} · talk ${talk || '-'} · ${settings.get(p.key)!.texture === 'model' ? 0 : p.walk.length + Object.keys(p.talk).length} Muse sheets`);
+    }
+    if (planOnly) return;
+    for (const p of plans) {
+      // A creature has no walk or gestures to paint: its 3D model hops, squashes and blinks in the game itself.
+      if (p.creature) {
+        console.log(modelled(p.key) ? `${p.key}: a creature, no sheets: it moves as its 3D model` : `${p.key}: a creature, no sheets and no usable 3D model: the cut-out moves as one piece (cast_animate, or diorama model ${slug} ${p.key}, tries a model)`);
+        continue;
+      }
+      if (!fs.existsSync(files.path('cast', p.key, 'model', 'model.json'))) {
+        console.log(`${p.key}: no model yet, skipped (diorama model ${slug} ${p.key})`);
+        continue;
+      }
+      const bad = modelProblem(files.path('cast', p.key, 'model'));
+      if (bad) {
+        console.log(`${p.key}: model is ${bad}, skipped: walks with the 2D rig (diorama model ${slug} ${p.key} tries again)`);
+        continue;
+      }
+      bindExistingAnimation(files, p.key);
+      const selected = settings.get(p.key)!;
+      if (selected.texture === 'model') await drawModelCharacter(files, p, selected);
+      else {
+        // The person's sprites_redo rounds (cast/fixes.json) start past the takes painted before, also in a rebuild.
+        const take = takeArg ? Number(takeArg) : (RETAKES + 1) * (readCastFixes(files)[p.key]?.spriteTake ?? 0);
+        await drawCharacter(files, p, take, tries, selected);
+      }
+      if (selected.texture === 'model' || Object.keys(options).length || fs.existsSync(files.path('cast', p.key, 'animation.json'))) saveAnimationSettings(files, p.key, selected);
+      const modelFile = files.path('cast', p.key, 'model', 'model.json');
+      const model = files.readJson(modelFile) as Record<string, unknown>;
+      if (selected.texture === 'model') model.texture = 'model';
+      else delete model.texture;
+      if (selected.coatCorrection !== undefined) model.coatCorrection = selected.coatCorrection;
+      files.write(modelFile, model);
+      bindAnimation(files, p.key, 'sprites');
+    }
+    console.log(`calls sent: muse ${files.memo.sent.muse}, spark ${files.memo.sent.spark}`);
+  },
+});
+
+async function drawCharacter(files: WorldFiles, plan: CharacterPlan, take: number, tries: number, settings: AnimationSettings) {
+  const { key } = plan;
+  const world = files.world();
+  const who = [world.hero, ...world.places.flatMap((p) => p.things)].find((w) => w.key === key);
+  const looks = who ? fixedLooks(files, who).looks : '';
+  // A world given another style names it, so the sheets follow the restyled character, not the gouache they were made for.
+  const style = readStyled(files).from ? castStyle(files, world, key) : undefined;
+  const modelDir = files.path('cast', key, 'model');
+  const projected: AnimationSettings = { ...settings, texture: 'views', frames: 8 };
+  // An older model's views were fitted on the whole silhouette only: the guides would show the profile's face twice.
+  if (await refitIfOld(modelDir)) console.log(`${key}: views fitted again, slice by slice`);
+  const view = (name: string) => fs.readFileSync(`${modelDir}/${name}.png`);
+  const out = (name: string) => files.path('cast', key, 'sprites', name);
+
+  // Walking: the first facing (the profile when it is used) is painted first; the others also see it,
+  // so patches and colours stay the same. Muse often hands the textured guide back with a filter over it
+  // (mean `same` above TRACED): that sheet looks like the 3D render, and as the first facing it passes the
+  // look on to every other facing. So a take that is traced or left the pose is painted again, up to
+  // RETAKES times, and the first drawn take that keeps the pose wins. Retakes cycle through three guides,
+  // because no one of them works for every facing (foghorn, 3 takes each): over a grey clay figure Muse
+  // draws the back view every time but turns the three-quarter back into a profile; over flat colour
+  // blocks it keeps the pose about half the time; over the textured render it traces about 3 takes in 4.
+  // A frame whose legs do not follow the guide makes the walk skip: with --tries, more takes, and the
+  // whole take whose legs follow best wins (frames mixed from several takes do not match).
+  const facings: Record<string, { sheet: string; yaw: number; stand: number; off: number[]; iou: number[]; legs: number[]; same: number[] }> = {};
+  if (plan.walk.length) {
+    const guides = await renderGuides(modelDir, plan.walk, undefined, false, projected);
+    const clay = await renderGuides(modelDir, plan.walk, undefined, true, projected);
+    const shown: Record<string, Buffer[]> = {};
+    for (const f of plan.walk) {
+      const grey = await onGrey(guides[f]);
+      files.write(out(`guide-${f}.png`), grey);
+      shown[f] = [grey, await onGrey(clay[f]), await flatGuide(grey)];
+    }
+    const first: Facing = plan.walk.includes('right') ? 'right' : plan.walk[0];
+    const refsFor = (f: Facing, painted?: Buffer) => [f.startsWith('back') ? view('back') : view('front'), painted ?? view('right')];
+    const painted: Record<string, Buffer> = {};
+    const walk = async (f: Facing, refs: Buffer[]) => {
+      type Take = Awaited<ReturnType<typeof cutSheet>> & { painted: Buffer; n: number };
+      const takes: Take[] = [];
+      let n = take;
+      const another = async () => {
+        const p = await paintSheet(files.memo, key, f, looks, shown[f][(n - take) % shown[f].length], refs, n, 0, style);
+        // Always measured against the textured guide: that is the look a traced sheet keeps.
+        takes.push({ ...(await cutSheet(guides[f], p)), painted: p, n: n++ });
+      };
+      const traced = (t: Take) => mean(t.same) > TRACED;
+      // A take that left the pose (Muse turned some frames to another facing) is worst, then traced takes;
+      // among drawn takes the legs that follow best win, among traced ones the least traced.
+      const rank = (t: Take) => (mean(t.iou) < POSE_OK ? 0 : traced(t) ? 1 : 2);
+      const pick = () => takes.reduce((a, b) => {
+        if (rank(a) !== rank(b)) return rank(b) > rank(a) ? b : a;
+        return traced(a) ? (mean(b.same) < mean(a.same) ? b : a) : (mean(b.legs) > mean(a.legs) ? b : a);
+      });
+      await another();
+      for (let t = 1; t <= RETAKES && rank(pick()) < 2; t++) await another();
+      for (let t = 1; t < tries && Math.min(...pick().legs) < LEGS_OK; t++) await another();
+      const best = pick();
+      painted[f] = best.painted;
+      files.write(out(`painted-${f}.png`), best.painted);
+      files.write(out(`${f}.png`), best.sheet);
+      facings[f] = { sheet: `${f}.png`, yaw: FACINGS[f], stand: best.stand, off: best.off, iou: best.iou, legs: best.legs, same: best.same };
+      console.log(`${key} walk ${f}: take ${best.n + 1} (${['textured', 'clay', 'flat'][(best.n - take) % 3]} guide, ${takes.length} painted), pose IoU ${mean(best.iou).toFixed(3)}, legs ${mean(best.legs).toFixed(3)} (worst ${Math.min(...best.legs)}), same ${mean(best.same).toFixed(3)}${best.off.length ? `, off the walk: cell ${best.off.join(', ')}` : ''}${traced(best) ? '  <- Muse kept the 3D look, try --take' : mean(best.iou) < POSE_OK ? '  <- frames left the pose, try --take' : ''}`);
+    };
+    await walk(first, [view('front'), view('right')]);
+    await Promise.all(plan.walk.filter((f) => f !== first).map((f) => walk(f, refsFor(f, painted[first]))));
+  }
+
+  // Talking: the gestures this character's lines use, in the facing its conversation is held in. The
+  // painted views are the reference, not a walk sheet: with a walk sheet Muse draws the legs walking.
+  const talk: Record<string, { sheet: string; yaw: number; gestures: string[]; iou: number[]; same: number[] }> = {};
+  await Promise.all(Object.entries(plan.talk).map(async ([facing, names]) => {
+    const f = facing as Facing;
+    const used = names.map(gestureIndex);
+    // Muse redraws a half-empty grid as a few big figures, so the used gestures repeat to fill all 8
+    // cells (the sheet costs the same); cell i < used.length is gestures[i].
+    const cells = Array.from({ length: SHEET.cols * SHEET.rows }, (_, i) => used[i % used.length]);
+    const guide = (await renderGuides(modelDir, [f], cells, false, projected))[f];
+    const g = await onGrey(guide);
+    files.write(out(`talk-guide-${f}.png`), g);
+    const refs = [view('front'), view('right')];
+    let p = await paintSheet(files.memo, key, f, looks, g, refs, take, used.length, style);
+    let cut = await cutSheet(guide, p);
+    const score = () => mean(cut.same.slice(0, used.length));
+    // From some angles the hands hide in front of the body and Muse hands the guide back unchanged.
+    for (let t = 1; t <= 2 && score() > TRACED; t++) {
+      p = await paintSheet(files.memo, key, f, looks, g, refs, take + t, used.length, style);
+      cut = await cutSheet(guide, p);
+    }
+    files.write(out(`talk-painted-${f}.png`), p);
+    files.write(out(`talk-${f}.png`), cut.sheet);
+    talk[f] = { sheet: `talk-${f}.png`, yaw: FACINGS[f], gestures: names, iou: cut.iou.slice(0, used.length), same: cut.same.slice(0, used.length) };
+    console.log(`${key} talk ${f} [${names.join(', ')}]: pose IoU ${mean(cut.iou.slice(0, used.length)).toFixed(3)}, same ${score().toFixed(3)}${score() > TRACED ? '  <- Muse kept the 3D look, try --take' : ''}`);
+  }));
+
+  files.write(out('sprites.json'), {
+    cols: SHEET.cols, rows: SHEET.rows, frames: SHEET.cols * SHEET.rows, width: SHEET.width, height: SHEET.height,
+    // In each cell the feet stand at (cell width / 2, cell height * feetAt); the figure is about `px` tall.
+    feetAt: SHEET.feetAt, px: SHEET.px,
+    // Walk sheets: 8 frames of a full cycle; `stand` is the frame shown standing still; a walk skips the `off` cells.
+    facings,
+    // Talk sheets: cell i is gestures[i]; cell 0 is `listen` (also how an NPC stands when idle).
+    talk,
+    // The gesture for each line this character says, by its text.
+    lines: plan.lines,
+  });
+}
+
+/** Direct UV sheets keep anatomy tied to the mesh; no Muse repainting or silhouette fitting. */
+export async function drawModelCharacter(files: WorldFiles, plan: CharacterPlan, settings: AnimationSettings) {
+  const modelDir = files.path('cast', plan.key, 'model');
+  const grid = modelSheet(settings.frames);
+  // TRELLIS often bakes a blank face: then the front painting goes on it (Spark compares the two heads once).
+  const modelFile = path.join(modelDir, 'model.json');
+  if (fs.existsSync(modelFile) && fs.existsSync(path.join(modelDir, 'front.png'))) {
+    const fromViews = await uvFaceLost(files.memo, plan.key, modelDir, settings).catch((error) => {
+      console.log(`${plan.key}: face check failed (${error instanceof Error ? error.message : String(error)}); the model texture's face stays`);
+      return false;
+    });
+    const info = files.readJson(modelFile) as Record<string, unknown>;
+    if (fromViews) info.face = 'views';
+    else delete info.face;
+    files.write(modelFile, info);
+    console.log(`${plan.key}: face ${fromViews ? 'from the front painting (the UV face came out blank)' : 'from the model texture'}`);
+  }
+  const facings: Record<string, { sheet: string; yaw: number; stand: number; off: number[] }> = {};
+  const talk: Record<string, { sheet: string; yaw: number; gestures: string[] }> = {};
+  const images: Record<string, Buffer> = {};
+  // Finish rendering everything before replacing any active sheet or its metadata.
+  if (plan.walk.length) {
+    const walk = await renderGuides(modelDir, plan.walk, undefined, false, settings);
+    for (const f of plan.walk) {
+      const sheet = `model-${settings.frames}-${f}.png`;
+      images[sheet] = walk[f];
+      facings[f] = { sheet, yaw: FACINGS[f], stand: settings.frames, off: [] };
+    }
+  }
+  for (const [facing, names] of Object.entries(plan.talk)) {
+    const f = facing as Facing;
+    const gestures = names.map(gestureIndex);
+    if (gestures.some((i) => i < 0)) throw new Error(`${plan.key}: unknown talking gesture`);
+    const sheet = `model-${settings.frames}-talk-${f}.png`;
+    images[sheet] = (await renderGuides(modelDir, [f], gestures, false, settings))[f];
+    talk[f] = { sheet, yaw: FACINGS[f], gestures: names };
+  }
+  const out = (name: string) => files.path('cast', plan.key, 'sprites', name);
+  for (const [name, image] of Object.entries(images)) files.write(out(name), image);
+  const { elevation: _elevation, ...layout } = grid;
+  files.write(out('sprites.json'), { ...layout, facings, talk, lines: plan.lines });
+  console.log(`${plan.key}: UV sprites · ${settings.frames} walk frames + standing · ${Object.keys(talk).length} talk sheets`);
+}

package/app/src/commands/story.ts

@@ -0,0 +1,37 @@
+// diorama story <slug>: puzzles, items, dialogue and endings for world.json, checked by playing every state.
+// The person's wish and reworded lines (story-fixes.json) are applied every time.
+// diorama story <slug> --check: re-check story.json.
+import { defineCommand } from '../registry.ts';
+import { checkStory } from '../story/check.ts';
+import { designStory } from '../story/design.ts';
+import { applyTexts, readStoryFixes } from '../story/fixes.ts';
+import { WorldFiles } from '../world/files.ts';
+
+defineCommand({
+  name: 'story',
+  usage: 'story <slug>            write story.json with Muse Spark and check every ending is reachable [--check]',
+  async run(args) {
+    const checkOnly = args.includes('--check');
+    const [slug] = args.filter((a) => !a.startsWith('--'));
+    if (!slug) throw new Error('usage: diorama story <slug> [--check]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const fixes = readStoryFixes(files);
+    let report;
+    if (checkOnly) report = checkStory(world, files.readJson(files.path('story.json')));
+    else {
+      if (fixes.wish) console.log(`  your wish: ${fixes.wish}`);
+      const designed = await designStory(files.memo, world, fixes.wish);
+      const { story, skipped } = applyTexts(designed.story, fixes);
+      for (const path of skipped) console.log(`  your wording for ${path} no longer fits the story; left out`);
+      if (Object.keys(fixes.texts).length > skipped.length) console.log(`  ${Object.keys(fixes.texts).length - skipped.length} line(s) in your wording`);
+      files.write(files.path('story.json'), story);
+      report = checkStory(world, story);
+    }
+    if (report.issues.length) throw new Error(`story.json has ${report.issues.length} issue(s):\n- ${report.issues.join('\n- ')}`);
+    files.write(files.path('routes.json'), report.routes);
+    console.log(`${report.states} states played, every ending reachable, no dead ends`);
+    for (const r of report.routes) console.log(`  ${r.ending} in ${r.steps.length} steps: ${r.steps.join(' → ')}`);
+    if (!checkOnly) console.log(`spark calls sent: ${files.memo.sent.spark}`);
+  },
+});

package/app/src/commands/studio.ts

@@ -0,0 +1,65 @@
+// diorama studio [slug]: the GUI. A local page to start, watch and fix worlds, driven by the same actions
+// as `diorama action` and the Muse Code agent.
+import { spawn } from 'node:child_process';
+import { actions } from '../actions/registry.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { writeStudioFile } from '../studio/discovery.ts';
+import type { StudioEvent } from '../studio/events.ts';
+import { startStudio } from '../studio/server.ts';
+
+defineCommand({
+  name: 'studio',
+  usage: 'studio [slug]           open Diorama Studio, the GUI, on 127.0.0.1 [--port N] [--no-open] [--quiet] [--verbose: every line jobs print]',
+  async run(args) {
+    const port = Number(takeOption(args, 'port', '0'));
+    const noOpen = args.includes('--no-open');
+    const quiet = args.includes('--quiet');
+    const verbose = args.includes('--verbose');
+    const slug = args.find((a) => !a.startsWith('--'));
+    const studio = await startStudio({ port });
+    const forget = writeStudioFile(process.cwd(), { url: studio.url, agentToken: studio.agentToken });
+    // The token rides in the fragment: browsers never send it to a server or put it in a Referer.
+    const link = `${studio.url}${slug ? `w/${slug}` : ''}#${studio.token}`;
+    console.log(`Diorama Studio: ${link}\n(only this link opens it; Ctrl+C to stop)`);
+    if (!quiet) studio.events.subscribe((e) => {
+      const line = describe(e, verbose);
+      if (line) console.log(`${new Date(e.at).toTimeString().slice(0, 8)} ${e.world ? `${e.world}: ` : ''}${line}`);
+    });
+    if (!noOpen) {
+      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'explorer' : 'xdg-open';
+      spawn(opener, [link], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
+    }
+    const stop = async () => {
+      forget();
+      await studio.close();
+      process.exit(0);
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    await new Promise(() => {});
+  },
+});
+
+/** One terminal line per event worth seeing: what runs, what ends, what the agent does. Keys are already redacted. */
+function describe(e: StudioEvent, verbose: boolean): string | null {
+  const job = e.job as { label?: string; by?: string; state?: string; error?: string } | undefined;
+  switch (e.type) {
+    case 'job.start': return `started ${job?.label} (${job?.by})`;
+    case 'job.end': return `${job?.state} ${job?.label}${job?.error ? `: ${job.error}` : ''}`;
+    case 'step.start': return `> ${e.step}`;
+    case 'step.end': return `ok ${e.step} ${e.seconds}s`;
+    case 'step.fail': return `FAILED ${e.step}: ${e.error}`;
+    case 'place.verdict': return `${e.place}: ${e.ok ? 'playable' : 'NOT playable'}`;
+    case 'action.start': return e.by === 'agent' || !actions.get(String(e.action))?.reads ? `${e.by}: ${e.action}` : null;
+    case 'action.end': return e.ok ? null : `${e.by}: ${e.action} failed: ${e.error}`;
+    case 'history.undo': return `${e.by}: undo to ${e.id}`;
+    case 'lock.changed': return `${e.by}: ${e.locked ? 'locked' : 'unlocked'} ${e.place ?? 'world'}`;
+    case 'agent.user': return `you -> agent: ${String(e.text).slice(0, 120)}`;
+    case 'agent.message': return `agent: ${String(e.text).slice(0, 200)}`;
+    case 'agent.turn.end': return e.status === 'completed' ? null : `agent stopped: ${e.error ?? e.status}`;
+    case 'agent.error': return `agent error: ${e.text}`;
+    case 'agent.agent': return `agent is now ${e.label}`;
+    case 'log': return verbose || e.stream === 'err' ? `  ${e.line}` : null;
+    default: return null;
+  }
+}

package/app/src/commands/style.ts

@@ -0,0 +1,87 @@
+// diorama style <slug> "<style>": give a world (or one place, or the cast) another painting style, and repaint
+// what is made in it with the composition kept, so masks, walk grids and the person's fixes still fit.
+import fs from 'node:fs';
+import { defineCommand, registry, takeOption } from '../registry.ts';
+import { readCastFixes, castFixesFile } from '../scene/cast-fixes.ts';
+import { readCorrections, writeCorrections } from '../scene/corrections.ts';
+import { WorldFiles } from '../world/files.ts';
+import { castStyle, placeStyle, readStyled, writeStyled } from '../world/styled.ts';
+import { castKeys, planLine, stylePlan, type Scope } from '../world/style-plan.ts';
+
+const run = (name: string, args: string[]) => registry.get(name)!.run(args);
+
+defineCommand({
+  name: 'style',
+  usage: 'style <slug> "<style>"  paint the world in another style: each place repainted with its composition kept (then masks to verify again), the cast repainted, their models and sprites made again [--place KEY: only that place] [--cast KEY|all: only the cast] [--estimate: only say what it redoes and costs]',
+  async run(args) {
+    const placeKey = takeOption(args, 'place', '');
+    const castKey = takeOption(args, 'cast', '');
+    const estimate = args.includes('--estimate');
+    const [slug, style] = args.filter((a) => a !== '--estimate');
+    if (!slug || !style) throw new Error('usage: diorama style <slug> "<style>" [--place KEY] [--cast KEY|all] [--estimate]');
+    if (style.trim().length < 10) throw new Error('say the style in a few words: medium, palette, light (at least 10 letters)');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const scope: Scope = placeKey ? 'place' : castKey ? 'cast' : 'world';
+    const key = placeKey || (castKey && castKey !== 'all' ? castKey : undefined);
+    if (placeKey && !world.places.some((p) => p.key === placeKey)) throw new Error(`${slug} has no place ${placeKey}: ${world.places.map((p) => p.key).join(', ')}`);
+    if (scope === 'cast' && key && !castKeys(world, files).includes(key)) throw new Error(`${slug} has no character ${key}: ${castKeys(world, files).join(', ')}`);
+    const plan = stylePlan(files, world, scope, key);
+    console.log(`style ${scope}${key ? ` ${key}` : ''}: ${planLine(plan)}`);
+    if (estimate) return;
+
+    // What is painted already keeps the style it was painted in, so paint and cast see the change and repaint it.
+    const styled = readStyled(files);
+    for (const p of world.places) if (!styled.places[p.key] && fs.existsSync(files.place(p.key, 'painting.png'))) styled.places[p.key] = placeStyle(files, world, p.key);
+    for (const k of castKeys(world, files)) if (!styled.cast[k] && fs.existsSync(files.path('cast', `${k}-painting.png`))) styled.cast[k] = castStyle(files, world, k);
+    styled.from ??= world.style;
+    writeStyled(files, styled);
+
+    // The new style: the world's (a place's or a character's own style gives way to it), or one place's or character's own.
+    const fixes = readCastFixes(files);
+    const castFix = (k: string, s: string | undefined) => {
+      if (s) fixes[k] = { ...fixes[k], style: s };
+      else if (fixes[k]) delete fixes[k].style;
+    };
+    if (scope === 'world') {
+      files.write(files.path('world.json'), { ...JSON.parse(fs.readFileSync(files.path('world.json'), 'utf8')), style });
+      for (const p of world.places) {
+        const c = readCorrections(files.place(p.key));
+        if (!c.style) continue;
+        delete c.style;
+        writeCorrections(files.place(p.key), c);
+      }
+      for (const k of Object.keys(fixes)) castFix(k, undefined);
+    } else if (scope === 'place') {
+      const c = readCorrections(files.place(placeKey));
+      c.style = style;
+      fs.mkdirSync(files.place(placeKey), { recursive: true });
+      writeCorrections(files.place(placeKey), c);
+    } else {
+      for (const k of key ? [key] : castKeys(world, files)) castFix(k, style);
+    }
+    if (scope !== 'place') files.write(castFixesFile(files), fixes);
+
+    if (plan.places.length) {
+      if (scope === 'place') await run('build', [slug, '--from', 'paint', '--to', 'verify', '--place', placeKey]);
+      else await run('build', [slug, '--from', 'paint', '--to', 'reactions']);
+      // Icons cut from a painting are cut again from the new one; painted ones are painted in the new style.
+      if (scope === 'place') await run('icons', [slug]);
+    }
+    if (plan.cast.length) {
+      console.log('\n# cast');
+      await run('cast', [slug, ...plan.cast]);
+      for (const k of plan.models) {
+        console.log(`\n# model ${k}`);
+        await run('model', [slug, k]);
+      }
+      for (const k of plan.sprites) {
+        console.log(`\n# sprites ${k}`);
+        await run('sprites', [slug, k]);
+      }
+    }
+    if (plan.faces.length) await run('faces', [slug, ...plan.faces]);
+    if (scope === 'world' && plan.places.length) await run('build', [slug, '--from', 'verify', '--to', 'verify']);
+    console.log(`\nstyle ${slug}: ${scope}${key ? ` ${key}` : ''} now "${style}"`);
+  },
+});