@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/actions/style.ts

@@ -0,0 +1,72 @@
+// The look of a world: style_set changes it for the whole world, one place or the cast, and repaints what is made.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { readCastFixes } from '../scene/cast-fixes.ts';
+import { readCorrections } from '../scene/corrections.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { WorldFiles } from '../world/files.ts';
+import { Slug } from '../world/schema.ts';
+import { castKeys, planLine, SCOPES, stylePlan } from '../world/style-plan.ts';
+import { readStyled } from '../world/styled.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+defineAction({
+  name: 'style_get',
+  reads: true,
+  description: 'The painting style of a world: world.json\'s, each place\'s and character\'s own where one was set, and the style each was last painted in.',
+  input: z.object({ slug: Slug }),
+  async run({ slug }, ctx) {
+    const files = new WorldFiles(slug, ctx.root);
+    if (!fs.existsSync(files.path('world.json'))) throw new ActionError(404, `no world ${slug} yet`);
+    const world = files.world();
+    const fixes = readCastFixes(files);
+    return {
+      style: world.style,
+      kids: world.audience === 'kids' || fs.existsSync(files.path('drawings')),
+      places: Object.fromEntries(world.places.map((p) => [p.key, readCorrections(files.place(p.key)).style ?? null])),
+      cast: Object.fromEntries(castKeys(world, files).map((k) => [k, fixes[k]?.style ?? null])),
+      painted: readStyled(files),
+    };
+  },
+});
+
+defineAction({
+  name: 'style_set',
+  description: 'Change the painting style ("realistic oil painting, soft natural light, muted palette"): of the whole world (scope world, the default), '
+    + 'one place (scope place, key = place) or the cast (scope cast, key = one character or leave out for all). Every place is repainted from its '
+    + 'painting with the composition kept (one Muse edit), then cut out and measured again; characters are repainted from their figure, keeping '
+    + 'who they are, and their 3D models and sprite sheets made again. Children\'s drawings stay the reference. Without go it only answers what it '
+    + 'redoes and about what it costs: tell the person, then call again with go true once they agree. Runs as a job; history_undo takes it back.',
+  input: z.object({
+    slug: Slug,
+    style: z.string().min(10).describe('The new style in a few words: medium, palette, light, no artist names.'),
+    scope: z.enum(SCOPES).optional(),
+    key: Slug.optional().describe('The place (scope place) or the character (scope cast).'),
+    go: z.boolean().optional().describe('true runs it; leave out to get the estimate first.'),
+  }),
+  job: true,
+  async run({ slug, style, scope = 'world', key, go }, ctx) {
+    const files = new WorldFiles(slug, ctx.root);
+    if (!fs.existsSync(files.path('world.json'))) throw new ActionError(404, `no world ${slug} yet`);
+    const world = files.world();
+    if (scope === 'place' && !world.places.some((p) => p.key === key)) throw new ActionError(400, `scope place needs key, one of ${world.places.map((p) => p.key).join(', ')}`);
+    if (scope === 'cast' && key && !castKeys(world, files).includes(key)) throw new ActionError(404, `${slug} has no character ${key}: ${castKeys(world, files).join(', ')}`);
+    if (scope === 'world' && key) throw new ActionError(400, 'scope world takes no key');
+    const plan = stylePlan(files, world, scope, key);
+    const kids = world.audience === 'kids' || fs.existsSync(files.path('drawings'));
+    if (!go) {
+      return {
+        estimate: plan,
+        line: planLine(plan),
+        was: scope === 'place' ? readCorrections(files.place(key!)).style ?? world.style : world.style,
+        ...(kids && { note: 'made from children\'s drawings: they stay the reference, so the children still know their things' }),
+        next: 'tell the person what it redoes and costs; call again with go: true when they agree',
+      };
+    }
+    const blocked = agentBlocked(files.dir, ctx.by, scope === 'place' ? key : undefined);
+    if (blocked) throw new ActionError(423, blocked);
+    const args = ['style', slug, style, ...(scope === 'place' ? ['--place', key!] : scope === 'cast' ? ['--cast', key ?? 'all'] : [])];
+    const job = ctx.jobs.start(slug, args, `style ${scope}${key ? ` ${key}` : ''}`, ctx.by);
+    return { job, line: planLine(plan) };
+  },
+});

package/app/src/actions/video.ts

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { defineAction } from './registry.ts';
+import { VIDEO_CHUNK, VIDEO_MAX, VIDEO_STEP, VideoId, inspectVideo, readVideoPart, save, videoDir, videoState } from '../world/video.ts';
+
+defineAction({ name: 'video_upload', description: 'Upload a video brief in ordered chunks, up to 2 GB and 4 hours. Start with name and size, then send id, byte offset and base64 data. Repeated identical chunks are safe.', input: z.object({ id: VideoId.optional(), name: z.string().max(200).optional(), size: z.number().int().positive().max(VIDEO_MAX).optional(), offset: z.number().int().nonnegative().optional(), data: z.string().max(Math.ceil(VIDEO_CHUNK / 3) * 4 + 4).optional() }), async run(input, ctx) {
+  if (!input.id) {
+    if (!input.name || !/\.(mp4|mov|webm|mkv|m4v|avi)$/i.test(input.name) || !input.size) throw new Error('Choose an MP4, MOV, WebM, MKV, M4V or AVI video, up to 2 GB.');
+    const id = randomBytes(16).toString('hex'), dir = videoDir(ctx.root, id);
+    fs.mkdirSync(dir, { recursive: true }); fs.writeFileSync(path.join(dir, 'source'), '');
+    save(path.join(dir, 'upload.json'), { name: input.name, size: input.size, received: 0 }); return { id, received: 0 };
+  }
+  const dir = videoDir(ctx.root, input.id), state = videoState(dir), file = path.join(dir, 'source');
+  if (input.offset === undefined || !input.data) return { id: input.id, received: state.received };
+  const bytes = Buffer.from(input.data, 'base64');
+  if (!bytes.length || bytes.length > VIDEO_CHUNK || input.offset + bytes.length > state.size) throw new Error('Invalid video chunk size.');
+  if (input.offset < state.received) {
+    const fd = fs.openSync(file, 'r'); const old = Buffer.alloc(bytes.length);
+    try { fs.readSync(fd, old, 0, bytes.length, input.offset); } finally { fs.closeSync(fd); }
+    if (input.offset + bytes.length > state.received || !old.equals(bytes)) throw new Error('Conflicting video chunk.');
+    return { id: input.id, received: state.received };
+  }
+  if (input.offset !== state.received) throw new Error(`Resume the video at byte ${state.received}.`);
+  // Positional writes also recover safely if the process stops before saving the offset.
+  const fd = fs.openSync(file, 'r+'); try { fs.writeSync(fd, bytes, 0, bytes.length, input.offset); } finally { fs.closeSync(fd); }
+  state.received += bytes.length; save(path.join(dir, 'upload.json'), state);
+  return { id: input.id, received: state.received };
+} });
+defineAction({ name: 'video_inspect', description: 'Finish a video upload, inspect duration and audio, and report how many intervals need analysis.', input: z.object({ id: VideoId }), async run({ id }, ctx) {
+  const state = await inspectVideo(videoDir(ctx.root, id)); return { ...state, parts: Math.ceil(state.duration / VIDEO_STEP) };
+} });
+defineAction({ name: 'video_read', description: 'Read one 30-second interval of a movie, with frames and timestamped speech; intervals run in order. Results are cached for resuming.', input: z.object({ id: VideoId, index: z.number().int().nonnegative(), note: z.string().max(4000).default('') }), async run({ id, index, note }, ctx) { return readVideoPart(ctx.root, id, index, note); } });
+defineAction({ name: 'video_result', description: 'Return a completed video interpretation and useful reference frames for review before creating a world. Keeps the source and full timestamped evidence.', input: z.object({ id: VideoId }), async run({ id }, ctx) {
+  const dir = videoDir(ctx.root, id), state = videoState(dir);
+  if (!state.duration) throw new Error('Inspect the video first.');
+  const count = Math.ceil(state.duration / VIDEO_STEP);
+  const parts = Array.from({ length: count }, (_, i) => JSON.parse(fs.readFileSync(path.join(dir, `part-${i}.json`), 'utf8')));
+  const selected = parts.flatMap((p) => p.reading.frames.filter((f: { use: boolean }) => f.use).map((f: { at: number }) => f.at)) as number[];
+  // Review capacity is explicit. All intervals remain archived even when only 32 reference images fit the world.
+  const times = selected.length <= 32 ? selected : Array.from({ length: 32 }, (_, i) => selected[Math.round(i * (selected.length - 1) / 31)]);
+  return { idea: parts.at(-1).reading.idea, observations: parts.map((p, i) => ({ at: i * VIDEO_STEP, text: p.reading.observations })), totalFrames: selected.length,
+    speech: parts.flatMap((p, i) => p.speech ? [{ at: i * VIDEO_STEP, ...p.speech }] : []),
+    photos: times.map((at) => ({ name: `video-${id.slice(0, 6)}-${at}s.jpg`, data: `data:image/jpeg;base64,${fs.readFileSync(path.join(dir, `frame-${at}.jpg`)).toString('base64')}` })) };
+} });

package/app/src/actions/view.ts

@@ -0,0 +1,109 @@
+// Looking at a place the way the fix tools see it: what the hero can and cannot reach and why, or what
+// SAM cut out for each thing. The agent gets the picture as an image, so it never has to dig in files.
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { z } from 'zod';
+import { maskFromPng } from '../image/mask.ts';
+import { PALETTE, svgLabel, tintOver } from '../image/overlay.ts';
+import { maskBox } from '../image/raster.ts';
+import { Geometry } from '../play/geometry.ts';
+import { diagnose, diagnosisPicture } from '../scene/diagnose.ts';
+import { readCorrections } from '../scene/corrections.ts';
+import { Depth } from '../scene/layers.ts';
+import { gridImage } from '../scene/locate.ts';
+import { Slug } from '../world/schema.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+type Box = [number, number, number, number];
+
+const iou = (a: Box, b: Box) => {
+  const w = Math.max(0, Math.min(a[2], b[2]) - Math.max(a[0], b[0]));
+  const h = Math.max(0, Math.min(a[3], b[3]) - Math.max(a[1], b[1]));
+  const area = (r: Box) => (r[2] - r[0]) * (r[3] - r[1]);
+  return (w * h) / (area(a) + area(b) - w * h || 1);
+};
+
+/** Each thing's mask against the box Spark saw it in: a mask far from its box has cut out the wrong thing. */
+async function thingMasks(dir: string) {
+  const read = <T>(f: string): T | null => (fs.existsSync(path.join(dir, f)) ? (JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')) as T) : null);
+  const made = read<{ things: Record<string, { kind?: string; phrase?: string; source?: string; coarse?: boolean }> }>('masks.json')?.things ?? {};
+  const seen = read<{ things: Record<string, { box: Box | null }> }>('locate.json')?.things ?? {};
+  // A box someone already fixed stands for where the thing is, not Spark's first guess.
+  const fixed = readCorrections(dir).things;
+  return Promise.all(Object.entries(made).map(async ([key, t]) => {
+    const file = path.join(dir, 'masks', `${key}.png`);
+    const mask = fs.existsSync(file) ? await maskFromPng(fs.readFileSync(file)) : null;
+    const box = (mask && maskBox(mask)) as Box | undefined;
+    const spark = (fixed[key]?.box as Box | undefined) ?? seen[key]?.box ?? null;
+    const overlap = box && spark ? Math.round(iou(box, spark) * 100) / 100 : null;
+    return { key, ...t, maskBox: box ?? null, expectedBox: spark, overlap, ...(overlap !== null && overlap < 0.3 && { suspect: 'the mask is not where the thing is: SAM may have cut out its neighbour; mask_fix box (the real box) or phrase' }), mask };
+  }));
+}
+
+defineAction({
+  name: 'place_view',
+  reads: true,
+  description: 'Look at a place, as a picture you see plus the same in words; use it instead of reading files. '
+    + 'layer "walk" (default): the painting with the 60 px cell grid floor_cells takes, reached floor green, unreached red, each gap to bridge '
+    + 'as a yellow dashed line, unreachable stand spots red, the start green; in words per floor how much is reached, each unreached patch with '
+    + 'the cells of its gap and the things in it, spots off the floor with the nearest reachable point. '
+    + 'layer "masks": each thing\'s mask tinted and labelled, its mask box solid and the box it should be in dashed (the fixed box, else the one Spark saw); in words per thing its kind, '
+    + 'SAM phrase, how the mask was found and how well it overlaps that box (low overlap: SAM cut out the wrong thing, fix with mask_fix box or phrase). '
+    + 'layer "water": where the water moves (tinted magenta), with the grid water_area takes; in words which way it flows and the cells the author added or removed. '
+    + 'layer "painting": the painting alone with the grid. "blockin": the authoritative layout plan; "first": the first painted candidate, including one rejected before masks.',
+  input: z.object({ slug: Slug, place: z.string().min(1), layer: z.enum(['walk', 'masks', 'water', 'painting', 'blockin', 'first']).optional() }),
+  async run({ slug, place, layer = 'walk' }, ctx) {
+    const dir = path.join(ctx.root, slug, 'places', place);
+    const at = (f: string) => path.join(dir, f);
+    const painting = ['painting.png', 'blockin.png'].map(at).find((f) => fs.existsSync(f));
+    if (!painting) throw new ActionError(404, `${slug}/${place} has no painting yet: build it first`);
+    const shown = async (picture: Buffer, file: string, words: Record<string, unknown>) => {
+      // Kept beside the other review pictures, so the page can show what the agent looked at.
+      fs.writeFileSync(at(file), picture);
+      const jpeg = await sharp(picture).jpeg({ quality: 78 }).toBuffer();
+      return { ...words, picture: `places/${place}/${file}`, images: [{ mimeType: 'image/jpeg', data: jpeg.toString('base64') }] };
+    };
+    if (layer === 'blockin' || layer === 'first') {
+      const file = layer === 'blockin' ? 'blockin.png' : 'painting-first.png';
+      if (!fs.existsSync(at(file))) throw new ActionError(404, `${slug}/${place} has no ${file} yet`);
+      return shown(await gridImage(fs.readFileSync(at(file))), `view-${layer}.png`, { layer });
+    }
+    if (layer === 'painting') return shown(await gridImage(fs.readFileSync(painting)), 'view-painting.png', { layer });
+    if (layer === 'water') {
+      const depth = Depth.parse(fs.existsSync(at('depth.json')) ? JSON.parse(fs.readFileSync(at('depth.json'), 'utf8')) : {});
+      const water = fs.existsSync(at('layers.json')) ? (JSON.parse(fs.readFileSync(at('layers.json'), 'utf8')) as { water?: { mask: string; box: Box; flow?: [number, number] } }).water : undefined;
+      const words = { layer, flow: depth.flow, flowHint: depth.flowHint, added: depth.waterAdd, removed: depth.waterRemove };
+      const grid = await gridImage(fs.readFileSync(painting));
+      if (!water || !fs.existsSync(at(water.mask))) return shown(grid, 'view-water.png', { ...words, moving: 'none: no water moves here (SAM found none, or the backdrop step has not run); water_area add marks it' });
+      // The mask is white with the water as alpha, over the water's box.
+      const alpha = await sharp(fs.readFileSync(at(water.mask))).ensureAlpha().extractChannel(3).toBuffer();
+      const [x0, y0, x1, y1] = water.box;
+      const tint = await sharp({ create: { width: x1 - x0, height: y1 - y0, channels: 3, background: { r: 255, g: 0, b: 200 } } }).joinChannel(await sharp(alpha).linear(0.55, 0).toBuffer()).png().toBuffer();
+      const picture = await sharp(grid).composite([{ input: tint, left: x0, top: y0 }]).png().toBuffer();
+      const [ux, uy] = water.flow ?? [1, 0];
+      const way = !ux && !uy ? 'still (sways in place)' : `flowing ${Math.abs(ux) >= Math.abs(uy) ? (ux > 0 ? 'left to right' : 'right to left') : uy > 0 ? 'toward the viewer' : 'away into the picture'}`;
+      return shown(picture, 'view-water.png', { ...words, moving: `${way}, in the box ${water.box.join(',')}` });
+    }
+    if (layer === 'masks') {
+      if (!fs.existsSync(at('masks.json'))) throw new ActionError(404, `${slug}/${place} has no masks yet: build it up to masks first`);
+      const things = await thingMasks(dir);
+      const tints = things.filter((t) => t.mask).map((t, i) => ({ mask: t.mask!, rgb: PALETTE[i % PALETTE.length], alpha: 0.45 }));
+      const svg = things.flatMap((t, i) => {
+        const rgb = PALETTE[i % PALETTE.length];
+        const out: string[] = [];
+        if (t.maskBox) out.push(`<rect x="${t.maskBox[0]}" y="${t.maskBox[1]}" width="${t.maskBox[2] - t.maskBox[0]}" height="${t.maskBox[3] - t.maskBox[1]}" fill="none" stroke="rgb(${rgb.join(',')})" stroke-width="3"/>`);
+        if (t.expectedBox) out.push(`<rect x="${t.expectedBox[0]}" y="${t.expectedBox[1]}" width="${t.expectedBox[2] - t.expectedBox[0]}" height="${t.expectedBox[3] - t.expectedBox[1]}" fill="none" stroke="rgb(${rgb.join(',')})" stroke-width="2" stroke-dasharray="8 6"/>`);
+        const anchor = t.maskBox ?? t.expectedBox;
+        if (anchor) out.push(svgLabel(anchor[0] + 4, anchor[1] + 18, `${t.key}${t.suspect ? ' ?' : ''}`, rgb));
+        return out;
+      }).join('');
+      const picture = await tintOver(await gridImage(fs.readFileSync(painting)), tints, svg);
+      return shown(picture, 'view-masks.png', { layer, things: things.map(({ mask: _, ...t }) => t) });
+    }
+    if (!fs.existsSync(at('geometry.json'))) throw new ActionError(404, `${slug}/${place} has no geometry.json yet: build it up to derive first`);
+    const g = Geometry.parse(JSON.parse(fs.readFileSync(at('geometry.json'), 'utf8')));
+    const diagnosis = diagnose(g);
+    return shown(await diagnosisPicture(fs.readFileSync(painting), g, diagnosis), 'diagnose.png', { layer, diagnosis });
+  },
+});

package/app/src/actions/weather.ts

@@ -0,0 +1,38 @@
+// Weather: what falls on a place and what drips there (the weather step), as the author wants it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { WeatherWish } from '../play/weather.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { Slug } from '../world/schema.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+defineAction({
+  name: 'weather_set',
+  description: 'Set the weather of a place when the person says it should (not) rain or snow there, it falls too hard or too lightly, '
+    + 'or water should drip from something: fall auto (as Spark reads the picture and the mood), none, rain or snow; strength 0..1 '
+    + '(0.3 drizzle, 1 downpour); fog 0..1 when mist should (not) drift there (0 clear, 0.3 haze, 0.7 thick fog); a hint in their words ("water drips from the tavern sign"). Kept in places/<place>/weather-wish.json '
+    + 'across rebuilds; reruns the weather step of that place as a job.',
+  input: z.object({
+    slug: Slug,
+    place: z.string().min(1),
+    fall: z.enum(['auto', 'none', 'rain', 'snow']),
+    strength: z.number().min(0).max(1).optional(),
+    fog: z.number().min(0).max(1).optional().describe('Mist drifting over the place: 0 none, 0.3 haze, 0.7 thick fog.'),
+    hint: z.string().min(3).optional().describe('What should drip or fall, in words, for Spark to follow.'),
+  }),
+  job: true,
+  async run({ slug, place, fall, strength, fog, hint }, ctx) {
+    const dir = path.join(ctx.root, slug);
+    const blocked = agentBlocked(dir, ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    const placeDir = path.join(dir, 'places', place);
+    if (!fs.existsSync(path.join(placeDir, 'geometry.json'))) throw new ActionError(404, `${slug}/${place} has no geometry yet: build it first`);
+    const file = path.join(placeDir, 'weather-wish.json');
+    return ctx.jobs.start(slug, ['weather', slug, place], `weather ${place}: ${fall}`, ctx.by, () => {
+      const was = fs.existsSync(file) ? WeatherWish.parse(JSON.parse(fs.readFileSync(file, 'utf8'))) : WeatherWish.parse({});
+      const wish: WeatherWish = { ...was, fall, ...(strength !== undefined && { strength }), ...(fog !== undefined && { fog }), ...(hint !== undefined && { hint }) };
+      fs.writeFileSync(file, `${JSON.stringify(wish, null, 2)}\n`);
+    });
+  },
+});

package/app/src/actions/world.ts

@@ -0,0 +1,289 @@
+// Reading a world: what exists, what each place has got so far, what verify said.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { withPlay } from '../scene/playbook.ts';
+import { currentVerdict } from '../scene/status.ts';
+import type { Verdict } from '../scene/verify.ts';
+import { readCorrections } from '../scene/corrections.ts';
+import { placeTrouble } from '../studio/trouble.ts';
+import { withThingEdits, WorldFiles } from '../world/files.ts';
+import { liveVoiceFailures } from '../sound/data.ts';
+import { Slug, World } from '../world/schema.ts';
+import { storyNeeds } from '../story/check.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+const STAGES = [
+  ['layout', 'layout.json'],
+  ['blockin', 'blockin.png'],
+  ['painting', 'painting.png'],
+  ['masks', 'masks.json'],
+  ['geometry', 'geometry.json'],
+  ['backdrop', 'backdrop.png'],
+  ['verify', 'verify.json'],
+] as const;
+
+/** What a place looks like after each step: Spark's plan (named; the bare block-in in worlds laid out before plans), Muse's first paint and the final one, SAM's masks, the depth map, the walk grid. */
+const LAYERS = [
+  ['blockin', 'plan.png', 'blockin.png'],
+  ['first', 'painting-first.png'],
+  ['painting', 'painting.png'],
+  ['masks', 'masks/overlay.png'],
+  ['depth', 'depth.png'],
+  ['walk', 'walk.png'],
+] as const;
+
+function stamp(file: string): number | null {
+  try {
+    return Math.round(fs.statSync(file).mtimeMs);
+  } catch {
+    return null;
+  }
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+/** Calls the models answered (sent, not memo hits) per model, from memo/calls.jsonl. */
+export function callCounts(dir: string, byVia = false): Record<string, number> {
+  const counts: Record<string, number> = {};
+  const log = path.join(dir, 'memo', 'calls.jsonl');
+  if (!fs.existsSync(log)) return counts;
+  for (const line of fs.readFileSync(log, 'utf8').split('\n')) {
+    if (!line) continue;
+    try {
+      const call = JSON.parse(line) as { model: string; hit: boolean; via?: string };
+      // byVia: "model|via", so Studio names who answered (Claude standing in for Spark) as the live counts do.
+      const key = byVia ? `${call.model}|${typeof call.via === 'string' ? call.via : ''}` : call.model;
+      if (!call.hit) counts[key] = (counts[key] ?? 0) + 1;
+    } catch {}
+  }
+  return counts;
+}
+
+/** How long each build step usually takes here: the median over the worlds built so far, for a world that has no times of its own. */
+// A first world on a new machine: the step times of a four-place build (2026-10-27), so its first job still says about how long.
+const FIRST_BUILD: Record<string, number> = { world: 17, story: 47, layout: 30, paint: 66, masks: 66, plates: 45, icons: 21, derive: 161, backdrop: 48, weather: 21, reactions: 21, cast: 61, model: 179, sprites: 188, sound: 67, voices: 49, verify: 1 };
+
+export function typicalSeconds(root: string): Record<string, number> {
+  const seen: Record<string, number[]> = {};
+  for (const slug of fs.existsSync(root) ? fs.readdirSync(root) : []) {
+    const steps = readJson<{ steps?: Record<string, { seconds?: number }> }>(path.join(root, slug, 'build.json'))?.steps ?? {};
+    for (const [step, s] of Object.entries(steps)) if (typeof s?.seconds === 'number') (seen[step] ??= []).push(s.seconds);
+  }
+  return { ...FIRST_BUILD, ...Object.fromEntries(Object.entries(seen).map(([step, all]) => [step, all.sort((a, b) => a - b)[Math.floor(all.length / 2)]])) };
+}
+
+export function worldSummary(root: string, slug: string) {
+  const dir = path.join(root, slug);
+  const parsed = World.safeParse(readJson(path.join(dir, 'world.json')));
+  const build = readJson<{ steps?: Record<string, { at: string; seconds: number }> }>(path.join(dir, 'build.json'));
+  const places = parsed.success ? withThingEdits(parsed.data, dir).places : [];
+  const verdicts = places.map((p) => currentVerdict(dir, p.key, p));
+  const cover = places.map((p) => ['painting.png', 'blockin.png'].map((f) => `places/${p.key}/${f}`).find((f) => fs.existsSync(path.join(dir, f)))).find(Boolean);
+  return {
+    slug,
+    title: parsed.success ? parsed.data.title : slug,
+    pitch: parsed.success ? parsed.data.pitch : null,
+    issue: parsed.success ? null : fs.existsSync(path.join(dir, 'world.json')) ? 'world.json does not parse' : 'no world.json yet',
+    places: places.length,
+    playable: verdicts.filter((v, i) => v?.ok && !placeTrouble(dir, places[i].key)).length,
+    verified: verdicts.filter(Boolean).length,
+    steps: Object.keys(build?.steps ?? {}),
+    cover: cover ? { file: cover, v: stamp(path.join(dir, cover)) } : null,
+    changed: stamp(dir),
+    // Children's drawings or recordings kept with it: a workshop world, which opens on them until it is built.
+    workshop: fs.existsSync(path.join(dir, 'drawings')) || fs.existsSync(path.join(dir, 'told')),
+  };
+}
+
+defineAction({
+  name: 'world_list',
+  reads: true,
+  description: 'List the worlds in worlds/: title, places, how many are playable, which build steps ran.',
+  input: z.object({}),
+  async run(_, ctx) {
+    if (!fs.existsSync(ctx.root)) return [];
+    return fs.readdirSync(ctx.root, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && Slug.safeParse(d.name).success)
+      .map((d) => worldSummary(ctx.root, d.name))
+      .sort((a, b) => (b.changed ?? 0) - (a.changed ?? 0));
+  },
+});
+
+defineAction({
+  name: 'world_status',
+  reads: true,
+  description: 'One world in detail: per place which stages exist (layout, painting, masks, geometry, backdrop, verify), verify errors and flags, build steps, model calls sent.',
+  input: z.object({ slug: Slug }),
+  async run({ slug }, ctx) {
+    const dir = path.join(ctx.root, slug);
+    // A world being built for the first time has no folder for its first seconds, but it has its job.
+    if (!fs.existsSync(dir) && !ctx.jobs.list(slug).length) throw new ActionError(404, `no world ${slug} yet`);
+    const raw = World.safeParse(readJson(path.join(dir, 'world.json')));
+    const parsed = raw.success ? { success: true as const, data: withThingEdits(raw.data, dir) } : raw;
+    const build = readJson<{ steps?: Record<string, unknown> }>(path.join(dir, 'build.json'));
+    const animation = readJson<Record<string, { face?: string | null; audio?: string[] }>>(path.join(dir, 'face-preparation.json'));
+    const buildSteps: Record<string, unknown> = { ...build?.steps };
+    // A step whose work is on disk but not in build.json (the world and story written by the idea flow, an agent's
+    // own step, an older build) was still made: the bar shows it kept from before and opens it, never "not part of this build".
+    const typical = typicalSeconds(ctx.root);
+    const placeKeys = parsed.success ? parsed.data.places.map((p) => p.key) : [];
+    const anyPlace = (f: string) => placeKeys.some((k) => fs.existsSync(path.join(dir, 'places', k, f)));
+    const made: Record<string, () => boolean> = {
+      world: () => fs.existsSync(path.join(dir, 'world.json')), story: () => fs.existsSync(path.join(dir, 'story.json')),
+      layout: () => anyPlace('layout.json'), paint: () => anyPlace('painting.png'), masks: () => anyPlace('masks.json'),
+      icons: () => fs.existsSync(path.join(dir, 'items', 'items.json')), derive: () => anyPlace('geometry.json'), backdrop: () => anyPlace('backdrop.png'),
+      weather: () => anyPlace('weather.json'), reactions: () => anyPlace('reactions.json'),
+      sound: () => fs.existsSync(path.join(dir, 'sound', 'sounds.json')), voices: () => fs.existsSync(path.join(dir, 'voices.json')), verify: () => anyPlace('verify.json'),
+    };
+    for (const [step, has] of Object.entries(made)) if (!buildSteps[step] && has()) buildSteps[step] = { seconds: typical[step] ?? 30, kept: true };
+    if (animation) {
+      // A face whose retry failed still speaks with the face it had (face.json): not a missing face.
+      const speaks = (key: string) => /^[a-z0-9][\w-]*$/.test(key) && fs.existsSync(path.join(dir, 'cast', key, 'face.json'));
+      const warnings = Object.entries(animation).flatMap(([key, state]) => [speaks(key) ? null : state.face, ...(state.audio ?? [])].filter(Boolean).map(reason => `${key}: ${reason}`));
+      if (buildSteps.faces || warnings.length) buildSteps.faces = { ...(buildSteps.faces as object ?? {}), status: warnings.length ? 'incomplete' : 'complete', warnings };
+    }
+    const places = (parsed.success ? parsed.data.places : []).map((p) => {
+      const at = (f: string) => path.join(dir, 'places', p.key, f);
+      const stages = Object.fromEntries(STAGES.map(([name, f]) => [name, stamp(at(f))]));
+      const verdict = currentVerdict(dir, p.key, p);
+      const image = ['painting.png', 'blockin.png'].find((f) => stages[f === 'painting.png' ? 'painting' : 'blockin']);
+      return {
+        key: p.key,
+        shows: p.shows,
+        things: p.things.map((t) => ({ key: t.key, role: t.role })),
+        exits: p.exits,
+        stages,
+        image: image ? { file: `places/${p.key}/${image}`, v: stamp(at(image)) } : null,
+        // The pictures each step leaves, in build order: Studio stacks them as the place is built.
+        layers: Object.fromEntries(LAYERS.map(([name, ...fs]) => [name, fs.find((f) => stamp(at(f)))]).filter(([, f]) => f).map(([name, f]) => [name, { file: `places/${p.key}/${f}`, v: stamp(at(f!)) }])),
+        verdict: verdict && { ok: verdict.ok, errors: verdict.errors.map((e) => withPlay(e, verdict.flags)), flags: verdict.flags.map((f) => withPlay(f, verdict.flags)) },
+        /** Why the place is not playable in one line, and the step place_fix rebuilds it from (null: the agent's). */
+        trouble: placeTrouble(dir, p.key),
+      };
+    });
+    return {
+      ...worldSummary(ctx.root, slug),
+      world: parsed.success ? { start: parsed.data.start, hero: parsed.data.hero, style: parsed.data.style } : null,
+      placeDetail: places,
+      build: buildSteps,
+      typical,
+      calls: callCounts(dir),
+      callsVia: callCounts(dir, true),
+      jobs: ctx.jobs.list(slug).slice(-10),
+      audioMisses: audioMisses(ctx.root, slug, dir),
+    };
+  },
+});
+
+/** Sounds and spoken lines the last run could not make: the game plays without them, Studio offers a retry. */
+function audioMisses(root: string, slug: string, dir: string) {
+  const sounds = readJson<{ failures?: Record<string, string> }>(path.join(dir, 'sound', 'sounds.json'))?.failures ?? {};
+  // Only lines the story still says: a rewritten line's old failure is history.
+  const lines = fs.existsSync(path.join(dir, 'world.json')) ? liveVoiceFailures(new WorldFiles(slug, root)) : [];
+  return { sounds: Object.entries(sounds).map(([id, reason]) => ({ id, reason })), lines };
+}
+
+defineAction({
+  name: 'place_status',
+  reads: true,
+  description: 'One place up close: each thing\'s kind, SAM phrase and how its mask was found (coarse ones need a look), each floor, '
+    + 'the review pictures (masks/overlay.png, walk.png), the stand spots, the fixes made so far, and each error that keeps it from being playable '
+    + 'with its playbook: where to look, the fix tools to try in order, and the costly last resort.',
+  input: z.object({ slug: Slug, place: z.string().min(1) }),
+  async run({ slug, place }, ctx) {
+    const dir = path.join(ctx.root, slug, 'places', place);
+    if (!new WorldFiles(slug, ctx.root).world().places.some((p) => p.key === place)) throw new ActionError(404, `${slug} has no place ${place}`);
+    type Made = { kind: string; phrase: string; source: string; coarse: boolean; brushed?: boolean };
+    const masks = readJson<{ things: Record<string, Made>; floors: Record<string, Omit<Made, 'kind' | 'phrase'>>; flagged: string[] }>(path.join(dir, 'masks.json'));
+    const geometry = readJson<{ things: Array<{ key: string; role?: string; box: [number, number, number, number]; stand: [number, number] }>; start: [number, number] }>(path.join(dir, 'geometry.json'));
+    const picture = (f: string) => (fs.existsSync(path.join(dir, f)) ? { file: `places/${place}/${f}`, v: stamp(path.join(dir, f)) } : null);
+    // A step that broke for this place in the last build stands before verify's errors: verify did not see it.
+    const report = readJson<{ places?: Array<{ place: string; ok: boolean; issues?: Verdict['errors'] }> }>(path.join(ctx.root, slug, 'build.json'))?.places?.find((r) => r.place === place);
+    const verdict = currentVerdict(path.join(ctx.root, slug), place);
+    // Whether thing_remove takes a thing: a prop the story does not use (exits, items and people are the story's).
+    const raw = World.safeParse(readJson(path.join(ctx.root, slug, 'world.json')));
+    const roles = new Map((raw.success ? withThingEdits(raw.data, path.join(ctx.root, slug)).places.find((p) => p.key === place)?.things ?? [] : []).map((t) => [t.key, t.role]));
+    const storyText = fs.existsSync(path.join(ctx.root, slug, 'story.json')) ? fs.readFileSync(path.join(ctx.root, slug, 'story.json'), 'utf8') : '';
+    const added = readCorrections(dir).added;
+    const removable = (key: string) => {
+      const role = roles.get(key);
+      if (added[key]) return { role: 'prop', removable: true };
+      if (role !== 'prop') return { role, removable: false, why: `${role === 'npc' ? 'a person' : `an ${role ?? 'unknown thing'}`} in the story: ask the agent to change the story` };
+      if (storyText && storyNeeds(JSON.parse(storyText), place, key)) return { role, removable: false, why: 'the story uses it: ask the agent to change the story' };
+      return { role, removable: true };
+    };
+    const broke = report?.issues?.filter((i) => i.code === 'STEP_FAILED') ?? [];
+    const composition = readJson<{ ok: boolean; pending?: boolean; error?: string; attempts?: Array<{ issues: string[] }> }>(path.join(dir, 'painting-layout.json'));
+    return {
+      playable: broke.length === 0 && (verdict?.ok ?? null),
+      errors: [...broke, ...(verdict?.errors ?? [])].map((e) => withPlay(e, verdict?.flags)),
+      flags: verdict?.flags ?? [],
+      place,
+      paintingLayout: composition && { ok: composition.ok, pending: composition.pending ?? false, attempts: composition.attempts?.length ?? 0, issues: composition.attempts?.at(-1)?.issues ?? [], error: composition.error ?? null },
+      pictures: { painting: picture('painting.png') ?? picture('blockin.png'), masks: picture('masks/overlay.png'), walk: picture('walk.png') },
+      things: Object.entries(masks?.things ?? {}).map(([key, t]) => ({ key, ...t, stand: geometry?.things.find((g) => g.key === key)?.stand ?? null, ...removable(key) })),
+      floors: Object.entries(masks?.floors ?? {}).map(([key, f]) => ({ key, ...f })),
+      flagged: masks?.flagged ?? [],
+      start: geometry?.start ?? null,
+      npcs: (geometry?.things ?? []).filter((g) => g.role === 'npc').map((g) => ({ key: g.key, box: g.box, at: [Math.round((g.box[0] + g.box[2]) / 2), Math.round(g.box[3])] as [number, number] })),
+      corrections: readCorrections(dir),
+    };
+  },
+});
+
+defineAction({
+  name: 'agent_sessions',
+  reads: true,
+  description: 'The recorded conversations with the agent on a world (studio/sessions), newest first: when, which agent, the prompts, how long. Open one in the Studio with ?replay=<file>.',
+  input: z.object({ slug: Slug }),
+  async run({ slug }, ctx) {
+    const dir = path.join(ctx.root, slug, 'studio', 'sessions');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl')).map((file) => {
+      const lines = fs.readFileSync(path.join(dir, file), 'utf8').split('\n').filter(Boolean).flatMap((l) => {
+        try {
+          return [JSON.parse(l) as { at: string; type: string; text?: string; agent?: string; turn?: { id: number } }];
+        } catch {
+          return [];
+        }
+      });
+      const states = lines.filter((l) => l.type === 'state');
+      return {
+        file,
+        started: lines[0]?.at ?? null,
+        ended: lines.at(-1)?.at ?? null,
+        agents: [...new Set(states.map((l) => l.agent).filter(Boolean))],
+        prompts: lines.filter((l) => l.type === 'user').map((l) => String(l.text).slice(0, 120)),
+        turns: new Set(states.map((l) => l.turn?.id)).size,
+        replayable: states.length > 0,
+      };
+    }).sort((a, b) => String(b.started).localeCompare(String(a.started)));
+  },
+});
+
+defineAction({
+  name: 'world_delete',
+  description: 'Delete a world: the person only, from the Studio\'s menu or the command line, never the agent. It is moved to worlds/.trash/<slug>-<time>, '
+    + 'so it can be brought back by moving the folder back. Refused while a job runs in it.',
+  input: z.object({ slug: Slug }),
+  async run({ slug }, ctx) {
+    if (ctx.by === 'agent') throw new ActionError(403, 'only the person deletes a world');
+    const dir = path.join(ctx.root, slug);
+    if (!fs.existsSync(dir)) throw new ActionError(404, `no world ${slug}`);
+    const busy = ctx.jobs.busy(slug);
+    if (busy) throw new ActionError(409, `${busy.label} is running in ${slug}: stop it first`);
+    const trash = path.join(ctx.root, '.trash');
+    fs.mkdirSync(trash, { recursive: true });
+    const to = path.join(trash, `${slug}-${new Date().toISOString().replace(/[:.]/g, '-')}`);
+    fs.renameSync(dir, to);
+    ctx.events.publish('world.deleted', { world: slug, by: ctx.by });
+    return { deleted: slug, movedTo: path.relative(ctx.root, to), restore: `move ${path.relative(process.cwd(), to)} back to ${path.relative(process.cwd(), dir)}` };
+  },
+});

package/app/src/commands/action.ts

@@ -0,0 +1,39 @@
+// diorama action <name> ['<json>']: any Studio action from a terminal, with the same input the GUI and the
+// agent send. A job action runs in the foreground here and prints its output.
+import path from 'node:path';
+import '../actions/index.ts';
+import { actions, describeActions, runAction } from '../actions/registry.ts';
+import { defineCommand } from '../registry.ts';
+import { Events } from '../studio/events.ts';
+import { snapshotBeforeJob } from '../studio/history.ts';
+import { Jobs, type Job } from '../studio/jobs.ts';
+
+defineCommand({
+  name: 'action',
+  usage: 'action <name> [\'<json>\'] run a Studio action (the same ones the GUI and Muse Code use); no name lists them',
+  async run([name, json]) {
+    if (!name) {
+      for (const a of describeActions()) console.log(`  ${a.name.padEnd(14)} ${a.description}\n  ${''.padEnd(14)} input ${JSON.stringify(a.input.properties ?? {})}`);
+      return;
+    }
+    const events = new Events();
+    const root = path.resolve('worlds');
+    const ctx = { by: 'cli' as const, root, events, jobs: new Jobs(events, { echo: true, beforeStart: snapshotBeforeJob(root, events) }) };
+    let input: unknown = {};
+    try {
+      input = json ? JSON.parse(json) : {};
+    } catch {
+      throw new Error(`the input must be JSON, e.g. diorama action ${name} '{"slug":"foghorn"}'`);
+    }
+    const result = await runAction(name, input, ctx);
+    const started = result && typeof result === 'object' ? ('job' in result ? (result as { job: Job }).job : actions.get(name)?.job ? result as Job : undefined) : undefined;
+    if (started && typeof started.id === 'string') {
+      const job = await ctx.jobs.wait(started.id);
+      if (job.state !== 'done') throw new Error(`${job.label}: ${job.state}${job.error ? `, ${job.error}` : ''}`);
+      return;
+    }
+    // Pictures are for the agent; here their file is enough.
+    const { images: _, ...shown } = (result && typeof result === 'object' && !Array.isArray(result) ? result : { result }) as { images?: unknown };
+    console.log(JSON.stringify(Array.isArray(result) || !result || typeof result !== 'object' ? result : shown, null, 2));
+  },
+});