@gtanczyk/diorama 0.0.0-stage → 0.1.0

package/app/src/world/drawings.ts

@@ -0,0 +1,198 @@
+// Children's drawings as the world: photos of drawings on paper, each read by Spark into the hero, an NPC,
+// an item, a prop or a place, kept with the world (drawings/) and used by world, paint, cast and icons.
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { z } from 'zod';
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import type { WorldFiles } from './files.ts';
+import { Slug, type Place, type World } from './schema.ts';
+
+export const PICTURE = /\.(png|jpe?g|webp|heic|heif|gif|tiff?)$/i;
+
+export const Drawn = z.object({
+  file: z.string(),
+  /** player: another hero, for another gamepad (only the grown-up marks one, kinds.json); it walks beside the hero, in no place. */
+  kind: z.enum(['hero', 'npc', 'player', 'item', 'prop', 'place']),
+  key: Slug,
+  looks: z.string().min(3),
+});
+export type Drawn = z.infer<typeof Drawn>;
+
+/** Upright, paper evened out, at most 1600 px on the long side: what Spark and Muse get. */
+export function normaliseDrawing(photo: Buffer): Promise<Buffer> {
+  return sharp(photo).rotate().resize(1600, 1600, { fit: 'inside', withoutEnlargement: true }).normalise().png().toBuffer();
+}
+
+/** The drawings kept with a world, in name order (drawings/*.png). */
+export function drawingFiles(files: WorldFiles): string[] {
+  const dir = files.path('drawings');
+  return fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.png')).sort() : [];
+}
+
+/** A file's name as kept: lowercase kebab, short. */
+export const keptName = (file: string) => path.basename(file).replace(/\.[^.]+$/, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 24) || 'x';
+
+/** Copies photos of drawings from a folder into the world, normalised, numbered after the ones already there. */
+export async function keepDrawings(files: WorldFiles, from: string): Promise<string[]> {
+  const sources = fs.statSync(from).isDirectory()
+    ? fs.readdirSync(from).filter((f) => PICTURE.test(f)).sort().map((f) => path.join(from, f))
+    : [from];
+  const kept: string[] = [];
+  for (const source of sources) {
+    const stem = keptName(source);
+    // Building again with the same folder keeps each drawing once.
+    if (drawingFiles(files).some((f) => f.slice(3) === `${stem}.png`)) continue;
+    const name = `${String(drawingFiles(files).length + 1).padStart(2, '0')}-${stem}.png`;
+    files.write(files.path('drawings', name), await normaliseDrawing(fs.readFileSync(source)));
+    kept.push(name);
+  }
+  return kept;
+}
+
+/** What each drawing was made into, from drawings.json; empty for a world without drawings. */
+export function readDrawn(files: WorldFiles): Drawn[] {
+  const file = files.path('drawings.json');
+  if (!fs.existsSync(file)) return [];
+  const parsed = z.array(Drawn).safeParse(JSON.parse(fs.readFileSync(file, 'utf8')));
+  return parsed.success ? parsed.data : [];
+}
+
+/** The drawing a character, item or place was made from, if a child drew it. */
+export function drawingFor(files: WorldFiles, key: string): Buffer | undefined {
+  const drawn = readDrawn(files).find((d) => d.key === key);
+  return drawn && fs.existsSync(files.path('drawings', drawn.file)) ? fs.readFileSync(files.path('drawings', drawn.file)) : undefined;
+}
+
+export const Kind = Drawn.shape.kind;
+export type Kind = z.infer<typeof Kind>;
+
+/** What the grown-up said a drawing is (drawings/kinds.json, by file), over what Spark sees. */
+export function readKinds(files: WorldFiles): Record<string, Kind> {
+  const file = files.path('drawings', 'kinds.json');
+  const parsed = z.record(z.string(), Kind).safeParse(fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, 'utf8')) : {});
+  return parsed.success ? parsed.data : {};
+}
+
+/** A kids' world looks like this, so a character painted from a drawing before the world exists is the one the game uses. */
+export const KIDS_STYLE = "the children's own drawings come alive: wax crayon and felt-tip texture, solidly coloured, bold simple rounded shapes with thick dark outlines, bright clean colours, soft sunny light, friendly and readable at a glance";
+
+const KIND_TEXT = `- kind: "character" (someone: a person, an animal, a creature), "item" (a small thing to pick up and carry), "prop" (a big thing that stays in a place) or "place" (a whole scene: a landscape, a room, a house with its surroundings)
+- key: a kebab-case English name for it ("green-dragon", "blue-hat", "mushroom-forest")
+- looks: what the child drew, as a description a painter can follow: shape, every colour, clothes, face, what it holds. Describe the drawing kindly as the real thing it shows (a "green dragon with orange wings and a round light-green belly", not "scribbles"). For a character or a thing, only it, not the sun, sky or ground drawn around it. For a place: what it shows front to back.
+Ignore any name written on the paper, the paper itself and the table.`;
+
+/** Spark says what one drawing is, as soon as its photo arrives (no story needed yet). */
+export async function readDrawing(memo: Memo, image: Buffer, file: string, taken: string[] = []): Promise<Drawn> {
+  const prompt = `A child of 5 or 6 drew this picture for a 2D point-and-click adventure game the class is making together. Say what it is in the game:
+${KIND_TEXT}${taken.length ? `\nKeys already used by other drawings: ${taken.join(', ')}. Use one of them only when this drawing shows that same thing again.` : ''}
+
+Reply with JSON only: {"kind": "...", "key": "...", "looks": "..."}`;
+  let ask = prompt;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    const answer = await askSparkJson<{ kind?: string; key?: string; looks?: string }>(memo, { label: `drawing:${file}#${attempt}`, prompt: ask, images: [image], personal: true });
+    const parsed = Drawn.safeParse({ file, kind: answer?.kind === 'character' ? 'npc' : answer?.kind, key: answer?.key, looks: answer?.looks });
+    if (parsed.success) return parsed.data;
+    ask = `${prompt}\n\nYour last answer was:\n${JSON.stringify(answer)}\n\nFix: ${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`;
+  }
+  throw new Error(`Spark could not read the drawing ${file} in 3 tries`);
+}
+
+/** Every kept drawing read (each once, kept in drawings.json), with what the grown-up said over what Spark saw. */
+export async function readDrawings(memo: Memo, files: WorldFiles): Promise<Drawn[]> {
+  const names = drawingFiles(files);
+  const known = new Map(readDrawn(files).map((d) => [d.file, d]));
+  // All at once (Spark's lane cap paces them): a class's 25 drawings read one after another took 6 minutes.
+  // A drawing read now keeps its own key, so two children's princesses are two princesses; ones read before keep theirs.
+  const read = await Promise.all(names.map((file) => known.get(file) ?? readDrawing(memo, fs.readFileSync(files.path('drawings', file)), file)));
+  const drawn = ownKeys(read, new Set(names.filter((f) => known.has(f))));
+  const kinds = readKinds(files);
+  for (const d of drawn) if (kinds[d.file]) d.kind = kinds[d.file];
+  return oneHero(drawn, drawn.find((d) => kinds[d.file] === 'hero')?.key);
+}
+
+/** A new drawing whose key another drawing has gets a number ("princess-2"); drawings in `kept` keep their keys as they are. */
+export function ownKeys(drawn: Drawn[], kept = new Set<string>()): Drawn[] {
+  const taken = new Set(drawn.filter((d) => kept.has(d.file)).map((d) => d.key));
+  return drawn.map((d) => {
+    if (kept.has(d.file)) return d;
+    let key = d.key;
+    for (let n = 2; taken.has(key); n++) key = `${d.key}-${n}`;
+    taken.add(key);
+    return key === d.key ? d : { ...d, key };
+  });
+}
+
+/**
+ * At most `places` drawn places stay places, the first ones; a drawn place over that becomes a big prop inside one.
+ * Every drawn place was a place to paint, mask and check, so a class's 8 place drawings made an 8-place, 40-minute build.
+ */
+export function fitPlaces(drawn: Drawn[], places: number): Drawn[] {
+  let kept = 0;
+  return drawn.map((d) => {
+    if (d.kind !== 'place' || ++kept <= places) return d;
+    return { ...d, kind: 'prop', looks: `${d.looks} (a child drew it as a whole place; here it is one big thing in a place: a picture, a model, a view through a window)` };
+  });
+}
+
+/** Exactly one character leads: the one asked for, else the one already leading, else the first drawn. */
+export function oneHero(drawn: Drawn[], hero?: string): Drawn[] {
+  const characters = drawn.filter((d) => d.kind === 'hero' || d.kind === 'npc');
+  const lead = (hero && characters.find((d) => d.key === hero)) ?? characters.find((d) => d.kind === 'hero') ?? characters[0];
+  for (const d of characters) d.kind = lead && d.key === lead.key ? 'hero' : 'npc';
+  return drawn;
+}
+
+/**
+ * The other heroes, one per extra gamepad: characters a child drew and the grown-up marked "player". They are painted
+ * and rigged with the cast and walk beside the hero; they belong to no place and say nothing in the story.
+ */
+export function players(files: WorldFiles): Array<{ key: string; looks: string }> {
+  const world = files.world();
+  const taken = new Set([world.hero.key, ...world.places.flatMap((p) => p.things.map((t) => t.key))]);
+  return [...new Map(readDrawn(files).filter((d) => d.kind === 'player' && !taken.has(d.key)).map((d) => [d.key, { key: d.key, looks: d.looks }])).values()];
+}
+
+/** What the world designer is told: every drawing is in the world, under its key, as drawn. */
+export function drawingsBrief(drawn: Drawn[], style = KIDS_STYLE, chooseHero = false): string {
+  const once = [...new Map(drawn.map((d) => [d.key, d])).values()];
+  const line = (d: Drawn) => chooseHero && (d.kind === 'hero' || d.kind === 'npc')
+    ? `- a character, key "${d.key}": ${d.looks} (hero or npc according to the creator's idea and clarifications)` : ({
+    hero: `- the hero, key "${d.key}": ${d.looks}`,
+    npc: `- an npc in one of the places, key "${d.key}", role "npc": ${d.looks}`,
+    item: `- an item to pick up in one of the places, key "${d.key}", role "item": ${d.looks}`,
+    prop: `- a prop in one of the places, key "${d.key}", role "prop": ${d.looks}`,
+    place: `- a place, key "${d.key}": ${d.looks}`,
+    player: '',
+  })[d.kind];
+  return `The children drew these, and every one of them must be in the world, under exactly this key, looking as drawn:
+${once.filter((d) => d.kind !== 'player').map(line).join('\n')}
+${chooseHero ? 'Choose exactly one of these drawn characters as the hero according to the creator\'s idea and answers; the other characters are NPCs. Do not choose the first drawing just because it came first.' : ''}
+The style is exactly: "${style}".`;
+}
+
+/** What the designed world left out of the drawings, said so Spark can put it back. */
+export function drawnIssues(world: World, drawn: Drawn[]): string[] {
+  const things = new Map(world.places.flatMap((p) => p.things.map((t) => [t.key, t.role] as const)));
+  const places = new Set(world.places.map((p) => p.key));
+  return [...new Map(drawn.map((d) => [d.key, d])).values()].flatMap((d) => {
+    if (d.kind === 'hero') return world.hero.key === d.key ? [] : [`the hero's key must be "${d.key}" (a child drew the hero)`];
+    if (d.kind === 'player') return [];
+    if (d.kind === 'place') return places.has(d.key) ? [] : [`a child drew the place "${d.key}": it must be one of the places, with that key`];
+    const role = things.get(d.key);
+    if (!role) return [`a child drew "${d.key}": it must be a thing with role "${d.kind}" in one of the places`];
+    // A drawn house or cave may well be the way into the next place.
+    if (role === d.kind || (d.kind === 'prop' && role === 'exit')) return [];
+    return [`"${d.key}" was drawn as ${d.kind === 'item' ? 'an item' : `a ${d.kind}`}: its role must be "${d.kind}"`];
+  });
+}
+
+/** The drawings a place's painting follows: the place itself first, then what was drawn of the props and items in it (three at most). */
+export function drawingsIn(files: WorldFiles, place: Place): Array<{ key: string; image: Buffer }> {
+  const keys = [place.key, ...place.things.filter((t) => t.role !== 'npc').map((t) => t.key)];
+  return keys.flatMap((key) => {
+    const image = drawingFor(files, key);
+    return image ? [{ key, image }] : [];
+  }).slice(0, 3);
+}

package/app/src/world/extend-stage.ts

@@ -0,0 +1,109 @@
+// Build an extension in a private copy. A failed/cancelled job cannot leave half a game installed.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { emit } from '../registry.ts';
+
+function files(dir: string, rel = ''): Map<string, string> {
+  const out = new Map<string, string>();
+  if (!fs.existsSync(path.join(dir, rel))) return out;
+  for (const entry of fs.readdirSync(path.join(dir, rel), { withFileTypes: true })) {
+    if (!rel && (entry.name === 'studio' || entry.name === 'memo')) continue;
+    const name = rel ? `${rel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) for (const [key, value] of files(dir, name)) out.set(key, value);
+    else if (entry.isFile()) out.set(name, createHash('sha256').update(fs.readFileSync(path.join(dir, name))).digest('hex'));
+  }
+  return out;
+}
+
+function retainMemo(staged: string, original: string, callBytes: number) {
+  const copy = (from: string, to: string) => {
+    if (!fs.existsSync(from)) return;
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+      if (entry.name === 'calls.jsonl') continue;
+      const src = path.join(from, entry.name), dest = path.join(to, entry.name);
+      if (entry.isDirectory()) copy(src, dest);
+      else if (entry.isFile() && !fs.existsSync(dest)) fs.copyFileSync(src, dest);
+    }
+  };
+  copy(path.join(staged, 'memo'), path.join(original, 'memo'));
+  const calls = path.join(staged, 'memo', 'calls.jsonl');
+  if (fs.existsSync(calls)) {
+    const log = fs.readFileSync(calls).subarray(callBytes);
+    if (log.length) fs.appendFileSync(path.join(original, 'memo', 'calls.jsonl'), log);
+  }
+}
+
+/** The callback runs in an isolated project cwd; commit checks for concurrent edits before changing anything. */
+export async function stagedExtension<T>(slug: string, run: () => Promise<T>): Promise<T> {
+  const cwd = process.cwd();
+  const original = path.join(cwd, 'worlds', slug);
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'diorama-extend-'));
+  const staged = path.join(temp, 'worlds', slug);
+  let callBytes: number | undefined;
+  try {
+    fs.mkdirSync(path.dirname(staged), { recursive: true });
+    fs.cpSync(original, staged, { recursive: true, mode: fs.constants.COPYFILE_FICLONE, filter: source => source !== path.join(original, 'studio') });
+    const before = files(staged);
+    const calls = path.join(staged, 'memo', 'calls.jsonl');
+    callBytes = fs.existsSync(calls) ? fs.statSync(calls).size : 0;
+    process.chdir(temp);
+    const stagedFlag = process.env.DIORAMA_STAGED_BUILD;
+    process.env.DIORAMA_STAGED_BUILD = '1';
+    let result: T;
+    try { result = await run(); } finally {
+      process.chdir(cwd);
+      if (stagedFlag === undefined) delete process.env.DIORAMA_STAGED_BUILD;
+      else process.env.DIORAMA_STAGED_BUILD = stagedFlag;
+    }
+    const after = files(staged);
+    const changed = [...new Set([...before.keys(), ...after.keys()])].filter(key => before.get(key) !== after.get(key));
+    const current = files(original);
+    // Any source change can invalidate the staged build, even if that source file itself was not rewritten.
+    const conflicts = [...new Set([...before.keys(), ...current.keys()])].filter(key => current.get(key) !== before.get(key));
+    if (conflicts.length) throw new Error(`world changed during extension (${conflicts.slice(0, 5).join(', ')}); nothing was installed, try again`);
+    emit('extension.progress', { phase: 'install' });
+    // Place the world and script last, after their new visual assets.
+    changed.sort((a, b) => Number(a === 'world.json' || a === 'story.json') - Number(b === 'world.json' || b === 'story.json'));
+    const backup = path.join(temp, 'backup');
+    for (const key of changed) if (before.has(key)) {
+      const target = path.join(backup, key);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(path.join(original, key), target, fs.constants.COPYFILE_FICLONE);
+    }
+    const installed: string[] = [];
+    try {
+      for (const key of changed) {
+        const target = path.join(original, key);
+        if (!after.has(key)) fs.rmSync(target, { force: true });
+        else {
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          const temporary = `${target}.extend-tmp`;
+          try {
+            fs.copyFileSync(path.join(staged, key), temporary, fs.constants.COPYFILE_FICLONE);
+            fs.renameSync(temporary, target);
+          } finally { fs.rmSync(temporary, { force: true }); }
+        }
+        installed.push(key);
+      }
+    } catch (error) {
+      for (const key of installed.reverse()) {
+        const target = path.join(original, key);
+        if (before.has(key)) fs.copyFileSync(path.join(backup, key), target);
+        else fs.rmSync(target, { force: true });
+      }
+      throw error;
+    }
+    return result;
+  } finally {
+    process.chdir(cwd);
+    // Even a failed generation consumed calls; retain the immutable cache and its accounting.
+    if (callBytes !== undefined) {
+      try { retainMemo(staged, original, callBytes); }
+      catch (error) { console.error(`could not retain extension memo: ${error instanceof Error ? error.message : error}`); }
+    }
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}

package/app/src/world/extend.ts

@@ -0,0 +1,123 @@
+// Incremental world design. Spark proposes additions; the existing world and story are never model output.
+import { z } from 'zod';
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import { checkStory, questionIssues, type StoryReport } from '../story/check.ts';
+import { Story } from '../story/schema.ts';
+import { NPC_STORY_GUIDANCE } from '../story/npc-guidance.ts';
+import { drawnIssues, type Drawn } from './drawings.ts';
+import { checkWorld, Place, Slug, Thing, type World } from './schema.ts';
+
+const Additions = z.object({
+  anchor: Slug,
+  things: z.array(Thing).min(1),
+  exits: z.array(z.object({ to: Slug, via: Slug })).default([]),
+  places: z.array(Place).default([]),
+  names: z.record(z.string(), z.string().min(1).max(40)).default({}),
+});
+export type Additions = z.infer<typeof Additions>;
+
+/** Merge only additions; the model cannot rewrite a place, hero or prior exit. */
+export function mergeWorld(world: World, raw: unknown, drawings: Drawn[]): { world?: World; issues: string[]; changed: string[] } {
+  const parsed = Additions.safeParse(raw);
+  if (!parsed.success) return { issues: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`), changed: [] };
+  const a = parsed.data;
+  const anchor = world.places.find(p => p.key === a.anchor);
+  if (!anchor) return { issues: [`unknown anchor ${a.anchor}`], changed: [] };
+  const existingPlaces = new Set(world.places.map(p => p.key));
+  const existingThings = new Set([world.hero.key, ...world.places.flatMap(p => p.things.map(t => t.key))]);
+  const issues: string[] = [];
+  const allNew = [...a.things, ...a.places.flatMap(p => p.things)];
+  if (a.places.some(p => existingPlaces.has(p.key))) issues.push('new place keys must not reuse existing places');
+  if (allNew.some(t => existingThings.has(t.key))) issues.push('new thing keys must not reuse existing things or the hero');
+  if (new Set(allNew.map(t => t.key)).size !== allNew.length) issues.push('new thing keys must be unique across places');
+  if (a.exits.some(e => !a.things.some(t => t.key === e.via && t.role === 'exit'))) issues.push('each new anchor exit must use a newly added exit thing');
+  if (a.exits.some(e => existingPlaces.has(e.to))) issues.push('new anchor exits must lead to new places');
+  if (a.places.length && !a.exits.length) issues.push('connect new places to the anchor');
+  for (const key of Object.keys(a.names)) if (existingThings.has(key) || existingPlaces.has(key) || world.names?.[key] !== undefined) issues.push(`cannot replace the existing name ${key}`);
+  const candidate = { ...world, places: world.places.map(p => p.key === a.anchor ? { ...p, things: [...p.things, ...a.things], exits: [...p.exits, ...a.exits] } : p).concat(a.places), names: { ...world.names, ...a.names } };
+  const checked = checkWorld(candidate);
+  issues.push(...checked.issues);
+  if (checked.world) issues.push(...drawnIssues(checked.world, drawings));
+  return { ...(checked.world && !issues.length ? { world: checked.world } : {}), issues, changed: [a.anchor, ...a.places.map(p => p.key)] };
+}
+
+const StoryAddition = Story.omit({ intro: true }).extend({ endings: z.array(Story.shape.endings.element).default([]) });
+export type StoryAddition = z.infer<typeof StoryAddition>;
+
+/** Existing script keeps its order, including conditional interactions and changes/plate indices. */
+export function mergeStory(world: World, old: Story, raw: unknown, changed: string[], oldWorld: World): { story?: Story; issues: string[]; report?: StoryReport } {
+  const parsed = StoryAddition.safeParse(raw);
+  if (!parsed.success) return { issues: parsed.error.issues.map(i => `${i.path.join('.')}: ${i.message}`) };
+  const a = parsed.data;
+  const oldKeys = new Set(oldWorld.places.flatMap(p => p.things.map(t => `${p.key}/${t.key}`)));
+  const newThings = world.places.filter(p => changed.includes(p.key)).flatMap(p => p.things.filter(t => !oldKeys.has(`${p.key}/${t.key}`)).map(t => ({ ...t, place: p.key })));
+  const issues: string[] = [];
+  if (a.interactions.some(i => oldKeys.has(`${i.place}/${i.thing}`)) || a.dialogues.some(d => oldKeys.has(`${d.place}/${d.npc}`)) || a.changes.some(c => oldKeys.has(`${c.place}/${c.thing}`)) || a.locks.some(l => oldKeys.has(`${l.place}/${l.via}`))) issues.push('add story only for new things; existing script must remain unchanged');
+  for (const t of newThings) {
+    if (!a.interactions.some(i => i.place === t.place && i.thing === t.key && i.verb === 'look')) issues.push(`${t.place}/${t.key} needs a look interaction`);
+    if (t.role === 'npc' && !a.dialogues.some(d => d.place === t.place && d.npc === t.key && d.lines.some(l => l.choices.length))) issues.push(`${t.place}/${t.key} needs a dialogue with choices`);
+    if (t.role === 'item' && (!a.items.some(i => i.key === t.key) || !a.interactions.some(i => i.place === t.place && i.thing === t.key && i.verb === 'take' && i.once && i.do.some(e => 'give' in e && e.give === t.key)))) issues.push(`${t.place}/${t.key} needs an item and a one-time take interaction`);
+  }
+  for (const field of ['items', 'endings'] as const) {
+    const keys = [...old[field], ...a[field]].map(x => x.key);
+    if (new Set(keys).size !== keys.length) issues.push(`${field} keys repeat`);
+  }
+  // New puzzles must not consume the old story's inventory or set/clear its flags.
+  const oldItems = new Set(old.items.map(i => i.key));
+  const oldFlags = new Set<string>();
+  const scan = (value: unknown) => {
+    if (typeof value === 'string' && /^!?[a-z][a-z0-9-]*$/.test(value)) oldFlags.add(value.replace(/^!/, ''));
+    else if (Array.isArray(value)) value.forEach(scan);
+    else if (value && typeof value === 'object') Object.values(value).forEach(scan);
+  };
+  for (const i of old.interactions) { scan(i.when); for (const e of i.do) if ('set' in e || 'clear' in e) scan('set' in e ? e.set : e.clear); }
+  for (const l of old.locks) scan(l.until);
+  for (const c of old.changes) scan(c.when);
+  for (const p of old.patrols ?? []) scan(p.when);
+  for (const d of old.dialogues) { scan(d.when); for (const l of d.lines) for (const c of l.choices) { scan(c.when); for (const e of c.do) if ('set' in e || 'clear' in e) scan('set' in e ? e.set : e.clear); } }
+  const effects = [...a.interactions.flatMap(i => i.do), ...a.dialogues.flatMap(d => d.lines.flatMap(l => l.choices.flatMap(c => c.do)))];
+  const oldNpcs = new Set(oldWorld.places.flatMap(p => p.things.filter(t => t.role === 'npc').map(t => t.key)));
+  if (effects.some(e => 'moveNpc' in e && oldNpcs.has(e.moveNpc.npc)) || a.patrols?.some(p => oldNpcs.has(p.npc))) issues.push('new motion must not change existing NPCs');
+  if (effects.some(e => ('set' in e && oldFlags.has(e.set)) || ('clear' in e && oldFlags.has(e.clear)) || ('take' in e && oldItems.has(e.take)) || ('give' in e && oldItems.has(e.give)))) issues.push('new effects must not change old flags or inventory items');
+  if (!a.dialogues.length && !a.interactions.some(i => i.verb !== 'look' && i.do.length)) issues.push('add a conversation or an interactive activity, not only look lines');
+  issues.push(...questionIssues(Story.parse({ intro: old.intro, ...a, endings: a.endings.length ? a.endings : old.endings })));
+  const story = Story.parse({ intro: old.intro, items: [...old.items, ...a.items], locks: [...old.locks, ...a.locks], interactions: [...old.interactions, ...a.interactions], dialogues: [...old.dialogues, ...a.dialogues], changes: [...old.changes, ...a.changes],
+    ...((old.patrols || a.patrols) && { patrols: [...(old.patrols ?? []), ...(a.patrols ?? [])] }), endings: [...old.endings, ...a.endings] });
+  const report = checkStory(world, story);
+  issues.push(...report.issues);
+  const oldPlaceKeys = new Set(oldWorld.places.map(p => p.key));
+  const newPlaces = world.places.filter(p => !oldPlaceKeys.has(p.key));
+  const newEndings = new Set(a.endings.map(e => e.key));
+  for (const place of newPlaces) {
+    const incoming = world.places.flatMap(p => p.exits.filter(e => e.to === place.key).map(e => e.via));
+    const endsHere = new Set([
+      ...a.interactions.filter(i => i.place === place.key).flatMap(i => i.do),
+      ...a.dialogues.filter(d => d.place === place.key).flatMap(d => d.lines.flatMap(l => l.choices.flatMap(c => c.do))),
+    ].flatMap(e => 'ending' in e ? [e.ending] : []));
+    if (!report.routes.some(r => newEndings.has(r.ending) && endsHere.has(r.ending) && r.actions.some(a => a.kind === 'go' && incoming.includes(a.via)))) issues.push(`a new ending must be reached by an activity in ${place.key}`);
+  }
+  return { ...(!issues.length ? { story } : {}), issues, report };
+}
+
+export async function designExtension(memo: Memo, oldWorld: World, oldStory: Story, drawings: Drawn[], wish: string): Promise<{ world: World; story: Story; changed: string[]; report: StoryReport }> {
+  const base = `Extend this existing point-and-click world from the new drawings and the person's wish. Do not rewrite existing places, people, exits, or script. Add a new place for each drawing whose kind is place, and include each new drawing under exactly its key and role. Add characters shown in scenes as NPCs where appropriate. Existing places have at most 10 things and the whole world at most 8 places. Connect each new place both ways with visible exit things. Use one existing anchor, adding visible things to it; its painting will be rebuilt. Keep descriptions in English, names in ${oldWorld.language ?? 'English'}. Wish: ${wish}\nDrawings: ${JSON.stringify(drawings)}\nExisting world: ${JSON.stringify(oldWorld)}\nReturn JSON only: {"anchor":"existing-place-key","things":[{"key":"new-key","role":"exit|npc|item|prop","looks":"..."}],"exits":[{"via":"new-exit-key","to":"new-place-key"}],"places":[{"key":"...","shows":"...","mood":"...","things":[...],"exits":[...]}],"names":{"new-key":"name"}}. No reused thing keys. For character/item-only drawings, add them to the anchor; places may be empty.`;
+  let prompt = base;
+  let world: World | undefined; let changed: string[] = [];
+  for (let i = 1; i <= 4; i++) {
+    const answer = await askSparkJson(memo, { label: `extend-world#${i}`, prompt });
+    const result = mergeWorld(oldWorld, answer, drawings);
+    if (result.world) { world = result.world; changed = result.changed; break; }
+    prompt = `${base}\nPrevious answer: ${JSON.stringify(answer)}\nFix: ${result.issues.join('; ')}`;
+  }
+  if (!world) throw new Error('Could not design a valid extension in 4 tries; the existing world was not changed');
+  const scriptBase = `Write ONLY additions to this point-and-click story. Preserve every existing line, ending and puzzle: do not repeat or edit them. Add look interactions for every new thing, take for new items (give their key, once true), dialogue with choices for new NPCs, and a small engaging activity involving the new material. Add a new ending reachable through each new place, triggered by an activity there. New interactions, dialogues, changes and locks may address only new things. Do not set or clear existing flags, or give or take existing items. Exit things may only have look interactions; they already move the player. Every ending must remain reachable from every non-ending state. A line with no choices must not ask a question.\n${NPC_STORY_GUIDANCE}\nExtension scope: apply these stages and optional motion only to newly added NPCs. Preserve existing NPC flags, patrol order, locations and script. Use fresh NPC-prefixed flags, including flags used only in negative conditions; new effects must not move old NPCs. Dialogue and interactions for a newly added travelling NPC may refer to its destination even though it is declared only at its original place. Use short friendly lines in ${world.language ?? 'English'}.\nWish: ${wish}\nDrawings: ${JSON.stringify(drawings)}\nExisting world: ${JSON.stringify(oldWorld)}\nExtended world: ${JSON.stringify(world)}\nExisting story: ${JSON.stringify(oldStory)}\nReturn JSON with arrays items, locks, interactions, dialogues, changes, endings and optional patrols (omit or [] when nobody needs a repeated walk). Same shapes and effects as existing story; empty arrays are fine. Do not include intro. Each new item and ending needs a unique key.`;
+  prompt = scriptBase;
+  for (let i = 1; i <= 4; i++) {
+    const answer = await askSparkJson(memo, { label: `extend-story#${i}`, prompt });
+    const result = mergeStory(world, oldStory, answer, changed, oldWorld);
+    if (result.story && result.report) return { world, story: result.story, changed, report: result.report };
+    prompt = `${scriptBase}\nPrevious answer: ${JSON.stringify(answer)}\nFix: ${result.issues.join('; ')}`;
+  }
+  throw new Error('Could not design a playable story extension in 4 tries; the existing world was not changed');
+}

package/app/src/world/extension-progress.ts

@@ -0,0 +1,10 @@
+/** Milestones for an extension job; a place build can repeat its steps several times. */
+export type ExtensionProgress = {
+  phase: 'plan' | 'places' | 'audio' | 'install';
+  place?: string;
+  index?: number;
+  total?: number;
+  task?: 'characters';
+  /** New place keys are provisional until the staged extension is installed. */
+  newPlaces?: string[];
+};

package/app/src/world/files.ts

@@ -0,0 +1,62 @@
+// Where a world lives on disk. Every step reads and writes plain files under worlds/<slug>/.
+import fs from 'node:fs';
+import path from 'node:path';
+import { Memo } from '../meta/memo.ts';
+import { World } from './schema.ts';
+
+/**
+ * The world with each place's thing list as the person edited it (places/<key>/corrections.json): props taken
+ * off the list are gone, props added are there. world.json stays as Spark wrote it; every step reads this.
+ */
+export function withThingEdits(world: World, dir: string): World {
+  const places = world.places.map((place) => {
+    const file = path.join(dir, 'places', place.key, 'corrections.json');
+    if (!fs.existsSync(file)) return place;
+    let c: { things?: Record<string, { removed?: boolean }>; added?: Record<string, { looks?: string }> };
+    try {
+      c = JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      return place;
+    }
+    const removed = new Set(Object.entries(c.things ?? {}).filter(([, t]) => t?.removed).map(([k]) => k));
+    const added = Object.entries(c.added ?? {}).filter(([k, a]) => !place.things.some((t) => t.key === k) && typeof a?.looks === 'string');
+    if (!removed.size && !added.length) return place;
+    // Only props: an exit, an item or a person belongs to the story, which changes with story_redo.
+    const taken = place.things.filter((t) => t.role === 'prop' && removed.has(t.key)).map((t) => t.key);
+    const things = [...place.things.filter((t) => !taken.includes(t.key)), ...added.map(([key, a]) => ({ key, role: 'prop' as const, looks: a.looks! }))];
+    return things.length ? { ...place, things: things.slice(0, 10), ...(taken.length && { taken }) } : place;
+  });
+  return { ...world, places };
+}
+
+export class WorldFiles {
+  readonly dir: string;
+  readonly memo: Memo;
+
+  constructor(readonly slug: string, root = 'worlds') {
+    this.dir = path.resolve(root, slug);
+    this.memo = new Memo(path.join(this.dir, 'memo'));
+  }
+
+  path(...parts: string[]) {
+    return path.join(this.dir, ...parts);
+  }
+
+  place(key: string, ...parts: string[]) {
+    return this.path('places', key, ...parts);
+  }
+
+  write(file: string, data: Buffer | string | object) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, Buffer.isBuffer(data) || typeof data === 'string' ? data : `${JSON.stringify(data, null, 2)}\n`);
+  }
+
+  readJson(file: string): unknown {
+    if (!fs.existsSync(file)) throw new Error(`missing ${path.relative(process.cwd(), file)}: run the step before this one`);
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  }
+
+  world(): World {
+    return withThingEdits(World.parse(this.readJson(this.path('world.json'))), this.dir);
+  }
+}

package/app/src/world/idea-review.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+
+export const IdeaReview = z.object({
+  understanding: z.string().min(1).max(700),
+  questions: z.array(z.object({
+    question: z.string().min(1).max(100),
+    why: z.string().max(300),
+    presentation: z.enum(['pictures', 'text']).optional(),
+    options: z.array(z.string().min(1).max(96)).max(3),
+    visuals: z.array(z.object({ scene: z.string().min(1).max(500), photo: z.number().int().nonnegative().optional() })).max(3).optional(),
+    photo: z.number().int().nonnegative().optional(),
+    video: z.object({ id: z.string(), seconds: z.number().nonnegative() }).optional(),
+  })).max(1),
+  styles: z.array(z.object({ title: z.string().min(1).max(80), description: z.string().min(10).max(500) })).max(3),
+});
+export type IdeaReview = z.infer<typeof IdeaReview>;
+
+/** Only explicit creator decisions, never the reviewer's guesses or unanswered suggestions. */
+export const CreativeChoices = z.object({
+  answers: z.array(z.object({ question: z.string().min(1).max(240), answer: z.string().trim().min(1).max(600) })).max(3),
+  style: z.string().trim().min(10).max(500).optional(),
+  styleReference: z.string().regex(/^[a-f0-9]{32}$/).optional(),
+  note: z.string().trim().max(1000).optional(),
+}).refine(v => !v.styleReference || !!v.style, 'A style reference needs a chosen style.');
+export type CreativeChoices = z.infer<typeof CreativeChoices>;
+export function refinedIdea(idea: string, choices?: CreativeChoices): string {
+  if (!choices) return idea.trim();
+  const lines = choices.answers.map(a => `${a.question}\n${a.answer}`);
+  if (choices.style) lines.push(`Visual style chosen by the creator: ${choices.style}`);
+  if (choices.note) lines.push(choices.note);
+  return [idea.trim(), ...(lines.length ? [`Creator's clarifications (these override earlier ambiguity; keep the original story language unless explicitly changed):\n${lines.join('\n\n')}`] : [])].join('\n\n');
+}

package/app/src/world/photo-limits.ts

@@ -0,0 +1,2 @@
+/** Shared by the start form and world_new: enough for a classroom's drawings. */
+export const MAX_WORLD_PHOTOS = 32;

package/app/src/world/pool.ts

@@ -0,0 +1,41 @@
+// Work that may run side by side, a few at a time: the cast's 3D bodies and faces, each character on its own.
+
+/** Runs `work` on every item, at most `limit` at once; results keep the items' order. Errors are kept per item. */
+export async function mapLimit<T, R>(items: readonly T[], limit: number, work: (item: T, index: number) => Promise<R>): Promise<PromiseSettledResult<R>[]> {
+  const results: PromiseSettledResult<R>[] = new Array(items.length);
+  let next = 0;
+  const runner = async () => {
+    while (next < items.length) {
+      const i = next++;
+      try {
+        results[i] = { status: 'fulfilled', value: await work(items[i], i) };
+      } catch (reason) {
+        results[i] = { status: 'rejected', reason };
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, runner));
+  return results;
+}
+
+const open = new Map<string, number>();
+const waiting = new Map<string, Array<() => void>>();
+
+/** At most `limit` of `lane`'s work at once in this process (a Hugging Face Space queue, a local GPU). */
+export async function inLane<T>(lane: string, limit: number, work: () => Promise<T>): Promise<T> {
+  if ((open.get(lane) ?? 0) >= limit) await new Promise<void>((go) => (waiting.get(lane) ?? waiting.set(lane, []).get(lane)!).push(go));
+  else open.set(lane, (open.get(lane) ?? 0) + 1);
+  try {
+    return await work();
+  } finally {
+    const go = waiting.get(lane)?.shift();
+    if (go) go();
+    else open.set(lane, (open.get(lane) ?? 1) - 1);
+  }
+}
+
+/** How many characters are worked on at once: DIORAMA_CAST_LANES, default 3. */
+export function castLanes(): number {
+  const n = Number(process.env.DIORAMA_CAST_LANES);
+  return Number.isFinite(n) && n >= 1 ? Math.floor(n) : 3;
+}