@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/commands/play.ts

@@ -0,0 +1,195 @@
+// diorama play <slug>: serves the world to a browser page where you walk through its places.
+import fs from 'node:fs';
+import { animationCurrent } from '../scene/animation-source.ts';
+import { registeredFace } from '../scene/faces-data.ts';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { build } from 'esbuild';
+import { Geometry } from '../play/geometry.ts';
+import { previewGeometry } from '../play/preview.ts';
+import type { Layers } from '../play/parallax.ts';
+import { Rig } from '../play/rig.ts';
+import { Reactions } from '../play/reactions.ts';
+import { reactionInput } from './reactions.ts';
+import { reactionSource } from '../scene/reactions.ts';
+import { Weather } from '../play/weather.ts';
+import { glowsOf, type Glow } from '../play/glow.ts';
+import { readBodies } from '../scene/cast.ts';
+import type { ModelInfo } from '../../web/hero3d.ts';
+import { modelProblem } from '../model/glb.ts';
+import type { SpriteInfo } from '../../web/main.ts';
+import { soundData } from '../sound/data.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { ItemsInfo } from '../scene/icons.ts';
+import { Layout } from '../scene/layout.ts';
+import { Story } from '../story/schema.ts';
+import { players } from '../world/drawings.ts';
+import { WorldFiles } from '../world/files.ts';
+
+/** layers.json as the backdrop step writes it: the same shape the page reads, its files relative to the place. */
+type Flats = Layers;
+
+export const WEB = fileURLToPath(new URL('../../web/', import.meta.url));
+const TYPES: Record<string, string> = { '.png': 'image/png', '.jpg': 'image/jpeg', '.webp': 'image/webp', '.json': 'application/json', '.mp3': 'audio/mpeg' };
+
+/** What the page loads: the world, and per place its geometry (measured, or a preview from the layout). */
+export function worldData(files: WorldFiles) {
+  const world = files.world();
+  const places: Record<string, { geometry: Geometry | null; painting: string | null; backdrop?: string; layers?: Layers; weather?: Weather; reactions?: Reactions; glows?: Glow[]; issue?: string }> = {};
+  for (const place of world.places) {
+    const painted = ['painting.png', 'blockin.png'].find((f) => fs.existsSync(files.place(place.key, f)));
+    let geometry: Geometry | null = null;
+    let issue: string | undefined;
+    try {
+      if (fs.existsSync(files.place(place.key, 'geometry.json'))) geometry = Geometry.parse(files.readJson(files.place(place.key, 'geometry.json')));
+      else if (fs.existsSync(files.place(place.key, 'layout.json'))) geometry = previewGeometry(Layout.parse(files.readJson(files.place(place.key, 'layout.json'))), place);
+      else issue = 'no layout.json or geometry.json yet';
+    } catch (error) {
+      issue = `geometry.json: ${error instanceof Error ? error.message.slice(0, 300) : error}`;
+    }
+    // backdrop.png: the painting without its standing things; with it the page draws the place as a parallax diorama.
+    // Not for a place painted from a photo: the film dissolves the photo into that exact frame, so it stays still.
+    const fromPhoto = fs.existsSync(files.place(place.key, 'photo.png'));
+    const backdrop = painted === 'painting.png' && !fromPhoto && fs.existsSync(files.place(place.key, 'backdrop.png')) ? `places/${place.key}/backdrop.png` : undefined;
+    // layers.json: the far view as flats (sky, then farthest to nearest), from the same backdrop step.
+    const layersFile = files.place(place.key, 'layers.json');
+    const flats = backdrop && fs.existsSync(layersFile) ? (files.readJson(layersFile) as Flats) : undefined;
+    const rel = (f: string) => `places/${place.key}/${f}`;
+    const layers: Layers | undefined = flats && {
+      sky: flats.sky ? rel(flats.sky) : null,
+      flats: flats.flats.map((f) => ({ file: rel(f.file), box: f.box })),
+      ...(flats.water && { water: { tex: rel(flats.water.tex), mask: rel(flats.water.mask), box: flats.water.box, flow: flats.water.flow } }),
+      ...(flats.mist && { mist: { ...flats.mist, tex: rel(flats.mist.tex), mask: rel(flats.mist.mask) } }),
+      // Smoke, rocking boats, waterfalls, animals and clouds: each a file or a few beside the place.
+      ...(flats.smoke?.length && { smoke: flats.smoke.map((f) => ({ ...f, file: rel(f.file) })) }),
+      ...(flats.floats?.length && { floats: flats.floats.map((f) => ({ ...f, file: rel(f.file) })) }),
+      ...(flats.falls?.length && { falls: flats.falls.map((f) => ({ ...f, file: rel(f.file) })) }),
+      ...(flats.critters?.length && { critters: flats.critters.map((f) => ({ ...f, file: rel(f.file) })) }),
+      ...(flats.clouds && { clouds: { ...flats.clouds, clip: rel(flats.clouds.clip), ...(flats.clouds.keep && { keep: rel(flats.clouds.keep) }), bands: flats.clouds.bands.map((b) => ({ ...b, file: rel(b.file) })) } }),
+    };
+    // weather.json (diorama weather): what falls here and where water drips, for the page to animate.
+    const weatherFile = files.place(place.key, 'weather.json');
+    const read = painted === 'painting.png' && fs.existsSync(weatherFile) ? Weather.safeParse(files.readJson(weatherFile)) : undefined;
+    const weather = read?.success ? { ...read.data, ...(read.data.ripples && { ripples: rel(read.data.ripples) }) } : undefined;
+    // layout.lights: the painted lights, to breathe, flicker, twinkle or turn their beam (src/play/glow.ts).
+    const layoutFile = files.place(place.key, 'layout.json');
+    const lights = painted === 'painting.png' && fs.existsSync(layoutFile) ? Layout.safeParse(files.readJson(layoutFile)) : undefined;
+    // On the lights as painted when derive found them (geometry.glows); an older derive has only the planned points.
+    const paintedAt = geometry?.glows;
+    const sources = lights?.success ? (paintedAt ? lights.data.lights.flatMap((l) => { const p = paintedAt.find((g) => g.key === l.key); return p ? [{ ...l, x: p.x, y: p.y }] : []; }) : lights.data.lights) : [];
+    const glows = sources.length ? glowsOf(sources) : undefined;
+    let reactions: Reactions | undefined;
+    const reactionsFile = files.place(place.key, 'reactions.json');
+    if (fs.existsSync(reactionsFile)) {
+      try {
+        const rules = Reactions.parse(files.readJson(reactionsFile));
+        if (rules.source === reactionSource(reactionInput(files, place.key))) reactions = rules;
+        else console.warn(`${place.key}: reactions stale; rerun reactions`);
+      } catch (e) { console.warn(`${place.key}: reactions unavailable: ${e instanceof Error ? e.message : String(e)}`); }
+    }
+    places[place.key] = { geometry, painting: painted ? `places/${place.key}/${painted}` : null, ...(backdrop && { backdrop }), ...(layers && { layers }), ...(weather && { weather }), ...(reactions && { reactions }), ...(glows && { glows }), issue };
+  }
+  const castDir = files.path('cast');
+  // cast/figures.json (diorama cast): metres each one stands (a grown-up 1.62) and whether upright; one that
+  // isn't (a cat) is drawn as painted, whatever rig, model or sheets an older build left.
+  const bodies = readBodies(files, fs.existsSync);
+  const cast = Object.fromEntries((fs.existsSync(castDir) ? fs.readdirSync(castDir) : [])
+    .filter((f) => f.endsWith('.png') && !f.endsWith('-painting.png'))
+    .map((f) => {
+      const key = f.slice(0, -4);
+      // A walk that measured torn when it was made (rig.json check) is left out: the painted figure slides as one piece.
+      const rig = animationCurrent(files,key,'rig') && fs.existsSync(files.path('cast', key, 'rig.json')) ? Rig.parse(files.readJson(files.path('cast', key, 'rig.json'))) : undefined;
+      // cast/<key>/model/model.json (diorama model): a rigged 3D figure the page draws instead of the 2D rig.
+      // A flat one (a card TRELLIS made of a flat drawing, kept before the model step checked) is left out, and so
+      // are the sheets painted over its guides: the character walks with its 2D rig.
+      const modelOk = animationCurrent(files,key,'model') && fs.existsSync(files.path('cast', key, 'model', 'model.json')) && !modelProblem(files.path('cast', key, 'model'));
+      const model = modelOk ? { dir: `cast/${key}/model`, info: files.readJson(files.path('cast', key, 'model', 'model.json')) as ModelInfo } : undefined;
+      // cast/<key>/sprites/sprites.json (diorama sprites): painted walk sheets, preferred over the 3D figure.
+      const sprites = modelOk && animationCurrent(files,key,'sprites') && fs.existsSync(files.path('cast', key, 'sprites', 'sprites.json')) ? { dir: `cast/${key}/sprites`, info: files.readJson(files.path('cast', key, 'sprites', 'sprites.json')) as SpriteInfo } : undefined;
+      const face = registeredFace(files, key);
+      const body = bodies[key];
+      // Sheets rendered straight from the model's UV texture (model-*.png, no Muse paint) are a blurry stand-in
+      // with the rig's A-pose arms: a 2D walk bent from the character's own painting, when it passed its check,
+      // looks like the place it walks in and wins over them. Sheets Muse painted still win over the 2D walk.
+      const rendered = sprites && Object.values(sprites.info.facings ?? {}).every((f) => f.sheet.startsWith('model-'));
+      const ownWalk = rig?.sheet && rig.check?.ok !== false;
+      const sheets = rendered && ownWalk && process.env.DIORAMA_UV_SPRITES !== '1' ? undefined : sprites;
+      const walks = body?.upright !== false;
+      // A creature has no legs for a 2D rig, but its own 3D model (no skeleton, model.json creature) hops and squashes.
+      const creatureModel = model?.info.creature ? model : undefined;
+      // cast/<key>/cut.json (diorama cast, rig): the share of the cut-out's height the body takes when it holds something above it.
+      const cutAt = files.path('cast', key, 'cut.json');
+      const share = fs.existsSync(cutAt) ? Number((files.readJson(cutAt) as { share?: unknown }).share) : 1;
+      return [key, { image: `cast/${f}`, ...(share > 0 && share < 1 && { share }), ...(face && { face }), ...(body && { height: body.height }), ...(!walks && { upright: false }), ...(walks && rig && rig.check?.ok !== false ? { rig, parts: `cast/${key}` } : {}), ...(walks ? model && { model } : creatureModel && { model: creatureModel }), ...(walks && sheets && { sprites: sheets }) }];
+    }));
+  const story = fs.existsSync(files.path('story.json')) ? Story.parse(files.readJson(files.path('story.json'))) : null;
+  // changes/<i>.png per place: how story.changes[i] looks once it holds.
+  const changes: Record<string, string> = {};
+  // changes/<i>-shape.png: the changed thing's shape in it, which its hover outline follows while the change holds.
+  const changeShapes: Record<string, string> = {};
+  (story?.changes ?? []).forEach((c, i) => {
+    const file = `places/${c.place}/changes/${i}.png`;
+    if (fs.existsSync(files.path(file))) changes[i] = file;
+    const shape = `places/${c.place}/changes/${i}-shape.png`;
+    if (changes[i] && fs.existsSync(files.path(shape))) changeShapes[i] = shape;
+  });
+  // sound.json + sound/: what the world sounds like (diorama sound); absent, the page plays silent.
+  const sound = soundData(files);
+  // items/items.json (diorama icons): a painted icon per story item; without it the bag shows names.
+  const itemsFile = files.path('items', 'items.json');
+  const items = fs.existsSync(itemsFile)
+    ? Object.fromEntries(Object.entries(ItemsInfo.parse(files.readJson(itemsFile))).filter(([, i]) => fs.existsSync(files.path(i.icon))).map(([k, i]) => [k, { icon: i.icon }]))
+    : undefined;
+  // The heroes of more gamepads (drawings marked player), in drawing order: pad 2 plays the first.
+  const others = players(files).map((p) => p.key).filter((k) => cast[k]);
+  return { slug: files.slug, world, places, cast, story, changes, changeShapes, ...(sound && { sound }), ...(items && { items }), ...(others.length && { players: others }) };
+}
+
+export async function bundle(forShip = false): Promise<string> {
+  const out = await build({ entryPoints: [path.join(WEB, 'main.ts')], bundle: true, format: 'esm', write: false, target: 'es2022', ...(forShip ? { minify: true } : { sourcemap: 'inline' }) });
+  return out.outputFiles[0].text;
+}
+
+/** Serves the page and the world's files on localhost; resolves once listening. */
+export async function serveWorld(files: WorldFiles, port: number): Promise<http.Server> {
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const send = (status: number, type: string, body: string | Buffer) => {
+      res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store' });
+      res.end(body);
+    };
+    try {
+      if (url.pathname === '/') return send(200, 'text/html; charset=utf-8', fs.readFileSync(path.join(WEB, 'index.html')));
+      if (url.pathname === '/prototype/conductor-lipsync') return send(200, 'text/html; charset=utf-8', fs.readFileSync(path.join(WEB, '../demo/conductor-lipsync/index.html')));
+      if (url.pathname === '/main.js') return send(200, 'text/javascript; charset=utf-8', await bundle());
+      if (url.pathname === '/world-data.json') return send(200, 'application/json', JSON.stringify(worldData(files)));
+      if (url.pathname.startsWith('/files/')) {
+        const file = path.resolve(files.dir, decodeURIComponent(url.pathname.slice('/files/'.length)));
+        if (!file.startsWith(files.dir + path.sep) || !fs.existsSync(file)) return send(404, 'text/plain', 'not found');
+        return send(200, TYPES[path.extname(file)] ?? 'application/octet-stream', fs.readFileSync(file));
+      }
+      send(404, 'text/plain', 'not found');
+    } catch (error) {
+      send(500, 'text/plain', String(error instanceof Error ? error.stack : error));
+    }
+  });
+  await new Promise<void>((resolve) => server.listen(port, resolve));
+  return server;
+}
+
+defineCommand({
+  name: 'play',
+  usage: 'play <slug> serve the world at http://localhost:4173 to walk through it [--port N]',
+  async run(args) {
+    const port = Number(takeOption(args, 'port', '4173'));
+    const [slug] = args;
+    if (!slug) throw new Error('usage: diorama play <slug>');
+    const files = new WorldFiles(slug);
+    files.world();
+
+    await serveWorld(files, port);
+    console.log(`play ${slug}: http://localhost:${port}  (g: grid and occluders, Ctrl+C to stop)`);
+    await new Promise(() => {});
+  },
+});

package/app/src/commands/playthrough.ts

@@ -0,0 +1,111 @@
+// diorama playthrough <slug> [ending...]: the bot plays the shortest route to each ending in the real page,
+// fails if an ending is not reached, and records each run (playthrough/<ending>.webm) when --video is given,
+// with the page's own sound laid under it (playthrough/<ending>.mp4) when the world has sound.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { Page } from 'playwright';
+import { playRoute } from '../qa/route.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { checkStory } from '../story/check.ts';
+import type { Action } from '../story/engine.ts';
+import { WorldFiles } from '../world/files.ts';
+import { chromium } from './explore.ts';
+import { serveWorld } from './play.ts';
+
+type Step = { use: string; verb?: string; with?: string } | { act: Action } | { wait: number };
+
+/** A story action as what a player does on the page: click the thing, or pick an answer. */
+export function toStep(action: Action): Step {
+  switch (action.kind) {
+    case 'go': return { use: action.via };
+    case 'talk': return { use: action.npc };
+    case 'do': return { use: action.thing, verb: action.verb, ...(action.with ? { with: action.with } : {}) };
+    default: return { act: action };
+  }
+}
+
+/** The run's video with the page's sound under it, as mp4; the sound started `offset` s into the video. */
+function withSound(webm: string, audio: Buffer, offset: number): string {
+  const sound = webm.replace(/\.webm$/, '.sound.webm');
+  const mp4 = webm.replace(/\.webm$/, '.mp4');
+  fs.writeFileSync(sound, audio);
+  execFileSync('ffmpeg', ['-y', '-loglevel', 'error', '-i', webm, '-itsoffset', offset.toFixed(3), '-i', sound, '-map', '0:v', '-map', '1:a',
+    '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-crf', '20', '-c:a', 'aac', '-b:a', '192k', mp4]);
+  return mp4;
+}
+
+type Run = { ending: string; reached: string | null; clicks: number; seconds: number; frames: number; video?: string; error?: string };
+
+defineCommand({
+  name: 'playthrough',
+  usage: 'playthrough <slug> [ending...] play the route to each ending in the browser and check it is reached [--video] [--query "parallax=1&track=1&voices=npc"] [--lead S] [--port N]',
+  async run(args) {
+    const video = args.includes('--video');
+    const port = Number(takeOption(args, 'port', '4193'));
+    // Extra page options, e.g. parallax=1&track=1, so a recording looks like the game people play.
+    const query = takeOption(args, 'query', '');
+    // Seconds of the first place before the first click, so the intro line is heard in full.
+    const lead = Number(takeOption(args, 'lead', '2.5'));
+    const [slug, ...only] = args.filter((a) => !a.startsWith('--'));
+    if (!slug) throw new Error('usage: diorama playthrough <slug> [ending...] [--video]');
+    const files = new WorldFiles(slug);
+    const world = files.world();
+    // Routes come from the story as it is now, never from an old routes.json.
+    const report = checkStory(world, files.readJson(files.path('story.json')));
+    if (report.issues.length) throw new Error(`story.json does not check out:\n- ${report.issues.join('\n- ')}`);
+    const routes = report.routes.filter((r) => only.length === 0 || only.includes(r.ending));
+    const outDir = files.path('playthrough');
+    // Only this run's endings start over, so recording one ending keeps the others' videos.
+    for (const r of routes) for (const ext of ['.webm', '.sound.webm', '.mp4']) fs.rmSync(path.join(outDir, `${r.ending}${ext}`), { force: true });
+
+    const server = await serveWorld(files, port);
+    // Headless pages may play sound without a click, so the recorder hears the game from the first frame.
+    const browser = await (await chromium()).launch({ args: ['--autoplay-policy=no-user-gesture-required'] });
+    const runs: Run[] = [];
+    // Studio counts the endings off these lines: "1/3 ...", then ok or FAIL for each.
+    console.log(`playing ${routes.length} ending${routes.length === 1 ? '' : 's'}: ${routes.map((r) => r.ending).join(', ')}`);
+    try {
+      for (const [i, route] of routes.entries()) {
+        console.log(`${i + 1}/${routes.length} playing to ${route.ending}`);
+        const opened = Date.now();
+        const page = (await browser.newPage({
+          viewport: { width: 1920, height: 1080 },
+          ...(video ? { recordVideo: { dir: outDir, size: { width: 1920, height: 1080 } } } : {}),
+        })) as Page & { close(): Promise<void>; video(): { path(): Promise<string> } | null };
+        page.on('pageerror', (e) => console.log(`  page error: ${e.message}`));
+        await page.goto(`http://localhost:${port}/?capture=1&cursor=0${query ? `&${query}` : ''}`);
+        await page.waitForFunction('window.diorama && window.diorama.place', undefined, { timeout: 30000 });
+        const steps: Step[] = [{ wait: lead * 1000 }, ...route.actions.map(toStep), { wait: 2500 }];
+        const started = Date.now();
+        const sound = video && (await page.evaluate<boolean>('!!(window.diorama.sound && window.diorama.data.sound && (window.diorama.sound.record(), true))'));
+        const run: Run = { ending: route.ending, reached: null, clicks: route.actions.length, seconds: 0, frames: 0 };
+        try {
+          const result = await playRoute(page, steps);
+          Object.assign(run, { reached: result.ending, frames: result.frames, seconds: Math.round(result.time * 10) / 10 });
+        } catch (error) {
+          run.error = (error as Error).message.split('\n')[0];
+        }
+        const audio = sound ? Buffer.from(await page.evaluate<string>('window.diorama.sound.stopRecording()'), 'base64') : undefined;
+        await page.close();
+        const recorded = video ? await page.video()?.path() : undefined;
+        if (recorded) {
+          run.video = path.join(outDir, `${route.ending}.webm`);
+          fs.renameSync(recorded, run.video);
+          if (audio?.length) run.video = withSound(run.video, audio, (started - opened) / 1000);
+        }
+        runs.push(run);
+        const ok = run.reached === route.ending;
+        console.log(`${ok ? 'ok  ' : 'FAIL'} ${route.ending}: ${run.clicks} clicks, ${run.seconds} s game time (${((Date.now() - started) / 1000).toFixed(0)} s wall)${run.error ? ` · ${run.error}` : ''}${!ok && !run.error ? ` · reached ${run.reached ?? 'no ending'}` : ''}`);
+      }
+    } finally {
+      await browser.close();
+      server.close();
+    }
+    const reportFile = path.join(outDir, 'report.json');
+    const earlier = fs.existsSync(reportFile) ? (files.readJson(reportFile) as Run[]).filter((r) => !runs.some((n) => n.ending === r.ending)) : [];
+    files.write(reportFile, [...earlier, ...runs]);
+    const failed = runs.filter((r) => r.reached !== r.ending);
+    if (failed.length) throw new Error(`${failed.length} of ${runs.length} ending(s) not reached in the page`);
+  },
+});

package/app/src/commands/publish.ts

@@ -0,0 +1,78 @@
+// diorama publish <slug>: exports the world onto the repo's gh-pages branch and pushes it, so anyone can play it at a link.
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { defineCommand, takeOption } from '../registry.ts';
+import { exportWorld } from './export.ts';
+
+/** https://<owner>.github.io/<repo>/ for a GitHub remote URL (https or ssh), or null for any other host. */
+export function pagesUrl(remote: string): string | null {
+  const m = remote.trim().match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (!m) return null;
+  const [, owner, repo] = m;
+  return repo.toLowerCase() === `${owner.toLowerCase()}.github.io` ? `https://${repo}/` : `https://${owner}.github.io/${repo}/`;
+}
+
+/** The front page of the published site: one link per world folder that holds a world-data.json. */
+export function indexPage(worlds: { slug: string; title: string }[]): string {
+  const esc = (s: string) => s.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+  const items = worlds.map((w) => `<li><a href="./${encodeURIComponent(w.slug)}/">${esc(w.title)}</a></li>`).join('\n');
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Diorama worlds</title>
+<style>body{margin:0;padding:40px 24px;background:#0b0b0e;color:#e8e2d6;font:18px/1.5 Georgia,serif}main{max-width:640px;margin:auto}a{color:#ffd37a}li{margin:8px 0}</style>
+</head><body><main><h1>Diorama worlds</h1><p>Painted point-and-click places made with Meta Muse and SAM 3.1. Click one to play in the browser.</p>
+<ul>
+${items}
+</ul><p><a href="https://github.com/gtanczyk/diorama">Source</a></p></main></body></html>
+`;
+}
+
+defineCommand({
+  name: 'publish',
+  usage: 'publish <slug> [--remote origin] [--branch gh-pages] [--no-push]   put the world on GitHub Pages and print its link',
+  async run(args) {
+    const remote = takeOption(args, 'remote', 'origin');
+    const branch = takeOption(args, 'branch', 'gh-pages');
+    const push = !args.includes('--no-push');
+    const [slug] = args.filter((a) => a !== '--no-push');
+    if (!slug) throw new Error('usage: diorama publish <slug> [--remote origin] [--branch gh-pages] [--no-push]');
+    const git = (cwd: string, ...a: string[]) => execFileSync('git', a, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+    const top = git(process.cwd(), 'rev-parse', '--show-toplevel');
+
+    // A worktree of the pages branch under .diorama/, so the checkout you work in never switches branch.
+    const site = path.join(top, '.diorama', 'pages');
+    if (fs.existsSync(site)) git(top, 'worktree', 'remove', '--force', site);
+    git(top, 'worktree', 'prune');
+    const onRemote = git(top, 'ls-remote', '--heads', remote, branch) !== '';
+    if (onRemote) {
+      git(top, 'fetch', remote, branch);
+      git(top, 'worktree', 'add', '-B', branch, site, 'FETCH_HEAD');
+    } else if (git(top, 'branch', '--list', branch) !== '') {
+      git(top, 'worktree', 'add', site, branch);
+    } else {
+      git(top, 'worktree', 'add', '--detach', site);
+      git(site, 'checkout', '--orphan', branch);
+      git(site, 'rm', '-rfq', '--ignore-unmatch', '.');
+    }
+
+    await exportWorld(slug, path.join(site, slug));
+    fs.writeFileSync(path.join(site, '.nojekyll'), '');
+    const worlds = fs.readdirSync(site)
+      .filter((d) => fs.existsSync(path.join(site, d, 'world-data.json')))
+      .map((d) => ({ slug: d, title: JSON.parse(fs.readFileSync(path.join(site, d, 'world-data.json'), 'utf8')).world?.title ?? d }));
+    fs.writeFileSync(path.join(site, 'index.html'), indexPage(worlds));
+
+    git(site, 'add', '-A');
+    if (git(site, 'status', '--porcelain') === '') console.log(`publish ${slug}: nothing changed`);
+    else git(site, 'commit', '-qm', `publish ${slug}`);
+    if (push) git(site, 'push', remote, branch);
+
+    const base = pagesUrl(git(top, 'remote', 'get-url', remote));
+    console.log(`publish ${slug}: ${push ? 'pushed' : 'committed, not pushed'} to ${remote}/${branch}`);
+    if (base) {
+      console.log(`  play: ${base}${slug}/`);
+      console.log(`  all worlds: ${base}`);
+      if (!onRemote) console.log(`  first publish: turn on Settings > Pages > Deploy from a branch > ${branch} once; the link works a minute after.`);
+    }
+  },
+});

package/app/src/commands/reactions.ts

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { defineCommand } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+import { Geometry } from '../play/geometry.ts';
+import { Reactions } from '../play/reactions.ts';
+import { Layout } from '../scene/layout.ts';
+import { Story } from '../story/schema.ts';
+import { planReactions, reactionSource, type ReactionInput } from '../scene/reactions.ts';
+
+export function reactionInput(files: WorldFiles, key: string): ReactionInput {
+  const world = files.world(), place = world.places.find((p) => p.key === key);
+  if (!place) throw new Error(`unknown place ${key}`);
+  const read = (file: string) => fs.existsSync(file) ? files.readJson(file) : undefined;
+  const wish = read(files.place(key, 'reactions-wish.json')) as { hint?: string } | undefined;
+  const story = read(files.path('story.json'));
+  return { world, place, layout: Layout.parse(files.readJson(files.place(key, 'layout.json'))),
+    geometry: Geometry.parse(files.readJson(files.place(key, 'geometry.json'))),
+    story: story ? Story.parse(story) : null, weather: read(files.place(key, 'weather.json')), hint: wish?.hint,
+    painting: fs.readFileSync(files.place(key, 'painting.png')) };
+}
+
+defineCommand({
+  name: 'reactions',
+  usage: 'reactions <slug> [place...] choose and bind subtle step, area-entry and object reactions automatically',
+  async run([slug, ...only]) {
+    if (!slug) throw new Error('usage: reactions <slug> [place...]');
+    const files = new WorldFiles(slug), world = files.world();
+    for (const key of only) if (!world.places.some((p) => p.key === key)) throw new Error(`unknown place ${key}`);
+    await Promise.all(world.places.filter((p) => !only.length || only.includes(p.key)).map(async (p) => {
+      const input = reactionInput(files, p.key), out = files.place(p.key, 'reactions.json');
+      const was = fs.existsSync(out) ? Reactions.safeParse(files.readJson(out)) : undefined;
+      if (was?.success && was.data.source === reactionSource(input)) { console.log(`${p.key}: reactions unchanged`); return; }
+      const { plan, reactions } = await planReactions(files.memo, input);
+      files.write(files.place(p.key, 'reactions-plan.json'), plan);
+      // Replace only after successful binding: a failed model call preserves the last good plan.
+      files.write(out, reactions);
+      console.log(`${p.key}: reactions — ${reactions.areas.length} areas, ${reactions.interactions.length} interactions. ${reactions.scene}`);
+    }));
+  },
+});

package/app/src/commands/reel.ts

@@ -0,0 +1,46 @@
+// diorama reel <slug> [place]: the build-up of a place as a video, one beat per step (film/reel-<place>.mp4).
+import { execFileSync } from 'node:child_process';
+import { placeBeats, SCREEN } from '../film/reel.ts';
+import { defineCommand, takeOption } from '../registry.ts';
+import { WorldFiles } from '../world/files.ts';
+
+defineCommand({
+  name: 'reel',
+  usage: 'reel <slug> [place]  the build-up of a place as a video, a beat per step (film/reel-<place>.mp4) [--beat 7] [--fade 0.6] [--clean: no captions]',
+  async run(args) {
+    const beat = Number(takeOption(args, 'beat', '7'));
+    const fade = Number(takeOption(args, 'fade', '0.6'));
+    const clean = args.includes('--clean');
+    const [slug, only] = args.filter((a) => a !== '--clean');
+    if (!slug) throw new Error('usage: diorama reel <slug> [place]');
+    const files = new WorldFiles(slug);
+    const placeKey = only ?? files.world().start;
+    const beats = await placeBeats(files, placeKey, clean);
+    if (beats.length < 2) throw new Error(`${placeKey} has ${beats.length} step(s) to show; run diorama build first`);
+
+    const name = `reel-${placeKey}${clean ? '-clean' : ''}`;
+    const stills = beats.map((b, i) => {
+      const file = files.path('film', name, `${String(i + 1).padStart(2, '0')}-${b.key}.png`);
+      files.write(file, b.still);
+      return file;
+    });
+    // Each still holds for one beat; a transition overlaps the end of one beat with the start of the next,
+    // so beat i starts at i * beat seconds and the film's cuts land on the click track.
+    const inputs = stills.flatMap((f, i) => ['-loop', '1', '-t', String(beat + (i < stills.length - 1 ? fade : 0)), '-i', f]);
+    let chain = '';
+    let last = '[0:v]';
+    for (let i = 1; i < stills.length; i++) {
+      const out = i === stills.length - 1 ? '[out]' : `[x${i}]`;
+      chain += `${last}[${i}:v]xfade=transition=${beats[i].enter}:duration=${fade}:offset=${i * beat}${out};`;
+      last = out;
+    }
+    const mp4 = files.path('film', `${name}.mp4`);
+    execFileSync('ffmpeg', ['-y', '-loglevel', 'error', ...inputs, '-filter_complex', `${chain}[out]fps=30,format=yuv420p[v]`, '-map', '[v]',
+      '-s', `${SCREEN.width}x${SCREEN.height}`, '-c:v', 'libx264', '-crf', '20', mp4], { stdio: 'inherit' });
+    files.write(files.path('film', `${name}.json`), {
+      place: placeKey, beat, fade,
+      beats: beats.map((b, i) => ({ key: b.key, title: b.title, by: b.by, start: i * beat, still: stills[i] })),
+    });
+    console.log(`${mp4}: ${beats.length} beats (${beats.map((b) => b.key).join(' > ')}), ${Math.round(beats.length * beat * 10) / 10}s`);
+  },
+});

package/app/src/commands/setup.ts

@@ -0,0 +1,85 @@
+// diorama setup: what this machine still needs, and the one place a key is typed in (hidden, in the terminal).
+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';
+
+const MARK: Record<Check['state'], string> = { ok: '  ok      ', missing: '  MISSING ', optional: '  -       ', fail: '  FAIL    ' };
+
+export function printChecks(checks: Check[]) {
+  for (const c of checks) {
+    console.log(`${MARK[c.state]}${c.label}: ${c.detail}`);
+    for (const line of c.fix ?? []) console.log(`            $ ${line}`);
+  }
+}
+
+/** 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');
+  process.stdout.write(question);
+  return new Promise((resolve, reject) => {
+    let value = '';
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    const done = (error?: Error) => {
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdin.off('data', onData);
+      process.stdout.write('\n');
+      if (error) reject(error);
+      else resolve(value.trim());
+    };
+    const onData = (chunk: string) => {
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') return done();
+        if (ch === '\u0003') return done(new Error('cancelled'));
+        if (ch === '\u007f' || ch === '\b') value = value.slice(0, -1);
+        else if (ch >= ' ') value += ch;
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+async function storeKey(name: SecretName, remove: boolean) {
+  const vault = await findVault();
+  if (!vault) throw new Error(NO_VAULT);
+  const store = new SecretStore(vault);
+  if (remove) {
+    await store.set(name, null);
+    return console.log(`removed ${name} from ${store.file}`);
+  }
+  const value = await askHidden(`${SECRETS[name].label} (${name}), hidden, Enter to skip: `);
+  if (!value) return console.log('skipped');
+  await store.set(name, value);
+  console.log(`stored ${name}: sealed in ${store.file}, its key in the ${vault.name}`);
+}
+
+defineCommand({
+  name: 'setup',
+  usage: 'setup                   check this machine and store keys, typed hidden [--key NAME] [--remove NAME] [--live]',
+  async run(args) {
+    const live = args.includes('--live');
+    const key = takeOption(args, 'key', '');
+    const remove = takeOption(args, 'remove', '');
+    for (const name of [key, remove].filter(Boolean)) {
+      if (!SECRET_NAMES.includes(name as SecretName)) throw new Error(`unknown key ${name}; diorama keeps ${SECRET_NAMES.join(', ')}`);
+    }
+    if (key || remove) return storeKey((key || remove) as SecretName, !!remove);
+
+    let checks = await runChecks({ live });
+    printChecks(checks);
+    // In a terminal, offer to store each missing key right away.
+    const missing = checks.filter((c) => SECRET_NAMES.includes(c.id as SecretName) && c.state !== 'ok');
+    if (process.stdin.isTTY && missing.length && (await findVault())) {
+      console.log('');
+      for (const c of missing) await storeKey(c.id as SecretName, false);
+      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');
+  },
+});