@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/actions/share.ts

@@ -0,0 +1,32 @@
+// Sharing a world: a zip to download (itch.io, e-mail) or the public link on GitHub Pages, as jobs.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { Slug } from '../world/schema.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+const playable = (root: string, slug: string) => {
+  if (!fs.existsSync(path.join(root, slug, 'world.json'))) throw new ActionError(404, `no world ${slug} yet`);
+};
+
+defineAction({
+  name: 'world_export',
+  description: 'Pack a playable copy of the world as a zip the person can download from the Studio (for itch.io or e-mail). Runs as a job.',
+  input: z.object({ slug: Slug }),
+  job: true,
+  async run({ slug }, ctx) {
+    playable(ctx.root, slug);
+    return ctx.jobs.start(slug, ['export', slug, '--zip'], 'export a zip', ctx.by);
+  },
+});
+
+defineAction({
+  name: 'world_publish',
+  description: 'Put the world on the public web (GitHub Pages of this repository) and get its link. Anyone can play it there: ask the person before you call this. Runs as a job.',
+  input: z.object({ slug: Slug }),
+  job: true,
+  async run({ slug }, ctx) {
+    playable(ctx.root, slug);
+    return ctx.jobs.start(slug, ['publish', slug], 'publish to GitHub Pages', ctx.by);
+  },
+});

package/app/src/actions/sound.ts

@@ -0,0 +1,73 @@
+// The world's sounds one by one (ambience beds, loops, footsteps, one-shots, music): what each is asked for, whether
+// it was made or rejected and why, and a redo for a single sound with a hint, kept in sound/fixes.json.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { jobsOf, SoundManifest } from '../sound/make.ts';
+import { readSoundFixes, SoundFixes, soundFixesFile } from '../sound/fixes.ts';
+import { SoundPlan } from '../sound/plan.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { WorldFiles } from '../world/files.ts';
+import { Slug } from '../world/schema.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+function soundFiles(slug: string, root: string) {
+  const files = new WorldFiles(slug, root);
+  if (!fs.existsSync(files.path('sound.json'))) throw new ActionError(404, `${slug} has no sound plan yet: run_step sound`);
+  const plan = SoundPlan.parse(files.readJson(files.path('sound.json')));
+  const made = fs.existsSync(files.path('sound', 'sounds.json')) ? SoundManifest.parse(files.readJson(files.path('sound', 'sounds.json'))) : { sounds: {}, failures: {} };
+  return { files, plan, made };
+}
+
+defineAction({
+  name: 'sound_status',
+  reads: true,
+  description: 'Every sound of a world (music, each place\'s ambience bed, loops of things, footsteps per surface, one-shots): the prompt it is asked for '
+    + '(with the person\'s hint), whether it was made (file, seconds, flags) or rejected and why (rejected ones stay silent in the game), and the hint kept for it. '
+    + 'Free. Use it before sound_redo.',
+  input: z.object({ slug: Slug }),
+  async run({ slug }, ctx) {
+    const { files, plan, made } = soundFiles(slug, ctx.root);
+    const fixes = readSoundFixes(files);
+    return jobsOf(plan, fixes).map((j) => {
+      const m = made.sounds[j.id];
+      const current = m && m.prompt === j.prompt && fs.existsSync(files.path(m.file));
+      return {
+        id: j.id, kind: j.kind, prompt: j.prompt,
+        state: current ? 'made' : made.failures[j.id] ? 'rejected' : m ? 'outdated' : 'not made',
+        ...(current && { file: m.file, seconds: m.seconds, flags: m.flags }),
+        ...(made.failures[j.id] && { rejected: made.failures[j.id] }),
+        fix: fixes[j.id] ?? null,
+      };
+    });
+  },
+});
+
+defineAction({
+  name: 'sound_redo',
+  description: 'Make one or more sounds again (ids from sound_status), e.g. an ambience rejected as "mostly hiss" or "nearly silent", or one the person says sounds wrong. '
+    + 'hint (English, a few words: "a clear ticking clock and soft room tone, audible") is added to its prompt and kept across rebuilds and new sound plans; '
+    + 'without a hint it simply asks ElevenLabs for new takes. Only these sounds are paid for (up to 3 takes each). Runs as a job; then play_reload.',
+  input: z.object({ slug: Slug, ids: z.array(z.string().min(1)).min(1), hint: z.string().min(3).optional() }),
+  job: true,
+  async run({ slug, ids, hint }, ctx) {
+    const { files, plan } = soundFiles(slug, ctx.root);
+    const known = new Set(jobsOf(plan).map((j) => j.id));
+    const unknown = ids.filter((id) => !known.has(id));
+    if (unknown.length) throw new ActionError(404, `${slug} has no sound ${unknown.join(', ')}: see sound_status`);
+    const blocked = agentBlocked(files.dir, ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    const prepare = () => {
+      const fixes = readSoundFixes(files);
+      for (const id of ids) {
+        const fix = (fixes[id] ??= {});
+        if (hint) fix.hint = hint;
+        // A new round of takes: the cached takes of the last round are not asked for again.
+        fix.take = (fix.take ?? 0) + 1;
+      }
+      fs.mkdirSync(path.dirname(soundFixesFile(files)), { recursive: true });
+      files.write(soundFixesFile(files), SoundFixes.parse(fixes));
+    };
+    return ctx.jobs.start(slug, ['sound', slug, '--redo', ids.join(',')], `sound ${ids.length === 1 ? ids[0] : `${ids.length} sounds`}`, ctx.by, prepare);
+  },
+});

package/app/src/actions/start.ts

@@ -0,0 +1,154 @@
+import { styleReferencePath } from '../world/style-reference.ts';
+// A new world from one idea: Spark reads it (and any photos) and picks the world's name, how many places the
+// story needs and the language it is told in, so the person writes the idea and nothing else. A spoken idea is heard here too.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { transcribe } from '../meta/voice.ts';
+import { normalisePhoto } from '../scene/photo.ts';
+import { decode } from '../sound/pcm.ts';
+import { pcm24k } from '../sound/voices.ts';
+import { PICTURE } from '../world/drawings.ts';
+import { pieces, SOUND } from '../world/told.ts';
+import { Slug } from '../world/schema.ts';
+import { MAX_WORLD_PHOTOS } from '../world/photo-limits.ts';
+import { CreativeChoices, refinedIdea } from '../world/idea-review.ts';
+import { VideoId, videoDir, videoState, VIDEO_STEP } from '../world/video.ts';
+import { ActionError, defineAction } from './registry.ts';
+import { SketchApproval, publishSketch } from '../world/sketch.ts';
+
+/** Calls made before a world has a folder are remembered here (a dot folder, so it is never listed as a world). */
+const startMemo = (root: string) => new Memo(path.join(root, '.start', 'memo'));
+
+const Shape = z.object({
+  title: z.string().min(1).max(80),
+  slug: z.string().min(2).max(40),
+  places: z.number().int().min(2).max(5),
+  language: z.string().min(2).max(30),
+  pictures: z.array(z.enum(['place', 'hero', 'drawing', 'none'])).optional(),
+});
+type Shape = z.infer<typeof Shape>;
+
+/** Read the idea and account for every photo before saving material or starting a build. */
+export async function shapeIdea(memo: Memo, idea: string, photos: Buffer[]): Promise<Shape> {
+  const prompt = `Someone wants a short 2D point-and-click adventure game made from this idea:
+"""${idea}"""
+${photos.length ? `\nThey added ${photos.length} photo${photos.length > 1 ? 's' : ''} (in order). For each say what it is for: "place" when it is a photo of a real room or spot that should become the first place of the game, "hero" when it is a photo of a real person who should be the hero, "drawing" when it is a drawing (a child's or anyone's, on paper or a screen) of a character, a thing or a place for the game, "none" otherwise. At most one "place" and one "hero"; any number of drawings.\n` : ''}
+Decide:
+- title: a short, evocative title for the game, in the language the idea is written in.
+- slug: a short name for its folder: 1 to 3 English words in lowercase-kebab, like "last-foghorn" or "lantern-market".
+- places: how many places the story needs, 2 to 5. Make only what the story needs: one scene or one room with a small task is 2; a usual small story with a goal is 3; a journey or a story that names more places is 4 or 5. If the idea names a number of places, use it.
+- language: the language the idea is written in, in English ("English", "Polish").
+
+Reply with JSON only: {"title": "...", "slug": "...", "places": 3, "language": "English"${photos.length ? `, "pictures": ${JSON.stringify(photos.map(() => 'drawing'))}` : ''}}
+${photos.length ? `The pictures array must contain exactly ${photos.length} classifications, one for each photo in input order. The example uses drawing for every entry; classify each actual photo. Never omit an entry.` : ''}`;
+  const schema = Shape.superRefine((shape, ctx) => {
+    if ((shape.pictures?.length ?? 0) !== photos.length) {
+      ctx.addIssue({ code: 'custom', path: ['pictures'], message: `expected exactly ${photos.length} classifications in photo order; received ${shape.pictures?.length ?? 0}` });
+    }
+    for (const role of ['place', 'hero']) {
+      if ((shape.pictures ?? []).filter((p) => p === role).length > 1) {
+        ctx.addIssue({ code: 'custom', path: ['pictures'], message: `at most one ${role} photo is supported; do not silently discard the others` });
+      }
+    }
+  });
+  let ask = prompt, problem = '';
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const answer = await askSparkJson(memo, { label: `idea-shape#${attempt}`, prompt: ask, images: photos, personal: true });
+    const parsed = schema.safeParse(answer);
+    if (parsed.success) return parsed.data;
+    problem = parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ');
+    ask = `${prompt}\n\nCorrection attempt ${attempt + 1}. Your last answer was:\n${JSON.stringify(answer)}\n\nFix: ${problem}`;
+  }
+  throw new ActionError(502, `Spark could not classify all ${photos.length} photos and read the idea after 3 attempts. No world build was started. ${problem}`);
+}
+
+/** The slug cleaned to a folder name, numbered when a world has it already. */
+function freeSlug(root: string, wanted: string): string {
+  const base = wanted.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^[^a-z]+|-+$/g, '').slice(0, 40).replace(/-+$/, '') || 'world';
+  let slug = base, n = 2;
+  while (fs.existsSync(path.join(root, slug))) slug = `${base}-${n++}`;
+  return slug;
+}
+
+const bytesOf = (data: string) => Buffer.from(data.replace(/^data:[^,]*,/, ''), 'base64');
+
+/** Seed the same source material for a preview and a direct build. Videos are copied only on publication. */
+export function seedIdea(dir: string, idea: string, choices: CreativeChoices | undefined, photos: Array<{ name: string; data: string }>, images: Buffer[], shape: Shape, sourceRoot: string) {
+  const styleImage = choices?.styleReference ? fs.readFileSync(styleReferencePath(sourceRoot, choices.styleReference)) : undefined;
+  if (choices) {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'creative-brief.json'), JSON.stringify({ idea, choices }, null, 2));
+    if (styleImage) fs.writeFileSync(path.join(dir, 'style-reference.png'), styleImage);
+  }
+  const photoFiles: { photoFile?: string; heroFile?: string } = {};
+  for (const role of ['place', 'hero'] as const) {
+    const at = (shape.pictures ?? []).indexOf(role);
+    if (at < 0 || !images[at]) continue;
+    const file = path.join(dir, 'start', `${role}.png`);
+    fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, images[at]);
+    photoFiles[role === 'place' ? 'photoFile' : 'heroFile'] = file;
+  }
+  const drawings = (shape.pictures ?? []).flatMap((role, i) => role === 'drawing' && images[i] ? [i] : []);
+  drawings.forEach((i, n) => {
+    const file = path.join(dir, 'drawings', `${String(n + 1).padStart(2, '0')}-${photos[i].name.replace(/\.[^.]+$/, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 30) || 'drawing'}.png`);
+    fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, images[i]);
+  });
+  return { ...photoFiles, drawings: drawings.length };
+}
+
+defineAction({
+  name: 'world_new',
+  description: 'Make a new world from an idea and build it: Spark picks its title, folder name, how many places the story needs (2 to 5) and its language, '
+    + 'unless given; photos (optional) of a real room become the first place, of a person the hero, and drawings the characters, things and places they show. Starts the world_build job and returns the slug.',
+  input: z.object({
+    idea: z.string().min(10).max(4000),
+    choices: CreativeChoices.optional().describe('Only answers, style and notes explicitly chosen by the creator in the optional idea review'),
+    sketch: SketchApproval.optional().describe('Build this exact reviewed world plan and selected visual references'),
+    slug: Slug.optional().describe('the folder name; picked from the idea when left out'),
+    places: z.number().int().min(1).max(8).optional().describe('picked from the idea when left out'),
+    language: z.string().min(2).max(30).optional().describe('the game\'s language ("Polish"); read from the idea when left out'),
+    videos: z.array(VideoId).max(8).optional(),
+    photos: z.array(z.object({ name: z.string().min(1).max(120), data: z.string().min(10) })).max(MAX_WORLD_PHOTOS).optional().describe('photos, base64: a real room becomes the first place, a person the hero, drawings the characters, things and places they show'),
+  }),
+  job: true,
+  async run({ idea, choices, sketch, slug, places, language, photos = [], videos = [] }, ctx) {
+    for (const id of videos) {
+      const dir = videoDir(ctx.root, id), state = videoState(dir);
+      if (!state.duration || !fs.existsSync(path.join(dir, `part-${Math.ceil(state.duration / VIDEO_STEP) - 1}.json`))) throw new ActionError(409, 'Finish interpreting the video before building.');
+    }
+    if (sketch) return publishSketch(ctx, { idea, choices, slug, places, language, photos, videos }, sketch);
+    for (const p of photos) if (!PICTURE.test(p.name)) throw new ActionError(400, `${p.name}: a photo is png, jpg, webp or heic`);
+    const images = await Promise.all(photos.map((p) => normalisePhoto(bytesOf(p.data))));
+    const brief = refinedIdea(idea, choices);
+    const shape = await shapeIdea(startMemo(ctx.root), brief, images);
+    if (slug && fs.existsSync(path.join(ctx.root, slug, 'world.json'))) throw new ActionError(409, `${slug} is built already: pick another name`);
+    const name = slug ?? freeSlug(ctx.root, shape.slug);
+    const dir = path.join(ctx.root, name);
+    const seeded = seedIdea(dir, idea, choices, photos, images, shape, ctx.root);
+    for (const id of videos) {
+      const dest = path.join(dir, 'videos', id);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.cpSync(videoDir(ctx.root, id), dest, { recursive: true });
+    }
+    const lang = language ?? shape.language;
+    const args = ['build', name, brief, '--from', 'world', '--places', String(places ?? shape.places), ...(/^english$/i.test(lang) ? [] : ['--language', lang]), ...(seeded.photoFile ? ['--photo', seeded.photoFile] : []), ...(seeded.heroFile ? ['--hero-photo', seeded.heroFile] : [])];
+    const job = await ctx.jobs.start(name, args, 'build world > verify', ctx.by);
+    return { slug: name, title: shape.title, places: places ?? shape.places, language: lang, drawings: seeded.drawings, job };
+  },
+});
+
+defineAction({
+  name: 'idea_hear',
+  description: 'Hear a spoken idea (a recording, base64) and return it as text, in the language it was said (Muse Voice Transcribe).',
+  input: z.object({ name: z.string().min(1).max(120), data: z.string().min(10) }),
+  async run({ name, data }, ctx) {
+    if (!SOUND.test(name)) throw new ActionError(400, `${name}: a recording is webm, m4a, mp3, wav or ogg`);
+    const audio = decode(bytesOf(data));
+    const said: string[] = [];
+    for (const [i, piece] of pieces(pcm24k(audio)).entries()) said.push(await transcribe(startMemo(ctx.root), `idea:${i}`, piece, 8));
+    return { text: said.join(' ').replace(/\s+/g, ' ').trim() };
+  },
+});

package/app/src/actions/step-work.ts

@@ -0,0 +1,150 @@
+// What a world-wide build step works from and what it made so far, card by card, for the Studio's live step view
+// (a click on that step's segment of the build bar): item icons (where SAM cuts each one from, the icon), plates
+// (what goes, the place without it), weather and reactions (each place, what was read for it). Free, reads files only.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { maskFromPng } from '../image/mask.ts';
+import { maskBox } from '../image/raster.ts';
+import { Reactions } from '../play/reactions.ts';
+import { Weather } from '../play/weather.ts';
+import { itemSources, ItemsInfo } from '../scene/icons.ts';
+import { removableThings } from '../story/engine.ts';
+import { Story } from '../story/schema.ts';
+import { WorldFiles } from '../world/files.ts';
+import { Slug } from '../world/schema.ts';
+import { defineAction } from './registry.ts';
+
+export type Pic = { file: string; v: number | null };
+/** A crop of a place's painting: the box as fractions of the picture, the SAM mask that was cut, and what lies over it. */
+export type Shot = { painting: Pic; box?: [number, number, number, number]; mask?: Pic; over?: Pic };
+export type WorkCard = {
+  key: string; title: string; place?: string;
+  /** What the step works from, and what it made (null: not yet). */
+  from: Shot | null; made: Shot | Pic | null;
+  /** How it is made or what was read, in a few words each. */
+  words: string[];
+  /** When its result was written (ms), to tell this run's result from the earlier build's. */
+  at: number | null;
+};
+
+export const WORK_STEPS = ['icons', 'plates', 'weather', 'reactions'] as const;
+
+const stamp = (file: string) => (fs.existsSync(file) ? Math.round(fs.statSync(file).mtimeMs) : null);
+const boxes = new Map<string, [number, number, number, number] | undefined>();
+
+/** The thing's box in a mask PNG as fractions, grown so there is some of the place around it; cached by file time. */
+async function boxOf(file: string): Promise<[number, number, number, number] | undefined> {
+  const at = `${file}@${stamp(file)}`;
+  if (boxes.has(at)) return boxes.get(at);
+  let out: [number, number, number, number] | undefined;
+  if (fs.existsSync(file)) {
+    const m = await maskFromPng(fs.readFileSync(file));
+    const b = maskBox(m);
+    if (b) {
+      // A square-ish view at least a fifth of the picture wide, so a small thing is still seen where it stands.
+      const side = Math.max(b[2] - b[0], b[3] - b[1], m.width / 5) * 1.5;
+      const [cx, cy] = [(b[0] + b[2]) / 2, (b[1] + b[3]) / 2];
+      const w = Math.min(m.width, side), h = Math.min(m.height, side);
+      const x0 = Math.max(0, Math.min(m.width - w, cx - w / 2)), y0 = Math.max(0, Math.min(m.height - h, cy - h / 2));
+      out = [x0 / m.width, y0 / m.height, (x0 + w) / m.width, (y0 + h) / m.height];
+    }
+  }
+  boxes.set(at, out);
+  return out;
+}
+
+const pic = (files: WorldFiles, rel: string): Pic | null => (fs.existsSync(files.path(rel)) ? { file: rel, v: stamp(files.path(rel)) } : null);
+const readJson = <T,>(files: WorldFiles, rel: string, parse: (x: unknown) => T): T | null => {
+  try {
+    return fs.existsSync(files.path(rel)) ? parse(files.readJson(files.path(rel))) : null;
+  } catch {
+    return null;
+  }
+};
+
+/** The painting where a thing stands, cropped to it, with the SAM mask that cut it out. */
+async function thingShot(files: WorldFiles, place: string, thing: string): Promise<Shot | null> {
+  const painting = pic(files, `places/${place}/painting.png`);
+  if (!painting) return null;
+  const mask = pic(files, `places/${place}/masks/${thing}.png`);
+  return { painting, ...(mask && { mask, box: await boxOf(files.path(mask.file)) }) };
+}
+
+export async function stepWork(files: WorldFiles, step: string): Promise<WorkCard[]> {
+  const story = readJson(files, 'story.json', (x) => Story.parse(x));
+  if (step === 'icons') {
+    if (!story) return [];
+    const sources = itemSources(story);
+    const info = readJson(files, 'items/items.json', (x) => ItemsInfo.parse(x)) ?? {};
+    return Promise.all(story.items.map(async (item) => {
+      const from = sources[item.key];
+      const icon = pic(files, `items/${item.key}.png`);
+      const how = info[item.key]?.how;
+      return {
+        key: item.key, title: item.name, place: from?.place,
+        from: from ? await thingShot(files, from.place, from.thing) : null,
+        made: icon,
+        words: [from ? `picked up in ${from.place} (${from.thing})` : 'handed over: Muse Image paints it',
+          ...(how ? [how === 'cut' ? 'cut from the painting with SAM\'s mask' : how === 'redraw' ? 'too small: Muse Image redrew the cut-out, SAM cut it' : 'painted by Muse Image, cut out by SAM'] : [])],
+        at: icon?.v ?? null,
+      };
+    }));
+  }
+  if (step === 'plates') {
+    if (!story) return [];
+    const takes = removableThings(story).map(async ({ place, thing }) => {
+      const from = await thingShot(files, place, thing);
+      const plate = pic(files, `places/${place}/plates/${thing}.png`);
+      return { key: `${place}/${thing}`, title: `${thing} taken`, place, from,
+        made: plate && from ? { ...from, mask: undefined, over: plate } : null,
+        words: [`${place}: the place once the hero takes the ${thing}`, 'Muse Image paints over where it stood'], at: plate?.v ?? null };
+    });
+    const changes = story.changes.map(async (c, i) => {
+      const from = await thingShot(files, c.place, c.thing);
+      const plate = pic(files, `places/${c.place}/changes/${i}.png`);
+      return { key: `${c.place}/change-${i}`, title: `${c.thing} changes`, place: c.place, from,
+        made: plate && from ? { ...from, mask: undefined, over: plate } : null,
+        words: [`${c.place}: ${c.looks}`, `once ${c.when.join(', ')}`], at: plate?.v ?? null };
+    });
+    return Promise.all([...takes, ...changes]);
+  }
+  if (step === 'weather' || step === 'reactions') {
+    return files.world().places.map((p) => {
+      const painting = pic(files, `places/${p.key}/painting.png`);
+      const from = painting && { painting };
+      if (step === 'weather') {
+        const rel = `places/${p.key}/weather.json`;
+        const w = readJson(files, rel, (x) => Weather.parse(x));
+        const ripples = pic(files, `places/${p.key}/weather/ripples.png`);
+        const words = w ? [
+          w.fall === 'none' ? 'nothing falls' : `${w.fall}, ${Math.round(w.strength * 100)}%${w.wind ? `, wind ${w.wind > 0 ? 'right' : 'left'}` : ''}`,
+          ...(w.fog ? [`fog ${Math.round(w.fog * 100)}%`] : []),
+          ...(ripples ? ['rings on water and puddles'] : []),
+          ...w.drips.map((d) => `drips from ${d.phrase}`),
+        ] : [];
+        return { key: p.key, title: p.key, place: p.key, from, made: w && painting ? { painting, ...(ripples && { mask: ripples }) } : null, words, at: stamp(files.path(rel)) };
+      }
+      const rel = `places/${p.key}/reactions.json`;
+      const r = readJson(files, rel, (x) => Reactions.parse(x));
+      const words = r ? [
+        ...r.areas.map((a) => `${a.key}: ${[a.step && `${a.step.kind} under each step`, a.enter && `${a.enter.kind} on entering`].filter(Boolean).join(', ')}`),
+        ...r.interactions.map((i) => `${i.thing} (${i.action}): ${i.burst.kind}`),
+      ] : [];
+      if (r && !words.length) words.push('nothing reacts here (a clean, still place)');
+      return { key: p.key, title: p.key, place: p.key, from, made: r && painting ? { painting } : null, words, at: stamp(files.path(rel)) };
+    });
+  }
+  return [];
+}
+
+defineAction({
+  name: 'step_work',
+  reads: true,
+  description: 'What a world-wide build step (icons, plates, weather, reactions) works from and what it made so far, card by card: '
+    + 'for icons each item with the painting crop and SAM mask it is cut from and its icon; for plates each taken or changed thing and its plate; '
+    + 'for weather and reactions each place and what was read for it. Free.',
+  input: z.object({ slug: Slug, step: z.enum(WORK_STEPS) }),
+  async run({ slug, step }, ctx) {
+    return stepWork(new WorldFiles(slug, ctx.root), step);
+  },
+});

package/app/src/actions/story.ts

@@ -0,0 +1,101 @@
+// The story: places and how exits join them, locks, items, conversations, changes and endings, with the
+// checker's verdict and a shortest route to each ending. Lines are reworded in place (story_text); anything
+// that changes what the player can do goes back to Spark as a wish (story_redo), so the checker always runs.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { storyLines, Voices } from '../sound/voices.ts';
+import { brevityIssues, checkStory, paintingIssues, questionIssues } from '../story/check.ts';
+import { applyTexts, readStoryFixes, StoryFixes, storyFixesFile, textAt } from '../story/fixes.ts';
+import { Story } from '../story/schema.ts';
+import { History } from '../studio/history.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { WorldFiles } from '../world/files.ts';
+import { Slug } from '../world/schema.ts';
+import { ActionError, defineAction, type ActionContext } from './registry.ts';
+
+function open(slug: string, ctx: ActionContext) {
+  const files = new WorldFiles(slug, ctx.root);
+  if (!fs.existsSync(files.path('world.json'))) throw new ActionError(404, `no world ${slug} yet`);
+  return files;
+}
+
+const readStory = (files: WorldFiles) => (fs.existsSync(files.path('story.json')) ? Story.parse(files.readJson(files.path('story.json'))) : null);
+
+defineAction({
+  name: 'story_status',
+  reads: true,
+  description: 'The story of a world: places with their exits and things, locks, items, interactions, conversations, changes, optional NPC patrols and endings (story). NPC stages use flags/when; moveNpc effects relocate them after events. Includes '
+    + 'the checker\'s issues and a shortest route to each ending, lines over the word limits (long), the person\'s wish and reworded lines (fixes), '
+    + 'spoken lines not voiced yet (unvoiced: run_step voices) and changes whose plate is not painted for the current wording (unpainted: run_step plates). '
+    + 'Text paths for story_text are dotted, like "dialogues.0.lines.2.says".',
+  input: z.object({ slug: Slug }),
+  async run({ slug }, ctx) {
+    const files = open(slug, ctx);
+    const world = files.world();
+    const places = world.places.map((p) => ({ key: p.key, shows: p.shows, exits: p.exits, things: p.things.map((t) => ({ key: t.key, role: t.role })) }));
+    const story = readStory(files);
+    const fixes = readStoryFixes(files);
+    if (!story) return { start: world.start, hero: world.hero.key, places, story: null, fixes, issues: [], routes: [], states: 0, long: [], unvoiced: [], unpainted: [] };
+    const report = checkStory(world, story);
+    const voices = fs.existsSync(files.path('voices.json')) ? Voices.safeParse(files.readJson(files.path('voices.json'))) : null;
+    const said = new Set(voices?.success ? voices.data.lines.filter((l) => !l.flags.some((f) => f.startsWith('heard')) && fs.existsSync(files.path(l.file))).map((l) => JSON.stringify([l.speaker, l.text])) : []);
+    const unvoiced = storyLines(world, story, world.audience === 'kids').filter((l) => !said.has(JSON.stringify([l.speaker, l.text]))).map((l) => l.text);
+    const unpainted = story.changes.flatMap((c, i) => {
+      const plate = files.path('places', c.place, 'changes', `${i}.png`);
+      const worded = fixes.texts[`changes.${i}.looks`]?.at;
+      const painted = fs.existsSync(plate) ? fs.statSync(plate).mtimeMs : 0;
+      return fs.existsSync(files.path('places', c.place, 'painting.png')) && (!painted || (worded && Date.parse(worded) > painted)) ? [i] : [];
+    });
+    return {
+      start: world.start, hero: world.hero.key, places, story, fixes,
+      issues: report.issues, states: report.states, routes: report.routes.map((r) => ({ ending: r.ending, steps: r.steps })),
+      long: brevityIssues(story), unanswerable: questionIssues(story), unseen: paintingIssues(world, story), unvoiced, unpainted,
+    };
+  },
+});
+
+defineAction({
+  name: 'story_text',
+  description: 'Reword one line of the story: the intro, what the hero says at a thing or a lock, an NPC line, an answer, an item name, an ending, or how a change looks. '
+    + 'Path is dotted into story.json ("intro", "interactions.3.say", "dialogues.0.lines.1.choices.0.text", "endings.1.text", "changes.0.looks"). '
+    + 'Only wording: what the player can do stays the same. Kept across rebuilds. Spoken lines need run_step voices afterwards, a change\'s looks run_step plates.',
+  input: z.object({ slug: Slug, path: z.string().min(1), text: z.string().trim().min(1).max(400) }),
+  async run({ slug, path, text }, ctx) {
+    const files = open(slug, ctx);
+    const blocked = agentBlocked(files.dir, ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    const story = readStory(files);
+    if (!story) throw new ActionError(409, `${slug} has no story yet: run_step story first`);
+    const before = textAt(story, path);
+    if (before === null) throw new ActionError(400, `"${path}" is not a line of the story; story_status lists them`);
+    const busy = ctx.jobs.busy(slug);
+    if (busy) throw new ActionError(409, `${busy.label} is ${busy.state}; wait before editing story text`);
+    new History(files.dir).snapshot(`story text ${path}`, ctx.by);
+    const fixes = readStoryFixes(files);
+    fixes.texts[path] = { text, at: new Date().toISOString() };
+    files.write(storyFixesFile(files), StoryFixes.parse(fixes));
+    const now = applyTexts(story, { texts: { [path]: fixes.texts[path] } }).story;
+    files.write(files.path('story.json'), now);
+    const spoken = storyLines(files.world(), now).some((l) => l.text === text);
+    const [kind, i] = path.split('.');
+    return { path, before, text, spoken, plate: kind === 'changes' ? now.changes[Number(i)].place : null };
+  },
+});
+
+defineAction({
+  name: 'story_redo',
+  description: 'Have Spark write the story again to a wish ("the ferrywoman should want something in return", "after receiving the key she goes to the garden and thanks me there"); '
+    + 'NPC stages use ordinary flags and conditional dialogue; patrols are optional, and moveNpc effects trigger travel through existing exits. '
+    + 'the checker plays every state, so it stays winnable. Reworded lines are dropped, since the lines change. Without a wish, goes back to Spark\'s first story. '
+    + 'Runs as a job; afterwards inspect story_status/cast_status. New walkers may need model/sprites; new lines need voices/faces and visual changes need plates.',
+  input: z.object({ slug: Slug, wish: z.string().trim().min(5).max(600).optional() }),
+  job: true,
+  async run({ slug, wish }, ctx) {
+    const files = open(slug, ctx);
+    const blocked = agentBlocked(files.dir, ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    return ctx.jobs.start(slug, ['story', slug], wish ? 'rewrite story' : 'first story', ctx.by, () => {
+      files.write(storyFixesFile(files), StoryFixes.parse({ ...(wish && { wish }), texts: {} }));
+    });
+  },
+});

package/app/src/actions/studio.ts

@@ -0,0 +1,133 @@
+// Setup checks and moving the view. Storing a key is deliberately not an action: keys are typed only
+// into `diorama setup` in a terminal, never into the GUI or through the agent.
+import { z } from 'zod';
+import { runChecks } from '../setup/checks.ts';
+import { Slug } from '../world/schema.ts';
+import { defineAction } from './registry.ts';
+import { soundQuality } from '../sound/cost.ts';
+import { writeSoundQuality } from '../sound/settings.ts';
+import { blenderEnv, blenderState, writeBlenderSettings } from '../model/blender.ts';
+import { facesState, writeFacesSettings } from '../scene/faces-settings.ts';
+
+const audioState = () => ({ quality: soundQuality(), env: process.env.DIORAMA_SOUND ?? null });
+
+defineAction({
+  name: 'audio_get',
+  reads: true,
+  description: 'Audio quality for new generations: final or draft, and any DIORAMA_SOUND override.',
+  input: z.object({}),
+  async run() { return audioState(); },
+});
+
+defineAction({
+  name: 'audio_set',
+  description: 'Save the machine-wide audio quality for future sound and voices generations. Existing recordings are unchanged.',
+  input: z.object({ quality: z.enum(['final', 'draft']) }),
+  async run({ quality }) {
+    if (process.env.DIORAMA_SOUND !== undefined) throw new Error('DIORAMA_SOUND overrides Setup. Unset it and restart Studio to choose audio quality here.');
+    writeSoundQuality(quality);
+    return audioState();
+  },
+});
+
+defineAction({
+  name: 'blender_get',
+  reads: true,
+  description: 'Whether a local Blender relaxes 3D figures\' rest pose (arms down, feet under the hips) before they walk: found or not, on or off.',
+  input: z.object({}),
+  async run() { return blenderState(); },
+});
+
+defineAction({
+  name: 'blender_set',
+  description: 'Turn the local Blender step for 3D figures on or off for this machine. On: new models get a calm rest pose; cast_relax fixes existing ones.',
+  input: z.object({ enabled: z.boolean() }),
+  async run({ enabled }) {
+    if (blenderEnv() !== undefined) throw new Error('DIORAMA_BLENDER overrides Setup. Unset it and restart Studio to switch Blender here.');
+    writeBlenderSettings({ enabled });
+    return blenderState();
+  },
+});
+
+defineAction({
+  name: 'faces_get',
+  reads: true,
+  description: 'Whether builds prepare talking mouths (the faces step) on this machine. Off by default.',
+  input: z.object({}),
+  async run() { return facesState(); },
+});
+
+defineAction({
+  name: 'faces_set',
+  description: 'Turn talking mouths on or off for builds on this machine (the person decides this in Setup; ask before changing it).',
+  input: z.object({ enabled: z.boolean() }),
+  async run({ enabled }) {
+    if (facesState().env !== null) throw new Error('DIORAMA_FACES overrides Setup. Unset it and restart Studio to switch it here.');
+    writeFacesSettings(enabled);
+    return facesState();
+  },
+});
+
+defineAction({
+  name: 'setup_status',
+  reads: true,
+  description: 'What this machine has and still needs (Node, Meta key, Muse Code, Chromium, ElevenLabs, Python, publishing). Never returns a key, only where it comes from.',
+  input: z.object({}),
+  async run() {
+    return runChecks();
+  },
+});
+
+defineAction({
+  name: 'setup_check',
+  description: 'Like setup_status, plus one live call with the Meta key to prove it works.',
+  input: z.object({}),
+  async run() {
+    return runChecks({ live: true });
+  },
+});
+
+defineAction({
+  name: 'ui_focus',
+  description: 'Point the Studio view at a world, a screen or a place, so the person sees what the agent is talking about (when they follow the agent).',
+  input: z.object({
+    slug: Slug.optional(),
+    view: z.enum(['worlds', 'start', 'setup', 'workshop', 'story', 'cast', 'play']).optional()
+      .describe('worlds: leave the world for the list of all worlds (start is the same); setup: keys and tools; workshop: the world\'s places; story, cast; play: the game'),
+    place: Slug.optional(),
+  }),
+  async run(input, ctx) {
+    // Pointing at a world or a place never means leaving it: "start" there reads as "begin at this place".
+    const view = (input.view === 'start' || input.view === 'worlds') && (input.slug || input.place) ? 'workshop' : input.view === 'worlds' ? 'start' : input.view;
+    ctx.events.publish('ui.focus', { ...input, ...(view && { view }), world: input.slug, by: ctx.by });
+    return { ok: true };
+  },
+});
+
+defineAction({
+  name: 'play_reload',
+  description: 'Reload the game the person is playing in the Studio, so it shows your change (opens it if they follow you and it is closed). '
+    + 'Call it after a change they should see in play, instead of asking them to refresh.',
+  input: z.object({ slug: Slug, place: Slug.optional() }),
+  async run({ slug, place }, ctx) {
+    ctx.events.publish('ui.focus', { slug, world: slug, view: 'play', reload: true, ...(place && { place }), by: ctx.by });
+    return { ok: true };
+  },
+});
+
+defineAction({
+  name: 'ask_person',
+  reads: true,
+  description: 'Ask the person a question with a few answers to tap (yes/no, which of two fixes, go ahead or not), shown in the Studio as a card with buttons. '
+    + 'Put the question here and not again in your text, then end your turn: their tap arrives as their next message, the answer\'s words exactly.',
+  input: z.object({
+    slug: Slug,
+    question: z.string().min(3).max(300).describe('One short question, in the language of the person\'s newest message'),
+    options: z.array(z.string().min(1).max(60)).min(2).max(4).describe('2 to 4 short answers, in that language: "Yes, rebuild it" and "No, leave it" rather than bare yes/no'),
+    recommended: z.number().int().min(0).max(3).optional().describe('Index of the answer you advise'),
+  }),
+  async run(input, ctx) {
+    ctx.events.publish('ui.ask', { ...input, world: input.slug, by: ctx.by });
+    return { asked: true, next: 'End your turn now. The person\'s tap comes back as their next message.' };
+  },
+});