@gtanczyk/diorama 0.4.0 → 0.5.0

package/app/src/actions/fix.ts

@@ -171,6 +171,20 @@ defineAction({
   },
 });
 
+defineAction({
+  name: 'hero_size_set',
+  description: 'Say how tall the hero stands in a place, against a thing painted there: times that thing\'s painted height ("about as tall as the candle jar": 1). '
+    + 'Use it when the hero is far too big or small for the place, or differs from place to place in one world (a desk seen whole and a close-up of a mug), '
+    + 'or when only a strip of floor is walkable because the hero would be taller than the picture at the front. Sets the place\'s scale. Kept across rebuilds. No repaint: reruns derive to verify for that place.',
+  input: z.object({ slug: Slug, place: z.string().min(1), like: z.string().min(1), times: z.number().positive().max(20) }),
+  job: true,
+  async run({ slug, place, like, times }, ctx) {
+    return fixPlace(ctx, slug, place, 'derive', `hero size ${times} x ${like}`, (c) => {
+      c.heroSize = { like, times };
+    });
+  },
+});
+
 defineAction({
   name: 'hero_start_set',
   description: 'Set where the hero begins in a place (painting pixels, on walkable floor; the nearest roomy cell of the main floor is used): '

package/app/src/actions/studio.ts

@@ -8,6 +8,8 @@ import { soundQuality } from '../sound/cost.ts';
 import { writeSoundQuality } from '../sound/settings.ts';
 import { blenderEnv, blenderState, writeBlenderSettings } from '../model/blender.ts';
 import { facesState, writeFacesSettings } from '../scene/faces-settings.ts';
+import { installChromium } from '../commands/browsers.ts';
+import { cli } from '../cli.ts';
 
 const audioState = () => ({ quality: soundQuality(), env: process.env.DIORAMA_SOUND ?? null });
 
@@ -87,6 +89,29 @@ defineAction({
   },
 });
 
+defineAction({
+  name: 'setup_cli',
+  reads: true,
+  description: 'The command that runs diorama in a terminal on this machine (diorama, npx @gtanczyk/diorama or npm run diorama --), for hints to the person.',
+  input: z.object({}),
+  async run() {
+    return { command: cli(), setup: cli('setup') };
+  },
+});
+
+let downloading: Promise<unknown> | null = null;
+
+defineAction({
+  name: 'setup_browsers',
+  description: 'Download Chromium for Explore, the playthrough bot and sprites (Playwright, ~150 MB, once), then check the machine again. Ask the person first.',
+  input: z.object({}),
+  async run(_input, ctx) {
+    downloading ??= installChromium([], (line) => /\d%/.test(line) && !/100%/.test(line) ? undefined : ctx.events.publish('log', { stream: 'out', line: `chromium: ${line}` })).finally(() => (downloading = null));
+    await downloading;
+    return runChecks();
+  },
+});
+
 defineAction({
   name: 'ui_focus',
   description: 'Point the Studio view at a world, a screen or a place, so the person sees what the agent is talking about (when they follow the agent).',

package/app/src/cli.ts

@@ -0,0 +1,53 @@
+// How to run diorama again from this shell, so every hint (setup fixes, errors, the Studio's Setup cards, the
+// agent's prompt) shows a command that works: `npx @gtanczyk/diorama` when it was started through npx, `diorama`
+// when the global install is on PATH, `npm run diorama --` from a checkout.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const BIN = path.join(ROOT, 'app', 'bin', 'diorama.mjs');
+const PACKAGE = '@gtanczyk/diorama';
+
+const real = (p: string) => {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return null;
+  }
+};
+
+/** A `diorama` on PATH that is this very package (npx and npm scripts put their own node_modules/.bin first: not those). */
+function globalOnPath(): boolean {
+  const mine = real(BIN);
+  for (const dir of (process.env.PATH ?? '').split(path.delimiter)) {
+    if (!dir || dir.split(/[\\/]/).slice(-2).join('/') === 'node_modules/.bin') continue;
+    if (real(path.join(dir, 'diorama')) === mine) return true;
+    // Windows: npm's global shim sits next to the package's node_modules folder, not as a link.
+    if (process.platform === 'win32' && fs.existsSync(path.join(dir, 'diorama.cmd')) && real(path.join(dir, 'node_modules', '@gtanczyk', 'diorama')) === real(ROOT)) return true;
+  }
+  return false;
+}
+
+function detect(): string {
+  if (process.env.DIORAMA_CLI) return process.env.DIORAMA_CLI;
+  const parts = ROOT.split(/[\\/]/);
+  if (parts.includes('_npx')) return `npx ${PACKAGE}`;
+  if (globalOnPath()) return 'diorama';
+  if (!parts.includes('node_modules') && fs.existsSync(path.join(ROOT, '.git'))) return 'npm run diorama --';
+  return `npx ${PACKAGE}`;
+}
+
+let prefix: string | null = null;
+
+/** The command to type for `diorama <rest>` here, e.g. cli('browsers') → `npx @gtanczyk/diorama browsers`. */
+export function cli(rest = ''): string {
+  prefix ??= detect();
+  return rest ? `${prefix} ${rest}` : prefix;
+}
+
+/** Rewrites the `diorama <command>` a message names (a usage line, an error) into the command that works here. */
+export function cliText(text: string): string {
+  if (cli() === 'diorama') return text;
+  return text.replace(/(^|usage: |`|run )diorama (?=[a-z])/g, (_, lead: string) => `${lead}${cli()} `);
+}

package/app/src/commands/browsers.ts

@@ -1,21 +1,37 @@
 // diorama browsers: downloads Chromium for the Playwright that ships with diorama, so explore, playthrough and
 // sprites work the same from a checkout, a global install or npx (a bare `npx playwright` may fetch another version).
+// `diorama setup` and the Studio's Setup page offer the same download, so nobody has to find this command.
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { defineCommand } from '../registry.ts';
 
+/** Runs Playwright's installer for Chromium; `onLine` gets its output (the terminal gets it as is when absent). */
+export async function installChromium(args: string[] = [], onLine?: (line: string) => void): Promise<void> {
+  const cli = path.join(path.dirname(createRequire(import.meta.url).resolve('playwright/package.json')), 'cli.js');
+  const code = await new Promise<number>((resolve) => {
+    // Loaded through -e so argv[1] is not the npx cache path, which makes Playwright warn about missing project dependencies.
+    const child = spawn(process.execPath, ['-e', `require(${JSON.stringify(cli)})`, 'diorama-browsers', 'install', 'chromium', ...args], { stdio: onLine ? ['ignore', 'pipe', 'pipe'] : 'inherit' });
+    if (onLine) {
+      for (const stream of [child.stdout, child.stderr]) {
+        let rest = '';
+        stream?.setEncoding('utf8').on('data', (chunk: string) => {
+          const lines = (rest + chunk).split(/\r?\n|\r/);
+          rest = lines.pop() ?? '';
+          for (const line of lines) if (line.trim()) onLine(line);
+        });
+      }
+    }
+    child.on('error', () => resolve(1));
+    child.on('close', (c) => resolve(c ?? 1));
+  });
+  if (code !== 0) throw new Error(`playwright install chromium exited with ${code}`);
+}
+
 defineCommand({
   name: 'browsers',
   usage: 'browsers                download Chromium for explore, playthrough and sprites (Playwright, ~150 MB, once)',
   async run(args) {
-    const cli = path.join(path.dirname(createRequire(import.meta.url).resolve('playwright/package.json')), 'cli.js');
-    const code = await new Promise<number>((resolve) => {
-      // Loaded through -e so argv[1] is not the npx cache path, which makes Playwright warn about missing project dependencies.
-      const child = spawn(process.execPath, ['-e', `require(${JSON.stringify(cli)})`, 'diorama-browsers', 'install', 'chromium', ...args], { stdio: 'inherit' });
-      child.on('error', () => resolve(1));
-      child.on('close', (c) => resolve(c ?? 1));
-    });
-    if (code !== 0) throw new Error(`playwright install chromium exited with ${code}`);
+    await installChromium(args);
   },
 });

package/app/src/commands/derive.ts

@@ -16,6 +16,7 @@ import { closeFaces, placeDepth } from '../scene/occlusion-check.ts';
 import { gridOf } from '../scene/verify.ts';
 import { unionAll } from '../image/raster.ts';
 import { WorldFiles } from '../world/files.ts';
+import { readBodies } from '../scene/cast.ts';
 
 type MasksJson = { things: Record<string, Omit<ThingIn, 'key' | 'mask'>> };
 
@@ -54,7 +55,8 @@ async function walkPicture(painting: Buffer, g: Geometry, footprint: ThingIn['ma
   // The hero's size at three depths, as little figures spread over the floor (far left, middle, near right):
   // stacked boxes in one column read as a path, not as a person.
   const rows = g.walk.map((row, r) => (row.includes('#') ? r : -1)).filter((r) => r >= 0);
-  for (const [q, across] of [[0.1, 0.2], [0.5, 0.5], [0.95, 0.8]] as const) {
+  // No walkable row at all (NO_FLOOR): no figures to draw; verify reports the missing floor.
+  for (const [q, across] of rows.length ? ([[0.1, 0.2], [0.5, 0.5], [0.95, 0.8]] as const) : []) {
     const r = rows[Math.floor(q * (rows.length - 1))];
     const cols = [...g.walk[r]].flatMap((ch, c) => (ch === '#' ? [c] : []));
     // The walkable cell nearest to a quarter, the middle and three quarters of the frame, so they stand apart.
@@ -94,6 +96,7 @@ defineCommand({
     const files = new WorldFiles(slug);
     const world = files.world();
     const places = world.places.filter((p) => only.length === 0 || only.includes(p.key));
+    const heroMetres = readBodies(files, fs.existsSync)[world.hero.key]?.height;
     await Promise.all(places.map(async (place) => {
       const at = (...parts: string[]) => files.place(place.key, ...parts);
       // NPCs are drawn by the runtime, not painted: moving one only moves its box (and where the hero talks to it).
@@ -121,7 +124,7 @@ defineCommand({
         console.log(`  ${place.key}: no depth model for walls (${e.message})`);
         return undefined;
       });
-      const out = await derive(files.memo, { place, layout: asPainted, things, floors, painting, plates, carry, lastScale, previousScale, ...(start && { start }), ...(upright && { upright }), ...(said && { said }) }, (line) => console.log(`  ${place.key}: ${line}`));
+      const out = await derive(files.memo, { place, layout: asPainted, things, floors, painting, plates, carry, lastScale, previousScale, ...(start && { start }), ...(upright && { upright }), ...(said && { said }), ...(heroMetres && { heroMetres }), ...(readCorrections(at()).heroSize && { heroSize: readCorrections(at()).heroSize }) }, (line) => console.log(`  ${place.key}: ${line}`));
       // Shadows only with a light: without one the runtime has nothing to darken by.
       const lit = out.shadows.light && maskArea(out.shadows.mask) > 0;
       if (lit) files.write(at('masks', 'shadows.png'), await maskToPng(out.shadows.mask));

package/app/src/commands/explore.ts

@@ -9,6 +9,7 @@ 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';
+import { cli } from '../cli.ts';
 
 export type Browser = { newPage(o?: object): Promise<Page>; close(): Promise<void> };
 export type Page = {
@@ -26,7 +27,7 @@ export async function chromium(): Promise<{ launch(o?: object): Promise<Browser>
     try {
       return (createRequire(import.meta.url)('playwright') as { chromium: never }).chromium;
     } catch {
-      throw new Error('this command needs Playwright with Chromium: diorama browsers');
+      throw new Error(`this command needs Playwright with Chromium: ${cli('browsers')}`);
     }
   }
 }

package/app/src/commands/model.ts

@@ -149,6 +149,14 @@ async function makeModel(files: WorldFiles, key: string, take: number, given: st
   try {
     views = await paintViews(files.memo, key, who.looks ?? '', painting, take, creature, (name, png) => files.write(out(`${name}.png`), png));
   } catch (error) {
+    // A creature whose sides never showed one body: no model, the painted figure hops as it is (an older model too
+    // was made from such sides, so it goes).
+    const message = error instanceof Error ? error.message : String(error);
+    if (creature && message.startsWith('its 4 sides do not show one creature')) {
+      if (fs.existsSync(out('model.json'))) fs.renameSync(out('model.json'), out('model-rejected.json'));
+      console.log(`${key}: no 3D model: ${message}; the painted figure hops as it is`);
+      return message;
+    }
     // Refused even in calm words: the model made before stays (a changed prompt reran it), else the 2D rig walks.
     if (!refusedByFilter(error)) throw error;
     if (fs.existsSync(out('model.json')) && fs.existsSync(out('model.glb'))) {

package/app/src/commands/paint.ts

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import { writeBrief } from '../scene/brief.ts';
 import { seedRan } from '../scene/carry.ts';
-import { addsPerson, critique, paintedPeople, repaint } from '../scene/critic.ts';
+import { addsPerson, castLooks, critique, paintedPeople, repaint } from '../scene/critic.ts';
 import { readCorrections, writeCorrections } from '../scene/corrections.ts';
 import { Layout } from '../scene/layout.ts';
 import { paintPlace } from '../scene/paint.ts';
@@ -98,7 +98,7 @@ defineCommand({
         const again = await critique(files.memo, worded(place, words), brief, first);
         // People are looked for on the painting as the game shows it, with every fix in, not only the first one.
         const shown = fs.existsSync(files.place(place.key, 'painting.png')) ? fs.readFileSync(files.place(place.key, 'painting.png')) : first;
-        for (const p of shown === first || place.kind === 'drive' ? [] : await paintedPeople(files.memo, place.key, shown)) {
+        for (const p of shown === first || place.kind === 'drive' ? [] : await paintedPeople(files.memo, place.key, shown, castLooks(place))) {
           again.issues.push({ key: 'person', problem: 'unwanted', region: p.box, fix: `Paint out the ${p.what}: continue what is behind them (planks, water, wall), add nothing new` });
         }
         const had = new Set(found.issues.map((i) => JSON.stringify([i.region, i.fix])));

package/app/src/commands/setup.ts

@@ -2,6 +2,8 @@
 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';
+import { installChromium } from './browsers.ts';
+import { cli } from '../cli.ts';
 
 const MARK: Record<Check['state'], string> = { ok: '  ok      ', missing: '  MISSING ', optional: '  -       ', fail: '  FAIL    ' };
 
@@ -15,7 +17,7 @@ export function printChecks(checks: Check[]) {
 /** 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');
+  if (!stdin.isTTY) throw new Error(`${cli('setup')} reads keys from a terminal only; or set them as environment variables`);
   process.stdout.write(question);
   return new Promise((resolve, reject) => {
     let value = '';
@@ -42,6 +44,17 @@ function askHidden(question: string): Promise<string> {
   });
 }
 
+/** A yes/no question in the terminal; Enter means yes. */
+async function askYes(question: string): Promise<boolean> {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return !/^n/i.test((await rl.question(question)).trim());
+  } finally {
+    rl.close();
+  }
+}
+
 async function storeKey(name: SecretName, remove: boolean) {
   const vault = await findVault();
   if (!vault) throw new Error(NO_VAULT);
@@ -79,6 +92,17 @@ defineCommand({
       console.log('');
       printChecks(checks);
     }
+    // Chromium is one download: offer it here instead of sending the person off to find another command.
+    if (process.stdin.isTTY && checks.some((c) => c.id === 'chromium' && c.state === 'missing') && (await askYes('\nDownload Chromium for Explore and Playthrough now (~150 MB, once)? [Y/n] '))) {
+      try {
+        await installChromium();
+      } catch (error) {
+        console.log(`Chromium download failed (${error instanceof Error ? error.message : error}); try again with ${cli('browsers')}`);
+      }
+      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/studio.ts

@@ -58,6 +58,7 @@ function describe(e: StudioEvent, verbose: boolean): string | null {
     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.limit': return `agent ${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/voices.ts

@@ -14,7 +14,7 @@ import { resumePendingVoices } from '../sound/voices.ts';
 
 defineCommand({
   name: 'voices',
-  usage: 'voices <slug>            cast a voice per character (stock, or designed by ElevenLabs Voice Design for children, teens and the old) and speak every story line, checked by Muse Voice Transcribe; conversations, intro and endings [--all: every line; always for a world for kids, whose players cannot read] [--recast] [--draft: Flash and 2 takes; default final uses Multilingual v2 and up to 3 takes]',
+  usage: 'voices <slug>            cast a voice per character (stock, or designed by ElevenLabs Voice Design for children, teens and the old) and speak every story line, checked by Muse Voice Transcribe; every line the hero and the others say, intro and endings [--essential: only conversations, intro and endings, not the hero\'s looks, uses and locked doors] [--recast] [--draft: Flash and 2 takes; default final uses Multilingual v2 and up to 3 takes]',
   async run(args) {
     // Keep this generation at one quality even if Setup changes while it runs.
     process.env.DIORAMA_SOUND = soundQuality(args);
@@ -27,7 +27,9 @@ defineCommand({
     if (!elevenKey()) return void console.log('no ELEVENLABS_API_KEY: lines stay unspoken');
     const story = Story.parse(files.readJson(files.path('story.json')));
     const guard = await creditGuard(elevenKey(), 'voices');
-    const lines = storyLines(world, story, args.includes('--all') || world.audience === 'kids');
+    // Every line by default: a hero who answers out loud in conversations and is silent looking at things reads as broken.
+    // --essential keeps to conversations, intro and endings (a world for kids always gets every line).
+    const lines = storyLines(world, story, !args.includes('--essential') || world.audience === 'kids');
     const outFile = files.path('voices.json');
     const old = fs.existsSync(outFile) ? Voices.parse(files.readJson(outFile)) : undefined;
     let cast: Cast;

package/app/src/main.ts

@@ -1,11 +1,12 @@
 import './commands/index.ts';
 import { registry } from './registry.ts';
 import { loadSecrets, redact } from './secrets.ts';
+import { cli, cliText } from './cli.ts';
 
 function help() {
-  console.log('diorama: a story prompt becomes painted scenes you can walk in\n\nusage: diorama <command> [args]\n');
+  console.log(`diorama: a story prompt becomes painted scenes you can walk in\n\nusage: ${cli('<command> [args]')}\n`);
   for (const cmd of registry.values()) console.log(`  ${cmd.usage}`);
-  console.log('\nfirst time: diorama setup (keys, what is missing), then diorama studio. Worlds are written to ./worlds here.');
+  console.log(`\nfirst time: ${cli('setup')} (keys, what is missing), then ${cli('studio')}. Worlds are written to ./worlds here.`);
 }
 
 const [name, ...args] = process.argv.slice(2);
@@ -15,7 +16,7 @@ if (!cmd) {
   process.exit(!name || name === 'help' ? 0 : 2);
 }
 if (args.includes('--help') || args.includes('-h')) {
-  console.log(`usage: diorama ${cmd.usage}`);
+  console.log(`usage: ${cli(cmd.usage)}`);
   process.exit(0);
 }
 try {
@@ -23,6 +24,6 @@ try {
   if (name !== 'setup') await loadSecrets();
   await cmd.run(args);
 } catch (error) {
-  console.error(redact(`diorama ${name}: ${error instanceof Error ? error.message : error}`));
+  console.error(redact(`diorama ${name}: ${cliText(error instanceof Error ? error.message : String(error))}`));
   process.exit(1);
 }

package/app/src/model/views.ts

@@ -158,6 +158,45 @@ async function paintCreatureViews(memo: Memo, key: string, looks: string, painti
     label: `${key}-view-${facing}`, size: SIZE, take, images: [front, back],
     prompt: `The same creature as in both pictures (front and back views), same colours and painted style, now seen exactly from the side in profile, facing to the ${facing} of the picture (${looks}), ${REST}. Same size and position in the frame as the pictures. ${PLAIN}`,
   }).then((png) => (onView?.(facing, png), png));
-  const [left, right] = await Promise.all([side('left'), side('right')]);
-  return { front, back, left, right };
+  const views: Record<ViewName, Buffer> = { front, back, left: front, right: front };
+  [views.left, views.right] = await Promise.all([side('left'), side('right')]);
+  // Muse can leave out or add a part between views (a mug drawn standing on a bottle loses the bottle in front and
+  // keeps it from the side): TRELLIS cannot make one body of that and the model comes out torn. Views that do not
+  // show the same creature as the front are painted again; still not one creature after that, there is no model.
+  for (let round = 0; round < CREATURE_ROUNDS; round++) {
+    const wrong = await checkCreature(memo, key, views, round);
+    const redo = Object.keys(wrong) as ViewName[];
+    if (!redo.length) return views;
+    console.log(`  ${key}: ${redo.map((v) => `${v} view: ${wrong[v]}`).join('; ')}; painting ${redo.length === 1 ? 'it' : 'them'} again`);
+    const t = take + 1 + round;
+    if (wrong.back) (views.back = await edit({
+      label: `${key}-view-back`, size: SIZE, take: t, images: [front],
+      prompt: `The same creature as in the picture (${looks}), with exactly the same parts and nothing more or less, same colours and painted style, in exactly the same pose, seen straight from behind: we see its back, its face is not visible. Same size and position in the frame as the picture. ${PLAIN}`,
+    }), onView?.('back', views.back));
+    await Promise.all((['left', 'right'] as const).filter((f) => wrong[f]).map(async (f) => {
+      views[f] = await edit({
+        label: `${key}-view-${f}`, size: SIZE, take: t, images: [front, views.back],
+        prompt: `The same creature as in both pictures (front and back views), with exactly the same parts as the front and nothing more or less, same colours and painted style, now seen exactly from the side in profile, facing to the ${f} of the picture (${looks}), ${REST}. Same size and position in the frame as the pictures. ${PLAIN}`,
+      });
+      onView?.(f, views[f]);
+    }));
+  }
+  const still = await checkCreature(memo, key, views, CREATURE_ROUNDS);
+  if (Object.keys(still).length) throw new Error(`its 4 sides do not show one creature (${Object.entries(still).map(([v, why]) => `${v}: ${why}`).join('; ')})`);
+  return views;
+}
+
+/** Rounds of repainting creature views that do not match the front. */
+const CREATURE_ROUNDS = 2;
+
+/** Which of the back and side views show a different creature from the front: a part left out or added (what it stands on, legs, a handle), another shape. */
+export async function checkCreature(memo: Memo, key: string, views: Record<ViewName, Buffer>, round = 0): Promise<Partial<Record<ViewName, string>>> {
+  const names: ViewName[] = ['front', 'back', 'left', 'right'];
+  const a = await askSparkJson<Record<string, { ok?: unknown; why?: unknown }>>(memo, {
+    label: `views-creature-check:${key}#${round}`, images: await Promise.all(names.map((v) => small(views[v]))),
+    prompt: 'Four pictures of one creature or living object, meant to be the same body seen from the front, from behind, from its left side and from its right side, so a 3D model can be built from them. '
+      + 'Compare pictures 2, 3 and 4 with picture 1 (the front). One is wrong when it shows a part the front does not, or lacks one the front has (something it stands on or in, a base, a bottle, a stand, legs, arms, a tail, a handle, a hat), or a clearly different body shape or size. Colours, light and the turned view itself are fine. '
+      + `Reply with JSON only: {${names.slice(1).map((v) => `"${v}": {"ok": true or false, "why": "a few words"}`).join(', ')}}`,
+  });
+  return Object.fromEntries(names.slice(1).flatMap((v) => (a[v]?.ok === false ? [[v, String(a[v]?.why ?? 'not the same creature as the front')]] : [])));
 }

package/app/src/scene/backdrop.ts

@@ -19,8 +19,10 @@ import { pasteInside } from './plates.ts';
 export const BACKDROP_GROW = 14;
 
 /**
- * Fills the masked pixels from their surroundings: a pyramid of averages of the known pixels,
- * read back from the finest level that has any. Smooth, never sharp; fine for a strip of a few px.
+ * Fills the masked pixels from their surroundings: a pyramid of averages of the known pixels (pull), then each
+ * level's empty cells read from the next coarser level, bilinearly (push), down to the hole's pixels. Smooth,
+ * never sharp. Read back nearest-cell, a big hole came out in square blocks of the coarse levels (64 px and more),
+ * which a tone correction carried into the backdrop as square patches round a lamp's light.
  * With `known`, only those pixels feed the fill.
  */
 export function smearFill(rgb: Uint8Array, W: number, H: number, hole: Mask, known?: Mask): Uint8Array {
@@ -46,18 +48,38 @@ export function smearFill(rgb: Uint8Array, W: number, H: number, hole: Mask, kno
     }
     levels.push(next);
   }
+  // Each level as colours: its own average where it has known pixels, else read from the level above it.
+  const colours = levels.map((l) => new Float32Array(l.w * l.h * 3));
+  const filled = levels.map((l) => Uint8Array.from(l.weight, (v) => (v > 0 ? 1 : 0)));
+  const sample = (k: number, fx: number, fy: number, out: Float32Array, at: number) => {
+    const l = levels[k];
+    const col = colours[k];
+    const x = Math.max(0, Math.min(l.w - 1, fx));
+    const y = Math.max(0, Math.min(l.h - 1, fy));
+    const [x0, y0] = [Math.floor(x), Math.floor(y)];
+    const [x1, y1] = [Math.min(l.w - 1, x0 + 1), Math.min(l.h - 1, y0 + 1)];
+    const [ax, ay] = [x - x0, y - y0];
+    for (let c = 0; c < 3; c++) {
+      const top = col[(y0 * l.w + x0) * 3 + c] * (1 - ax) + col[(y0 * l.w + x1) * 3 + c] * ax;
+      const bottom = col[(y1 * l.w + x0) * 3 + c] * (1 - ax) + col[(y1 * l.w + x1) * 3 + c] * ax;
+      out[at + c] = top * (1 - ay) + bottom * ay;
+    }
+  };
+  for (let k = levels.length - 1; k >= 1; k--) {
+    const l = levels[k];
+    for (let j = 0; j < l.w * l.h; j++) {
+      if (filled[k][j]) for (let c = 0; c < 3; c++) colours[k][j * 3 + c] = l.sum[j * 3 + c] / l.weight[j];
+      else if (k < levels.length - 1) sample(k + 1, ((j % l.w) + 0.5) / 2 - 0.5, (Math.floor(j / l.w) + 0.5) / 2 - 0.5, colours[k], j * 3);
+    }
+  }
   const out = rgb.slice();
+  if (levels.length === 1) return out;
+  const px = new Float32Array(3);
   for (let i = 0; i < W * H; i++) {
-    if (!hole.bits[i]) continue;
-    let [x, y] = [i % W, Math.floor(i / W)];
-    for (const l of levels) {
-      const j = y * l.w + x;
-      if (l.weight[j] > 0) {
-        for (let c = 0; c < 3; c++) out[i * 3 + c] = l.sum[j * 3 + c] / l.weight[j];
-        break;
-      }
-      [x, y] = [x >> 1, y >> 1];
-    }
+    // A known pixel in the hole (with `known`) keeps its own colour.
+    if (!hole.bits[i] || base.weight[i] > 0) continue;
+    sample(1, ((i % W) + 0.5) / 2 - 0.5, (Math.floor(i / W) + 0.5) / 2 - 0.5, px, 0);
+    for (let c = 0; c < 3; c++) out[i * 3 + c] = Math.round(px[c]);
   }
   return out;
 }

package/app/src/scene/corrections.ts

@@ -67,6 +67,12 @@ export const Corrections = z.object({
   take: z.number().int().min(0).optional(),
   /** Where the hero begins in this place (hero_start_set), instead of the front middle of the biggest floor. */
   start: XY.optional(),
+  /**
+   * How tall the hero stands here, against a thing painted in this place (hero_size_set): `times` that thing's painted
+   * height. The place's scale is set from it, over Spark's guess of a person. One world's places can come out ten
+   * times apart (a desk seen whole, people-sized, and a close-up of a mug, props-sized), and the hero with them.
+   */
+  heroSize: z.object({ like: z.string().min(1), times: z.number().positive().max(20) }).optional(),
   /** This place's own painting style over world.json's (style_set with scope place). */
   style: z.string().min(10).optional(),
 });

package/app/src/scene/critic.ts

@@ -43,7 +43,7 @@ Reply with JSON only: {"issues": [{"key": "...", "problem": "missing | wrong | f
   // The critic weighs the whole picture and lets a figure pass when the place's words name one ("a child floats
   // candle boats"); people are asked about on their own, as every one of them is a double or a stranger.
   // A drive's hero is painted at the wheel on purpose: no one is looked for there.
-  const people = place.kind === 'drive' ? [] : await paintedPeople(memo, place.key, painting);
+  const people = place.kind === 'drive' ? [] : await paintedPeople(memo, place.key, painting, castLooks(place));
   const near = (a: number[], b: number[]) => Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) < 120;
   const extra = people.filter((p) => !found.issues.some((i) => i.problem === 'unwanted' && near(i.region, p.box))).map((p) => ({
     key: 'person', problem: 'unwanted' as const, region: pad(p.box, 24),
@@ -52,6 +52,13 @@ Reply with JSON only: {"issues": [{"key": "...", "problem": "missing | wrong | f
   return { issues: [...found.issues, ...extra].slice(0, 6) };
 }
 
+/**
+ * How the place's NPCs look. A drawn world's NPC is often a thing (a steaming mug, a candle in a jar) that the place's
+ * words also name as part of the scene, so the painter paints it in and the critic, looking for people, lets it pass:
+ * the game then draws its figure beside the painted one, a double. They are looked for by their looks too.
+ */
+export const castLooks = (place: Place) => place.things.filter((t) => t.role === 'npc').map((t) => t.looks ?? t.key.replace(/-/g, ' '));
+
 const PERSON = /\b(child|children|kid|boy|girl|man|woman|men|women|person|people|figure|keeper|seller|vendor|fisherman|sailor|someone|crowd|silhouette)s?\b/i;
 
 /**
@@ -63,9 +70,12 @@ export const addsPerson = (i: { problem: string; fix: string }) => i.problem !==
 const People = z.object({ people: z.array(z.object({ what: z.string(), box: z.tuple([z.number(), z.number(), z.number(), z.number()]) })).max(6) });
 
 /** Every person or figure painted in, with a box: none belongs in a background, the game adds its people itself. */
-export async function paintedPeople(memo: Memo, key: string, painting: Buffer): Promise<Array<{ what: string; box: [number, number, number, number] }>> {
+export async function paintedPeople(memo: Memo, key: string, painting: Buffer, cast: string[] = []): Promise<Array<{ what: string; box: [number, number, number, number] }>> {
+  const others = cast.length
+    ? `\nAlso list each of these characters if it is painted in, however it is drawn (as an object, an animal or a creature, standing on or inside something else): ${cast.join('; ')}. The game draws them over the picture itself, so a painted one would be a double. Box only the character, not what it stands on.`
+    : '';
   const prompt = `This is a painted background (${FRAME.width}x${FRAME.height} px) for a 2D adventure. It must show no people at all.
-List every person or human figure painted in it: adults, children, sitting, crouching or far away, a silhouette in a window or a doorway. Not statues, scarecrows, posters or pictures of people.
+List every person or human figure painted in it: adults, children, sitting, crouching or far away, a silhouette in a window or a doorway. Not statues, scarecrows, posters or pictures of people.${others}
 For each give what it is in a few words ("a crouching child in a grey hoodie") and its box [x0, y0, x1, y1] in pixels, tight around the figure.
 Reply with JSON only: {"people": [{"what": "...", "box": [0, 0, 0, 0]}]}`;
   try {

package/app/src/scene/derive.ts

@@ -33,10 +33,15 @@ export type DeriveIn = { place: Place; layout: Layout; things: ThingIn[]; floors
    * Floor someone said is floor: brush strokes that add to a floor (the person's, the agent's, the free bridge's)
    * and floor cells the person added. It is walked on whatever thing's mask lies over it.
    */
-  said?: Mask };
+  said?: Mask;
+  /** How tall the hero stands (cast/figures.json), in metres; the scale is for a grown-up. Absent: a grown-up. */
+  heroMetres?: number;
+  /** The hero as tall as `times` this thing's painted height (corrections heroSize): sets the scale. */
+  heroSize?: { like: string; times: number } };
 export type Derived = { geometry: Geometry; grid: Grid; blobs: Blob[]; footprint: Mask; probes: Sample[]; shadows: Shadows };
 
 const { width: W, height: H } = FRAME;
+const round3 = (v: number) => Math.round(v * 1000) / 1000;
 /** The tallest the hero may be: three quarters of the picture. */
 export const NEAR_MAX_PX = Math.round(0.75 * H);
 /** How far (px) a layout light's point may lie outside the thing it belongs to: a glow drawn just off the lamp. */
@@ -362,14 +367,28 @@ export async function derive(memo: Memo, input: DeriveIn, log: (line: string) =>
     scale = { horizonY: Math.min(layout.horizon, topY - 40), pxPerY: 0.5, source: 'layout' };
     flag('scale: guessed from the layout horizon');
   }
+  // The person said how tall the hero is here, against a painted thing: the scale follows it (the horizon stays).
+  const heroMetres = input.heroMetres ?? PERSON_M;
+  const like = input.heroSize && things.find((t) => t.key === input.heroSize!.like);
+  const likeBox = like ? maskBox(like.mask) : undefined;
+  if (input.heroSize && !likeBox) flag(`hero size: no thing ${input.heroSize.like} with a mask here; the scale stays`);
+  if (input.heroSize && likeBox) {
+    const footY = likeBox[3];
+    const horizonY = scale.horizonY < footY - 20 ? scale.horizonY : Math.min(layout.horizon, footY - 40, topY - 40);
+    const personAt = (input.heroSize.times * (likeBox[3] - likeBox[1]) * PERSON_M) / heroMetres;
+    scale = { horizonY, pxPerY: round3(personAt / Math.max(1, footY - horizonY)), source: scale.source };
+    log(`scale from the hero's size: ${input.heroSize.times} x ${input.heroSize.like} (${Math.round((likeBox[3] - likeBox[1]) * input.heroSize.times)} px at y ${footY})`);
+  }
 
   // The frame gate: no standing where a good part of the hero would be outside the picture.
   const sized = scale;
+  // The gates are for the hero as tall as it is: a small one (a figurine among props) fits where a grown-up would not.
+  const heroShare = Math.min(1, heroMetres / PERSON_M);
   let framed = 0;
   grid.open.forEach((v, i) => {
     if (!v) return;
     const [x, y] = grid.centre(i);
-    const h = Math.max(8, sized.pxPerY * (y - sized.horizonY));
+    const h = Math.max(8, heroShare * sized.pxPerY * (y - sized.horizonY));
     if (x < 0.1 * h || x > W - 0.1 * h || y < 0.7 * h) {
       grid.open[i] = 0;
       shut[i] = 1;
@@ -378,7 +397,7 @@ export async function derive(memo: Memo, input: DeriveIn, log: (line: string) =>
   });
   // The near gate: in a close-up interior the front rows sit right under the camera, where the hero would be
   // taller than the picture (a bakery at 942 px). Those rows are foreground to look past, not floor to stand on.
-  const tooNear = [...grid.open.keys()].filter((i) => grid.open[i] && sized.pxPerY * (grid.centre(i)[1] - sized.horizonY) > NEAR_MAX_PX);
+  const tooNear = [...grid.open.keys()].filter((i) => grid.open[i] && heroShare * sized.pxPerY * (grid.centre(i)[1] - sized.horizonY) > NEAR_MAX_PX);
   if (tooNear.length && grid.count() - tooNear.length >= 200) {
     tooNear.forEach((i) => (grid.open[i] = 0, shut[i] = 1));
     framed += tooNear.length;

package/app/src/secrets.ts

@@ -7,6 +7,7 @@ import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { cli } from './cli.ts';
 
 /** The keys diorama knows how to keep, with the other names each one is accepted under. */
 export const SECRETS = {
@@ -138,7 +139,7 @@ export class SecretStore {
   async read(): Promise<Record<string, string>> {
     if (!fs.existsSync(this.file)) return {};
     const key = await this.vault.get();
-    if (!key) throw new Error(`credentials.bin exists but its key is missing from the ${this.vault.name}; run diorama setup to store your keys again`);
+    if (!key) throw new Error(`credentials.bin exists but its key is missing from the ${this.vault.name}; run ${cli('setup')} to store your keys again`);
     return open(key, fs.readFileSync(this.file));
   }
 

package/app/src/setup/checks.ts

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { blenderState } from '../model/blender.ts';
 import { envValue, findVault, loadSecrets, NO_VAULT, type SecretName } from '../secrets.ts';
+import { cli } from '../cli.ts';
 
 export type Check = {
   id: string;
@@ -22,7 +23,7 @@ function sh(cmd: string, args: string[], timeout = 8000): Promise<string | null>
 
 async function keyCheck(name: SecretName, label: string, required: boolean, what: string, source?: 'env' | 'store'): Promise<Check> {
   const value = envValue(name);
-  if (!value) return { id: name, label, state: required ? 'missing' : 'optional', detail: what, fix: [`diorama setup --key ${name}`] };
+  if (!value) return { id: name, label, state: required ? 'missing' : 'optional', detail: what, fix: [cli(`setup --key ${name}`)] };
   return { id: name, label, state: 'ok', detail: source === 'store' ? 'in your system keychain' : 'from the environment' };
 }
 
@@ -78,7 +79,7 @@ export async function runChecks(opts: { live?: boolean } = {}): Promise<Check[]>
   } catch {}
   checks.push(chromium && fs.existsSync(chromium)
     ? { id: 'chromium', label: 'Chromium for Explore and Playthrough', state: 'ok', detail: 'installed' }
-    : { id: 'chromium', label: 'Chromium for Explore and Playthrough', state: 'missing', detail: 'Explore and the playthrough bot drive a browser.', fix: ['diorama browsers'] });
+    : { id: 'chromium', label: 'Chromium for Explore and Playthrough', state: 'missing', detail: 'Explore and the playthrough bot drive a browser.', fix: [cli('browsers')] });
 
   checks.push(await keyCheck('ELEVENLABS_API_KEY', 'ElevenLabs key', false, 'Optional: sound effects, music and voices. Without it the world plays silent.', sources.ELEVENLABS_API_KEY));
   checks.push(await keyCheck('HF_TOKEN', 'Hugging Face token', false, 'Optional: 3D hero figures (TRELLIS, auto-rig) on ZeroGPU Spaces.', sources.HF_TOKEN));
@@ -103,8 +104,8 @@ export async function runChecks(opts: { live?: boolean } = {}): Promise<Check[]>
 
   const remote = await sh('git', ['remote', 'get-url', 'origin']);
   checks.push(remote
-    ? { id: 'publish', label: 'Publishing', state: 'ok', detail: `git remote ${remote.replace(/\/\/[^@/]+@/, '//')}; diorama publish pushes to gh-pages` }
-    : { id: 'publish', label: 'Publishing', state: 'optional', detail: 'No git remote: diorama export --zip still makes an itch.io upload.' });
+    ? { id: 'publish', label: 'Publishing', state: 'ok', detail: `git remote ${remote.replace(/\/\/[^@/]+@/, '//')}; ${cli('publish <slug>')} pushes to gh-pages` }
+    : { id: 'publish', label: 'Publishing', state: 'optional', detail: `No git remote: ${cli('export <slug> --zip')} still makes an itch.io upload.` });
 
   return checks;
 }

package/app/src/studio/agent.ts

@@ -5,11 +5,12 @@
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import { antigravity, claude, codexLive, createAgentSession, detectAgents, museLive, type CodingAgent, withoutProviderCredentials, type AgentSession, type ApprovalDecision, type ApprovalRequest, type SessionState, type SessionTurn } from 'genaicode/agents';
+import { antigravity, claude, codexLive, createAgentSession, detectAgents, museLive, type CodingAgent, withoutProviderCredentials, type AgentSession, type ApprovalDecision, type ApprovalRequest, type SessionState, type SessionTurn, type AgentBudget, type RateLimit } from 'genaicode/agents';
 import { configDir, redact, withoutSecrets } from '../secrets.ts';
 import type { Events } from './events.ts';
 import { History } from './history.ts';
 import { NPC_STORY_GUIDANCE } from '../story/npc-guidance.ts';
+import { cli } from '../cli.ts';
 
 export const AGENT_BRIEF = (slug: string) => `You are the coding agent inside Diorama Studio, working on the world "${slug}" with the person.
 Use only the diorama MCP tools: they are the same actions as the Studio's buttons, and the person watches each call live.
@@ -26,7 +27,7 @@ When a job seems slow or the person asks what it is doing, call job_inspect for
 To fix a place use the fix tools, which are kept across rebuilds: mask_fix (a better SAM phrase, the real box, or the kind of a thing), floor_cells, mask_brush, stand_set, repaint_region (costs a Muse edit), paint_words (how the place, its things and floors are described to the painter); corrections_get shows what is fixed already, corrections_clear takes fixes back. When asked to go through the person's notes, read feedback_pending, fix each one and close it with feedback_done in one sentence. Check budget before a rebuild of many places.
 When the person wants the game in another language ("make it English", "po polsku"), call world_language: it translates the title, names and the whole story in one pass and casts and records the voices again as native speakers; first without go, tell them what it redoes and what the voices cost, then call it with go true once they agree (voices false when they only want the text now). Never translate it line by line with story_text, and never say the language cannot be changed.
 When the person wants the game to look different (more realistic, watercolour, like a picture book, less cartoon), call style_set with the style in a few words (medium, palette, light; scope place or cast for only one place or the characters): first without go, tell them what it repaints and about what it costs, then call it with go true once they agree. It repaints each picture keeping where everything is, so masks and their fixes still fit; children's drawings stay the reference; history_undo takes it back. Never write world.json's style by hand.
-Before a risky change, say what you will do; history_undo can take back a job. Respect locks. Keys are never yours: if a key is missing, ask the person to run \`diorama setup\` in a terminal.
+Before a risky change, say what you will do; history_undo can take back a job. Respect locks. Keys are never yours: if a key is missing, ask the person to run \`${cli('setup')}\` in a terminal.
 Read files freely to find out why something failed, but do not edit world files or run commands that change them: make every change through the diorama MCP tools, so the person sees it live, can undo it, and it survives the next build (a hand edit is overwritten by the next build). When no single tool makes the change the person asks for, do not stop at "there is no tool": find the nearest way with the tools you have (several story_text calls, a story_redo with their wish, a run_step) and offer it with what it costs, using ask_person; mention the missing tool only as a side note, so it can be added later. Refuse only what would need a hand edit or would throw away their work. Start from world_status, place_status, place_view, job_wait, corrections_get and feedback_pending: place_view shows you a place as a picture (layer walk, masks or painting), which files and the shell cannot. Reach for the shell only when no Studio tool answers the question.
 When a build fails for another reason (a step that broke, a service that did not answer), the Studio wakes you with the error and the job's last lines: job_inspect it, give a service error (HTTP 5xx, a timeout, a busy Space) one job_retry, which picks up at the failed step, and fix anything else with that step's own tool; never retry the same error twice, tell the person instead. A character the 3D service left in 2D (cast_status: the 3D service did not answer) still plays with its 2D rig; cast_animate tries its model again once the service is back. When a build leaves places not playable, repair them one by one: place_status lists each error with its playbook (where to look, the fix tools in order, the last resort), and place_view shows you the walkable floor with the 60 px cells floor_cells takes, the gaps to bridge and the spots off the floor. An unreached patch where nothing is floor (a wall, the sky) is taken back, not bridged: corrections_clear the fix that made it, or mask_brush erase. Try the tools in that order; each fix rebuilds only that place, so read place_status again after its job ends. After three fixes that did not change the error, do not repeat one that failed: look again with place_view and take a different path (mask_brush by hand, floor_cells, thing_remove, corrections_clear); the fix tools refuse an exact repeat, and after six they keep repaints and relayouts for the person. If the new path fails too, tell the person briefly what you tried and what you would do next. Ask before the last resort, except one repaint_region per place.
 When layout failed and there is no picture, do not wait for place_view: inspect place_status errors, then call layout_fix with concrete layout guidance, or place_fix to resume. Both work before the place directory exists. Failed layout batches retain their diagnostics and retry with new feedback instead of replaying the same rejected batch. When paint fails with content_policy_violation, the image safety filter refused a word, not the picture: paint already lets Spark reword the place twice, so call paint_words with calm, plain words for the scene and the looks the brief had (leafless, not bare; a seat that rests, not hangs on chains; no children, blood or weapons), never an edit of world.json. A place that never got past a step is rebuilt from that step: place_fix (the Fix it button on its card) or job_retry does that by itself.
@@ -60,6 +61,22 @@ export function studioTool(request: ApprovalRequest): boolean {
  */
 export const shellTool = (name: string) => /(^|[/_.])(shell|bash|sh|exec|exec_command|repl|js)$/i.test(name);
 
+/** DIORAMA_AGENT_MAX_COST (dollars) and DIORAMA_AGENT_MAX_TOKENS cap each world's conversation; unset, nothing is capped. */
+export function agentBudget(env: NodeJS.ProcessEnv = process.env): AgentBudget | undefined {
+  const cost = Number(env.DIORAMA_AGENT_MAX_COST);
+  const tokens = Number(env.DIORAMA_AGENT_MAX_TOKENS);
+  const budget: AgentBudget = { ...(cost > 0 && { maxCostUsd: cost }), ...(tokens > 0 && { maxTokens: Math.floor(tokens) }) };
+  return Object.keys(budget).length ? budget : undefined;
+}
+
+/** An agent's plan limit close to running out or used up, in words for the feed; null while it is fine. */
+export function limitText(limit: RateLimit): string | null {
+  if (limit.status === 'ok') return null;
+  const used = limit.usedPercent === undefined ? '' : ` (${Math.round(limit.usedPercent)}% used)`;
+  const resets = limit.resetsAt === undefined ? '' : `, resets ${new Date(limit.resetsAt).toLocaleString()}`;
+  return `${limit.name ? `${limit.name} ` : ''}${limit.window} limit ${limit.status === 'exceeded' ? 'reached' : 'nearly used up'}${used}${resets}`;
+}
+
 /** Turns a session snapshot into what the page may see: secrets blanked. */
 const safe = (state: SessionState): SessionState => JSON.parse(redact(JSON.stringify(state))) as SessionState;
 
@@ -108,6 +125,8 @@ class Talk {
   /** Tools announced already: a running tool is announced when it starts and must not be again once it settles. */
   private tools = new Set<string>();
   private ended = new Set<number>();
+  /** Plan limits announced already, by limit and state, so a warning shows once. */
+  private limits = new Set<string>();
 
   /**
    * The Studio's tools as the Studio saw them called (arguments, outcome). Some agents report a tool call by
@@ -213,6 +232,13 @@ class Talk {
 
   /** The feed (Activity, the terminal) gets the gist: what was said, each tool, refusals, how a turn ended. */
   private announce(state: SessionState) {
+    for (const limit of state.rateLimits ?? []) {
+      const key = `${limit.name ?? ''}/${limit.window}/${limit.status}`;
+      const text = limitText(limit);
+      if (!text || this.limits.has(key)) continue;
+      this.limits.add(key);
+      this.publish('limit', { text });
+    }
     for (const turn of state.turns) {
       if (!this.seen.has(turn.id)) {
         this.seen.set(turn.id, 0);
@@ -415,6 +441,7 @@ export class AgentHub {
       agent,
       cwd,
       model: agentModel(name),
+      budget: agentBudget(),
       task: {
         env: withoutProviderCredentials(withoutSecrets(process.env)) as Record<string, string>,
         // genaicode hands the server to Muse as -c overrides, the token through an environment variable, never argv.

package/app/src/studio/mcp.ts

@@ -2,6 +2,7 @@
 // this over streamable HTTP at /mcp (Muse Code connects there) and `diorama mcp` over stdio.
 import { actions, describeActions, runAction, type ActionContext } from '../actions/registry.ts';
 import { redact } from '../secrets.ts';
+import { cli } from '../cli.ts';
 
 type Message = { jsonrpc: '2.0'; id?: string | number | null; method?: string; params?: Record<string, unknown> };
 export type Reply = { jsonrpc: '2.0'; id: string | number | null; result?: unknown; error?: { code: number; message: string } };
@@ -10,7 +11,7 @@ const PROTOCOL = '2025-06-18';
 
 export const INSTRUCTIONS = 'Diorama builds painted point-and-click worlds. Every tool here is a Diorama Studio action; the person sees each call '
   + 'in the Studio at once. Long work (world_build, run_step) starts a job: follow it with job_wait. Use ui_focus to show the person the '
-  + 'world or place you are talking about. Keys are never available to you: if setup_status says one is missing, ask the person to run diorama setup.';
+  + 'world or place you are talking about. Keys are never available to you: if setup_status says one is missing, ask the person to run ' + cli('setup') + '.';
 
 export function mcpTools() {
   return describeActions().map((a) => ({

package/app/src/studio/server.ts

@@ -24,6 +24,7 @@ import { bundle, WEB, worldData } from '../commands/play.ts';
 import { WorldFiles } from '../world/files.ts';
 import { snapshotBeforeJob } from './history.ts';
 import { handleMcp } from './mcp.ts';
+import { cli } from '../cli.ts';
 
 export const STUDIO_WEB = fileURLToPath(new URL('../../studio/', import.meta.url));
 const CHAT_CSS = createRequire(import.meta.url).resolve('genaicode/react/styles.css');
@@ -184,7 +185,7 @@ export async function startStudio(opts: { port?: number; root?: string; cwd?: st
   });
 
   // The game and pictures read the world through the Studio's session cookie; a browser that never opened the Studio has none.
-  const NO_SESSION = 'no session: open the Studio link from `diorama studio` in this browser first, or play the world on its own with `diorama play <slug>`';
+  const NO_SESSION = `no session: open the Studio link from \`${cli('studio')}\` in this browser first, or play the world on its own with \`${cli('play <slug>')}\``;
   const server = http.createServer(async (req, res) => {
     const headers = { 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'referrer-policy': 'no-referrer', 'cross-origin-resource-policy': 'same-origin' };
     const send = (status: number, type: string, body: string | Buffer, extra: Record<string, string> = {}) => {
@@ -239,7 +240,7 @@ export async function startStudio(opts: { port?: number; root?: string; cwd?: st
       }
 
       if (url.pathname.startsWith('/api/')) {
-        if (!authed) return json(401, { error: 'missing or wrong token: open the link diorama studio printed' });
+        if (!authed) return json(401, { error: `missing or wrong token: open the link ${cli('studio')} printed` });
         if (req.method === 'POST' && !(req.headers['content-type'] ?? '').startsWith('application/json')) return json(415, { error: 'JSON only' });
 
         if (url.pathname === '/api/session' && req.method === 'POST') {

package/app/studio/agent.tsx

@@ -1,6 +1,6 @@
 // The Muse Code panel: genaicode's own chat (genaicode/react), fed the session state the Studio server keeps
 // for this world. The page holds no agent and no key: it sends what the person types and answers approvals.
-import { AgentChat, type ChatNotice, type SessionState, type SessionTurn } from 'genaicode/react';
+import { AgentChat, limitChips, type ChatNotice, type SessionState, type SessionTurn } from 'genaicode/react';
 import type { ComponentChildren } from 'preact';
 import { useEffect, useRef, useState } from 'preact/hooks';
 import { call, fileUrl, token } from './api.ts';
@@ -19,7 +19,7 @@ export const SAYS: Record<string, string> = {
   corrections_get: 'Read fixes', corrections_clear: 'Take fixes back', mask_fix: 'Fix a mask', thing_remove: 'Remove a thing', thing_add: 'Add a thing', mask_brush: 'Brush a mask',
   floor_cells: 'Fix floor cells', stand_set: 'Move a stand spot', repaint_region: 'Repaint a region', water_flow: 'Set water flow', water_area: 'Fix where water moves', fog_drift: 'Set fog drift', weather_set: 'Set weather', reactions_set: 'Set reactions', reactions_status: 'Scene reactions',
   feedback_pending: 'Read open notes', feedback_list: 'Read notes', feedback_done: 'Close a note', feedback_add: 'Leave a note', feedback_reopen: 'Reopen a note',
-  history_list: 'Read history', history_undo: 'Undo a job', history_redo: 'Redo', lock_set: 'Change a lock', ui_focus: 'Show a place', ask_person: 'Ask you', budget: 'Check budget', setup_status: 'Check Setup',
+  history_list: 'Read history', history_undo: 'Undo a job', history_redo: 'Redo', lock_set: 'Change a lock', ui_focus: 'Show a place', ask_person: 'Ask you', budget: 'Check budget', setup_status: 'Check Setup', setup_cli: 'Read the terminal command', setup_browsers: 'Download Chromium',
   cast_status: 'Look at the cast', cast_redo: 'Repaint a character', voice_list: 'List voices', voice_set: 'Change a voice',
   story_status: 'Read the story', story_text: 'Reword a line', story_redo: 'Rewrite the story', place_view: 'Look at the floor', play_reload: 'Reload the game', npc_move: 'Move an NPC',
 };
@@ -309,6 +309,8 @@ export function AgentPanel({ slug, replay, speed = 1, jobs = [], notices, afterT
               </select>
             )}
             <span class="grow" />
+            {/* The agent's plan limits and the conversation's budget, once near their end or reported. */}
+            {!replay && state && limitChips(state).map((chip) => <span key={chip.key} class="gc-chip gc-limit" data-level={chip.level} title={chip.title}>{chip.text}</span>)}
             {replay
               ? <span class="live on">{replayDone ? 'replay done' : 'replay'}</span>
               : <span class={`live ${live ? 'on' : ''}`}>{running ? 'working…' : live ? 'ready' : 'reconnecting'}</span>}

package/app/studio/main.tsx

@@ -224,7 +224,9 @@ function Setup() {
   const [checks, setChecks] = useState<Check[] | null>(null);
   const [busy, setBusy] = useState('');
   const [error, setError] = useState('');
-  const run = async (name: 'setup_status' | 'setup_check') => {
+  const [setupCommand, setSetupCommand] = useState('diorama setup');
+  useEffect(() => void call<{ setup: string }>('setup_cli').then((c) => setSetupCommand(c.setup)).catch(() => {}), []);
+  const run = async (name: 'setup_status' | 'setup_check' | 'setup_browsers') => {
     setBusy(name);
     setError('');
     try {
@@ -250,7 +252,7 @@ function Setup() {
           <h1>Setup</h1>
         </div>
         <p class="lead">{!checks ? 'Checking this machine…' : blocking.length ? `${blocking.map((c) => c.label).join(' and ')} still ${blocking.length > 1 ? 'need' : 'needs'} you. Everything else is ready or optional.` : `Everything diorama needs is here.${ok < checks.length ? ' The unticked ones are optional.' : ''}`}</p>
-        <p class="note">Keys are typed only in your terminal with <code>diorama setup</code>, hidden, and kept in your system keychain. This page never sees them.</p>
+        <p class="note">Keys are typed only in your terminal with <code>{setupCommand}</code>, hidden, and kept in your system keychain. This page never sees them.</p>
         {error && <p class="error">{error}</p>}
         <div class="row">
           <button type="button" class="primary" disabled={!!busy} title="Look at this computer again: keys, tools, the agent. Free" onClick={() => run('setup_status')}>{busy === 'setup_status' ? 'Checking…' : 'Check again'}</button>
@@ -273,6 +275,7 @@ function Setup() {
                   <div class="fix">
                     <pre>{c.fix.join('\n')}</pre>
                     <Copy text={c.fix.join('\n')} />
+                    {c.id === 'chromium' && <button type="button" class="primary small" disabled={!!busy} title="Download Playwright's Chromium now (~150 MB, once), then check again. Free" onClick={() => run('setup_browsers')}>{busy === 'setup_browsers' ? 'Downloading…' : 'Download'}</button>}
                   </div>
                 )}
               </div>

package/app/web/main.ts

@@ -2935,9 +2935,15 @@ class Game {
     const img = c.getImageData(0, 0, w, h);
     const d = img.data;
     const ramp = (v: number, a: number, b: number) => Math.max(0, Math.min(1, (v - a) / (b - a)));
+    // Only the flame's own pixels: near white-hot and strongly warm. Wood or paper lit warm by it (a letter by a
+    // candle) passed a looser test, and the whole box flared over them as a bright square. Faded to nothing at
+    // the box's edge, so what still passes never ends on a straight line.
     for (let i = 0; i < d.length; i += 4) {
       const luma = 0.3 * d[i] + 0.59 * d[i + 1] + 0.11 * d[i + 2];
-      d[i + 3] = Math.round(255 * ramp(luma, 140, 215) * ramp(d[i] - d[i + 2], 40, 100));
+      const k = i / 4;
+      const [u, v] = [((k % w) + 0.5) / w * 2 - 1, (Math.floor(k / w) + 0.5) / h * 2 - 1];
+      const edge = Math.max(0, 1 - (u * u + v * v)) ** 0.5;
+      d[i + 3] = Math.round(255 * ramp(luma, 170, 235) * ramp(d[i] - d[i + 2], 70, 130) * edge);
     }
     c.putImageData(img, 0, 0);
     return { canvas, x0, y0 };

package/docs/setup.md

@@ -8,7 +8,7 @@ Without a checkout, from npm. Run it in an empty folder: worlds are written to `
 
 ```sh
 mkdir my-worlds && cd my-worlds
-npx -y @gtanczyk/diorama setup     # what this machine still needs; asks for keys, hidden
+npx -y @gtanczyk/diorama setup     # what this machine still needs; asks for keys, hidden, and offers to download Chromium
 npx -y @gtanczyk/diorama doctor    # one live call to each model
 npx -y @gtanczyk/diorama studio    # the GUI
 ```

package/docs/studio.md

@@ -34,7 +34,7 @@ The agent can use `job_inspect` to see a job's timestamped recent activity, how
 
 Every fix is kept in a file next to what it fixes and applied again by every later build, so a rebuild never loses it: `places/<place>/corrections.json` (rebuilding only that place from the step it feeds), `story-fixes.json`, `cast/fixes.json`. A place's thing list is edited the same way: Remove takes a prop off it (kept in the picture, or painted out with one Muse edit) and Add makes something painted a thing of its own (`removed` and `added` in `corrections.json`, which every step reads with world.json); exits, items and people belong to the story. A small repaint rebuilds only what it reaches (`app/src/scene/carry.ts`): each place step keeps the painting it last ran on (`places/<place>/.ran/`), compares the new one with it tile by tile, and asks again only about what the changed tiles reach (a thing's or floor's mask, a plate, the backdrop's cards, the light, the stairs); everything else is asked about the old painting, which the memo answers for nothing, and the place keeps its scale. Lighting the lanterns of a harbour takes about 100 s instead of 270 s, and a rebuild on the same painting asks nothing new. A change over a third of the painting rebuilds everything. A place whose steps have not kept their painting (built before this, or put back by an Undo) takes the painting on disk as theirs before a repaint, so that repaint carries too. **History** lists the jobs the world went through, the agent's included, each with who ran it, when and which places it changed, and puts the world back as it was before any of them (Redo takes that back right after); a locked world or place is left alone by the agent.
 
-The conversation is genaicode's chat with Muse Code (default), Claude Code or Codex, picked in its header before the first message (Setup's **Default agent**, or a pick here, is remembered in `~/.config/diorama/studio.json` for new worlds; a world keeps the agent it last talked with, and `DIORAMA_AGENT=codex` overrides both; `DIORAMA_AGY_MODEL=gemini-4-argon-high`, `DIORAMA_CODEX_MODEL`, `DIORAMA_MUSE_MODEL`, `DIORAMA_AGENT_CLAUDE_MODEL` or `DIORAMA_AGENT_MODEL` picks the agent's model); after it, "Hand over…" passes the conversation to another agent and a line marks where it changed hands. After a Studio restart the earlier turns come back on screen from `studio/sessions/`. The conversation is also kept in words in `studio/conversation.md`: a new agent session (another agent, or after the Studio restarts) is told to read it first, so nothing agreed is lost. The agent works through the same actions as the page, so its steps show live and its changes survive rebuilds; when a build leaves places unplayable it is woken to repair them, three tries a place. Every conversation is recorded in `studio/sessions/`: open one from "Recorded sessions", or `/w/<slug>?replay=<file>&speed=2`, to play it back for a film.
+The conversation is genaicode's chat with Muse Code (default), Claude Code or Codex, picked in its header before the first message (Setup's **Default agent**, or a pick here, is remembered in `~/.config/diorama/studio.json` for new worlds; a world keeps the agent it last talked with, and `DIORAMA_AGENT=codex` overrides both; `DIORAMA_AGY_MODEL=gemini-4-argon-high`, `DIORAMA_CODEX_MODEL`, `DIORAMA_MUSE_MODEL`, `DIORAMA_AGENT_CLAUDE_MODEL` or `DIORAMA_AGENT_MODEL` picks the agent's model); after it, "Hand over…" passes the conversation to another agent and a line marks where it changed hands. After a Studio restart the earlier turns come back on screen from `studio/sessions/`. The conversation is also kept in words in `studio/conversation.md`: a new agent session (another agent, or after the Studio restarts) is told to read it first, so nothing agreed is lost. The agent works through the same actions as the page, so its steps show live and its changes survive rebuilds; when a build leaves places unplayable it is woken to repair them, three tries a place. When the agent reports its plan limits (Claude Code's 5-hour and weekly limits, Codex's), the header shows how much is used and when it resets once a limit is near its end, and the terminal says so once. `DIORAMA_AGENT_MAX_COST` (dollars) and `DIORAMA_AGENT_MAX_TOKENS` cap what one world's conversation may spend: the header shows the budget, warns at 80%, and once it is used up a new message does not start. Every conversation is recorded in `studio/sessions/`: open one from "Recorded sessions", or `/w/<slug>?replay=<file>&speed=2`, to play it back for a film.
 
 **Setup** shows what this machine still needs, which agents it found, and the model calls sent across all worlds, priced once you enter the per-call prices from your billing pages. Keys are only ever typed in the terminal (`diorama setup`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtanczyk/diorama",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Turn a story prompt into playable painted point-and-click scenes with Meta Muse and SAM 3.1",
   "license": "Apache-2.0",
   "repository": {
@@ -54,7 +54,7 @@
     "@meta-sam/parser": "^0.1.0",
     "@preact/signals": "^2.11.3",
     "esbuild": "^0.25.0",
-    "genaicode": "^2.28.1",
+    "genaicode": "^2.29.0",
     "onnxruntime-web": "^1.31.1",
     "playwright": "^1.63.0",
     "preact": "^10.29.8",