@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/studio/server.ts

@@ -0,0 +1,423 @@
+// The Studio's local server. It listens on 127.0.0.1 only and trusts nobody by default: every API call
+// carries the per-run token (handed to the browser in the URL fragment, so it never reaches a log or a
+// Referer), the Host must be ours (no DNS rebinding), cross-site requests are refused (Origin and
+// Sec-Fetch-Site), writes are JSON only and no CORS header is ever sent. World files are served to <img>
+// with a SameSite=Strict cookie the page gets in exchange for the token.
+import { callVia } from '../meta/memo.ts';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { createRequire } from 'node:module';
+import '../actions/index.ts';
+import { ActionError, describeActions, runAction, type ActionContext } from '../actions/registry.ts';
+import { redact } from '../secrets.ts';
+import { Slug } from '../world/schema.ts';
+import { Events, type StudioEvent } from './events.ts';
+import { Jobs, type Job } from './jobs.ts';
+import { repairPrompt, wantsRepair } from './repair.ts';
+import { readBudget } from '../actions/budget.ts';
+import { AgentHub, isAgentName } from './agent.ts';
+import { bundle, WEB, worldData } from '../commands/play.ts';
+import { WorldFiles } from '../world/files.ts';
+import { snapshotBeforeJob } from './history.ts';
+import { handleMcp } from './mcp.ts';
+
+export const STUDIO_WEB = fileURLToPath(new URL('../../studio/', import.meta.url));
+const CHAT_CSS = createRequire(import.meta.url).resolve('genaicode/react/styles.css');
+const TYPES: Record<string, string> = { '.png': 'image/png', '.jpg': 'image/jpeg', '.webp': 'image/webp', '.json': 'application/json', '.mp3': 'audio/mpeg', '.jsonl': 'text/plain; charset=utf-8', '.webm': 'audio/webm', '.m4a': 'audio/mp4', '.mp4': 'audio/mp4', '.ogg': 'audio/ogg', '.wav': 'audio/wav', '.txt': 'text/plain; charset=utf-8', '.glb': 'model/gltf-binary' };
+const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' blob: data:; media-src 'self' blob:; connect-src 'self' blob:; font-src 'self'; frame-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'";
+/** The game page: its own inline styles, framed only by the Studio. */
+const PLAY_CSP = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:; media-src 'self' blob:; connect-src 'self'; worker-src 'self' blob:; frame-ancestors 'self'; base-uri 'none'; form-action 'none'";
+let playJs: Promise<string> | null = null;
+const COOKIE = 'diorama_studio';
+// Photos of drawings and recordings arrive as base64 JSON.
+const MAX_BODY = 16 << 20;
+
+/** token opens the page; agentToken is the agent's (MCP, `diorama mcp`), so its calls show as the agent's. */
+export type Studio = { url: string; port: number; token: string; agentToken: string; root: string; events: Events; jobs: Jobs; close(): Promise<void> };
+
+function same(a: string, b: string): boolean {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+async function bundleApp(): Promise<string> {
+  const out = await build({
+    entryPoints: [path.join(STUDIO_WEB, 'main.tsx')],
+    bundle: true,
+    format: 'esm',
+    write: false,
+    target: 'es2022',
+    jsx: 'automatic',
+    jsxImportSource: 'preact',
+    // genaicode's chat is a React component; Preact's compat layer stands in for React.
+    alias: { react: 'preact/compat', 'react-dom': 'preact/compat', 'react/jsx-runtime': 'preact/jsx-runtime' },
+    sourcemap: 'inline',
+    // Aliases resolve from the working dir; Studio may be started from anywhere, so resolve from the package.
+    absWorkingDir: path.dirname(STUDIO_WEB),
+  });
+  return out.outputFiles[0].text;
+}
+
+/** Watches a world folder while someone looks at it: file changes and new model calls become events. */
+class WorldWatch {
+  private watcher: fs.FSWatcher | null = null;
+  private readonly pending = new Map<string, NodeJS.Timeout>();
+  private callsAt = 0;
+  users = 0;
+
+  constructor(private readonly slug: string, private readonly dir: string, private readonly events: Events) {
+    const calls = path.join(dir, 'memo', 'calls.jsonl');
+    this.callsAt = fs.existsSync(calls) ? fs.statSync(calls).size : 0;
+  }
+
+  start() {
+    if (this.watcher || this.users <= 0 || !fs.existsSync(this.dir)) return;
+    this.tailCalls();
+    try {
+      this.watcher = fs.watch(this.dir, { recursive: true }, (_, name) => name && this.changed(String(name)));
+      this.watcher.on('error', () => this.stop());
+    } catch {}
+  }
+
+  stop() {
+    this.watcher?.close();
+    this.watcher = null;
+    for (const t of this.pending.values()) clearTimeout(t);
+    this.pending.clear();
+  }
+
+  private changed(name: string) {
+    const file = name.split(path.sep).join('/');
+    if (file === 'memo/calls.jsonl') return this.tailCalls();
+    if (file.startsWith('memo/') || file.startsWith('studio/') || file.endsWith('.tmp')) return;
+    clearTimeout(this.pending.get(file));
+    this.pending.set(file, setTimeout(() => {
+      this.pending.delete(file);
+      const at = path.join(this.dir, file);
+      const exists = fs.existsSync(at);
+      this.events.publish('file.changed', { world: this.slug, file, exists, v: exists ? Math.round(fs.statSync(at).mtimeMs) : null });
+    }, 150));
+  }
+
+  private tailCalls() {
+    const file = path.join(this.dir, 'memo', 'calls.jsonl');
+    if (!fs.existsSync(file)) return;
+    const size = fs.statSync(file).size;
+    if (size < this.callsAt) this.callsAt = 0;
+    if (size === this.callsAt) return;
+    const fd = fs.openSync(file, 'r');
+    const chunk = Buffer.alloc(size - this.callsAt);
+    fs.readSync(fd, chunk, 0, chunk.length, this.callsAt);
+    fs.closeSync(fd);
+    const text = chunk.toString('utf8');
+    const complete = text.lastIndexOf('\n') + 1;
+    this.callsAt += Buffer.byteLength(text.slice(0, complete));
+    for (const line of text.slice(0, complete).split('\n')) {
+      if (!line) continue;
+      try {
+        const call = JSON.parse(line) as Record<string, unknown>;
+        const { model, label, ms, hit } = call;
+        this.events.publish('call', { world: this.slug, model, label, ms, hit, via: callVia(this.dir, call as { model: string; hash?: string; via?: unknown }) });
+      } catch {}
+    }
+  }
+}
+
+export async function startStudio(opts: { port?: number; root?: string; cwd?: string; token?: string; bin?: string; muse?: string } = {}): Promise<Studio> {
+  const root = path.resolve(opts.root ?? 'worlds');
+  const token = opts.token ?? randomBytes(32).toString('base64url');
+  const agentToken = randomBytes(32).toString('base64url');
+  const cookie = randomBytes(32).toString('base64url');
+  const events = new Events();
+  const jobs = new Jobs(events, {
+    // Commands find worlds in ./worlds, so a Studio on another worlds folder runs them beside it.
+    cwd: opts.cwd ?? (path.basename(root) === 'worlds' ? path.dirname(root) : undefined),
+    bin: opts.bin,
+    beforeStart: snapshotBeforeJob(root, events),
+  });
+  const watches = new Map<string, WorldWatch>();
+  let app: Promise<string> | null = null;
+  let port = 0;
+  // Filled in once the port is known (the agent needs the MCP URL).
+  let agents: AgentHub = null as unknown as AgentHub;
+
+  const watch = (slug: string) => {
+    let w = watches.get(slug);
+    if (!w) watches.set(slug, (w = new WorldWatch(slug, path.join(root, slug), events)));
+    w.users++;
+    w.start();
+    return () => {
+      if (--w!.users <= 0) w!.stop();
+    };
+  };
+  // A job's world folder may appear only once the job runs; watch it from then on while anyone looks.
+  events.subscribe((e) => {
+    if (e.world && e.type !== 'file.changed' && e.type !== 'call') watches.get(e.world)?.start();
+  });
+  // A failed build wakes the agent to repair it: places left unplayable, or the step that broke (budget_set autoRepair turns it off).
+  events.subscribe((e) => {
+    if (e.type !== 'job.end' || !e.world) return;
+    const job = e.job as Job;
+    // A busy agent gets it after its turn: the Studio's messages wait as notes.
+    if (!agents || !wantsRepair(job, { enabled: readBudget().autoRepair })) return;
+    const places = (job.unplayable ?? []).map((u) => u.place);
+    const step = places.length ? undefined : job.step ?? (job.warnings?.faces?.length ? 'faces' : undefined);
+    // With no agent on this machine there is nobody to wake; the person is told what would help instead.
+    const using = agents.agents(e.world).find((a) => a.using);
+    if (!using?.installed) return events.publish('repair.agent', { world: e.world, job: job.id, places, step, missing: using?.label ?? 'an agent' });
+    events.publish('repair.agent', { world: e.world, job: job.id, places, step });
+    agents.say(e.world, repairPrompt(job), 'studio').catch((error) => events.publish('log', { world: e.world, stream: 'err', line: `could not wake the agent: ${error instanceof Error ? error.message : error}` }));
+  });
+
+  // Fix it on a place the build could not mend hands it to the agent, as a finished build does.
+  events.subscribe((e) => {
+    if (e.type !== 'repair.ask' || !e.world || !agents) return;
+    const using = agents.agents(e.world).find((a) => a.using);
+    if (!using?.installed) return events.publish('repair.agent', { world: e.world, places: [e.place], missing: using?.label ?? 'an agent' });
+    events.publish('repair.agent', { world: e.world, places: [e.place] });
+    agents.say(e.world, String(e.prompt), 'studio').catch((error) => events.publish('log', { world: e.world, stream: 'err', line: `could not wake the agent: ${error instanceof Error ? error.message : error}` }));
+  });
+
+  // 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 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> = {}) => {
+      res.writeHead(status, { ...headers, 'content-type': type, ...extra });
+      res.end(body);
+    };
+    const json = (status: number, body: unknown) => send(status, 'application/json', JSON.stringify(body));
+    try {
+      const host = req.headers.host ?? '';
+      if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`) return send(421, 'text/plain', 'wrong host');
+      const site = req.headers['sec-fetch-site'];
+      if (site && site !== 'same-origin' && site !== 'none') return send(403, 'text/plain', 'cross-site request refused');
+      const origin = req.headers.origin;
+      if (origin && origin !== `http://${host}`) return send(403, 'text/plain', 'cross-origin request refused');
+
+      const url = new URL(req.url ?? '/', `http://${host}`);
+      const bearer = /^Bearer (.+)$/.exec(req.headers.authorization ?? '')?.[1] ?? '';
+      const asAgent = !!bearer && same(bearer, agentToken);
+      const authed = asAgent || (!!bearer && same(bearer, token));
+      const body = async (): Promise<{ value?: unknown; error?: [number, string] }> => {
+        let size = 0;
+        const chunks: Buffer[] = [];
+        for await (const chunk of req) {
+          size += (chunk as Buffer).length;
+          if (size > MAX_BODY) return { error: [413, 'too large'] };
+          chunks.push(chunk as Buffer);
+        }
+        try {
+          return { value: chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {} };
+        } catch {
+          return { error: [400, 'body is not JSON'] };
+        }
+      };
+      const cookieOk = (req.headers.cookie ?? '').split(/;\s*/).some((c) => c.startsWith(`${COOKIE}=`) && same(c.slice(COOKIE.length + 1), cookie));
+
+      // MCP over streamable HTTP, for the agent: plain JSON answers to POSTed JSON-RPC, no server stream.
+      if (url.pathname === '/mcp') {
+        if (!asAgent) return json(401, { error: 'the agent token is required' });
+        if (req.method !== 'POST') return send(405, 'text/plain', 'POST JSON-RPC here', { allow: 'POST' });
+        if (!(req.headers['content-type'] ?? '').startsWith('application/json')) return json(415, { error: 'JSON only' });
+        const { value, error } = await body();
+        if (error) return json(error[0], { jsonrpc: '2.0', id: null, error: { code: -32700, message: error[1] } });
+        const batch = Array.isArray(value) ? value : [value];
+        const world = Slug.safeParse(url.searchParams.get('world'));
+        const ctx: ActionContext = { by: 'agent', root, jobs, events, ...(world.success && { onPersonSays: (listener: (text: string) => void) => agents.onPersonSays(world.data, listener) }) };
+        const replies = (await Promise.all(batch.map((m) => handleMcp(m as Parameters<typeof handleMcp>[0], ctx, world.success ? world.data : undefined, world.success ? (name, args) => agents.called(world.data, name, args) : undefined)))).filter(Boolean);
+        if (!replies.length) {
+          res.writeHead(202, headers);
+          return res.end();
+        }
+        return json(200, Array.isArray(value) ? replies : replies[0]);
+      }
+
+      if (url.pathname.startsWith('/api/')) {
+        if (!authed) return json(401, { error: 'missing or wrong token: open the link diorama 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') {
+          return send(200, 'application/json', '{"ok":true}', { 'set-cookie': `${COOKIE}=${cookie}; HttpOnly; SameSite=Strict; Path=/` });
+        }
+        if (url.pathname === '/api/actions' && req.method === 'GET') return json(200, describeActions());
+        // Setup: which agent new worlds start with.
+        if (url.pathname === '/api/agent-default' && !asAgent) {
+          if (req.method === 'GET') return json(200, agents.defaults());
+          if (req.method === 'POST') {
+            const { value, error } = await body();
+            if (error) return json(error[0], { error: error[1] });
+            const name = String((value as { name?: unknown } | undefined)?.name ?? '');
+            if (!isAgentName(name)) return json(400, { error: 'no such agent' });
+            agents.setDefault(name);
+            return json(200, agents.defaults());
+          }
+        }
+        // The agent conversation: the person's side only (the agent itself never posts here).
+        const talk = /^\/api\/agent\/([a-z][a-z0-9-]*)(?:\/(say|stop|approval|live|agents|use))?$/.exec(url.pathname);
+        if (talk && !asAgent) {
+          const [, slug, verb] = talk;
+          if (!verb && req.method === 'GET') return json(200, agents.state(slug));
+          if (verb === 'agents' && req.method === 'GET') return json(200, agents.agents(slug));
+          if (verb === 'live' && req.method === 'GET') {
+            // genaicode's session state, whole, on every change (at most ten a second while text streams).
+            res.writeHead(200, { ...headers, 'content-type': 'text/event-stream; charset=utf-8', connection: 'keep-alive' });
+            let timer: NodeJS.Timeout | undefined;
+            let latest: unknown = agents.state(slug);
+            const flush = () => {
+              timer = undefined;
+              res.write(`data: ${JSON.stringify(latest)}\n\n`);
+            };
+            flush();
+            const off = agents.watch(slug, (state) => {
+              latest = state;
+              timer ??= setTimeout(flush, 100);
+            });
+            const beat = setInterval(() => res.write(': beat\n\n'), 15_000);
+            req.on('close', () => {
+              off();
+              clearTimeout(timer);
+              clearInterval(beat);
+            });
+            return;
+          }
+          if (verb && req.method === 'POST') {
+            const { value, error } = await body();
+            if (error) return json(error[0], { error: error[1] });
+            const input = (value ?? {}) as { text?: unknown; id?: unknown; decision?: unknown; name?: unknown };
+            try {
+              if (verb === 'say') {
+                if (typeof input.text !== 'string' || !input.text.trim() || input.text.length > 8000) return json(400, { error: 'say something (up to 8000 characters)' });
+                await agents.say(slug, input.text.trim());
+              } else if (verb === 'stop') agents.stop(slug);
+              else if (verb === 'use') {
+                if (typeof input.name !== 'string' || !isAgentName(input.name)) return json(400, { error: 'name one of the offered agents' });
+                agents.use(slug, input.name);
+              }
+              else {
+                if (input.decision !== 'approve' && input.decision !== 'deny') return json(400, { error: 'decision is approve or deny' });
+                agents.answer(slug, String(input.id), input.decision);
+              }
+              return json(200, { ok: true });
+            } catch (e) {
+              return json(409, { error: redact(e instanceof Error ? e.message : String(e)) });
+            }
+          }
+        }
+        if (url.pathname.startsWith('/api/actions/') && req.method === 'POST') {
+          const { value: input, error } = await body();
+          if (error) return json(error[0], { error: error[1] });
+          const ctx: ActionContext = { by: asAgent ? 'agent' : 'user', root, jobs, events };
+          try {
+            return json(200, { result: await runAction(url.pathname.slice('/api/actions/'.length), input, ctx) });
+          } catch (error) {
+            const status = error instanceof ActionError ? error.status : 500;
+            return json(status, { error: redact(error instanceof Error ? error.message : String(error)) });
+          }
+        }
+        if (url.pathname === '/api/events' && req.method === 'GET') {
+          const world = url.searchParams.get('world') ?? undefined;
+          if (world && !Slug.safeParse(world).success) return json(400, { error: 'bad world' });
+          const since = Number(url.searchParams.get('since') ?? 0);
+          res.writeHead(200, { ...headers, 'content-type': 'text/event-stream; charset=utf-8', connection: 'keep-alive' });
+          const write = (e: StudioEvent) => {
+            if (!world || !e.world || e.world === world) res.write(`id: ${e.seq}\ndata: ${JSON.stringify(e)}\n\n`);
+          };
+          for (const e of events.since(since, world)) write(e);
+          res.write(': ready\n\n');
+          const off = events.subscribe(write);
+          const unwatch = world ? watch(world) : () => {};
+          const beat = setInterval(() => res.write(': beat\n\n'), 15_000);
+          req.on('close', () => {
+            off();
+            unwatch();
+            clearInterval(beat);
+          });
+          return;
+        }
+        return json(404, { error: 'no such endpoint' });
+      }
+
+      if (req.method !== 'GET' && req.method !== 'HEAD') return send(405, 'text/plain', 'method not allowed');
+
+      // The game itself, in a frame of the Workshop: the same page `diorama play` serves, at /play/<slug>/,
+      // reading the world through the session cookie like the pictures do.
+      const play = /^\/play\/([a-z][a-z0-9-]*)\/(.*)$/.exec(url.pathname);
+      if (play) {
+        if (!cookieOk) return send(401, 'text/plain', NO_SESSION);
+        const [, slug, rest] = play;
+        if (!fs.existsSync(path.join(root, slug, 'world.json'))) return send(404, 'text/plain', 'no such world yet');
+        const framed = { 'content-security-policy': PLAY_CSP, 'x-frame-options': 'SAMEORIGIN' };
+        if (rest === '') return send(200, 'text/html; charset=utf-8', fs.readFileSync(path.join(WEB, 'index.html')), framed);
+        if (rest === 'main.js') return send(200, 'text/javascript; charset=utf-8', await (playJs ??= bundle().catch((e) => ((playJs = null), Promise.reject(e)))));
+        if (rest === 'world-data.json') return json(200, worldData(new WorldFiles(slug, root)));
+        if (rest.startsWith('files/')) url.pathname = `/files/${slug}/${rest.slice('files/'.length)}`;
+        else return send(404, 'text/plain', 'not found');
+      }
+      if (url.pathname.startsWith('/files/')) {
+        if (!cookieOk) return send(401, 'text/plain', NO_SESSION);
+        const [slug, ...rest] = decodeURIComponent(url.pathname.slice('/files/'.length)).split('/');
+        if (!Slug.safeParse(slug).success) return send(404, 'text/plain', 'not found');
+        const dir = path.join(root, slug);
+        const file = path.resolve(dir, rest.join('/'));
+        // Only a world's own files, and never its memo (model answers) or anything outside the folder.
+        if (!file.startsWith(dir + path.sep) || file.startsWith(path.join(dir, 'memo') + path.sep) || !fs.existsSync(file) || !fs.statSync(file).isFile()) return send(404, 'text/plain', 'not found');
+        return send(200, TYPES[path.extname(file)] ?? 'application/octet-stream', fs.readFileSync(file));
+      }
+      // A world's exported zip, for the person to download: exports/ sits beside the worlds folder, where the jobs run.
+      const zip = /^\/exports\/([a-z][a-z0-9-]*)\.zip$/.exec(url.pathname);
+      if (zip) {
+        if (!cookieOk) return send(401, 'text/plain', NO_SESSION);
+        const file = path.join(path.dirname(root), 'exports', `${zip[1]}.zip`);
+        if (!fs.existsSync(file)) return send(404, 'text/plain', 'not exported yet');
+        return send(200, 'application/zip', fs.readFileSync(file), { 'content-disposition': `attachment; filename="${zip[1]}.zip"` });
+      }
+      if (url.pathname === '/app.js') {
+        if (!app || process.env.DIORAMA_STUDIO_DEV) app = bundleApp();
+        try {
+          return send(200, 'text/javascript; charset=utf-8', await app);
+        } catch (error) {
+          app = null;
+          throw error;
+        }
+      }
+      // The Studio's own fonts, then genaicode's chat styles, then the Studio's, which tune them to its look.
+      if (url.pathname === '/app.css') return send(200, 'text/css; charset=utf-8', Buffer.concat([fs.readFileSync(path.join(STUDIO_WEB, 'fonts', 'fonts.css')), fs.readFileSync(CHAT_CSS), Buffer.from('\n'), fs.readFileSync(path.join(STUDIO_WEB, 'style.css'))]));
+      if (url.pathname === '/favicon.svg' || url.pathname === '/favicon.ico') return send(200, 'image/svg+xml', fs.readFileSync(path.join(STUDIO_WEB, 'favicon.svg')), { 'cache-control': 'max-age=86400' });
+      const font = /^\/fonts\/([a-z-]+\.woff2)$/.exec(url.pathname);
+      if (font && fs.existsSync(path.join(STUDIO_WEB, 'fonts', font[1]))) return send(200, 'font/woff2', fs.readFileSync(path.join(STUDIO_WEB, 'fonts', font[1])), { 'cache-control': 'max-age=86400' });
+      // Every other path is a screen of the single-page app.
+      return send(200, 'text/html; charset=utf-8', fs.readFileSync(path.join(STUDIO_WEB, 'index.html')), { 'content-security-policy': CSP, 'x-frame-options': 'DENY' });
+    } catch (error) {
+      send(500, 'text/plain', redact(String(error instanceof Error ? error.message : error)));
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(opts.port ?? 0, '127.0.0.1', () => resolve());
+  });
+  port = (server.address() as { port: number }).port;
+  agents = new AgentHub(events, { root, mcpUrl: `http://127.0.0.1:${port}/mcp`, agentToken, command: opts.muse });
+  return {
+    url: `http://127.0.0.1:${port}/`,
+    port,
+    token,
+    agentToken,
+    root,
+    events,
+    jobs,
+    async close() {
+      jobs.stopAll();
+      agents.stopAll();
+      for (const w of watches.values()) w.stop();
+      server.closeAllConnections();
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}

package/app/src/studio/trouble.ts

@@ -0,0 +1,48 @@
+// What is wrong with a place, in one line, and the step to rebuild it from: a step the last build set aside the
+// place at (build.json), a step an earlier job never got it past (a missing file), or verify's first error.
+import fs from 'node:fs';
+import path from 'node:path';
+import { PLACE_STEPS, placeGap, STEPS } from '../commands/build.ts';
+import type { Verdict } from '../scene/verify.ts';
+import { currentVerdict } from '../scene/status.ts';
+import { refusedByFilter } from '../scene/words.ts';
+
+type Step = (typeof STEPS)[number];
+export type Trouble = { why: string; from: string | null; errors: string[] };
+
+const readJson = <T>(file: string): T | null => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+};
+
+/** The short reason a failed step gives, without the model API's JSON. */
+function said(step: string, error: string): string {
+  if (refusedByFilter(new Error(error))) return `${step}: the image safety filter refused the painting`;
+  if (/never got past/.test(error)) return error.split(':')[0];
+  return `${step}: ${error.replace(/\s*\{.*$/s, '').slice(0, 140)}`;
+}
+
+/** Null when the place is playable or not built far enough to tell. */
+export function placeTrouble(worldDir: string, place: string): Trouble | null {
+  const dir = path.join(worldDir, 'places', place);
+  const log = readJson<{ steps?: Record<string, unknown>; places?: Array<{ place: string; from?: string; errors?: string[] }> }>(path.join(worldDir, 'build.json'));
+  const report = log?.places?.find((r) => r.place === place);
+  // A step an earlier job never got the place past, once the world's build went on beyond it (not while it builds).
+  // Only place steps count: the cast, voices and sound run alongside and finish while a place is still being cut out.
+  const gap = fs.existsSync(path.join(dir, 'blockin.png')) ? placeGap(dir, 'verify') : null;
+  const past = gap && [...Object.keys(log?.steps ?? {}), ...(report?.from ? [report.from] : [])].some((s) => PLACE_STEPS.includes(s as Step) && STEPS.indexOf(s as Step) > STEPS.indexOf(gap.step));
+  const gapFirst = gap && past && (!report?.from || STEPS.indexOf(gap.step) < STEPS.indexOf(report.from as Step));
+  if (gapFirst) return { why: `${gap.step} never finished here (no ${gap.file})`, from: gap.step, errors: report?.errors ?? [] };
+  if (report?.from) return { why: said(report.from, firstError(report.errors)), from: report.from, errors: report.errors ?? [] };
+  const verdict = currentVerdict(worldDir, place);
+  if (verdict && !verdict.ok) {
+    const lines = verdict.errors.map((x) => `${x.code}${x.key ? ` ${x.key}` : ''}: ${x.detail}`);
+    return { why: (lines[0] ?? 'not playable').slice(0, 160), from: null, errors: lines };
+  }
+  return null;
+}
+
+const firstError = (errors?: string[]) => (errors?.[0] ?? '').replace(/^STEP_FAILED \S+: /, '');

package/app/src/world/design.ts

@@ -0,0 +1,72 @@
+// The world step: a prompt becomes world.json. Spark designs it; the gate sends problems back.
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { checkWorld, type Place, type World } from './schema.ts';
+
+const EXAMPLE = `{
+  "title": "...",
+  "pitch": "two sentences for the back of the box",
+  "style": "one painting style for every place: medium, palette, light (no artist names)",
+  "start": "<place key>",
+  "hero": { "key": "kebab-key", "looks": "the hero head to toe" },
+  "places": [{
+    "key": "kebab-key",
+    "shows": "what the painting of this place shows, front to back",
+    "mood": "time of day, weather, feeling",
+    "things": [{ "key": "kebab-key", "role": "prop | exit | item | npc", "looks": "a few words" }],
+    "exits": [{ "to": "<place key>", "via": "<key of a thing with role exit here>" }]
+  }]
+}`;
+
+function brief(idea: string, places: number, fixed?: Place, extra = ''): string {
+  const first = fixed
+    ? `\nThe first place is a real room from a photo and is fixed. It is the start; copy its key, shows, mood and things unchanged and only add exits through its exit things:\n${JSON.stringify(fixed)}\n`
+    : '';
+  return `You design worlds for a 2D point-and-click adventure. Each place is one painted background seen from a fixed camera, slightly from above, with open floor the hero walks on.
+
+The idea:
+"""
+${idea}
+"""
+
+${first}
+${extra ? `${extra}
+
+` : ''}Design ${places} places that tell this idea${fixed ? ', the room included' : ''}. Rules:
+- 3 to 7 things per place, big enough to see and click; no tiny details.
+- Exits are things you can see (door, path, ladder, boat) and every exit has one back.
+- The world has at least one item to pick up and one npc to talk to.
+- Everything is original: no characters, places or names from existing films, books, games or brands.
+- A place's shows and its props' looks go to a painter whose safety filter refuses single words: calm, plain words (leafless trees, not bare; a swing seat that rests, not hangs on chains; no blood, weapons, graves or bodies).
+
+Reply with JSON only, shaped like:
+${EXAMPLE}`;
+}
+
+/** More to ask of the world than the idea: a brief part, and what to check the answer for. */
+export type Extra = { brief: string; issues: (world: World) => string[] };
+
+/** Up to three tries: the second and third show Spark its last answer and what was wrong with it. */
+export async function designWorld(memo: Memo, idea: string, places = 4, fixed?: Place, extra?: Extra): Promise<World> {
+  let prompt = brief(idea, places, fixed, extra?.brief);
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const answer = await askSparkJson(memo, { label: `world#${attempt}`, prompt });
+    const checked = checkWorld(fixed ? keepFixed(answer, fixed) : answer);
+    const { world } = checked;
+    const issues = world && extra ? extra.issues(world) : checked.issues;
+    if (world && issues.length === 0) return world;
+    console.log(`  world try ${attempt}: ${issues.length} issue(s): ${issues.slice(0, 4).join('; ')}`);
+    prompt = `${brief(idea, places, fixed, extra?.brief)}\n\nYour last answer was:\n${JSON.stringify(answer)}\n\nFix every one of these and reply with the whole JSON again:\n- ${issues.join('\n- ')}`;
+  }
+  throw new Error('Spark gave no valid world in 3 tries');
+}
+
+/** The photo room is what the photo shows, whatever Spark wrote: only its exits come from the answer. */
+function keepFixed(answer: unknown, fixed: Place): unknown {
+  const world = answer as { start?: string; places?: { key?: string; exits?: unknown }[] };
+  if (!Array.isArray(world?.places)) return answer;
+  const at = world.places.findIndex((p) => p?.key === fixed.key);
+  const exits = at >= 0 ? world.places[at].exits : [];
+  const places = at >= 0 ? world.places.map((p, i) => (i === at ? { ...fixed, exits } : p)) : [{ ...fixed, exits }, ...world.places];
+  return { ...world, start: fixed.key, places };
+}