@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/actions/build.ts

@@ -0,0 +1,158 @@
+import { WorldFiles } from '../world/files.ts';
+import { placesFirst } from './faces.ts';
+// Building: the whole pipeline or one step, as a job; plus the job list and cancel.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { STEPS } from '../commands/build.ts';
+import { Slug } from '../world/schema.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+const Step = z.enum(STEPS);
+
+/** Places the last build set aside at a step (build.json `places[].from`), optionally only one. */
+export function brokenPlaces(dir: string, only?: string): Array<{ place: string; from: string }> {
+  const log = path.join(dir, 'build.json');
+  if (!fs.existsSync(log)) return [];
+  const places = (JSON.parse(fs.readFileSync(log, 'utf8')) as { places?: Array<{ place: string; from?: string }> }).places ?? [];
+  return places.filter((r): r is { place: string; from: string } => !!r.from && (!only || r.place === only));
+}
+
+defineAction({
+  name: 'world_build',
+  description: 'Build a world: every step from world to verify, or a range. A new world needs an idea. Runs as a job; follow it with world_status or the live feed.',
+  input: z.object({
+    slug: Slug,
+    idea: z.string().min(10).optional().describe('What the world is about; needed when the build starts at the world step.'),
+    from: Step.optional(),
+    to: Step.optional(),
+    places: z.number().int().min(1).max(8).optional(),
+  }),
+  job: true,
+  async run({ slug, idea, from, to, places }, ctx) {
+    const blocked = agentBlocked(path.join(ctx.root, slug), ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    const fresh = !fs.existsSync(path.join(ctx.root, slug, 'world.json'));
+    if (fresh && !idea && (!from || from === 'world')) throw new Error(`${slug} is a new world: give it an idea`);
+    // An existing world picks up at the first step it has not finished.
+    const log = path.join(ctx.root, slug, 'build.json');
+    const done = !fresh && fs.existsSync(log) ? (JSON.parse(fs.readFileSync(log, 'utf8')) as { steps?: object }).steps ?? {} : {};
+    const unfinished = fresh ? 'world' : STEPS.find((s) => s !== 'world' && !(s in done)) ?? 'verify';
+    const broken = brokenPlaces(path.join(ctx.root, slug)).map((p) => p.from).filter((s): s is typeof STEPS[number] => (STEPS as readonly string[]).includes(s));
+    const start = from ?? [unfinished, ...broken].sort((a, b) => STEPS.indexOf(a) - STEPS.indexOf(b))[0];
+    const args = ['build', slug, ...(idea ? [idea] : []), '--from', start, ...(to ? ['--to', to] : []), ...(places ? ['--places', String(places)] : [])];
+    return ctx.jobs.start(slug, args, `build ${start} > ${to ?? STEPS[STEPS.length - 1]}`, ctx.by);
+  },
+});
+
+defineAction({
+  name: 'run_step',
+  description: `Run one build step on a world (${STEPS.join(', ')}). Runs as a job. With place: that place only, from the step through verify.`,
+  input: z.object({ slug: Slug, step: Step, place: Slug.optional().describe('Only this place: rebuilt from the step through verify') }),
+  job: true,
+  async run({ slug, step, place }, ctx) {
+    if (step === 'world') throw new Error('the world step makes a new world: use world_build with an idea');
+    const blocked = agentBlocked(path.join(ctx.root, slug), ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    if (step === 'faces') { const later = placesFirst(new WorldFiles(slug, ctx.root), slug, ctx); if (later) throw new ActionError(409, later); }
+    if (place) return ctx.jobs.start(slug, ['build', slug, '--from', step, '--to', 'verify', '--place', place], `${step} · ${place}`, ctx.by);
+    return ctx.jobs.start(slug, ['build', slug, '--from', step, '--to', step], step, ctx.by);
+  },
+});
+
+defineAction({
+  name: 'job_list',
+  reads: true,
+  description: 'Jobs this studio ran or queued, newest last, optionally for one world.',
+  input: z.object({ slug: Slug.optional() }),
+  async run({ slug }, ctx) {
+    return ctx.jobs.list(slug);
+  },
+});
+
+defineAction({
+  name: 'job_inspect',
+  reads: true,
+  description: 'Inspect a job without waiting: elapsed and quiet time, timestamped recent logs and failures, current locally observed model/API operations and their duration, and voice/sound item counts. These describe the Studio process, not the remote provider internals; silence alone does not prove a hang. Use this when a job appears slow, and before deciding what to do. A staged extension is not in the game until it succeeds.',
+  input: z.object({ id: z.string().min(1), limit: z.number().int().min(1).max(100).optional() }),
+  async run({ id, limit }, ctx) {
+    if (!ctx.jobs.get(id)) throw new ActionError(404, `no job ${id}`);
+    return ctx.jobs.inspect(id, limit ?? 40);
+  },
+});
+
+defineAction({
+  name: 'job_wait',
+  reads: true,
+  description: 'Wait for a job to end (or up to timeoutSeconds, default 120) and return its state plus recent activity, locally observed operations and progress counts. A return with state running means it is still running. It returns early with personWrote when the person writes to you meanwhile: deal with that message before waiting again. job_inspect shows more activity without waiting.',
+  input: z.object({ id: z.string().min(1), timeoutSeconds: z.number().int().min(1).max(600).optional() }),
+  async run({ id, timeoutSeconds }, ctx) {
+    // The person writing to the agent ends the wait at once: a steer only reaches the agent between tool calls,
+    // so a two-minute wait would hold their message (\"never mind the freckles\") until the job had gone on.
+    const heard = new AbortController();
+    let said: string | undefined;
+    const off = ctx.onPersonSays?.((text) => {
+      said = text;
+      heard.abort();
+    });
+    let job;
+    try {
+      job = await ctx.jobs.wait(id, (timeoutSeconds ?? 120) * 1000, heard.signal);
+    } finally {
+      off?.();
+    }
+    const interrupted = said !== undefined && (job.state === 'running' || job.state === 'queued')
+      ? { personWrote: said, hint: 'The person wrote to you while you waited; their message follows this result. Read it and act on it first (answer, change course, or job_cancel this job if they want something else) before waiting again.' }
+      : {};
+    // Still queued: say what it waits behind, so a wait never hangs on a job that has not started.
+    const ahead = job.state === 'queued' ? ctx.jobs.list(job.world).find((j) => j.state === 'running') : undefined;
+    return { ...job, ...(job.state === 'queued' && { waitingBehind: ahead ? `${ahead.label} (${ahead.id}), running since ${ahead.startedAt}` : 'nothing; it starts next', hint: ahead ? 'Not started yet. If what runs ahead is not more important, job_cancel it; otherwise do something else and wait again.' : undefined }), ...interrupted, telemetry: ctx.jobs.inspect(id, 12) };
+  },
+});
+
+defineAction({
+  name: 'job_cancel',
+  description: 'Stop a running or queued job.',
+  input: z.object({ id: z.string().min(1) }),
+  async run({ id }, ctx) {
+    return ctx.jobs.cancel(id);
+  },
+});
+
+defineAction({
+  name: 'job_retry',
+  description: 'Run a failed or stopped job again; a build picks up at the step it failed on, or earlier at the step where a place was set aside.',
+  input: z.object({ id: z.string().min(1) }),
+  job: true,
+  async run({ id }, ctx) {
+    const job = ctx.jobs.get(id);
+    if (!job) throw new ActionError(404, `no job ${id}`);
+    if (job.state === 'running' || job.state === 'queued') throw new ActionError(409, `${job.label} is still ${job.state}`);
+    const args = [...job.args];
+    const place = args.includes('--place') ? args[args.indexOf('--place') + 1] : undefined;
+    const blocked = agentBlocked(path.join(ctx.root, job.world), ctx.by, place);
+    if (blocked) throw new ActionError(423, blocked);
+    const from = args.indexOf('--from');
+    // Steps before the failed one are done; start where it broke. A place set aside earlier in the build (its paint
+    // refused, say) broke at its own step while the others went on: start at the earliest such step, or the retry
+    // runs only the last step, which skips that place again.
+    if (args[0] === 'build' && from >= 0 && job.step && (STEPS as readonly string[]).includes(job.step)) {
+      const steps = STEPS as readonly string[];
+      const broke = brokenPlaces(path.join(ctx.root, job.world), place).map((r) => r.from).filter((s) => steps.includes(s));
+      args[from + 1] = [job.step, ...broke].sort((a, b) => steps.indexOf(a) - steps.indexOf(b))[0];
+    }
+    return ctx.jobs.retry(job.id, args, ctx.by);
+  },
+});
+
+defineAction({
+  name: 'playthrough',
+  description: 'Let the bot play the world in a browser along the story\'s routes and check each ending is reached; says where it got stuck. Runs as a job.',
+  input: z.object({ slug: Slug, ending: z.string().min(1).optional().describe('One ending; leave out for all of them.') }),
+  job: true,
+  async run({ slug, ending }, ctx) {
+    if (!fs.existsSync(path.join(ctx.root, slug, 'story.json'))) throw new ActionError(404, `${slug} has no story yet: build it to the story step first`);
+    return ctx.jobs.start(slug, ['playthrough', slug, ...(ending ? [ending] : [])], `playthrough${ending ? ` ${ending}` : ''}`, ctx.by);
+  },
+});

package/app/src/actions/cast.ts

@@ -0,0 +1,267 @@
+// The cast: the hero and every NPC, how each looks, which parts the runtime has for them (cut-out, rig,
+// 3D model, sprite sheets) and which voice speaks their lines. Fixes go to cast/fixes.json.
+import fs from 'node:fs';
+import { animationCurrent } from '../scene/animation-source.ts';
+import path from 'node:path';
+import { z } from 'zod';
+import { CastFixes, castFixesFile, readCastFixes } from '../scene/cast-fixes.ts';
+import { DESIGNED, designDescriptions, needsDesign, stockVoices, voiceCandidates, Voices } from '../sound/voices.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { players } from '../world/drawings.ts';
+import { modelProblem } from '../model/glb.ts';
+import { POSE_OK } from '../model/sprites.ts';
+import { readBodies } from '../scene/cast.ts';
+import { WorldFiles } from '../world/files.ts';
+import { liveVoiceFailures } from '../sound/data.ts';
+import { voiceRetryTarget } from '../sound/retry.ts';
+import { Slug } from '../world/schema.ts';
+import { faceStatus } from './faces.ts';
+import { ActionError, defineAction, type ActionContext } from './registry.ts';
+
+const stamp = (file: string) => (fs.existsSync(file) ? Math.round(fs.statSync(file).mtimeMs) : null);
+const ModelAttempt = z.object({ state: z.enum(['ready', 'fallback', 'failed']), reason: z.string().nullable(), at: z.string() });
+const RigAttempt = z.object({ ok: z.boolean(), reason: z.string().nullable(), at: z.string() });
+
+defineAction({
+  name: 'voice_retry',
+  description: 'Retry one missing spoken line using its exact speaker key and text from cast_status voiceFailures. Keeps the selected voice and all other recordings. Rejected takes get fresh seeds; a transcription outage reuses saved audio. Costs ElevenLabs/verification calls when needed; wait with job_wait, then check cast_status and play_reload.',
+  input: z.object({ slug: Slug, key: Slug, text: z.string().min(1).max(5000) }),
+  job: true,
+  async run({ slug, key, text }, ctx) {
+    const files = new WorldFiles(slug, ctx.root);
+    const blocked = agentBlocked(files.dir, ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    voiceRetryTarget(files, key, text);
+    return ctx.jobs.start(slug, ['voice-retry', slug, key, text], `retry line ${key}`, ctx.by);
+  },
+});
+
+function pendingModel(ctx: ActionContext, slug: string, key: string) {
+  return ctx.jobs.list(slug).find((j) => (j.state === 'queued' || j.state === 'running')
+    && j.args.length >= 3 && j.args[0] === 'model' && j.args[1] === slug && j.args[2] === key);
+}
+
+function characters(files: WorldFiles) {
+  const world = files.world();
+  const npcs = new Map(world.places.flatMap((p) => p.things.filter((t) => t.role === 'npc').map((t) => [t.key, { ...t, place: p.key }] as const)));
+  return [
+    { key: world.hero.key, looks: world.hero.looks, role: 'hero' as 'hero' | 'npc' | 'player', place: null as string | null },
+    ...[...npcs.values()].map((n) => ({ key: n.key, looks: n.looks, role: 'npc' as const, place: n.place })),
+    // Heroes for more gamepads (drawings marked player): painted and rigged like the hero, in no place.
+    ...players(files).map((p) => ({ key: p.key, looks: p.looks, role: 'player' as const, place: null })),
+  ];
+}
+
+function prepareFix(ctx: ActionContext, slug: string, key: string, change: (f: CastFixes[string]) => void) {
+  const files = new WorldFiles(slug, ctx.root);
+  if (key !== 'narrator' && !characters(files).some((c) => c.key === key)) throw new ActionError(404, `${slug} has no hero or NPC called ${key}`);
+  const blocked = agentBlocked(files.dir, ctx.by);
+  if (blocked) throw new ActionError(423, blocked);
+  return () => {
+    const fixes = readCastFixes(files);
+    const fix = (fixes[key] ??= {});
+    change(fix);
+    fs.mkdirSync(path.dirname(castFixesFile(files)), { recursive: true });
+    files.write(castFixesFile(files), CastFixes.parse(fixes));
+  };
+}
+
+defineAction({
+  name: 'cast_status',
+  reads: true,
+  description: 'Every character of a world (hero and NPCs): how they look (and the person\'s fixes), which parts exist (cut-out figure, rig, 3D model, sprite sheets; '
+    + 'rigIssue says why there is no 2D walk, modelIssue why a model is not used, e.g. flat), how the game moves them (moves: sprites, 3D model, 2D rig or the cut-out sliding as one piece), '
+    + 'their voice and how many lines they speak, with a sample, and voiceFailures for lines the story still has that have no recording.',
+  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 fixes = readCastFixes(files);
+    const voices = fs.existsSync(files.path('voices.json')) ? Voices.safeParse(files.readJson(files.path('voices.json'))) : null;
+    const pic = (f: string) => (fs.existsSync(files.path(f)) ? { file: f, v: stamp(files.path(f)) } : null);
+    const bodies = readBodies(files, fs.existsSync);
+    const failures = liveVoiceFailures(files);
+    const narrator = voices?.success && voices.data.cast.narrator ? [{ key: 'narrator', looks: 'reads the intro and the endings', role: 'narrator' as const, place: null }] : [];
+    return [...characters(files), ...narrator].map((c) => {
+      const lines = voices?.success ? voices.data.lines.filter((l) => l.speaker === c.key) : [];
+      return {
+        ...c,
+        looksNow: fixes[c.key]?.looks ?? c.looks,
+        fix: fixes[c.key] ?? null,
+        figure: pic(`cast/${c.key}.png`),
+        // What the cut-out keeps beyond the body (cast_holds) and the share of its height the body takes.
+        cut: fs.existsSync(files.path('cast', c.key, 'cut.json')) ? files.readJson(files.path('cast', c.key, 'cut.json')) : null,
+        face: faceStatus(files, c.key),
+        painting: pic(`cast/${c.key}-painting.png`),
+        rig: animationCurrent(files,c.key,'rig') && fs.existsSync(files.path('cast', c.key, 'rig.json')),
+        ...(() => {
+          const file = files.path('cast', c.key, 'rig-attempt.json');
+          const a = fs.existsSync(file) ? RigAttempt.safeParse(files.readJson(file)) : null;
+          return { rigIssue: !animationCurrent(files,c.key,'rig') ? 'The figure changed; rebuild the 2D walk.' : a?.success && !a.data.ok ? a.data.reason : null };
+        })(),
+        // Metres tall and whether upright on two legs; not upright (a creature) moves as one body, no 2D rig or sheets.
+        body: bodies[c.key] ?? null,
+        ...(() => {
+          // A flat model (and the sheets painted over it) is not used by the game; say why instead.
+          const has = fs.existsSync(files.path('cast', c.key, 'model', 'model.json'));
+          const attemptFile = files.path('cast', c.key, 'model', 'attempt.json');
+          const parsed = fs.existsSync(attemptFile) ? ModelAttempt.safeParse(files.readJson(attemptFile)) : null;
+          const modelAttempt = parsed?.success ? parsed.data : null;
+          const modelIssue = has ? !animationCurrent(files,c.key,'model') ? 'The figure changed; rebuild the 3D model.' : modelProblem(files.path('cast', c.key, 'model')) : modelAttempt?.reason ?? null;
+          const pending = pendingModel(ctx, slug, c.key);
+          const sprites = has && !modelIssue && animationCurrent(files,c.key,'sprites') && fs.existsSync(files.path('cast', c.key, 'sprites', 'sprites.json'));
+          const rigged = animationCurrent(files,c.key,'rig') && fs.existsSync(files.path('cast', c.key, 'rig.json'));
+          const creature = bodies[c.key]?.upright === false;
+          // What the game does with them, in the order it prefers: the person sees the fallback, not a silent gap.
+          const moves = !fs.existsSync(files.path('cast', `${c.key}.png`)) ? 'not painted: a stand-in'
+            : sprites ? 'walks with painted sprite sheets' : has && !modelIssue ? (creature ? 'moves as its 3D model (hops, breathes, blinks)' : 'walks as its 3D model')
+              : rigged ? 'walks with its 2D rig (the painting bent by its bones)' : 'the cut-out slides as one piece (no rig, no model)';
+          // Walk sheets whose frames left the pose (Muse turned some frames to another facing): the walk stutters there.
+          const sheet = sprites ? z.object({ facings: z.record(z.string(), z.object({ iou: z.array(z.number()).optional() })).optional() }).safeParse(files.readJson(files.path('cast', c.key, 'sprites', 'sprites.json'))) : null;
+          const mean = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / xs.length;
+          const spriteIssues = !animationCurrent(files,c.key,'sprites') ? ['The figure or model changed; rebuild the sprite sheets.'] : sheet?.success ? Object.entries(sheet.data.facings ?? {}).filter(([, f]) => f.iou?.length && mean(f.iou) < POSE_OK).map(([f, x]) => `walk ${f}: frames left the pose (pose IoU ${mean(x.iou!).toFixed(2)}); sprites_redo paints new takes`) : [];
+          return {
+            model: has && !modelIssue, sprites, modelIssue, modelAttempt, moves, spriteIssues,
+            modelJob: pending ? { id: pending.id, state: pending.state } : null,
+            // When each was last written, so Studio's preview reloads them after a rebuild.
+            stamps: { rig: stamp(files.path('cast', c.key, 'rig.json')), model: has && !modelIssue ? stamp(files.path('cast', c.key, 'model', 'model.json')) : null, sprites: sprites ? stamp(files.path('cast', c.key, 'sprites', 'sprites.json')) : null },
+          };
+        })(),
+        voice: voices?.success ? voices.data.cast[c.key] ?? null : null,
+        lines: lines.length,
+        flagged: lines.filter((l) => l.flags.some((f) => f.startsWith('heard'))).length,
+        voiceFailures: failures.filter((l) => l.speaker === c.key),
+        voiceWarnings: voices?.success ? voices.data.cast[c.key]?.warnings ?? [] : [],
+        sample: lines[0] ? { text: lines[0].text, file: lines[0].file } : null,
+      };
+    });
+  },
+});
+
+defineAction({
+  name: 'cast_redo',
+  description: 'Paint a character again: with a new description of how they look (kept across rebuilds), or simply another take. '
+    + 'Repaints and cuts out the figure (Muse + SAM); run_step model and sprites afterwards if the character walks with sprites. Runs as a job.',
+  input: z.object({ slug: Slug, key: z.string().min(1), looks: z.string().min(10).optional(), anotherTake: z.boolean().optional() }),
+  job: true,
+  async run({ slug, key, looks, anotherTake }, ctx) {
+    if (!looks && !anotherTake) throw new ActionError(400, 'give new looks, or anotherTake: true');
+    const prepare = prepareFix(ctx, slug, key, (f) => {
+      if (looks) f.looks = looks;
+      if (anotherTake) f.take = (f.take ?? 0) + 1;
+    });
+    return ctx.jobs.start(slug, ['cast', slug, key], `cast ${key}`, ctx.by, prepare);
+  },
+});
+
+defineAction({
+  name: 'cast_holds',
+  description: 'Keep what a character holds or carries on their cut-out (a giant slice of toast over the head, a lantern, a net), however big: SAM finds each '
+    + 'thing by its name and it is cut out with them and walks with their hands. Without holds, what their description says they hold is used (read by Spark); '
+    + 'holds names the things yourself in a few words each ("slice of toast"), [] keeps nothing extra. Kept across rebuilds. Cuts the figure again from its '
+    + 'painting and makes its 2D walk again: no Muse calls, a few SAM calls. Use it when the person says the figure lost what it holds. '
+    + 'A 3D model and its sprites never hold anything (held things tear its rig): when the held thing is who they are, say so. Then play_reload. Runs as a job.',
+  input: z.object({ slug: Slug, key: z.string().min(1), holds: z.array(z.string().min(2).max(60)).max(4).optional() }),
+  job: true,
+  async run({ slug, key, holds }, ctx) {
+    const prepare = prepareFix(ctx, slug, key, (f) => {
+      if (holds) f.holds = holds;
+    });
+    return ctx.jobs.start(slug, ['rig', slug, key], `cut out ${key} with what they hold`, ctx.by, prepare);
+  },
+});
+
+defineAction({
+  name: 'cast_animate',
+  description: 'Give a character a 3D model now, also one the build skips (an NPC with no lines, a creature or an animated object): '
+    + 'Muse paints it from 4 sides, TRELLIS builds the model (HF, only where the HF token works). A creature (not upright, cast_status body) gets no skeleton: '
+    + 'in the game it hops, squashes as it lands, leans, breathes and blinks as one body. Kept across rebuilds (the model step builds it every time). For a walking or speaking person, the same job also builds sprites and chooses 16-frame UV automatically when supported. Runs as a job.',
+  input: z.object({ slug: Slug, key: z.string().min(1) }),
+  job: true,
+  async run({ slug, key }, ctx) {
+    const prepare = prepareFix(ctx, slug, key, (f) => void (f.animate = true));
+    const pending = pendingModel(ctx, slug, key);
+    if (pending) return pending;
+    return ctx.jobs.start(slug, ['model', slug, key, '--sprites'], `animate ${key}`, ctx.by, prepare);
+  },
+});
+
+defineAction({
+  name: 'cast_relax',
+  description: 'Put 3D figures into a calm rest pose with the local Blender (no calls, free): arms down by the sides and feet under the hips, '
+    + 'then their UV sprites are drawn again. Use it when the person says characters walk straddle-legged, with arms out to the sides, like zombies, '
+    + 'or hands stick out. Needs Blender (blender_get). Without key, every character with a 3D model. Then play_reload. Runs as a job.',
+  input: z.object({ slug: Slug, key: z.string().min(1).optional() }),
+  job: true,
+  async run({ slug, key }, ctx) {
+    return ctx.jobs.start(slug, ['model', slug, ...(key ? [key] : []), '--relax'], key ? `relax ${key}` : 'relax the cast', ctx.by);
+  },
+});
+
+defineAction({
+  name: 'cast_rewalk',
+  description: 'Make a character\'s 2D walk again from its painting (no Muse calls): the painting bent by its bones as one piece, so an apron, a coat '
+    + 'or a skirt stretches with the legs and never tears, and what they hold (a lantern, a net) stays on. Use it when the person says a walk tears, '
+    + 'a leg or arm comes off, or the figure has holes; then play_reload. Without key, every character. Runs as a job.',
+  input: z.object({ slug: Slug, key: z.string().min(1).optional() }),
+  job: true,
+  async run({ slug, key }, ctx) {
+    return ctx.jobs.start(slug, ['rig', slug, ...(key ? [key] : [])], key ? `walk ${key}` : 'walk the cast', ctx.by);
+  },
+});
+
+defineAction({
+  name: 'sprites_redo',
+  description: 'Paint a character\'s walk and talk sprite sheets again over their 3D model (new Muse takes, the picture of the character stays): '
+    + 'for cast_status spriteIssues (walk frames that left the pose) or when the person says the walk looks wrong in one direction. '
+    + 'Up to 5 takes per facing, the one that keeps the pose wins; kept across rebuilds. About 2-10 Muse Image calls per facing. Runs as a job; then play_reload.',
+  input: z.object({ slug: Slug, key: z.string().min(1) }),
+  job: true,
+  async run({ slug, key }, ctx) {
+    const files = new WorldFiles(slug, ctx.root);
+    if (!fs.existsSync(files.path('cast', key, 'model', 'model.json')) || modelProblem(files.path('cast', key, 'model'))) {
+      throw new ActionError(409, `${key} has no usable 3D model, so no sheets to paint: cast_animate makes one first`);
+    }
+    const prepare = prepareFix(ctx, slug, key, (f) => void (f.spriteTake = (f.spriteTake ?? 0) + 1));
+    return ctx.jobs.start(slug, ['sprites', slug, key, '--tries', '3'], `sheets ${key}`, ctx.by, prepare);
+  },
+});
+
+defineAction({
+  name: 'voice_list',
+  reads: true,
+  description: 'The stock ElevenLabs voices a character can be given: id, name and what they sound like. With slug and key, '
+    + 'the voices that fit that character (gender and age Spark saw in their figure) come first, marked fits. The first entry, id "design", is a voice ElevenLabs Voice Design makes from a description: '
+    + 'children, teens and the old always get one, since no stock voice is a child or truly old.',
+  input: z.object({ slug: Slug.optional(), key: z.string().min(1).optional() }),
+  async run({ slug, key }, ctx) {
+    let stock;
+    try {
+      stock = await stockVoices();
+    } catch (error) {
+      throw new ActionError(503, `no voices: ${error instanceof Error ? error.message : error}`);
+    }
+    const files = slug ? new WorldFiles(slug, ctx.root) : undefined;
+    const voices = files && fs.existsSync(files.path('voices.json')) ? Voices.safeParse(files.readJson(files.path('voices.json'))) : null;
+    const profile = key && voices?.success ? voices.data.cast[key]?.profile : undefined;
+    const fit = new Set(profile ? voiceCandidates(stock, profile).map((v) => v.voice_id) : []);
+    const list = stock.map((v) => ({ id: v.voice_id, name: v.name, sounds: [...Object.values(v.labels ?? {}), v.description].filter(Boolean).join(', '), ...(profile && { fits: fit.has(v.voice_id) && !needsDesign(profile) }) }));
+    const now = key && voices?.success ? voices.data.cast[key]?.design?.description : undefined;
+    list.unshift({ id: DESIGNED, name: 'Designed for this character', sounds: now ?? (profile ? designDescriptions(profile)[0] : 'made from a description'), ...(profile && { fits: true }) });
+    return profile ? { character: { key, ...profile }, voices: [...list.filter((v) => v.fits), ...list.filter((v) => !v.fits)] } : list;
+  },
+});
+
+defineAction({
+  name: 'voice_set',
+  description: 'Give a character another voice (an id from voice_list), optionally steadier (stability up) or more expressive (style up). '
+    + 'voice "design" with design (English, how they sound: "a very old man, gravelly, slow") makes a new voice with ElevenLabs Voice Design; never name a child or an age in years there, ElevenLabs refuses it nor "girl" or "boy" ("youthful high-pitched male character voice for an animated game" works). '
+    + 'Kept across rebuilds; speaks the lines again (only that character\'s lines cost anything). Runs as a job.',
+  input: z.object({ slug: Slug, key: z.string().min(1), voice: z.string().min(1), design: z.string().min(10).optional(), stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional() }),
+  job: true,
+  async run({ slug, key, voice, design, stability, style }, ctx) {
+    if (design && voice !== DESIGNED) throw new ActionError(400, `design goes with voice "${DESIGNED}"`);
+    const prepare = prepareFix(ctx, slug, key, (f) => void (f.voice = { voice, why: 'chosen by the person', ...(design && { design }), ...(stability !== undefined && { stability }), ...(style !== undefined && { style }) }));
+    return ctx.jobs.start(slug, ['voices', slug], `voice ${key}`, ctx.by, prepare);
+  },
+});

package/app/src/actions/depth.ts

@@ -0,0 +1,95 @@
+// Depth: how a place moves as a diorama (the backdrop step's parallax layers, flowing water and drifting painted fog).
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { Depth } from '../scene/layers.ts';
+import { parseCell } from '../scene/locate.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { Slug } from '../world/schema.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+defineAction({
+  name: 'water_flow',
+  description: 'Set which way the water of a place flows, when the person says it runs the wrong way or should not flow: '
+    + 'reverse (the other way round), still (a pond, a harbour basin), or auto (as Spark reads the picture), with an optional hint in words '
+    + '("downstream is toward the bridge"). Kept in places/<place>/depth.json across rebuilds; reruns the backdrop step of that place as a job.',
+  input: z.object({
+    slug: Slug,
+    place: z.string().min(1),
+    flow: z.enum(['auto', 'reverse', 'still']),
+    hint: z.string().min(3).optional().describe('Where the water runs, in words, for Spark to follow.'),
+  }),
+  job: true,
+  async run({ slug, place, flow, 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, 'depth.json');
+    return ctx.jobs.start(slug, ['backdrop', slug, place], `water ${place}: ${flow}`, ctx.by, () => {
+      const was = fs.existsSync(file) ? Depth.parse(JSON.parse(fs.readFileSync(file, 'utf8'))) : Depth.parse({});
+      const depth: Depth = { ...was, flow, ...(hint !== undefined && { flowHint: hint }) };
+      fs.writeFileSync(file, `${JSON.stringify(depth, null, 2)}\n`);
+    });
+  },
+});
+
+const Cell = z.string().refine((c) => !!parseCell(c), 'a grid cell like C12: a letter per 60 px column from A, a number per 60 px row from 1');
+
+defineAction({
+  name: 'water_area',
+  description: 'Say which 60 px grid cells are water that should move (add) or are not water (remove), when the person says only part of '
+    + 'a river, lake or sea moves, or something that is not water ripples. Cells are named like C12 (column letter from A at the left, '
+    + 'row number from 1 at the top, as on the grid of place_view). An added cell flows along the edge SAM sees there, or whole. '
+    + 'Kept in places/<place>/depth.json across rebuilds; reruns the backdrop step of that place as a job.',
+  input: z.object({ slug: Slug, place: z.string().min(1), add: z.array(Cell).optional(), remove: z.array(Cell).optional() }),
+  job: true,
+  async run({ slug, place, add, remove }, ctx) {
+    if (!add?.length && !remove?.length) throw new ActionError(400, 'give cells to add or remove');
+    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, 'depth.json');
+    const up = (cells?: string[]) => (cells ?? []).map((c) => c.trim().toUpperCase());
+    return ctx.jobs.start(slug, ['backdrop', slug, place], `water area ${place}`, ctx.by, () => {
+      const was = fs.existsSync(file) ? Depth.parse(JSON.parse(fs.readFileSync(file, 'utf8'))) : Depth.parse({});
+      const depth: Depth = {
+        ...was,
+        waterAdd: [...new Set([...was.waterAdd.filter((c) => !up(remove).includes(c)), ...up(add)])],
+        waterRemove: [...new Set([...was.waterRemove.filter((c) => !up(add).includes(c)), ...up(remove)])],
+      };
+      fs.writeFileSync(file, `${JSON.stringify(depth, null, 2)}\n`);
+    });
+  },
+});
+
+defineAction({
+  name: 'fog_drift',
+  description: 'Set how the fog or mist painted into a place drifts (the backdrop step cuts it with SAM and the page slides it), '
+    + 'when the person says the fog stands still, drifts the wrong way, or too fast or slow: auto (with the wind), left, right, '
+    + 'or still (stays as painted), and speed 0.25..3 (1 by default). Kept in places/<place>/depth.json across rebuilds; reruns the backdrop step of that place as a job. '
+    + 'For extra mist that is not in the picture, use weather_set fog.',
+  input: z.object({
+    slug: Slug,
+    place: z.string().min(1),
+    drift: z.enum(['auto', 'left', 'right', 'still']),
+    speed: z.number().min(0.25).max(3).optional().describe('How fast it drifts: 0.5 slow, 1 as by default, 2 rolling.'),
+  }),
+  job: true,
+  async run({ slug, place, drift, speed }, 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, 'depth.json');
+    return ctx.jobs.start(slug, ['backdrop', slug, place], `fog ${place}: ${drift}${speed !== undefined ? ` x${speed}` : ''}`, ctx.by, () => {
+      const was = fs.existsSync(file) ? Depth.parse(JSON.parse(fs.readFileSync(file, 'utf8'))) : Depth.parse({});
+      const depth: Depth = { ...was, fog: drift, ...(speed !== undefined && { fogSpeed: speed }) };
+      fs.writeFileSync(file, `${JSON.stringify(depth, null, 2)}\n`);
+    });
+  },
+});

package/app/src/actions/extend.ts

@@ -0,0 +1,36 @@
+// Add new workshop drawings to a built world without redesigning its existing places or script.
+import fs from 'node:fs';
+import { z } from 'zod';
+import { readDrawn } from '../world/drawings.ts';
+import { WorldFiles } from '../world/files.ts';
+import { Slug, World } from '../world/schema.ts';
+import { agentBlocked } from '../studio/locks.ts';
+import { ActionError, defineAction } from './registry.ts';
+
+export const DrawingFile = z.string().regex(/^drawings\/[a-z0-9-]+\.png$/);
+defineAction({
+  name: 'world_extend',
+  description: 'Extend an existing playable world with drawings already saved by kids_add. files are the drawings/ paths from kids_status, wish is what the person wants. Keeps existing places and story; rebuilds the connecting place and new places, creates new characters and story, and checks playability. Builds in a private copy and installs only on success. Runs as a job; wait with job_wait, inspect the result and reload play only if it succeeds. Costs model calls; the connecting place is repainted. History can undo the job. A drawing already represented by an existing key cannot be added again.',
+  input: z.object({ slug: Slug, files: z.array(DrawingFile).min(1).max(8), wish: z.string().trim().min(5).max(2000) }),
+  job: true,
+  async run({ slug, files: selected, wish }, ctx) {
+    const files = new WorldFiles(slug, ctx.root);
+    if (!fs.existsSync(files.path('world.json')) || !fs.existsSync(files.path('story.json'))) throw new ActionError(404, 'build the world and story before extending it');
+    const blocked = agentBlocked(files.dir, ctx.by);
+    if (blocked) throw new ActionError(423, blocked);
+    const busy = ctx.jobs.busy(slug);
+    if (busy) throw new ActionError(409, `${busy.label} is ${busy.state}; wait before extending`);
+    if (new Set(selected).size !== selected.length) throw new ActionError(400, 'each drawing may be selected only once');
+    const drawn = readDrawn(files);
+    const world = World.parse(files.readJson(files.path('world.json')));
+    const known = new Set([world.hero.key, ...world.places.flatMap(p => [p.key, ...p.things.map(t => t.key)])]);
+    for (const file of selected) {
+      const d = drawn.find(x => `drawings/${x.file}` === file);
+      if (!d || !fs.existsSync(files.path(file))) throw new ActionError(404, `${file} is not a saved, read drawing; use kids_add first`);
+      if (d.kind === 'hero' || d.kind === 'player') throw new ActionError(400, `${file} is marked ${d.kind}; choose npc, place, item or prop with kids_kind before extending`);
+      if (known.has(d.key)) throw new ActionError(409, `${file} refers to ${d.key}, already in the world; it cannot be added again`);
+    }
+    if (new Set(selected.map(f => drawn.find(d => `drawings/${d.file}` === f)!.key)).size !== selected.length) throw new ActionError(400, 'selected drawings share a key; resolve their identity first');
+    return ctx.jobs.start(slug, ['extend', slug, JSON.stringify(selected), wish], 'extend world from drawings', ctx.by);
+  },
+});