@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/commands/sound.ts

@@ -0,0 +1,100 @@
+// 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';
+import type { World } from '../world/schema.ts';
+
+/** What each place's sounds are planned from: its painting brief and floors. */
+export function placeSources(files: WorldFiles, world: World): Record<string, PlaceSources> {
+  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) };
+  }
+  return sources;
+}
+
+/** sound.json's `from`: the plan is made again when this changes. */
+export const soundPlanFrom = (world: World, story: Story | null, sources: Record<string, PlaceSources>) => inputHash(JSON.stringify(world), JSON.stringify(story), JSON.stringify(sources));
+
+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 = placeSources(files, world);
+
+    // 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 = soundPlanFrom(world, story, 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}"`);
+  },
+});

package/app/src/commands/verify.ts

@@ -0,0 +1,45 @@
+// diorama verify <slug> [place...]: verify.json per place; exits 1 when a place has errors.
+import fs from 'node:fs';
+import { Geometry } from '../play/geometry.ts';
+import { defineCommand } from '../registry.ts';
+import { gapError, placeGap } from './build.ts';
+import { verifyPlace, type BackdropNotes, type MaskNotes, type PlateNotes } from '../scene/verify.ts';
+import { WorldFiles } from '../world/files.ts';
+import { checkPlaceOcclusion, occlusionFindings } from '../scene/occlusion-check.ts';
+import { Reactions } from '../play/reactions.ts';
+import { reactionInput } from './reactions.ts';
+import { reactionSource } from '../scene/reactions.ts';
+
+defineCommand({
+  name: 'verify',
+  usage: 'verify <slug> [place...] check each place can be walked and used (verify.json)',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: diorama verify <slug> [place...]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    let failed = 0;
+    for (const place of world.places.filter((p) => only.length === 0 || only.includes(p.key))) {
+      const at = (...parts: string[]) => files.place(place.key, ...parts);
+      const gap = placeGap(files.place(place.key), 'verify');
+      if (gap) throw new Error(gapError(place.key, gap));
+      const geometry = Geometry.parse(files.readJson(at('geometry.json')));
+      const plates = (fs.existsSync(at('plates.json')) ? files.readJson(at('plates.json')) : {}) as PlateNotes;
+      const backdrop = (fs.existsSync(at('backdrop.json')) ? files.readJson(at('backdrop.json')) : {}) as BackdropNotes;
+      const verdict = verifyPlace(place, geometry, files.readJson(at('masks.json')) as MaskNotes, plates, backdrop);
+      // Who the painting hides where, by the depth map: also the things nobody named (a lamp post, a bridge's side).
+      verdict.flags.push(...occlusionFindings(geometry, await checkPlaceOcclusion(files.place(place.key), geometry)));
+      if (fs.existsSync(at('reactions.json'))) {
+        try {
+          const rules = Reactions.parse(files.readJson(at('reactions.json')));
+          if (rules.source !== reactionSource(reactionInput(files, place.key))) verdict.flags.push({ code: 'REACTIONS_STALE', detail: 'Scene or story changed; rerun reactions. Stale effects are disabled in play.' });
+        } catch (e) { verdict.flags.push({ code: 'REACTIONS_INVALID', detail: `Rerun reactions: ${e instanceof Error ? e.message : String(e)}` }); }
+      }
+      files.write(at('verify.json'), verdict);
+      if (!verdict.ok) failed++;
+      console.log(`${place.key}: ${verdict.ok ? 'ok' : `${verdict.errors.length} error(s)`}, ${verdict.flags.length} flag(s)`);
+      for (const e of verdict.errors) console.log(`  ERROR ${e.code}${e.key ? ` ${e.key}` : ''}: ${e.detail}`);
+      for (const f of verdict.flags) console.log(`  flag  ${f.code}${f.key ? ` ${f.key}` : ''}: ${f.detail}`);
+    }
+    if (failed) process.exitCode = 1;
+  },
+});

package/app/src/commands/voice-retry.ts

@@ -0,0 +1,14 @@
+import { defineCommand } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { soundQuality } from '../sound/cost.ts';
+import { retryVoiceLine } from '../sound/retry.ts';
+
+defineCommand({
+  name: 'voice-retry',
+  usage: 'voice-retry <slug> <speaker> "<exact text>"  retry one line without changing its voice or other recordings',
+  async run([slug, speaker, text]) {
+    if (!slug || !speaker || !text) throw new Error('usage: voice-retry <slug> <speaker> "<exact text>"');
+    process.env.DIORAMA_SOUND = soundQuality();
+    await retryVoiceLine(new WorldFiles(slug), speaker, text);
+  },
+});