@gtanczyk/diorama 0.0.0-stage → 0.2.0

package/app/src/story/check.ts

@@ -0,0 +1,230 @@
+// The story gate: every name must exist in the world, every ending must be reachable, and no
+// reachable state may cut the player off from all endings. Finds a shortest route to each ending too.
+import type { World } from '../world/schema.ts';
+import { actions, apply, describe, pickInteraction, startState, stateKey, type Action, type State } from './engine.ts';
+import { Story } from './schema.ts';
+
+export type Route = { ending: string; steps: string[]; actions: Action[] };
+export type StoryReport = { issues: string[]; states: number; routes: Route[] };
+
+const MAX_STATES = 200_000;
+
+/** Whether the story needs a thing for more than a look line (what it gives, a lock, a change, a talk): then it stays. */
+export function storyNeeds(raw: unknown, place: string, thing: string): boolean {
+  const story = Story.safeParse(raw);
+  if (!story.success) return JSON.stringify(raw ?? '').includes(`"${thing}"`);
+  const s = story.data;
+  return s.interactions.some((i) => i.place === place && i.thing === thing && (i.verb !== 'look' || i.do.length > 0))
+    || s.locks.some((l) => l.place === place && l.via === thing)
+    || s.changes.some((c) => c.place === place && c.thing === thing)
+    || s.patrols?.some((p) => p.place === place && p.via.includes(thing)) === true
+    || s.dialogues.some((d) => d.place === place && d.npc === thing);
+}
+
+export function storyNameIssues(world: World, story: Story): string[] {
+  const issues: string[] = [];
+  const place = (key: string) => world.places.find((p) => p.key === key);
+  const items = new Set(story.items.map((i) => i.key));
+  const endings = new Set(story.endings.map((e) => e.key));
+  const setFlags = new Set<string>();
+  const given = new Set<string>();
+  const allEffects = [...story.interactions.flatMap((i) => i.do), ...story.dialogues.flatMap((d) => d.lines.flatMap((l) => l.choices.flatMap((c) => c.do)))];
+  const moves = allEffects.flatMap((e) => 'moveNpc' in e ? [e.moveNpc] : []);
+  const isNpc = (key: string) => world.places.some((p) => p.things.some((t) => t.key === key && t.role === 'npc'));
+  const canVisit = (npc: string, placeKey: string) => isNpc(npc) && moves.some((m) => m.npc === npc && m.to === placeKey);
+  for (const e of allEffects) {
+    if ('set' in e) setFlags.add(e.set);
+    if ('give' in e) given.add(e.give);
+    if ('give' in e || 'take' in e) { const k = 'give' in e ? e.give : (e as { take: string }).take; if (!items.has(k)) issues.push(`effect uses unknown item "${k}"`); }
+    if ('go' in e && !place(e.go)) issues.push(`effect goes to unknown place "${e.go}"`);
+    if ('ending' in e && !endings.has(e.ending)) issues.push(`effect ends with unknown ending "${e.ending}"`);
+    if ('moveNpc' in e) {
+      const { npc, to } = e.moveNpc;
+      const homes = world.places.filter((p) => p.things.some((t) => t.key === npc && t.role === 'npc'));
+      if (homes.length !== 1) issues.push(`moveNpc: "${npc}" must be an NPC declared in exactly one place`);
+      if (!place(to)) issues.push(`moveNpc: unknown place "${to}"`);
+      if (world.places.some((p) => p.things.some((t) => t.key === npc && t.role !== 'npc'))) issues.push(`moveNpc: "${npc}" also names an object`);
+    }
+  }
+  const checkWhen = (where: string, when: string[]) => {
+    for (const fact of when) {
+      const body = fact.replace(/^!/, '');
+      if (body.startsWith('has:') && !items.has(body.slice(4))) issues.push(`${where}: unknown item in "${fact}"`);
+      else if (body.startsWith('at:') && !place(body.slice(3))) issues.push(`${where}: unknown place in "${fact}"`);
+      else if (!body.includes(':') && !fact.startsWith('!') && !setFlags.has(body)) issues.push(`${where}: flag "${body}" is never set`);
+    }
+  };
+  const thingIn = (where: string, placeKey: string, thing: string, role?: string) => {
+    const p = place(placeKey);
+    if (!p) return issues.push(`${where}: unknown place "${placeKey}"`);
+    const t = p.things.find((x) => x.key === thing);
+    if (!t && role !== 'exit' && canVisit(thing, placeKey)) return;
+    if (!t) issues.push(`${where}: "${thing}" is not a thing in ${placeKey}`);
+    else if (role && t.role !== role) issues.push(`${where}: "${thing}" must have role "${role}"`);
+  };
+  story.interactions.forEach((it, i) => {
+    const where = `interaction ${i + 1} (${it.verb} ${it.thing})`;
+    // A look line on a prop the person took off the place's list is never clicked; it does no harm.
+    if (it.verb === 'look' && !it.do.length && place(it.place)?.taken?.includes(it.thing)) return;
+    thingIn(where, it.place, it.thing, it.verb === 'talk' ? 'npc' : undefined);
+    // Clicking an exit always walks through it (and obeys its lock), so an exit only answers "look".
+    const exit = place(it.place)?.things.find((t) => t.key === it.thing)?.role === 'exit';
+    if (exit && it.verb !== 'look') issues.push(`${where}: "${it.thing}" is an exit; clicking it goes through, so it can only have "look" interactions (use a lock to stop it)`);
+    if (it.with && !items.has(it.with)) issues.push(`${where}: unknown item "${it.with}"`);
+    checkWhen(where, it.when);
+  });
+  for (const lock of story.locks) {
+    thingIn(`lock on ${lock.via}`, lock.place, lock.via, 'exit');
+    checkWhen(`lock on ${lock.via}`, lock.until);
+  }
+  story.changes.forEach((c, i) => {
+    thingIn(`change ${i + 1} (${c.thing})`, c.place, c.thing);
+    checkWhen(`change ${i + 1} (${c.thing})`, c.when);
+  });
+  for (const d of story.dialogues) {
+    const where = `dialogue with ${d.npc}`;
+    thingIn(where, d.place, d.npc, 'npc');
+    checkWhen(where, d.when);
+    const keys = new Set(d.lines.map((l) => l.key));
+    if (!keys.has(d.start)) issues.push(`${where}: start line "${d.start}" is missing`);
+    for (const l of d.lines) for (const c of l.choices) {
+      if (c.next && !keys.has(c.next)) issues.push(`${where}: line "${l.key}" leads to missing "${c.next}"`);
+      checkWhen(`${where}, line ${l.key}`, c.when);
+    }
+  }
+  for (const item of items) if (!given.has(item)) issues.push(`item "${item}" is never given`);
+  for (const patrol of story.patrols ?? []) {
+    const where = `patrol of ${patrol.npc} in ${patrol.place}`;
+    thingIn(where, patrol.place, patrol.npc, 'npc');
+    checkWhen(where, patrol.when);
+    if (new Set(patrol.via).size < 2) issues.push(`${where}: needs at least two different stops`);
+    for (const key of patrol.via) {
+      thingIn(where, patrol.place, key);
+      if (isNpc(key)) issues.push(`${where}: stop "${key}" must be a fixed object, not a person`);
+    }
+  }
+  return issues;
+}
+
+/** Breadth-first over every state the player can reach. */
+export function checkStory(world: World, raw: unknown): StoryReport & { story?: Story } {
+  const parsed = Story.safeParse(raw);
+  if (!parsed.success) return { issues: parsed.error.issues.map((i) => `${i.path.join('.') || 'story'}: ${i.message}`), states: 0, routes: [] };
+  const story = parsed.data;
+  const nameIssues = storyNameIssues(world, story);
+  if (nameIssues.length) return { issues: nameIssues, states: 0, routes: [] };
+
+  const start = startState(world);
+  const seen = new Map<string, { state: State; from?: string; via?: Action }>([[stateKey(start), { state: start }]]);
+  const edges = new Map<string, string[]>();
+  const queue = [stateKey(start)];
+  const fired = new Set<number>();
+  const movementIssues = new Set<string>();
+  while (queue.length && seen.size < MAX_STATES) {
+    const key = queue.shift()!;
+    const { state } = seen.get(key)!;
+    const out: string[] = [];
+    for (const action of actions(world, story, state)) {
+      const step = apply(world, story, state, action);
+      for (const issue of step.issues ?? []) movementIssues.add(issue);
+      if (action.kind === 'do') fired.add(pickInteraction(story, state, action, world));
+      const nextKey = stateKey(step.state);
+      out.push(nextKey);
+      if (!seen.has(nextKey)) { seen.set(nextKey, { state: step.state, from: key, via: action }); queue.push(nextKey); }
+    }
+    edges.set(key, out);
+  }
+  const issues: string[] = [...movementIssues];
+  if (seen.size >= MAX_STATES) issues.push(`more than ${MAX_STATES} states; the story is too loose to check`);
+
+  const actionsTo = (key: string) => {
+    const out: Action[] = [];
+    for (let at = seen.get(key); at?.from; at = seen.get(at.from)) out.unshift(at.via!);
+    return out;
+  };
+  const routeTo = (key: string) => actionsTo(key).map(describe);
+  const routes: Route[] = [];
+  for (const ending of story.endings) {
+    const hit = [...seen.entries()].find(([, v]) => v.state.ending === ending.key);
+    if (hit) routes.push({ ending: ending.key, steps: routeTo(hit[0]), actions: actionsTo(hit[0]) });
+    else issues.push(`ending "${ending.key}" cannot be reached`);
+  }
+
+  // States that can still reach an ending, found backwards from the ending states.
+  const back = new Map<string, string[]>();
+  for (const [from, tos] of edges) for (const to of tos) back.set(to, [...(back.get(to) ?? []), from]);
+  const alive = new Set([...seen.keys()].filter((k) => seen.get(k)!.state.ending));
+  const stack = [...alive];
+  while (stack.length) for (const from of back.get(stack.pop()!) ?? []) if (!alive.has(from)) { alive.add(from); stack.push(from); }
+  const stuck = [...seen.keys()].filter((k) => !alive.has(k) && edges.has(k));
+  if (stuck.length) {
+    const first = stuck.reduce((a, b) => (routeTo(a).length <= routeTo(b).length ? a : b));
+    issues.push(`${stuck.length} reachable state(s) can never reach an ending, e.g. after: ${routeTo(first).join(' → ') || 'the start'}`);
+  }
+
+  story.interactions.forEach((it, i) => {
+    if (!fired.has(i)) issues.push(`interaction ${i + 1} (${it.verb} ${it.thing} in ${it.place}) can never happen`);
+  });
+  return { issues, states: seen.size, routes, story: issues.length ? undefined : story };
+}
+
+/** Word limits per kind of line: everything said is read or voiced, so less is better. */
+export const BREVITY = { intro: 30, say: 14, nope: 8, npcLine: 20, choice: 8, ending: 25, linesPerDialogue: 6 } as const;
+
+const words = (text: string) => text.trim().split(/\s+/).filter(Boolean).length;
+
+/** Lines over the limits, for the designer to shorten. Not part of checkStory: a person may write longer by hand. */
+export function brevityIssues(story: Story): string[] {
+  const issues: string[] = [];
+  const over = (where: string, text: string, max: number) => {
+    if (words(text) > max) issues.push(`${where} has ${words(text)} words, keep it to ${max}: "${text}"`);
+  };
+  over('intro', story.intro, BREVITY.intro);
+  story.interactions.forEach((it, i) => over(`interaction ${i + 1} (${it.verb} ${it.thing}) say`, it.say, BREVITY.say));
+  story.locks.forEach((l) => over(`lock on ${l.via} say`, l.say, BREVITY.say));
+  story.items.forEach((it) => it.nope && over(`item ${it.key} nope`, it.nope, BREVITY.nope));
+  for (const d of story.dialogues) {
+    if (d.lines.length > BREVITY.linesPerDialogue) issues.push(`dialogue with ${d.npc} has ${d.lines.length} lines, keep it to ${BREVITY.linesPerDialogue}`);
+    for (const l of d.lines) {
+      over(`${d.npc} line ${l.key}`, l.says, BREVITY.npcLine);
+      l.choices.forEach((c, i) => over(`${d.npc} line ${l.key} choice ${i + 1}`, c.text, BREVITY.choice));
+    }
+  }
+  story.endings.forEach((e) => over(`ending ${e.key} text`, e.text, BREVITY.ending));
+  return issues;
+}
+
+const asks = (text: string) => /\?["'”’)]*\s*$/.test(text.trim());
+
+/** Questions the player cannot answer: a "say" is not a conversation, and a line without choices ends one. */
+export function questionIssues(story: Story): string[] {
+  const issues: string[] = [];
+  story.interactions.forEach((it, i) => {
+    if (asks(it.say)) issues.push(`interaction ${i + 1} (${it.verb} ${it.thing}) say ends with a question the player cannot answer: "${it.say}". Make it a statement, or ask it in a dialogue line with choices`);
+  });
+  for (const d of story.dialogues) {
+    for (const l of d.lines) {
+      if (asks(l.says) && l.choices.length === 0) issues.push(`${d.npc} line ${l.key} asks "${l.says}" but has no choices, so the conversation ends on the question. Give it answers, or make it a statement`);
+    }
+  }
+  return issues;
+}
+
+/**
+ * What plays but does not show: an item thing whose item has another key stays lying in the painting after it is
+ * taken, and a change on a person is never drawn (people are characters over the painting).
+ */
+export function paintingIssues(world: World, story: Story): string[] {
+  const issues: string[] = [];
+  const role = (place: string, thing: string) => world.places.find((p) => p.key === place)?.things.find((t) => t.key === thing)?.role;
+  story.interactions.forEach((it, i) => {
+    const gives = it.do.flatMap((e) => ('give' in e ? [e.give] : []));
+    if (it.verb === 'take' && role(it.place, it.thing) === 'item' && gives.length && !gives.includes(it.thing)) {
+      issues.push(`interaction ${i + 1} (take ${it.thing}): "${it.thing}" is an item thing, so the item it gives must have the key "${it.thing}"`);
+    }
+  });
+  story.changes.forEach((c, i) => {
+    if (role(c.place, c.thing) === 'npc') issues.push(`change ${i + 1} (${c.thing}): "${c.thing}" is a person; a change can only repaint a thing in the painting, not a person`);
+  });
+  return issues;
+}

package/app/src/story/design.ts

@@ -0,0 +1,108 @@
+// The story step: world.json becomes story.json. Spark writes it; the checker plays every state
+// and sends dead ends and unreachable endings back.
+import type { Memo } from '../meta/memo.ts';
+import { askSparkJson } from '../meta/spark.ts';
+import type { World } from '../world/schema.ts';
+import { BREVITY, brevityIssues, checkStory, paintingIssues, questionIssues, type StoryReport } from './check.ts';
+import { fromWire, WireStory, type Story } from './schema.ts';
+import { z } from 'zod';
+import { NPC_STORY_GUIDANCE } from './npc-guidance.ts';
+
+const MIN_STEPS = 6;
+
+const EXAMPLE = `{
+  "intro": "two or three sentences shown before the first place",
+  "items": [{ "key": "<thing key with role item, or a new key for something given>", "name": "short name", "nope": "what the hero says trying it where it does not help" }],
+  "locks": [{ "place": "<place>", "via": "<exit thing>", "until": ["<fact>"], "say": "why it will not open yet" }],
+  "interactions": [{
+    "place": "<place>", "thing": "<thing key in that place>", "verb": "look | use | take | talk",
+    "with": "<item key, only when using an item on the thing>",
+    "when": ["<fact>"], "say": "what the hero says or sees", "do": [{ "set": "flag" }], "once": false
+  }],
+  "dialogues": [{
+    "npc": "<thing key with role npc>", "place": "<place>", "when": [], "start": "<line key>",
+    "lines": [{ "key": "kebab-key", "says": "what the npc says", "choices": [{ "text": "what the hero answers", "when": [], "do": [], "next": "<line key or leave out to end>" }] }]
+  }],
+  "changes": [{ "place": "<place>", "thing": "<thing key>", "when": ["<fact>"], "looks": "how it looks once changed, a few words" }],
+  "patrols": [],
+  "endings": [{ "key": "kebab-key", "title": "short", "text": "two sentences" }]
+}`;
+
+/** For players of 5 to 7 who cannot read yet: they hear every line, so it has to be plain and kind. */
+const KIDS = `
+- The players are 5 to 7 years old and cannot read: every line is read aloud to them. Use the words a small child uses, short sentences, no irony.
+- Puzzles a small child solves by trying: give the thing to someone who asks for it, use an item on the thing that obviously needs it. The npc says plainly what they need.
+- Friendly and gentle: nobody is hurt, nothing is scary, both endings are happy (one may be a little funny).`;
+
+function brief(world: World): string {
+  return `You write the puzzles and dialogue of a short 2D point-and-click adventure. The world is fixed:
+${JSON.stringify(world, null, 2)}
+
+Write story.json for it. Rules:
+- 3 to 6 minutes of play: 2 to 4 items, 1 or 2 locked exits, one conversation with real choices, 2 endings.
+- A fact is "flag", "!flag", "has:item", "!has:item" or "at:place". A condition is a list of facts that must all hold.
+- Effects: {"set": flag}, {"clear": flag}, {"give": item}, {"take": item}, {"go": place}, {"ending": ending key}.
+${NPC_STORY_GUIDANCE}
+- For structured wire effects, a move is {"op":"moveNpc","key":"<npc key>","to":"<place key>"}.
+- Clicking picks the first interaction listed for that thing, verb and item whose condition holds, so list special cases before the plain one.
+- Every thing should answer "look". Every item thing has a "take" with "once": true and gives the item keyed like the thing; taking it lifts it out of the painting. Something found in another thing (a fish from a stall) is a new item key; that thing stays.
+- Exits move the hero by themselves when clicked: give an exit only "look" interactions, never use/take/talk or a go effect; stop it with a lock.
+- Unlock with a flag set when the problem is solved, not with "has:item", so the player is never locked out after giving the item away.
+- When solving something visibly changes a thing (a fire lit, a gate open, a lamp glowing), add a change for it; the painting is updated when its condition holds. At least one change, never on a person (npc).
+- No ending may be reachable in fewer than ${MIN_STEPS} clicks; each ending needs a solved puzzle.
+- Every ending must be reachable, and from any state the player must still be able to reach an ending.
+- Only a dialogue line with choices may ask the player something. A "say", and a line without choices, ends on a statement, never a question: the player has no way to answer it.
+- Write for actors, not a task checklist. Give each character a distinct personality, motive and way of talking, grounded in the drawings and this story. Include brief reactions, gentle humour and reciprocal exchanges. Let relationships develop when the player helps; do not make every character simply order an item and redirect the player.
+- The hero speaks in first person, reacting in their own voice: "Oof, this can is heavy!", never player-facing narration such as "You take the watering can" or "Bierzesz konewkę". NPCs speak as themselves; only the intro and endings are narrated. Do not put stage directions or emotion tags into spoken text.
+- Keep each line easy to follow, with room for personality: the intro at most ${BREVITY.intro} words, a "say" at most ${BREVITY.say}, an npc line at most ${BREVITY.npcLine}, an answer choice at most ${BREVITY.choice}, an ending at most ${BREVITY.ending}, an item's \"nope\" at most ${BREVITY.nope}, and at most ${BREVITY.linesPerDialogue} lines per conversation. One idea per line; concise does not mean robotic or purely instructional.
+- Text is ${world.language ?? 'English'}, short and specific to this world. No names from existing films, books, games or brands.${world.audience === 'kids' ? KIDS : ''}
+
+Reply with JSON only, shaped like:
+${EXAMPLE}`;
+}
+
+/** Up to four tries; each retry shows Spark its last answer and everything the checker found. */
+export async function designStory(memo: Memo, world: World, wish?: string): Promise<{ story: Story; report: StoryReport }> {
+  // The person's wish goes last, so a story without one asks Spark exactly what it asked before.
+  const ask = (w: World) => brief(w) + (wish ? `\n\nThe author asks for this; follow it, keeping every ending reachable and the exit rules: ${wish}` : '');
+  let prompt = ask(world);
+  // A story every ending of which plays, kept in case the editor never runs out of notes on its wording.
+  let playable: { story: Story; report: StoryReport; notes: string[] } | undefined;
+  for (let attempt = 1; attempt <= 4; attempt++) {
+    // Claude is held to the wire shape (effects as {op, key}); Spark answers in Story's own shape. Both read the same.
+    const answer = fromWire(await askSparkJson(memo, { label: `story#${attempt}`, prompt, schema: WireStory }));
+    const report = checkStory(world, answer);
+    if (report.story) report.issues.push(...brevityIssues(report.story), ...questionIssues(report.story), ...paintingIssues(world, report.story));
+    for (const r of report.routes) {
+      if (r.steps.length < MIN_STEPS) report.issues.push(`ending "${r.ending}" is reached in only ${r.steps.length} clicks: ${r.steps.join(' → ')}`);
+    }
+    if (report.story && report.issues.length === 0) {
+      const notes = await dialogueIssues(memo, world, report.story);
+      if (!notes.length) return { story: report.story, report };
+      if (!playable || notes.length <= playable.notes.length) playable = { story: report.story, report: { ...report, issues: [] }, notes };
+      report.issues.push(...notes);
+    }
+    console.log(`  story try ${attempt}: ${report.issues.length} issue(s): ${report.issues.slice(0, 3).join('; ')}`);
+    prompt = `${ask(world)}\n\nYour last answer was:\n${JSON.stringify(answer)}\n\nA checker played every possible state and found these problems. Fix every one and reply with the whole JSON again:\n- ${report.issues.join('\n- ')}`;
+  }
+  // Wording notes are taste; a story that plays is the step's job. The person can reword any line in the Studio.
+  if (playable) {
+    console.log(`  story: kept the playable version with the fewest wording notes (${playable.notes.length}): ${playable.notes.slice(0, 3).join('; ')}`);
+    return { story: playable.story, report: playable.report };
+  }
+  throw new Error('Spark gave no playable story in 4 tries');
+}
+
+/** Editorial review is separate from reachability: a playable checklist can still be a poor conversation. */
+export async function dialogueIssues(memo: Memo, world: World, story: Story): Promise<string[]> {
+  const review = await askSparkJson(memo, {
+    label: 'story-dialogue-review',
+    schema: z.object({ issues: z.array(z.string()) }),
+    prompt: `Review the spoken script of this game in ${world.language ?? 'English'} for ${world.audience === 'kids' ? 'children aged 5–7' : 'its intended audience'}.
+World: ${JSON.stringify(world)}
+Script: ${JSON.stringify(story)}
+Check native natural phrasing, consistent speaker perspective, distinct character personalities, reactions and meaningful exchanges beyond fetching items. Hero remarks and choices must be things the hero says, not a narrator telling the player what they do. Keep age-appropriate simplicity without making every voice generic or babyish. Do not demand longer dialogue just for length. Check that humour and reactions stay consistent with the story and do not obscure the next action.
+Return JSON {"issues": ["exact text path and concrete correction needed"]}; [] if it works. At most 6 substantive issues. Do not judge mechanics or rewrite the story here.`,
+  });
+  return z.object({ issues: z.array(z.string()).max(6) }).parse(review).issues;
+}

package/app/src/story/engine.ts

@@ -0,0 +1,233 @@
+// The story rules as pure functions over a plain state. The browser runtime plays with them,
+// and the checker walks every state with them, so what the checker proves is what the player gets.
+import type { World } from '../world/schema.ts';
+import type { Effect, Story } from './schema.ts';
+import { goodbye } from './phrases.ts';
+
+export type State = {
+  place: string;
+  flags: string[];
+  items: string[];
+  /** Indexes of `once` interactions already fired. */
+  spent: number[];
+  talk?: { dialogue: number; line: string };
+  ending?: string;
+  /** Only people relocated by the story: absence preserves their world.json placement. */
+  npcs?: Record<string, string>;
+};
+
+export type Action =
+  | { kind: 'go'; via: string }
+  | { kind: 'do'; thing: string; verb: string; with?: string }
+  | { kind: 'talk'; npc: string }
+  | { kind: 'choose'; index: number }
+  | { kind: 'leave' };
+
+export type Step = { state: State; say: string[]; issues?: string[] };
+
+/** Who says an interaction's line: a person talked to answers in their own voice; everything else is the hero's remark. */
+export function speakerOf(world: World, it: { place: string; thing: string; verb: string }): string {
+  if (it.verb !== 'talk') return world.hero.key;
+  const local = world.places.find((p) => p.key === it.place)?.things.find((t) => t.key === it.thing);
+  const npc = local ? local.role === 'npc' : world.places.some((p) => p.things.some((t) => t.key === it.thing && t.role === 'npc'));
+  return npc ? it.thing : world.hero.key;
+}
+
+export function startState(world: World): State {
+  return { place: world.start, flags: [], items: [], spent: [] };
+}
+
+export function holds(state: State, when: readonly string[]): boolean {
+  return when.every((fact) => {
+    const negated = fact.startsWith('!');
+    const body = negated ? fact.slice(1) : fact;
+    const value = body.startsWith('has:') ? state.items.includes(body.slice(4))
+      : body.startsWith('at:') ? state.place === body.slice(3)
+      : state.flags.includes(body);
+    return value !== negated;
+  });
+}
+
+/** The interaction a click would fire right now, if any: the first one listed whose condition holds. */
+export function npcHere(world: World, state: State, npc: string): boolean {
+  return state.npcs?.[npc] ? state.npcs[npc] === state.place
+    : !!world.places.find((p) => p.key === state.place)?.things.some((t) => t.key === npc && t.role === 'npc');
+}
+
+export function pickInteraction(story: Story, state: State, a: { thing: string; verb: string; with?: string }, world: World): number {
+  const local = world.places.find((p) => p.key === state.place)?.things.find((t) => t.key === a.thing);
+  if ((!local || local.role === 'npc') && world.places.some((p) => p.things.some((t) => t.key === a.thing && t.role === 'npc')) && !npcHere(world, state, a.thing)) return -1;
+  return story.interactions.findIndex((it, i) =>
+    it.place === state.place && it.thing === a.thing && it.verb === a.verb && it.with === a.with
+    && !state.spent.includes(i) && holds(state, it.when));
+}
+
+export function pickDialogue(story: Story, state: State, npc: string, world: World): number {
+  if (!npcHere(world, state, npc)) return -1;
+  return story.dialogues.findIndex((d) => d.place === state.place && d.npc === npc && holds(state, d.when));
+}
+
+export function lockOn(story: Story, state: State, via: string) {
+  return story.locks.find((l) => l.place === state.place && l.via === via && !holds(state, l.until));
+}
+
+/**
+ * The next step toward facts the player still lacks (a lock's `until`): the first interaction that sets a missing
+ * fact and can be done now, the item for it in the bag. A nudge for a stuck player; undefined when the way there
+ * starts somewhere the player has not been yet (an item still to find).
+ */
+export function hintFor(story: Story, state: State, facts: readonly string[]): { place: string; thing: string; with?: string } | undefined {
+  for (const fact of facts) {
+    if (fact.startsWith('!') || holds(state, [fact])) continue;
+    const it = story.interactions.find((i, k) => !state.spent.includes(k) && holds(state, i.when) && i.do.some((d) => 'set' in d && d.set === fact)
+      && (!i.with || state.items.includes(i.with)));
+    if (it) return { place: it.place, thing: it.thing, ...(it.with && { with: it.with }) };
+  }
+  return undefined;
+}
+
+/** Where an item in hand is wanted in this place now, when it was tried on the wrong thing. */
+export function useFor(story: Story, state: State, item: string): string | undefined {
+  return story.interactions.find((i, k) => i.place === state.place && i.with === item && !state.spent.includes(k) && holds(state, i.when))?.thing;
+}
+
+/** Everything that would change the state from here. Clicks that only print a refusal are left out. */
+export function actions(world: World, story: Story, state: State): Action[] {
+  if (state.ending) return [];
+  if (state.talk) {
+    const line = lineOf(story, state)!;
+    const open = line.choices.flatMap((c, index) => (holds(state, c.when) ? [{ kind: 'choose' as const, index }] : []));
+    return open.length ? open : [{ kind: 'leave' }];
+  }
+  const place = world.places.find((p) => p.key === state.place)!;
+  const out: Action[] = [];
+  for (const exit of place.exits) if (!lockOn(story, state, exit.via)) out.push({ kind: 'go', via: exit.via });
+  const seen = new Set<string>();
+  for (const it of story.interactions) {
+    const id = `${it.thing}|${it.verb}|${it.with ?? ''}`;
+    if (it.place !== state.place || seen.has(id)) continue;
+    if (it.with && !state.items.includes(it.with)) continue;
+    const a = { kind: 'do' as const, thing: it.thing, verb: it.verb, ...(it.with ? { with: it.with } : {}) };
+    if (pickInteraction(story, state, a, world) >= 0) { seen.add(id); out.push(a); }
+  }
+  for (const d of story.dialogues) {
+    if (d.place === state.place && !out.some((a) => a.kind === 'talk' && a.npc === d.npc) && pickDialogue(story, state, d.npc, world) >= 0) {
+      out.push({ kind: 'talk', npc: d.npc });
+    }
+  }
+  return out;
+}
+
+export function apply(world: World, story: Story, state: State, action: Action): Step {
+  const next: State = { ...state, flags: [...state.flags], items: [...state.items], spent: [...state.spent], ...(state.npcs && { npcs: { ...state.npcs } }) };
+  const say: string[] = [];
+  const issues: string[] = [];
+  switch (action.kind) {
+    case 'go': {
+      const lock = lockOn(story, state, action.via);
+      if (lock) return { state, say: [lock.say] };
+      const exit = world.places.find((p) => p.key === state.place)?.exits.find((e) => e.via === action.via);
+      if (!exit) throw new Error(`no exit "${action.via}" in ${state.place}`);
+      next.place = exit.to;
+      break;
+    }
+    case 'do': {
+      const i = pickInteraction(story, state, action, world);
+      if (i < 0) return { state, say: [] };
+      const it = story.interactions[i];
+      say.push(it.say);
+      if (it.once) next.spent.push(i);
+      issues.push(...run(world, next, it.do));
+      break;
+    }
+    case 'talk': {
+      const d = pickDialogue(story, state, action.npc, world);
+      if (d < 0) return { state, say: [] };
+      next.talk = { dialogue: d, line: story.dialogues[d].start };
+      say.push(lineOf(story, next)!.says);
+      break;
+    }
+    case 'choose': {
+      const choice = lineOf(story, state)?.choices[action.index];
+      if (!choice || !holds(state, choice.when)) return { state, say: [] };
+      say.push(choice.text);
+      issues.push(...run(world, next, choice.do));
+      next.talk = choice.next && !next.ending ? { dialogue: state.talk!.dialogue, line: choice.next } : undefined;
+      if (next.talk) say.push(lineOf(story, next)!.says);
+      break;
+    }
+    case 'leave':
+      if (state.talk) say.push(goodbye(world.language));
+      next.talk = undefined;
+      break;
+  }
+  next.flags.sort();
+  next.items.sort();
+  next.spent.sort((a, b) => a - b);
+  if (!next.talk) delete next.talk;
+  if (next.npcs) next.npcs = Object.fromEntries(Object.entries(next.npcs).sort(([a], [b]) => a.localeCompare(b)));
+  return { state: next, say, ...(issues.length && { issues }) };
+}
+
+function lineOf(story: Story, state: State) {
+  if (!state.talk) return undefined;
+  return story.dialogues[state.talk.dialogue].lines.find((l) => l.key === state.talk!.line);
+}
+
+function run(world: World, state: State, effects: Effect[]) {
+  const issues: string[] = [];
+  for (const e of effects) {
+    if ('set' in e && !state.flags.includes(e.set)) state.flags.push(e.set);
+    if ('clear' in e) state.flags = state.flags.filter((f) => f !== e.clear);
+    if ('give' in e && !state.items.includes(e.give)) state.items.push(e.give);
+    if ('take' in e) state.items = state.items.filter((i) => i !== e.take);
+    if ('go' in e) state.place = e.go;
+    if ('ending' in e) state.ending = e.ending;
+    if ('moveNpc' in e) {
+      const { npc, to } = e.moveNpc;
+      const from = state.npcs?.[npc] ?? world.places.find((p) => p.things.some((t) => t.key === npc && t.role === 'npc'))?.key;
+      // A repeated action is harmless; an NPC cannot teleport across an unrelated place.
+      if (from && from !== to && world.places.find((p) => p.key === from)?.exits.some((exit) => exit.to === to))
+        state.npcs = { ...state.npcs, [npc]: to };
+      else if (from !== to) issues.push(`NPC "${npc}" cannot move from "${from ?? 'unknown'}" to "${to}" without a connecting exit`);
+    }
+  }
+  return issues;
+}
+
+export function stateKey(state: State): string {
+  return JSON.stringify(state);
+}
+
+export function describe(action: Action): string {
+  switch (action.kind) {
+    case 'go': return `go ${action.via}`;
+    case 'do': return `${action.verb} ${action.thing}${action.with ? ` with ${action.with}` : ''}`;
+    case 'talk': return `talk ${action.npc}`;
+    case 'choose': return `choose ${action.index + 1}`;
+    case 'leave': return 'leave';
+  }
+}
+
+/** Things the player can carry off: a once-only "take" that gives an item. Each one needs a clean plate under it. */
+/**
+ * A take carries the thing itself off only when it gives the item of the same key (the brief keys an item after its
+ * thing). Taking a dried fish from the market stalls gives an item and leaves the stalls standing.
+ */
+export const carriesOff = (it: Story['interactions'][number]) => it.verb === 'take' && it.do.some((e) => 'give' in e && e.give === it.thing);
+
+export function removableThings(story: Story): { place: string; thing: string }[] {
+  const out = story.interactions.filter((it) => it.once && carriesOff(it));
+  return [...new Map(out.map((it) => [`${it.place}|${it.thing}`, { place: it.place, thing: it.thing }])).values()];
+}
+
+/** Things already carried off in this state, to be painted over with their clean plate. */
+export function hiddenThings(story: Story, state: State): { place: string; thing: string }[] {
+  return state.spent.map((i) => story.interactions[i]).filter(carriesOff)
+    .map((it) => ({ place: it.place, thing: it.thing }));
+}
+
+/** Indexes into story.changes whose condition holds in this state: the runtime draws their plates. */
+export function activeChanges(story: Story, state: State): number[] {
+  return story.changes.flatMap((c, i) => (holds(state, c.when) ? [i] : []));
+}

package/app/src/story/fixes.ts

@@ -0,0 +1,54 @@
+// The person's changes to the story, kept in story-fixes.json and applied by every rebuild of story.json:
+// a wish Spark writes the story to (puzzles, conditions, endings), and lines reworded by hand.
+import fs from 'node:fs';
+import { z } from 'zod';
+import type { WorldFiles } from '../world/files.ts';
+import type { Story } from './schema.ts';
+
+export const StoryFixes = z.object({
+  wish: z.string().min(5).optional(),
+  /** Reworded text by its place in story.json, e.g. "dialogues.0.lines.2.says". */
+  texts: z.record(z.string(), z.object({ text: z.string().min(1), at: z.string() })).default({}),
+});
+export type StoryFixes = z.infer<typeof StoryFixes>;
+
+/** The fields that are only words: changing them never changes what the player can do. */
+export const TEXT_KEYS = ['intro', 'say', 'says', 'text', 'title', 'name', 'looks'] as const;
+
+export const storyFixesFile = (files: WorldFiles) => files.path('story-fixes.json');
+
+export function readStoryFixes(files: WorldFiles): StoryFixes {
+  const file = storyFixesFile(files);
+  return fs.existsSync(file) ? StoryFixes.parse(files.readJson(file)) : { texts: {} };
+}
+
+/** The object holding a text field and the field's name, or null when the path names no text. */
+function locate(story: unknown, path: string): [Record<string, unknown>, string] | null {
+  const parts = path.split('.');
+  const last = parts.pop()!;
+  if (!(TEXT_KEYS as readonly string[]).includes(last)) return null;
+  let at: unknown = story;
+  for (const p of parts) {
+    if (Array.isArray(at) && /^\d+$/.test(p)) at = at[Number(p)];
+    else if (at && typeof at === 'object' && !Array.isArray(at) && /^[a-z]+$/.test(p)) at = (at as Record<string, unknown>)[p];
+    else return null;
+  }
+  return at && typeof at === 'object' && typeof (at as Record<string, unknown>)[last] === 'string' ? [at as Record<string, unknown>, last] : null;
+}
+
+export function textAt(story: Story, path: string): string | null {
+  const hit = locate(story, path);
+  return hit ? (hit[0][hit[1]] as string) : null;
+}
+
+/** The story with the reworded lines in; paths that no longer name a text are left out and listed. */
+export function applyTexts(story: Story, fixes: StoryFixes): { story: Story; skipped: string[] } {
+  const out = structuredClone(story);
+  const skipped: string[] = [];
+  for (const [path, { text }] of Object.entries(fixes.texts)) {
+    const hit = locate(out, path);
+    if (hit) hit[0][hit[1]] = text;
+    else skipped.push(path);
+  }
+  return { story: out, skipped };
+}

package/app/src/story/npc-guidance.ts

@@ -0,0 +1,7 @@
+// Shared authoring rules for new stories, story extensions and the Studio agent.
+export const NPC_STORY_GUIDANCE = `NPC story stages and movement:
+- Give a character only the simple story stages needed by the author's idea, such as waiting for a key, key received, then in the garden. Represent progress with ordinary story flags named after the NPC (for example gardener-key-received and gardener-outside), not a new state schema or autonomous memory/goals system.
+- Set or clear those flags in the interaction or dialogue choice that causes the event. Use when conditions on dialogues, interactions and optional patrols so the character's words and behaviour match the current stage. Put specific branches before a fallback; earlier-stage branches must stop matching once progress changes. A flag does not move an NPC by itself.
+- Walking is optional for each NPC. Omit patrols or use [] when a person stays still. Use a short purposeful patrol only when it fits the character and the scene; there is no quota of walking NPCs. A patrol is {"npc":"<npc key>","place":"<place>","via":["<fixed thing>","<other fixed thing>"],"when":[],"pause":2}; via names at least two different non-NPC things in that place, pause is seconds. First matching patrol wins; NPCs stop for conversations.
+- An interaction or dialogue choice can relocate a person with {"moveNpc":{"npc":"<npc key>","to":"<neighbouring place>"}} in do. A person may travel once without having any patrol. The event must have a connecting exit from that NPC's current location. Declare the NPC only in its original world place; use the same key for destination dialogue and interactions. Location is recorded separately in state.npcs; at:place describes the player's location.
+- Gate one-time departures and source/destination story branches with persistent flags or once, so replaying a conversation cannot send someone from the wrong place. Include a useful response in the destination, keep every interaction reachable and every remaining puzzle solvable, and do not require the player to catch a moving NPC or wait for a timer.`;

package/app/src/story/phrases.ts

@@ -0,0 +1,4 @@
+/** Phrases supplied by the game rather than the story, shared by play and voice generation. */
+export function goodbye(language?: string): string {
+  return language === 'Polish' ? 'Do widzenia.' : 'Goodbye.';
+}