@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/commands/doctor.ts

@@ -0,0 +1,74 @@
+// diorama doctor: one live call per model, so a bad key or a changed API shows up before a build.
+import fs from 'node:fs';
+import path from 'node:path';
+import { maskArea, maskToPng } from '../image/mask.ts';
+import { Memo } from '../meta/memo.ts';
+import { museEdit, musePaint } from '../meta/muse.ts';
+import { samFind } from '../meta/sam.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { defineCommand } from '../registry.ts';
+
+defineCommand({
+  name: 'doctor',
+  usage: 'doctor [dir] [--now]    check the API key with one call to Spark, Muse paint, Muse edit and SAM 3.1; --now skips the memo and says if the network and Meta are fast enough for a live build',
+  async run(args) {
+    const nowAt = args.indexOf('--now');
+    if (nowAt >= 0) args.splice(nowAt, 1);
+    const [dir = '.diorama/doctor'] = args;
+    const out = path.resolve(dir);
+    fs.mkdirSync(out, { recursive: true });
+    // A memo hit takes no time, so --now asks afresh to measure this network and Meta as they are.
+    const memo = new Memo(path.join(out, nowAt >= 0 ? `memo-${Date.now()}` : 'memo'));
+    let failed = 0;
+    const took: Record<string, number> = {};
+    async function check<T>(name: string, run: () => Promise<T>, describe: (v: T) => string): Promise<T | undefined> {
+      const started = Date.now();
+      try {
+        const value = await run();
+        took[name] = Date.now() - started;
+        console.log(`  ok    ${name.padEnd(11)}${`${Date.now() - started} ms`.padStart(9)}  ${describe(value)}`);
+        return value;
+      } catch (error) {
+        failed++;
+        console.log(`  FAIL  ${name.padEnd(11)}${error instanceof Error ? error.message : error}`);
+      }
+    }
+
+    await check('spark', () => askSparkJson<{ thing: string }>(memo, {
+      label: 'doctor',
+      prompt: 'Name one thing a traveller might find at a crossroads inn. Reply as JSON: {"thing": "..."}',
+    }), (a) => `"${a.thing}"`);
+
+    const painting = await check('muse paint', () => musePaint(memo, {
+      label: 'doctor',
+      prompt: 'A painted background for a 2D adventure game: the yard of a crossroads inn at dusk, a cart with a wooden barrel, a well, lanterns on the porch. Gouache, no people, no text.',
+    }), (png) => `${Math.round(png.length / 1024)} KB`);
+    if (!painting) return void process.exit(1);
+    fs.writeFileSync(path.join(out, 'paint.png'), painting);
+
+    const edited = await check('muse edit', () => museEdit(memo, {
+      label: 'doctor',
+      images: [painting],
+      prompt: 'The same yard on a snowy winter night. Keep the composition exactly.',
+    }), (png) => `${Math.round(png.length / 1024)} KB`);
+    if (edited) fs.writeFileSync(path.join(out, 'edit.png'), edited);
+
+    const found = await check('sam', () => samFind(memo, { label: 'doctor', image: painting, prompt: 'barrel' }),
+      (f) => `${f.length} barrel(s), ${f.reduce((s, x) => s + maskArea(x.mask), 0)} px`);
+    if (found?.[0]) fs.writeFileSync(path.join(out, 'sam-barrel.png'), await maskToPng(found[0].mask));
+
+    if (nowAt >= 0) console.log(`\n  ${liveVerdict(took)}`);
+    console.log(`\n  sent: spark ${memo.sent.spark}, muse ${memo.sent.muse}, sam ${memo.sent.sam} · files in ${out}`);
+    if (failed) process.exit(1);
+  },
+});
+
+/** Slower than this, one call is a sign of a slow network or a busy Meta: a 25-drawing build took 45 min at 3x these. */
+const SLOW_MS: Record<string, number> = { spark: 30_000, 'muse paint': 60_000, 'muse edit': 60_000, sam: 20_000 };
+
+/** Whether a build in front of people will finish in time, from one call to each model. */
+export function liveVerdict(took: Record<string, number>): string {
+  const slow = Object.entries(SLOW_MS).filter(([name, limit]) => (took[name] ?? Infinity) > limit).map(([name]) => name);
+  if (!slow.length) return 'fast enough for a live build (3 places in about 15 min)';
+  return `SLOW: ${slow.join(', ')}. A live build may take 30+ min: play a world built beforehand, or build with fewer drawings and places`;
+}

package/app/src/commands/explore.ts

@@ -0,0 +1,123 @@
+// diorama explore <slug> [place...]: walks the hero over every place in the real play page and
+// reports what looks wrong (explore/ per place: report.json, heatmap.png, sheet.png).
+// --fix closes the cells around bad spots in geometry.json; --no-judge skips the Spark juror.
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { Geometry } from '../play/geometry.ts';
+import { classify, contactSheet, fixGrid, heatmap, ISSUES, judge, positions, type Checked } from '../qa/explore.ts';
+import { CROP_JS, PROBE_JS, type ProbeHit } from '../qa/probe.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { serveWorld } from './play.ts';
+
+export type Browser = { newPage(o?: object): Promise<Page>; close(): Promise<void> };
+export type Page = {
+  goto(url: string): Promise<unknown>;
+  waitForFunction(js: string, arg?: unknown, o?: object): Promise<unknown>;
+  evaluate<T>(js: string, arg?: unknown): Promise<T>;
+  on(event: 'pageerror' | 'console', fn: (e: { message?: string; text?: () => string; type?: () => string }) => void): void;
+};
+
+/** Playwright ships with diorama; its Chromium is a separate download (diorama browsers). */
+export async function chromium(): Promise<{ launch(o?: object): Promise<Browser> }> {
+  try {
+    return ((await import('playwright' as string)) as { chromium: never }).chromium;
+  } catch {
+    try {
+      return (createRequire(import.meta.url)('playwright') as { chromium: never }).chromium;
+    } catch {
+      throw new Error('this command needs Playwright with Chromium: diorama browsers');
+    }
+  }
+}
+
+/** Runs a page function given as source text, so the bundler adds nothing it can't see. */
+const call = <T>(page: Page, fn: string, arg: unknown) => page.evaluate<T>(`(${fn})(${JSON.stringify(arg)})`);
+
+defineCommand({
+  name: 'explore',
+  usage: 'explore <slug> [place...] walk the hero over each place and check every frame [--fix] [--no-judge] [--port N]',
+  async run(args) {
+    const fix = args.includes('--fix');
+    const noJudge = args.includes('--no-judge');
+    const port = Number(takeOption(args, 'port', '4183'));
+    const [slug, ...only] = args.filter((a) => !a.startsWith('--'));
+    if (!slug) throw new Error('usage: diorama explore <slug> [place...] [--fix] [--no-judge]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    const places = world.places.filter((p) => only.length === 0 || only.includes(p.key));
+
+    const server = await serveWorld(files, port);
+    const browser = await (await chromium()).launch();
+    try {
+      const page = await browser.newPage({ viewport: { width: 1280, height: 960 } });
+      page.on('pageerror', (e) => console.log(`  page error: ${e.message}`));
+      for (const place of places) {
+        const at = (...parts: string[]) => files.place(place.key, ...parts);
+        if (!fs.existsSync(at('geometry.json'))) {
+          console.log(`${place.key}: no geometry.json, skipped`);
+          continue;
+        }
+        const g = Geometry.parse(files.readJson(at('geometry.json')));
+        await page.goto(`http://localhost:${port}/?capture=1&place=${place.key}`);
+        await page.waitForFunction(`window.diorama && window.diorama.place && window.diorama.place.key === ${JSON.stringify(place.key)}`, undefined, { timeout: 30000 });
+
+        const spots = positions(g);
+        const started = Date.now();
+        const hits: ProbeHit[] = [];
+        for (let i = 0; i < spots.length; i += 100) hits.push(...(await call<ProbeHit[]>(page, PROBE_JS, { placeKey: place.key, positions: spots.slice(i, i + 100) })));
+        const checked = hits.map(classify);
+        const bad = checked.filter((h) => h.issues.length);
+        const counts = Object.fromEntries(ISSUES.map((k) => [k, checked.filter((h) => h.issues.includes(k)).length]));
+        console.log(`${place.key}: ${checked.length} spots in ${((Date.now() - started) / 1000).toFixed(1)} s, ${bad.length} with issues ${JSON.stringify(counts)}`);
+
+        fs.rmSync(at('explore'), { recursive: true, force: true });
+        const painting = fs.readFileSync(at('painting.png'));
+        files.write(at('explore', 'heatmap.png'), await heatmap(painting, g, checked));
+
+        // The juror: the worst spots first, the rest random clean ones, so it also says when all is fine.
+        let jury: { tiles: Checked[]; wrong: { id: number; why: string }[] } | undefined;
+        if (!noJudge) {
+          const severity = (h: Checked) => h.issues.length * 1000 + h.drawn - h.hidden;
+          const worst = [...bad].sort((a, b) => severity(b) - severity(a)).slice(0, 10);
+          const clean = checked.filter((h) => !h.issues.length);
+          const random = Array.from({ length: Math.min(16 - worst.length, clean.length) }, (_, i) => clean[Math.floor(((i + 0.5) * clean.length) / Math.min(16 - worst.length, clean.length))]);
+          const tiles = [...worst, ...random];
+          const crops = await Promise.all(tiles.map(async (t) => {
+            const url = await call<string>(page, CROP_JS, { placeKey: place.key, x: t.x, y: t.y, size: 256 });
+            return Buffer.from(url.slice(url.indexOf(',') + 1), 'base64');
+          }));
+          const sheet = await contactSheet(crops, 256);
+          files.write(at('explore', 'sheet.png'), sheet);
+          const wrong = await judge(files.memo, `explore:${place.key}`, sheet, tiles.length);
+          jury = { tiles, wrong };
+          const agree = wrong.filter((w) => tiles[w.id - 1].issues.length).length;
+          console.log(`  juror: ${wrong.length} of ${tiles.length} tiles look wrong (${agree} also failed a code check)${wrong.map((w) => `\n    #${w.id} ${tiles[w.id - 1].issues.join('+') || 'clean'}: ${w.why}`).join('')}`);
+        }
+
+        let fixed: { closed: number; undone: string[] } | undefined;
+        if (fix && bad.length) {
+          const result = fixGrid(g, checked);
+          fixed = { closed: result.closed, undone: result.undone };
+          if (result.closed) {
+            const flagged = [...(g.flagged ?? []), `explorer closed ${result.closed} cells where the hero looked wrong`];
+            files.write(at('geometry.json'), Geometry.parse({ ...result.geometry, flagged }));
+          }
+          console.log(`  fix: closed ${result.closed} cells${result.undone.map((u) => `; not fixed: ${u}`).join('')}`);
+        }
+
+        files.write(at('explore', 'report.json'), {
+          spots: checked.length,
+          counts,
+          bad: bad.map(({ x, y, issues, worst, drawn, hidden }) => ({ x, y, issues, worst, drawn, hidden })),
+          ...(jury && { juror: jury.wrong.map((w) => ({ ...w, x: jury.tiles[w.id - 1].x, y: jury.tiles[w.id - 1].y, codeIssues: jury.tiles[w.id - 1].issues })) }),
+          ...(fixed && { fixed }),
+        });
+      }
+    } finally {
+      await browser.close();
+      server.close();
+    }
+    console.log(`spark calls sent: ${files.memo.sent.spark}`);
+  },
+});

package/app/src/commands/export.ts

@@ -0,0 +1,142 @@
+// diorama export <slug> [dir]: the world as a static folder (index.html, main.js, world-data.json, files/) any web host can serve.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { defineCommand } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { bundle, WEB, worldData } from './play.ts';
+
+const esc = (s: string) => s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** The link preview (X, Facebook, chats): the world's title and pitch, and a 1200x630 picture: the world's own og.jpg when it has one, else its first painted place. */
+async function sharePreview(files: WorldFiles, out: string, url?: string): Promise<string> {
+  const world = files.world();
+  const title = `${world.title} · Diorama`;
+  const pitch = world.pitch.length > 200 ? `${world.pitch.slice(0, 197).replace(/\s+\S*$/, '')}…` : world.pitch;
+  const own = files.path('og.jpg');
+  const painted = [world.start, ...world.places.map((p) => p.key)].map((key) => files.place(key, 'painting.png')).find((f) => fs.existsSync(f));
+  const source = fs.existsSync(own) ? own : painted;
+  const base = url ? (url.endsWith('/') ? url : `${url}/`) : '';
+  const tags = [`<title>${esc(title)}</title>`, `<meta name="description" content="${esc(pitch)}">`, `<meta property="og:type" content="website">`, `<meta property="og:title" content="${esc(title)}">`, `<meta property="og:description" content="${esc(pitch)}">`];
+  if (base) tags.push(`<meta property="og:url" content="${esc(base)}">`);
+  if (source) {
+    await sharp(source).resize(1200, 630, { fit: 'cover', position: 'attention' }).jpeg({ quality: 85, mozjpeg: true }).toFile(path.join(out, 'og.jpg'));
+    // Crawlers want an absolute address; the stamp makes X fetch a new picture after a re-export.
+    const image = `${base}og.jpg?v=${Date.now().toString(36)}`;
+    tags.push(`<meta property="og:image" content="${esc(image)}">`, '<meta property="og:image:width" content="1200">', '<meta property="og:image:height" content="630">', `<meta property="og:image:alt" content="${esc(world.title)}, a playable paper diorama world">`, '<meta name="twitter:card" content="summary_large_image">', `<meta name="twitter:image" content="${esc(image)}">`);
+  } else tags.push('<meta name="twitter:card" content="summary">');
+  tags.push(`<meta name="twitter:title" content="${esc(title)}">`, `<meta name="twitter:description" content="${esc(pitch)}">`);
+  return tags.join('\n');
+}
+
+/** Writes the playable copy of world `slug` to `out`, replacing whatever was there; `home` adds a link back to the page it is shared from; `url` is where the copy will be served, so its link preview has absolute addresses. */
+export async function exportWorld(slug: string, out: string, home?: string, url?: string): Promise<void> {
+  const files = new WorldFiles(slug);
+  const data = worldData(files);
+  fs.rmSync(out, { recursive: true, force: true });
+  fs.mkdirSync(out, { recursive: true });
+  const copy = async (rel: string, asJpeg = false): Promise<string> => {
+    const target = asJpeg ? rel.replace(/\.png$/, '.jpg') : rel;
+    const dest = path.join(out, 'files', target);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    // Paintings are opaque, so JPEG keeps them a fraction of the size; masks and figures stay PNG.
+    if (asJpeg) await sharp(files.path(rel)).jpeg({ quality: 88, mozjpeg: true }).toFile(dest);
+    else fs.copyFileSync(files.path(rel), dest);
+    return target;
+  };
+  // Cut-outs, sprite sheets and icons only need their look and an exact edge: WebP with lossless alpha is a
+  // fraction of the PNG, and those files are most of what a player waits for. A file is changed only when it gets smaller.
+  const done = new Map<string, string>();
+  const art = async (rel: string): Promise<string> => {
+    if (done.has(rel)) return done.get(rel)!;
+    let target = rel;
+    const webp = /\.png$/i.test(rel) ? await sharp(files.path(rel)).webp({ quality: 90, alphaQuality: 100, effort: 5 }).toBuffer() : undefined;
+    if (webp && webp.length < fs.statSync(files.path(rel)).size * 0.9) {
+      target = rel.replace(/\.png$/i, '.webp');
+      const dest = path.join(out, 'files', target);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, webp);
+    } else await copy(rel);
+    done.set(rel, target);
+    return target;
+  };
+  /** `file` inside `dir`, as art; its new name, still inside `dir`. */
+  const artIn = async (dir: string, file: string) => path.posix.relative(dir, await art(`${dir}/${file}`));
+  for (const [key, entry] of Object.entries(data.places)) {
+    if (entry.painting) entry.painting = await copy(entry.painting, true);
+    if (entry.backdrop) entry.backdrop = await copy(entry.backdrop, true);
+    if (entry.layers) {
+      if (entry.layers.sky) entry.layers.sky = await copy(entry.layers.sky, true);
+      if (entry.layers.water) {
+        entry.layers.water.tex = await copy(entry.layers.water.tex);
+        entry.layers.water.mask = await copy(entry.layers.water.mask);
+      }
+      if (entry.layers.mist) {
+        entry.layers.mist.tex = await copy(entry.layers.mist.tex);
+        entry.layers.mist.mask = await copy(entry.layers.mist.mask);
+      }
+      for (const f of entry.layers.flats) f.file = await art(f.file); // transparent around the flat
+      for (const f of [...(entry.layers.smoke ?? []), ...(entry.layers.floats ?? []), ...(entry.layers.falls ?? []), ...(entry.layers.critters ?? []), ...(entry.layers.clouds?.bands ?? [])]) f.file = await art(f.file);
+      if (entry.layers.clouds) {
+        entry.layers.clouds.clip = await copy(entry.layers.clouds.clip);
+        if (entry.layers.clouds.keep) entry.layers.clouds.keep = await copy(entry.layers.clouds.keep);
+      }
+    }
+    for (const thing of entry.geometry?.things ?? []) {
+      if (thing.mask) await copy(`places/${key}/${thing.mask}`);
+      // A plate is the patch where the thing was, transparent elsewhere.
+      if (thing.plate) thing.plate = await artIn(`places/${key}`, thing.plate);
+    }
+    for (const occ of entry.geometry?.occluders ?? []) if (occ.mask) await copy(`places/${key}/${occ.mask}`);
+    if (entry.geometry?.shadows) await copy(`places/${key}/${entry.geometry.shadows}`);
+    if (entry.geometry?.depth) await copy(`places/${key}/${entry.geometry.depth}`);
+    if (entry.weather?.ripples) entry.weather.ripples = await copy(entry.weather.ripples);
+  }
+  for (const [i, rel] of Object.entries(data.changes)) data.changes[i] = await art(rel); // transparent around the thing
+  for (const [i, rel] of Object.entries(data.changeShapes)) data.changeShapes[i] = await copy(rel);
+  for (const figure of Object.values(data.cast)) {
+    figure.image = await art(figure.image);
+    if (figure.face) await copy(`${figure.face.dir}/${figure.face.info.image}`); // the face atlas is read cell by cell, so as is
+    for (const part of figure.rig?.parts ?? []) part.file = await artIn(figure.parts!, part.file);
+    if (figure.rig?.sheet) figure.rig.sheet.file = await artIn(figure.parts!, figure.rig.sheet.file);
+    if (figure.sprites) for (const f of [...Object.values(figure.sprites.info.facings), ...Object.values(figure.sprites.info.talk ?? {})]) f.sheet = await artIn(figure.sprites.dir, f.sheet);
+    // The page draws sprites when it has them; the 3D model behind them (a glb and four big views) is only for ?model=1.
+    if (figure.sprites) delete figure.model;
+    if (figure.model) for (const file of [figure.model.info.glb, ...Object.values(figure.model.info.views).map((v) => v.image)]) await copy(`${figure.model.dir}/${file}`);
+  }
+  for (const item of Object.values(data.items ?? {})) item.icon = await art(item.icon); // transparent
+  const recordings = Object.values(data.sound?.bySpeaker ?? {}).flatMap(lines => Object.values(lines));
+  const audioFiles = new Set([...Object.values(data.sound?.files ?? {}), ...Object.values(data.sound?.lines ?? {}), ...recordings].map(sound => sound.file));
+  for (const file of audioFiles) await copy(file);
+  fs.writeFileSync(path.join(out, 'world-data.json'), JSON.stringify(data));
+  fs.writeFileSync(path.join(out, 'main.js'), await bundle(true));
+  let page = fs.readFileSync(path.join(WEB, 'index.html'), 'utf8');
+  page = page.replace('<body>', '<body data-shipped>');
+  if (home) page = page.replace('<div id="soundless"', `<a id="home" href="${esc(home)}">← Diorama</a>\n<div id="soundless"`);
+  page = page.replace('<title>Diorama</title>', await sharePreview(files, out, url));
+  fs.writeFileSync(path.join(out, 'index.html'), page);
+}
+
+defineCommand({
+  name: 'export',
+  usage: 'export <slug> [dir] [--zip] [--home <url>] [--url <url>]   write a static, playable copy of the world (default exports/<slug>); --zip also packs it for itch.io or e-mail; --home puts a "← Diorama" link to <url> in the corner; --url is where it will be served, for the X/Facebook link preview (title, pitch, og.jpg: worlds/<slug>/og.jpg if you made one, else the first place)',
+  async run(args) {
+    const zip = args.includes('--zip');
+    const flag = (name: string) => { const i = args.indexOf(name); if (i >= 0 && !args[i + 1]) throw new Error(`${name} needs a url`); return i; };
+    const h = flag('--home'), u = flag('--url');
+    const home = h >= 0 ? args[h + 1] : undefined;
+    const url = u >= 0 ? args[u + 1] : undefined;
+    const [slug, dir = path.join('exports', slug ?? '')] = args.filter((a, i) => a !== '--zip' && ![h, u].some((f) => f >= 0 && (i === f || i === f + 1)));
+    if (!slug) throw new Error('usage: diorama export <slug> [dir] [--zip] [--home <url>] [--url <url>]');
+    const out = path.resolve(dir);
+    await exportWorld(slug, out, home, url);
+    console.log(`export ${slug}: ${out}`);
+    if (zip) {
+      // index.html at the zip's root, which is what itch.io wants for an HTML5 upload.
+      fs.rmSync(`${out}.zip`, { force: true });
+      execFileSync('zip', ['-qr', `${out}.zip`, '.'], { cwd: out });
+      console.log(`zip: ${out}.zip`);
+    }
+  },
+});

package/app/src/commands/extend.ts

@@ -0,0 +1,75 @@
+// One Studio job: plan and validate first, then build only the anchor and additions.
+import fs from 'node:fs';
+import { defineCommand, emit, registry } from '../registry.ts';
+import { readDrawn } from '../world/drawings.ts';
+import { designExtension } from '../world/extend.ts';
+import { stagedExtension } from '../world/extend-stage.ts';
+import { WorldFiles, withThingEdits } from '../world/files.ts';
+import { World } from '../world/schema.ts';
+import { Story } from '../story/schema.ts';
+import { checkStory } from '../story/check.ts';
+
+export async function extendWorld(slug: string, selected: string[], wish: string) {
+  const files = new WorldFiles(slug);
+  const oldWorld = World.parse(files.readJson(files.path('world.json')));
+  const oldStory = Story.parse(files.readJson(files.path('story.json')));
+  const drawings = selected.map(file => {
+    const d = readDrawn(files).find(x => `drawings/${x.file}` === file);
+    if (!d || !fs.existsSync(files.path(file))) throw new Error(`${file} is not a saved, read drawing`);
+    return d;
+  });
+  // The story uses effective props (including manual edits), while only the base world is persisted.
+  const effective = withThingEdits(oldWorld, files.dir);
+  const designed = await designExtension(files.memo, effective, oldStory, drawings, wish);
+  // Preserve the corrections layer: use each unchanged original place and add only new things to the anchor.
+  const oldByKey = new Map(oldWorld.places.map(p => [p.key, p]));
+  const effectiveByKey = new Map(effective.places.map(p => [p.key, p]));
+  const world = { ...designed.world, places: designed.world.places.map(p => {
+    const old = oldByKey.get(p.key);
+    if (!old) return p;
+    if (!designed.changed.includes(p.key)) return old;
+    const before = effectiveByKey.get(p.key)!;
+    return { ...old, things: [...old.things, ...p.things.filter(t => !before.things.some(x => x.key === t.key))], exits: p.exits };
+  }) };
+  const checked = checkStory(withThingEdits(World.parse(world), files.dir), designed.story);
+  if (checked.issues.length) throw new Error(`story does not fit the corrected world: ${checked.issues.join('; ')}`);
+  const oldNpc = new Set(oldWorld.places.flatMap(p => p.things.filter(t => t.role === 'npc').map(t => t.key)));
+  const newNpc = [...new Set(world.places.flatMap(p => p.things.filter(t => t.role === 'npc' && !oldNpc.has(t.key)).map(t => t.key)))];
+  const newItems = designed.story.items.filter(i => !oldStory.items.some(o => o.key === i.key)).map(i => i.key);
+  files.write(files.path('world.json'), world);
+  files.write(files.path('story.json'), designed.story);
+  files.write(files.path('routes.json'), checked.routes);
+  console.log(`extension planned: ${designed.changed.join(', ')}; ${checked.states} story states checked`);
+  const newPlaces = designed.changed.filter(key => !oldWorld.places.some(place => place.key === key));
+  emit('extension.progress', { phase: 'places', total: designed.changed.length, newPlaces, ...(newNpc.length && { task: 'characters' }) });
+  // Builds run in the private copy; the original remains playable until the whole job succeeds.
+  if (newNpc.length) {
+    await registry.get('cast')!.run([slug, ...newNpc]);
+    const missing = newNpc.filter(key => !fs.existsSync(files.path('cast', `${key}.png`)));
+    if (missing.length) throw new Error(`characters could not be painted: ${missing.join(', ')}`);
+  }
+  for (const [index, place] of designed.changed.entries()) {
+    emit('extension.progress', { phase: 'places', place, index: index + 1, total: designed.changed.length });
+    console.log(`building ${place}`);
+    process.exitCode = 0;
+    await registry.get('build')!.run([slug, '--from', 'layout', '--to', 'verify', '--place', place]);
+    if (process.exitCode) throw new Error(`${place} is not playable; extension was not installed`);
+  }
+  emit('extension.progress', { phase: 'audio' });
+  if (newItems.length) await registry.get('icons')!.run([slug, ...newItems]);
+  await registry.get('voices')!.run([slug]);
+  await registry.get('sound')!.run([slug]);
+  console.log(`extension complete: ${designed.changed.join(', ')}; new characters: ${newNpc.join(', ') || 'none'}`);
+}
+
+defineCommand({
+  name: 'extend',
+  usage: 'extend <slug> <JSON drawing paths> <wish>  extend a built world from saved drawings',
+  async run([slug, json, wish]) {
+    if (!slug || !json || !wish) throw new Error('usage: diorama extend <slug> <JSON drawing paths> <wish>');
+    const selected: unknown = JSON.parse(json);
+    if (!Array.isArray(selected) || !selected.length || !selected.every(f => typeof f === 'string' && /^drawings\/[a-z0-9-]+\.png$/.test(f))) throw new Error('drawings must be an array of drawings/*.png paths');
+    emit('extension.progress', { phase: 'plan' });
+    await stagedExtension(slug, () => extendWorld(slug, selected, wish));
+  },
+});

package/app/src/commands/faces.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import { castLanes, mapLimit } from '../world/pool.ts';
+import { CalibrationTarget, setFaceCalibration } from '../scene/face-calibration.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { players } from '../world/drawings.ts';
+import { prepareFace, repairFaceFrame, calibrateFaceFrame } from '../scene/faces.ts';
+import { registeredFace } from '../scene/faces-data.ts';
+import { FacePreparationError, LipBox, MouthName } from '../scene/face-work.ts';
+import { prepareLipSync } from '../sound/lipsync-make.ts';
+
+export function faceCharacters(files: WorldFiles): string[] {
+  const world = files.world();
+  return [...new Set([world.hero.key, ...world.places.flatMap(p => p.things.filter(t => t.role === 'npc').map(t => t.key)), ...players(files).map(p => p.key)])];
+}
+
+defineCommand({
+  name: 'faces',
+  usage: 'faces <slug> [key...]    prepare speaking faces for paintings, 2D rigs and talk sprites, and cached audio lip-sync [--audio-only] [--image-only] [--force] [--take N] [--rhubarb PATH]',
+  async run(args) {
+    let take = Number(takeOption(args, 'take', '0'));
+    let repairWorkId: string | undefined;
+    const executable = takeOption(args, 'rhubarb', '');
+    const repairId=takeOption(args,'repair-frame',''), calibrateId=takeOption(args,'calibrate-frame','');
+    const revision=takeOption(args,'revision',''), mouth=takeOption(args,'mouth',''), hint=takeOption(args,'hint','');
+    const box=takeOption(args,'box','');
+    const calibration=takeOption(args,'calibration',''), imageHash=takeOption(args,'image-hash',''), open=takeOption(args,'open','');
+    const flag = (name: string) => { const i = args.indexOf(`--${name}`); return i >= 0 ? (args.splice(i, 1), true) : false; };
+    const audioOnly = flag('audio-only'), imageOnly = flag('image-only'), force = flag('force');
+    const [slug, ...only] = args;
+    if (!slug) throw new Error('usage: diorama faces <slug> [key...]');
+    const files = new WorldFiles(slug), keys = faceCharacters(files);
+    for (const key of only) if (!keys.includes(key)) throw new Error(`${slug} has no character ${key}`);
+    if(calibration) {
+      if(only.length!==1 || repairId || calibrateId || !['true','false'].includes(open))throw new Error('Choose one inspected calibration');
+      await setFaceCalibration(files,only[0],CalibrationTarget.parse(JSON.parse(calibration)),revision,imageHash,LipBox.parse(JSON.parse(box)),open==='true');
+    }
+    if(repairId || calibrateId) {
+      if(only.length!==1 || repairId && calibrateId) throw new Error('Choose one character and one face correction');
+      const work = repairId ? await repairFaceFrame(files,only[0],repairId,revision,MouthName.parse(mouth),hint)
+        : calibrateFaceFrame(files,only[0],calibrateId,revision,MouthName.parse(mouth),LipBox.parse(JSON.parse(box)));
+      take = work.take; repairWorkId = work.id;
+    }
+    const statusFile = files.path('face-preparation.json');
+    const status = fs.existsSync(statusFile) ? files.readJson(statusFile) as Record<string, { face?: string | null; audio?: string[] }> : {};
+    for (const key of keys) if (!status[key]) {
+      const attempt=files.path('cast',key,'face-attempt.json');
+      if(fs.existsSync(attempt)) {
+        const previous=files.readJson(attempt) as {state?:string;reason?:string};
+        status[key]=previous.state==='failed'&&!registeredFace(files,key)?.info.imagePose?.lips?{face:previous.reason??'Face preparation failed'}:previous.state?{face:null}:{};
+      }
+    }
+    const failures: string[] = [];
+    // Each character's face is its own work (its own files under cast/<key>): a few side by side.
+    if (!audioOnly) await mapLimit(keys.filter(k => !only.length || only.includes(k)), castLanes(), async (key) => {
+      try { await prepareFace(files, key, { take, force, imageOnly, repairWorkId }); (status[key] ??= {}).face = null; }
+      catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        files.write(files.path('cast', key, 'face-attempt.json'), { at: new Date().toISOString(), state: 'failed', take, reason });
+        console.log(`${key}: face preparation failed; existing face retained: ${reason}`);
+        // A retry (new talk sheets, a new take) that fails leaves the working face in place: the character
+        // still speaks with moving lips, so the build is not short of faces. Asked for by name, it is reported.
+        if (registeredFace(files, key)?.info.imagePose?.lips && !only.length) { (status[key] ??= {}).face = null; return; }
+        failures.push(`${key}: ${reason}`);
+        (status[key] ??= {}).face = reason;
+      }
+    });
+    files.write(statusFile, status);
+    if (fs.existsSync(files.path('voices.json'))) {
+      const audio = await prepareLipSync(files, only, executable || undefined);
+      for (const key of [...new Set([...keys, ...Object.keys(status)])].filter(k => !only.length || only.includes(k))) delete (status[key] ??= {}).audio;
+      for (const failure of audio.failures ?? []) {
+        failures.push(`${failure.speaker}: ${failure.reason}`);
+        ((status[failure.speaker] ??= {}).audio ??= []).push(failure.reason);
+      }
+      files.write(statusFile, status);
+    }
+    if (failures.length) throw new FacePreparationError(failures);
+  },
+});

package/app/src/commands/icons.ts

@@ -0,0 +1,69 @@
+// diorama icons <slug> [item...]: items/<key>.png for every item in story.json, and items/items.json saying how each was made.
+import fs from 'node:fs';
+import sharp from 'sharp';
+import { maskFromPng } from '../image/mask.ts';
+import { maskBox } from '../image/raster.ts';
+import { defineCommand } from '../registry.ts';
+import { cutIcon, itemSources, ItemsInfo, MIN_CUT_PX, paintIcon, readIconFixes, redrawIcon } from '../scene/icons.ts';
+import { Story } from '../story/schema.ts';
+import { WorldFiles } from '../world/files.ts';
+
+defineCommand({
+  name: 'icons',
+  usage: 'icons <slug> [item...]  an inventory icon per story item: cut from the painting where the hero picks it up, else painted by Muse (items/fixes.json: how, hint, take)',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: diorama icons <slug> [item...]');
+    const files = new WorldFiles(slug);
+    if (!fs.existsSync(files.path('story.json'))) {
+      console.log('no story.json: no items, no icons');
+      return;
+    }
+    const world = files.world();
+    const story = Story.parse(files.readJson(files.path('story.json')));
+    const sources = itemSources(story);
+    const fixes = readIconFixes(files);
+    const infoFile = files.path('items', 'items.json');
+    const info: ItemsInfo = fs.existsSync(infoFile) ? ItemsInfo.parse(files.readJson(infoFile)) : {};
+    // Items the story no longer has lose their icons.
+    for (const key of Object.keys(info)) if (!sources[key] && !story.items.some((i) => i.key === key)) delete info[key];
+    const items = story.items.filter((i) => only.length === 0 || only.includes(i.key));
+    const failed: string[] = [];
+    // An item without an icon shows its name in the bag, so one failure does not stop the build.
+    await Promise.all(items.map(async (item) => { try {
+      const from = sources[item.key];
+      const fix = fixes[item.key] ?? {};
+      let png: Buffer;
+      let how: ItemsInfo[string]['how'];
+      const maskFile = from && files.place(from.place, 'masks', `${from.thing}.png`);
+      if (from && maskFile && fs.existsSync(maskFile) && fix.how !== 'paint') {
+        const painting = fs.readFileSync(files.place(from.place, 'painting.png'));
+        const mask = await maskFromPng(fs.readFileSync(maskFile));
+        const box = maskBox(mask);
+        const side = box ? Math.max(box[2] - box[0], box[3] - box[1]) : 0;
+        // A hint from the person means the picture itself should change, so Muse redraws even a large cut-out.
+        if (fix.how === 'cut' || (side >= MIN_CUT_PX && !fix.hint)) {
+          png = await cutIcon(painting, mask);
+          how = 'cut';
+        } else {
+          // Too small to blow up, or the person asked for changes: Muse redraws the cut-out.
+          const crop = await sharp(await cutIcon(painting, mask, 12)).flatten({ background: '#f3ead8' }).png().toBuffer();
+          png = await redrawIcon(files.memo, world, item, crop, fix.hint, fix.take);
+          how = 'redraw';
+        }
+      } else {
+        if (from) console.log(`  ${item.key}: ${from.place}/${from.thing} has no mask, Muse paints it`);
+        png = await paintIcon(files.memo, world, item, fix.hint, fix.take);
+        how = 'paint';
+      }
+      files.write(files.path('items', `${item.key}.png`), png);
+      info[item.key] = { icon: `items/${item.key}.png`, how, from };
+      console.log(`${item.key}: ${how}${from ? ` from ${from.place}/${from.thing}` : ''}`);
+    } catch (error) {
+      failed.push(item.key);
+      console.log(`  ${item.key}: no icon (${error instanceof Error ? error.message : error}); the bag shows its name. icon_redo with a hint tries again`);
+    } }));
+    files.write(infoFile, info);
+    if (failed.length) console.log(`no icon for: ${failed.join(', ')}`);
+    console.log(`calls sent: muse ${files.memo.sent.muse}, sam ${files.memo.sent.sam}`);
+  },
+});

package/app/src/commands/index.ts

@@ -0,0 +1,36 @@
+// Command modules; each one calls defineCommand.
+import './doctor.ts';
+import './world.ts';
+import './extend.ts';
+import './story.ts';
+import './playthrough.ts';
+import './layout.ts';
+import './paint.ts';
+import './masks.ts';
+import './plates.ts';
+import './icons.ts';
+import './derive.ts';
+import './backdrop.ts';
+import './weather.ts';
+import './reactions.ts';
+import './sound.ts';
+import './voices.ts';
+import './faces.ts';
+import './voice-retry.ts';
+import './verify.ts';
+import './explore.ts';
+import './build.ts';
+import './cast.ts';
+import './model.ts';
+import './sprites.ts';
+import './style.ts';
+import './play.ts';
+import './export.ts';
+import './publish.ts';
+import './reel.ts';
+import './clip.ts';
+import './setup.ts';
+import './browsers.ts';
+import './action.ts';
+import './studio.ts';
+import './mcp.ts';

package/app/src/commands/layout.ts

@@ -0,0 +1,31 @@
+// diorama layout <slug> [place...]: layout.json, blockin.png (for Muse) and plan.png (for people) for each place.
+import fs from 'node:fs';
+import { renderBlockin, renderPlan } from '../scene/blockin.ts';
+import { readCorrections } from '../scene/corrections.ts';
+import { layOut } from '../scene/layout.ts';
+import { defineCommand } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { approvedConcept } from '../world/sketch.ts';
+
+defineCommand({
+  name: 'layout',
+  usage: 'layout <slug> [place...] lay out places (layout.json, blockin.png) with Muse Spark',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: diorama layout <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) => {
+      // A place made from a photo is measured from it, and the photo stands in for the block-in.
+      const photoFile = files.place(place.key, 'photo.png');
+      const photo = fs.existsSync(photoFile) ? fs.readFileSync(photoFile) : undefined;
+      const layout = await layOut(files.memo, world, place, photo, readCorrections(files.place(place.key)).layout?.guidance, approvedConcept(files, 'place', place.key));
+      files.write(files.place(place.key, 'layout.json'), layout);
+      const blockin = photo ?? await renderBlockin(layout, place);
+      files.write(files.place(place.key, 'blockin.png'), blockin);
+      files.write(files.place(place.key, 'plan.png'), await renderPlan(layout, place, blockin, world.names));
+      console.log(`${place.key}: ${layout.floors.length} floor(s), ${layout.things.length} things, horizon ${layout.horizon}`);
+    }));
+    console.log(`spark calls sent: ${files.memo.sent.spark}`);
+  },
+});