@gtanczyk/diorama 0.4.0 → 0.4.1

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/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/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/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/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

@@ -10,6 +10,7 @@ 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.

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

@@ -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',
 };

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtanczyk/diorama",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Turn a story prompt into playable painted point-and-click scenes with Meta Muse and SAM 3.1",
   "license": "Apache-2.0",
   "repository": {