plotcoder-board 0.1.13 → 0.1.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotcoder-board",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "type": "module",
   "scripts": {
     "dev": "vite",

package/scripts/plotcoder-mcp-server.mjs

@@ -51,6 +51,7 @@ import { segmentBrief, WORKFLOWS } from "../src/board/workflows.js";
 import { DEFAULT_REMINDERS, titleFromBody } from "../src/board/reminders.js";
 import crypto from "node:crypto";
 import { describeRuns, describeSetups, readWall } from "../src/board/readWall.js";
+import { compareStructure, describeComparison, MATCH_PAGES } from "../src/board/compareStructure.js";
 import { GAP, ROW_WIDTH, organizePoses } from "../src/board/organize.js";
 import { sceneLineCount } from "../src/board/paginate.js";
 import {
@@ -69,6 +70,11 @@ import {
   structureBeats,
   reidentifyProject,
   renameProject,
+  castElsewhere,
+  liftCast,
+  mergeRoster,
+  sameRoster,
+  withRoster,
 } from "../src/board/project.js";
 
 /**
@@ -626,7 +632,23 @@ async function openBoardEverywhere(project, boards, projectRev, base, boardId) {
   return { project: opened, state, live };
 }
 
+/**
+ * The open board with the project's cast in it (R51). A project written
+ * before the cast moved to the record is lifted once, here, and written back.
+ */
 async function readBoard() {
+  const raw = await readBoardRaw();
+  const held = await readProject();
+  if (!Array.isArray(held.project.characters)) {
+    const boardId = raw.boardId ?? held.project.activeBoardId;
+    const lifted = liftCast(held.project, { ...held.boards, [boardId]: raw.state });
+    await writeProject(lifted.project, lifted.boards, held.rev, held.base);
+    return { ...raw, state: lifted.boards[boardId] ?? withRoster(raw.state, lifted.project) };
+  }
+  return { ...raw, state: withRoster(raw.state, held.project) };
+}
+
+async function readBoardRaw() {
   const viaAccount = await throughAccount(accountReadBoard);
   if (viaAccount) return viaAccount;
   const base = await findBridge();
@@ -653,7 +675,36 @@ async function readBoard() {
   return { ...file, base: null, live: false };
 }
 
-async function writeBoard(next, rev, base, boardId = null) {
+/**
+ * Write the board, keeping the project's cast (R51) with it. A kernel
+ * command's result ("exact": commit, undo, redo) is the roster as the writer
+ * now wants it, removals included, and it is lifted onto the record. Any
+ * other state — a board opened, a file imported — joins the cast without
+ * shrinking it ("merge"), and is written composed with the record.
+ */
+async function writeBoard(next, rev, base, boardId = null, roster = "merge") {
+  const held = await readProject();
+  let toWrite = next;
+  if (Array.isArray(held.project.characters)) {
+    let project = held.project;
+    if (roster === "exact") {
+      if (!sameRoster(project.characters, next.characters)) project = { ...project, characters: next.characters, updatedAt: new Date().toISOString() };
+    } else {
+      const merged = mergeRoster(project, next);
+      project = merged.project;
+      toWrite = merged.state;
+    }
+    if (project !== held.project) {
+      const boards = {};
+      for (const [id, state] of Object.entries(held.boards)) boards[id] = withRoster(state, project);
+      boards[boardId ?? project.activeBoardId] = withRoster(toWrite, project);
+      await writeProject(project, boards, held.rev, held.base);
+    }
+  }
+  return writeBoardRaw(toWrite, rev, base, boardId);
+}
+
+async function writeBoardRaw(next, rev, base, boardId = null) {
   if (base === ACCOUNT) return accountWriteBoard(next, rev, boardId);
   if (base) {
     try {
@@ -734,7 +785,7 @@ async function commit(command) {
   // command teaches the agent the board is in a state it is not.
   if (!changed) return { state: next, changed, result, live: base !== null };
 
-  const live = await writeBoard(next, rev, base, boardId);
+  const live = await writeBoard(next, rev, base, boardId, "exact");
   trail.push({ before: state, after: canon(next), what: describeCommand(command) });
   if (trail.length > TRAIL_CAP) trail.shift();
   undone.length = 0;
@@ -873,7 +924,7 @@ function summarize(state) {
       ? `runtime: about ${formatPages(runtime)} pages (an estimate from the cards; a page runs about a minute); no target set — set_target for a pilot (60) or a half-hour (30); against the feature default of 120 it would be ${formatPages(-over)} under`
       : `runtime: about ${formatPages(runtime)} pages of a ${formatPages(state.targetEighths)}-page target — ${over > 0 ? `${formatPages(over)} over` : over < 0 ? `${formatPages(-over)} under` : "on it"} (an estimate from the cards; a page runs about a minute)`,
     `notes: ${state.notes.length}, groups: ${state.groups.length}, arrows: ${state.arrows.length}, cast: ${state.characters.length}`,
-    "cast:",
+    "cast (the project's; every board of it casts from here):",
     cast || "  (no one yet — add_character to start the roster)",
     "places (each phrase is its own place, and the app relates none of them — if two are one place, set_location them the same):",
     places || "  (no card says where it happens yet)",
@@ -1188,14 +1239,16 @@ server.registerTool(
   {
     title: "Read the wall",
     description:
-      "Read the board back: the beats in wall order (rows top to bottom, cards left to right), the pages of scenes between consecutive beats with the cards in each, every setup with the distance to its payoff, and the questions the wall raises — no beat marked yet; a run out of proportion with the others; beats back to back with nothing between them (a chain of them is one question); a card with a placeholder headline or no change line; a card no arrow touches; two headlines that read like the same scene; a group too long to be one sequence; a person in the cast on no card; a person gone for more than a third of the story and ten pages; a payoff before its setup on the wall; a folded card no setup arrow pays off; cards that say no place once any card has one. These are questions, not fixes: put them to the writer and do not act on them unasked. It says nothing about how many beats there should be, and neither should you. The prose carries every id; the JSON after it is the same reading for a program, and PLOTCODER_JSON=0 in the server's environment drops it.",
+      "Read the board back: the beats in wall order (rows top to bottom, cards left to right), the pages of scenes between consecutive beats with the cards in each, every setup with the distance to its payoff, and the questions the wall raises — no beat marked yet; a run out of proportion with the others; beats back to back with nothing between them (a chain of them is one question); a card with a placeholder headline or no change line; a card no arrow touches; two headlines that read like the same scene; a group too long to be one sequence; a person in the cast on no card; a person gone for more than a third of the story and ten pages; a payoff before its setup on the wall; a folded card no setup arrow pays off; cards that say no place once any card has one. These are questions, not fixes: put them to the writer and do not act on them unasked. A question the writer answers with \"leave it\" is left with leave_question and listed under \"left, for now\" instead, until it would read differently. It says nothing about how many beats there should be, and neither should you. The prose carries every id; the JSON after it is the same reading for a program, and PLOTCODER_JSON=0 in the server's environment drops it.",
     inputSchema: {},
   },
   async () => {
     const { state, live, base, boardId: readBoardId } = await readBoard();
     const { project: projectForRead } = await readProject();
     const readBoardMeta = boardById(projectForRead, readBoardId ?? projectForRead.activeBoardId);
-    const reading = readWall(state);
+    const { boards: boardsForRead } = await readProject();
+    const elsewhereForRead = castElsewhere(projectForRead, boardsForRead, readBoardId ?? projectForRead.activeBoardId);
+    const reading = readWall(state, { elsewhere: Object.keys(elsewhereForRead) });
     const runs = describeRuns(reading, state).map((line, index) => {
       const ids = reading.runs[index]?.ids ?? [];
       return ids.length ? `${line} — ${ids.map((id) => `"${state.notes.find((note) => note.id === id)?.headline ?? id}"`).join(", ")}` : line;
@@ -1238,13 +1291,20 @@ server.registerTool(
       "questions the wall raises:",
       ...(reading.findings.length
         ? reading.findings.map((finding) => `  - [${finding.kind}] ${finding.text}${finding.ids.length ? ` (ids: ${finding.ids.join(", ")})` : ""}`)
-        : ["  (none that this reading can see)"]),
+        : [reading.left.length ? "  (none the writer has not left)" : "  (none that this reading can see)"]),
+      ...(reading.left.length
+        ? [
+            "left, for now (the writer's word; kept until the question would read differently, and ask_again brings one back):",
+            ...reading.left.map((finding) => `  - [${finding.kind}] ${finding.text} (left ${String(finding.since).slice(0, 10)}${finding.ids.length ? `; ids: ${finding.ids.join(", ")}` : ""})`),
+          ]
+        : []),
       `checks: ${CHECKS.length} run — ${(() => {
         const asked = reading.findings;
-        if (asked.length === 0) return "asking nothing";
+        const held = reading.left.length ? `, ${reading.left.length} left by the writer` : "";
+        if (asked.length === 0) return `asking nothing${held}`;
         const counts = new Map();
         for (const finding of asked) counts.set(finding.kind, (counts.get(finding.kind) ?? 0) + 1);
-        return `asking ${asked.length} question${asked.length === 1 ? "" : "s"} of ${counts.size} kind${counts.size === 1 ? "" : "s"}: ${[...counts.entries()].map(([kind, n]) => (n > 1 ? `${kind} ×${n}` : kind)).join(", ")}`;
+        return `asking ${asked.length} question${asked.length === 1 ? "" : "s"} of ${counts.size} kind${counts.size === 1 ? "" : "s"}: ${[...counts.entries()].map(([kind, n]) => (n > 1 ? `${kind} ×${n}` : kind)).join(", ")}${held}`;
       })()}; checked and clean: ${CHECKS.filter((kind) => !reading.findings.some((finding) => finding.kind === kind)).map((kind) => {
         if (kind === "unlinked" && state.arrows.length === 0) return "no card without an arrow (not asked: no arrows yet)";
         if (kind === "unplaced" && !state.notes.some((note) => (note.location ?? "").trim())) return "no card without a place (not asked: no card placed yet)";
@@ -1257,6 +1317,60 @@ server.registerTool(
   },
 );
 
+// --- Leaving a question (R53) ----------------------------------------
+
+const sameList = (a, b) => a.length === b.length && a.every((id, index) => id === b[index]);
+
+server.registerTool(
+  "leave_question",
+  {
+    title: "Leave a question, for now",
+    description:
+      "Write the writer's word on a question the wall asks — \"leave it\" — so the reading stops asking it. Pass the question's kind as read_wall names it (sag, empty, unpaid, …) and, when that kind is asked more than once, its ids as read_wall lists them. The wall keeps the question and asks it again on its own the moment it would read differently — a card in it changes, a page moves, the median shifts — so a left question is never a dismissal; ask_again brings one back now. Only on the writer's word: never leave a question unasked.",
+    inputSchema: { kind: z.string().min(1), ids: z.array(z.string()).optional() },
+  },
+  async (args) => {
+    const { state } = await readBoard();
+    const reading = readWall(state);
+    const already = reading.left.filter((finding) => finding.kind === args.kind && (!args.ids || sameList(finding.ids, args.ids)));
+    const matches = reading.findings.filter((finding) => finding.kind === args.kind && (!args.ids || sameList(finding.ids, args.ids)));
+    if (matches.length === 0) {
+      if (already.length) return ok(`Already left: [${args.kind}] ${already[0].text} It stays left until the question would read differently; ask_again brings it back.`);
+      return ok(`The wall is not asking a question of kind "${args.kind}"${args.ids ? ` about ids ${args.ids.join(", ")}` : ""}. read_wall lists the questions it asks now, each with its kind and ids.`);
+    }
+    if (matches.length > 1) {
+      return ok(`The wall asks ${matches.length} questions of kind "${args.kind}"; pass ids to say which:\n${matches.map((finding) => `  - ${finding.text} (ids: ${finding.ids.join(", ")})`).join("\n")}`);
+    }
+    const finding = matches[0];
+    const { result, live } = await commit({ type: "leave_question", kind: finding.kind, ids: finding.ids, text: finding.text });
+    return ok(
+      `Left, for now: [${finding.kind}] ${finding.text}${where(live)} The wall stops asking it and keeps the writer's word; it asks again on its own when the question would read differently, and ask_again brings it back now. read_wall lists it under "left, for now".`,
+      result,
+    );
+  },
+);
+
+server.registerTool(
+  "ask_again",
+  {
+    title: "Ask a left question again",
+    description: "Take back a left question by its kind (and ids, when that kind was left more than once), so the wall asks it again now. Without ids, every left question of that kind comes back.",
+    inputSchema: { kind: z.string().min(1), ids: z.array(z.string()).optional() },
+  },
+  async (args) => {
+    const { state } = await readBoard();
+    const held = (state.left ?? []).filter((item) => item.kind === args.kind && (!args.ids || sameList(item.ids, args.ids)));
+    if (held.length === 0) return ok(`Nothing of kind "${args.kind}"${args.ids ? ` about ids ${args.ids.join(", ")}` : ""} is left. read_wall lists what is, under "left, for now".`);
+    const { result, live } = await commit({ type: "ask_again", kind: args.kind, ids: args.ids });
+    const reading = readWall((await readBoard()).state);
+    const back = reading.findings.filter((finding) => held.some((item) => item.kind === finding.kind && sameList(item.ids, finding.ids)));
+    return ok(
+      `Asked again${where(live)}: ${held.length} question${held.length === 1 ? "" : "s"} of kind "${args.kind}" ${held.length === 1 ? "is" : "are"} no longer left${back.length ? ` — the wall asks ${back.length === 1 ? "it" : `${back.length} of them`} now: ${back.map((finding) => finding.text).join(" ")}` : " — and the wall no longer asks it; the question had already changed"}.`,
+      result,
+    );
+  },
+);
+
 server.registerTool(
   "move_scene",
   {
@@ -1403,7 +1517,7 @@ server.registerTool(
   "list_structures",
   {
     title: "List the structures",
-    description: "The structures apply_template can lay on a wall: the built-in ones, and the writer's own saved from their walls (save_structure), each with its beats.",
+    description: "The structures apply_template can lay on a wall: the built-in ones, and the writer's own saved from their walls (save_structure), each with its beats. compare_structure sets one beside this wall's beats without laying anything.",
     inputSchema: {},
   },
   async () => {
@@ -1413,11 +1527,43 @@ server.registerTool(
       `the writer's own: ${own.length}`,
       ...own.map((structure) => `  - ${structure.id} — "${structure.name}" (${structure.beats.length} beats: ${structure.beats.map((beat) => `${beat.name} at ${Math.round(beat.at * 100)}%`).join(", ")})`),
       `built in: ${TEMPLATES.length} — ${TEMPLATES.map((template) => `${template.id} "${template.name}" (${template.beats.length} beats)`).join(", ")}; each beat's name, prompt and place in the story are in the JSON`,
+      "compare_structure sets one of these beside this wall's beats, page by page, and lays nothing",
     ];
     return ok(lines.join("\n"), { builtIn: TEMPLATES.map((template) => ({ id: template.id, name: template.name, beats: template.beats })), own });
   },
 );
 
+server.registerTool(
+  "compare_structure",
+  {
+    title: "A structure beside the wall",
+    description:
+      "Set a structure beside this wall's beats without laying anything: each of the structure's beats with the page it falls near on this board's target, and the nearest of the wall's own beats within six pages — one to one, in order — with how far off it is (here, near, N pp early or late). A reading, like read_wall: nothing moves and no card is made. Takes a built-in structure by id (turns, three-acts, eight-sequences, fifteen-beats, story-circle) or one of the writer's own by name or id; turns is the default.",
+    inputSchema: { structure: z.string().optional() },
+  },
+  async (args) => {
+    const { state } = await readBoard();
+    const { project } = await readProject();
+    const wanted = (args.structure ?? "turns").trim().toLowerCase();
+    const own = project.structures ?? [];
+    const chosen =
+      TEMPLATES.find((template) => template.id === wanted || template.name.toLowerCase() === wanted) ??
+      own.find((structure) => structure.id === wanted || structure.name.toLowerCase() === wanted);
+    if (!chosen) return ok(`No structure called "${args.structure}". list_structures names the built-in five and the writer's own.`);
+    const comparison = compareStructure(state, chosen.beats);
+    const beats = state.notes.filter((note) => note.rank === "beat").length;
+    const lines = [
+      `"${chosen.name}" beside this wall's ${beats} beat${beats === 1 ? "" : "s"}, of ${formatPages(state.targetEighths)} pages (the story so far runs to p. ${comparison.soFar}); a match is the nearest of the wall's beats within ${MATCH_PAGES} pages, one to one and in order:`,
+      ...describeComparison(comparison).map((line) => `  - ${line}`),
+      comparison.unmatched.length
+        ? `beats of the wall no beat of the structure answers: ${comparison.unmatched.map((beat) => `"${beat.headline}" (p. ${beat.page})`).join(", ")}`
+        : "every beat of the wall answers one of the structure's",
+      beats === 0 ? "No card on this board is marked as a beat (set_rank), so there is nothing to compare; apply_template lays the structure's beats to fill." : "Nothing moved and nothing was made: this is a reading. apply_template lays the beats as cards when the writer wants them.",
+    ];
+    return ok(lines.join("\n"), { structure: { id: chosen.id, name: chosen.name }, ...comparison });
+  },
+);
+
 server.registerTool(
   "save_structure",
   {
@@ -1916,7 +2062,7 @@ server.registerTool(
     trail.pop();
     undone.push(last);
     const { boardId } = await readBoard();
-    const live = await writeBoard(last.before, rev, base, boardId);
+    const live = await writeBoard(last.before, rev, base, boardId, "exact");
     const orderLine = /^(move_scene|organize)/.test(last.what) ? ` Story order now: ${readingOrder(last.before.notes).map((note, index) => `${index + 1}. ${note.headline}`).join(", ")}.` : "";
     const cardsDiff = last.before.notes.length - state.notes.length;
     const countLine = cardsDiff > 0 ? ` ${cardsDiff} card(s) back.` : cardsDiff < 0 ? ` ${-cardsDiff} card(s) gone.` : "";
@@ -1942,7 +2088,7 @@ server.registerTool(
     }
     undone.pop();
     const after = normalizeState(JSON.parse(last.after));
-    const live = await writeBoard(after, rev, base, boardId);
+    const live = await writeBoard(after, rev, base, boardId, "exact");
     trail.push(last);
     return ok(`Redid ${last.what}${where(live)}. ${undone.length} more can be redone. list_board has the board.`, { redid: last.what, notes: after.notes.length, arrows: after.arrows.length, groups: after.groups.length });
   },
@@ -2012,7 +2158,7 @@ server.registerTool(
   {
     title: "Add character",
     description:
-      "Add a person to the board's cast — the roster every card casts from. One record per person: the same name twice is refused and the existing record returned. Add someone here before casting them on a card.",
+      "Add a person to the project's cast — one roster every board of the project casts from, so a person is one record across the pilot and the episodes after it. The same name twice is refused and the existing record returned. Add someone here before casting them on a card.",
     inputSchema: { name: z.string().min(1) },
   },
   async (args) => {
@@ -2022,7 +2168,7 @@ server.registerTool(
         ? ok(`Already in the cast as "${result.name}" (${result.id}). Use that id.`, result)
         : ok("No character added: the name was empty.");
     }
-    return ok(`Added "${result.name}" to the cast${where(live)}.`, result);
+    return ok(`Added "${result.name}" to the project's cast${where(live)}; every board of the project casts from it.`, result);
   },
 );
 
@@ -2161,13 +2307,23 @@ server.registerTool(
   {
     title: "Remove character",
     description:
-      "Remove a person from the cast by id. They leave every card they were on. The cards themselves stay.",
+      "Remove a person from the project's cast by id. They leave every card they were on here; the cards themselves stay. Refused while another board of the project has them on a card: take them off there first.",
     inputSchema: { id: z.string() },
   },
   async (args) => {
+    const { state, boardId } = await readBoard();
+    const person = state.characters.find((character) => character.id === args.id);
+    if (!person) return ok(`No character with id ${args.id}. Call list_board for the cast.`);
+    const { project, boards } = await readProject();
+    const elsewhere = castElsewhere(project, boards, boardId ?? project.activeBoardId)[args.id] ?? [];
+    if (elsewhere.length) {
+      return ok(
+        `"${person.name}" stays: the cast is the project's, and a person leaves it only when no board has them on a card — they are on ${elsewhere.map((item) => `${item.cards} card${item.cards === 1 ? "" : "s"} of "${item.board}"`).join(" and ")}. open_board there and cast them off those cards first, or leave them.`,
+      );
+    }
     const { changed, live } = await commit({ type: "remove_character", id: args.id });
     if (!changed) return ok(`No character with id ${args.id}. Call list_board for the cast.`);
-    return ok(`Removed from the cast and from every card${where(live)}.`);
+    return ok(`Removed "${person.name}" from the project's cast and from every card${where(live)}.`);
   },
 );
 
@@ -2838,7 +2994,7 @@ server.registerTool(
     const fresh = { ...emptyState(), ...(target ? { targetEighths: target } : {}) };
     const { live } = await openBoardEverywhere(next, { ...boards, [board.id]: fresh }, rev, base, board.id);
     return ok(
-      `Added "${board.name}" (${board.id}) and opened it${where(live)}: every card call lands there now, and the writer's open wall switched with it; open_board "${project.boards.findIndex((item) => item.id === project.activeBoardId) + 1}" comes back. It is empty. The logline is the story's question when the writer has one — leave it empty rather than invent it — and the cards come next.${next.name === "Untitled project" ? " The project is still \"Untitled project\": rename_project names it." : ""}${next.boards.length === 2 && isSampleWall(isBoardState(boards[next.boards[0].id]) ? normalizeState(boards[next.boards[0].id]) : emptyState()) ? " The sample stays as Board 1; delete_board drops it." : ""}`,
+      `Added "${board.name}" (${board.id}) and opened it${where(live)}: every card call lands there now, and the writer's open wall switched with it; open_board "${project.boards.findIndex((item) => item.id === project.activeBoardId) + 1}" comes back. It is empty, and the project's cast is already there to cast from. The logline is the story's question when the writer has one — leave it empty rather than invent it — and the cards come next.${next.name === "Untitled project" ? " The project is still \"Untitled project\": rename_project names it." : ""}${next.boards.length === 2 && isSampleWall(isBoardState(boards[next.boards[0].id]) ? normalizeState(boards[next.boards[0].id]) : emptyState()) ? " The sample stays as Board 1; delete_board drops it." : ""}`,
       board,
     );
   },

package/src/board/compareStructure.d.ts

@@ -0,0 +1,32 @@
+// Type surface for compareStructure.js — a structure beside the wall (R52).
+
+import type { BoardState } from "./reducer";
+
+export declare const MATCH_PAGES: number;
+export declare const NEAR_PAGES: number;
+
+export type ComparedBeat = {
+  name: string;
+  at: number;
+  /** The page the structure's beat falls near on this board's target. */
+  page: number;
+  /** The wall's beat that answers it, or null. */
+  match: { id: string; headline: string; page: number } | null;
+  /** Pages the wall's beat is off by: negative is early. Null with no match. */
+  drift: number | null;
+  /** No match, and the page is past the story so far. */
+  beyond: boolean;
+};
+
+export type StructureComparison = {
+  rows: ComparedBeat[];
+  /** The wall's beats no beat of the structure took. */
+  unmatched: Array<{ id: string; headline: string; page: number }>;
+  /** Pages on the wall so far. */
+  soFar: number;
+  targetEighths: number;
+};
+
+export declare function compareStructure(state: BoardState, beats: ReadonlyArray<{ name: string; at: number }>): StructureComparison;
+export declare function driftWord(drift: number | null | undefined): string | null;
+export declare function describeComparison(comparison: StructureComparison): string[];

package/src/board/compareStructure.js

@@ -0,0 +1,85 @@
+// A structure beside the wall (R52).
+//
+// A structure's beats each carry the share of the story they tend to fall
+// near. Laying one out makes cards; this is the other thing the sheet's
+// words promise — a comparison. Each of the structure's beats gets the page
+// it falls near on this board's target, and the nearest of the wall's own
+// beats within reach, one to one and in order, with how far off it is. A
+// reading, like read_wall: it moves nothing and makes nothing.
+//
+// Pure and DOM-free, like the kernel: the sheet, the strip and the MCP
+// server all read the same rows.
+
+import { readingOrder } from "./readWall.js";
+import { EIGHTHS_PER_PAGE, noteEighths } from "./reducer.js";
+import { beatPage } from "./templates.js";
+
+/** Within this many pages a beat of the wall answers a beat of the structure. */
+export const MATCH_PAGES = 6;
+/** Within this many pages the match is "near" rather than early or late. */
+export const NEAR_PAGES = 2;
+
+/**
+ * Set a structure's beats beside this wall's. `beats` are a template's or a
+ * saved structure's: `{ name, at }`. The wall's beats are taken in reading
+ * order; each of the structure's takes the nearest wall beat not yet taken
+ * and not before the last one taken, within MATCH_PAGES, so the matching
+ * never crosses.
+ */
+export function compareStructure(state, beats) {
+  const order = readingOrder(state.notes);
+  const wallBeats = [];
+  let at = 0;
+  for (const note of order) {
+    if (note.rank === "beat") {
+      wallBeats.push({ id: note.id, headline: note.headline, page: Math.floor(at / EIGHTHS_PER_PAGE) + 1 });
+    }
+    at += noteEighths(note);
+  }
+  const soFar = Math.ceil(at / EIGHTHS_PER_PAGE);
+  let from = 0;
+  const taken = new Set();
+  const rows = beats.map((beat) => {
+    const page = beatPage(beat.at, state.targetEighths);
+    let best = -1;
+    for (let i = from; i < wallBeats.length; i += 1) {
+      const gap = Math.abs(wallBeats[i].page - page);
+      if (gap > MATCH_PAGES) continue;
+      if (best < 0 || gap < Math.abs(wallBeats[best].page - page)) best = i;
+    }
+    if (best >= 0) {
+      taken.add(best);
+      from = best + 1;
+    }
+    const match = best >= 0 ? wallBeats[best] : null;
+    return {
+      name: beat.name,
+      at: beat.at,
+      page,
+      match,
+      drift: match ? match.page - page : null,
+      // No match and the page is past the story so far: nothing is there yet.
+      beyond: !match && page > soFar,
+    };
+  });
+  const unmatched = wallBeats.filter((_, index) => !taken.has(index));
+  return { rows, unmatched, soFar, targetEighths: state.targetEighths };
+}
+
+/** The drift as a word or two: here, near, 3 pp early, 12 pp late. */
+export function driftWord(drift) {
+  if (drift === null || drift === undefined) return null;
+  if (drift === 0) return "here";
+  if (Math.abs(drift) <= NEAR_PAGES) return "near";
+  return drift < 0 ? `${-drift} pp early` : `${drift} pp late`;
+}
+
+/** One line per row, for a reply or a sheet: the structure's beat, its page, and the wall's answer. */
+export function describeComparison(comparison) {
+  return comparison.rows.map((row) => {
+    const head = `${row.name} (p. ${row.page})`;
+    if (row.match) return `${head} — yours: "${row.match.headline}" p. ${row.match.page} · ${driftWord(row.drift)}`;
+    if (row.beyond) return `${head} — nothing yet: past p. ${comparison.soFar}, the story so far`;
+    return `${head} — none of yours within ${MATCH_PAGES} pages`;
+  });
+}

package/src/board/project.d.ts

@@ -1,6 +1,6 @@
 // Type surface for project.js — the project record (R35).
 
-import type { BoardNote } from "./reducer";
+import type { BoardCharacter, BoardNote, BoardState } from "./reducer";
 
 export declare const PROJECT_VERSION: number;
 export declare const DEFAULT_PROJECT_NAME: string;
@@ -22,6 +22,8 @@ export type ProjectRecord = {
   activeBoardId: string;
   /** A writer's own structures, saved from a wall's beats (Roadmap 2, item 7). */
   structures?: OwnStructure[];
+  /** The project's cast (R51): one roster every board draws from. Absent until liftCast has run. */
+  characters?: BoardCharacter[];
   createdAt: string;
   updatedAt: string;
 };
@@ -70,3 +72,19 @@ export declare function reidentifyProject(
   project: ProjectRecord,
   now?: string,
 ): ProjectRecord & { renamed: Record<string, string> };
+
+/** A board's state composed with the project's cast (R51). */
+export declare function withRoster(state: BoardState, project: ProjectRecord): BoardState;
+export declare function sameRoster(a: BoardCharacter[] | undefined, b: BoardCharacter[] | undefined): boolean;
+export declare function liftCast(
+  project: ProjectRecord,
+  boards: Record<string, BoardState>,
+  now?: string,
+): { project: ProjectRecord; boards: Record<string, BoardState>; changed: boolean };
+export type CastElsewhere = Record<string, Array<{ board: string; boardId: string; cards: number }>>;
+export declare function castElsewhere(project: ProjectRecord, boards: Record<string, BoardState>, activeBoardId: string): CastElsewhere;
+export declare function mergeRoster(
+  project: ProjectRecord,
+  state: BoardState,
+  now?: string,
+): { project: ProjectRecord; state: BoardState };

package/src/board/project.js

@@ -9,7 +9,7 @@
 // Plain ESM with a sibling .d.ts, like the kernel, so the browser store and the
 // MCP server share one idea of what a project is. Keep it free of `window`.
 
-import { newId, noteEighths, nowIso } from "./reducer.js";
+import { CHARACTER_FIELDS, fillCharacter, isCharacter, newId, normalizeState, noteEighths, nowIso, sameName } from "./reducer.js";
 
 export const PROJECT_VERSION = 2;
 export const DEFAULT_PROJECT_NAME = "Untitled project";
@@ -75,7 +75,7 @@ export function normalizeProject(value, now = nowIso()) {
     : [];
   // `renamed` is reidentifyProject's map for the store, never part of the record.
   const { renamed: _renamed, ...rest } = value;
-  return {
+  const record = {
     ...rest,
     version: PROJECT_VERSION,
     name: trimmed(value.name, DEFAULT_PROJECT_NAME),
@@ -86,6 +86,138 @@ export function normalizeProject(value, now = nowIso()) {
     createdAt: typeof value.createdAt === "string" ? value.createdAt : now,
     updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : now,
   };
+  // The project's cast (R51). A record with none has not been lifted yet —
+  // its boards still carry their own rosters — and liftCast does that at the
+  // next load boundary; so absent stays absent, and never becomes [].
+  if (Array.isArray(value.characters)) record.characters = value.characters.filter(isCharacter).map(fillCharacter);
+  else delete record.characters;
+  return record;
+}
+
+// --- The project's cast (R51) -----------------------------------------
+//
+// One roster for the project, on the record, that every board draws from.
+// A board's state still carries `characters`, but as a copy of the
+// project's: every load boundary composes it with withRoster, and every
+// store lifts a roster a kernel command changed back onto the record. So
+// the kernel, the readings and the wall go on reading state.characters,
+// and there is one Nessa across the pilot and episode two.
+
+/** A board's state with the project's cast in it; unknown cast ids on cards drop. */
+export function withRoster(state, project) {
+  if (!Array.isArray(project.characters) || sameRoster(project.characters, state.characters)) return state;
+  const next = normalizeState({ ...state, characters: project.characters });
+  return next.characters === project.characters ? next : { ...next, characters: project.characters };
+}
+
+/** True when two rosters are the same people with the same pages. */
+export function sameRoster(a, b) {
+  if (a === b) return true;
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  return a.every((character, index) => {
+    const other = b[index];
+    return other && character.id === other.id && character.name === other.name && CHARACTER_FIELDS.every((field) => (character[field] ?? "") === (other[field] ?? ""));
+  });
+}
+
+/**
+ * Lift the cast onto the project. A record that already has one composes
+ * every board with it. A record with none — written before R51 — takes the
+ * boards' rosters in board order and merges them by name: the first record
+ * of a name keeps its id, later ones fold into it (a page line fills from the
+ * first board that had it), and every card that cast a folded id casts the
+ * kept one. Returns the record, every board composed, and whether anything
+ * changed.
+ */
+export function liftCast(project, boards, now = nowIso()) {
+  if (Array.isArray(project.characters)) {
+    let changed = false;
+    const out = {};
+    for (const [id, state] of Object.entries(boards)) {
+      const next = withRoster(state, project);
+      if (next !== state) changed = true;
+      out[id] = next;
+    }
+    return { project, boards: out, changed };
+  }
+  const roster = [];
+  const folded = {};
+  const order = [
+    ...project.boards.map((meta) => meta.id).filter((id) => boards[id]),
+    ...Object.keys(boards).filter((id) => !project.boards.some((meta) => meta.id === id)),
+  ];
+  for (const boardId of order) {
+    const map = {};
+    for (const character of boards[boardId].characters ?? []) {
+      if (!isCharacter(character)) continue;
+      const kept = roster.find((item) => sameName(item.name, character.name));
+      if (!kept) {
+        roster.push(fillCharacter({ ...character }));
+        continue;
+      }
+      map[character.id] = kept.id;
+      for (const field of CHARACTER_FIELDS) {
+        if (!kept[field].trim() && typeof character[field] === "string" && character[field].trim()) kept[field] = character[field];
+      }
+    }
+    folded[boardId] = map;
+  }
+  const lifted = { ...project, characters: roster, updatedAt: now };
+  const out = {};
+  for (const [boardId, state] of Object.entries(boards)) {
+    const map = folded[boardId] ?? {};
+    const notes = state.notes.map((note) => {
+      const ids = [...new Set(note.characterIds.map((id) => map[id] ?? id))];
+      return ids.length === note.characterIds.length && ids.every((id, index) => id === note.characterIds[index]) ? note : { ...note, characterIds: ids };
+    });
+    out[boardId] = normalizeState({ ...state, notes, characters: roster });
+  }
+  return { project: lifted, boards: out, changed: true };
+}
+
+/**
+ * A board with a roster of its own — an imported file, a board opened from
+ * elsewhere — joins the project's cast without shrinking it: a name the
+ * project already has keeps the project's record (its cards recast to that
+ * id), a new name is appended with the record it came with. Returns the
+ * record and the board composed with it.
+ */
+export function mergeRoster(project, state, now = nowIso()) {
+  if (!Array.isArray(project.characters)) return { project, state };
+  const roster = [...project.characters];
+  const map = {};
+  let grew = false;
+  for (const character of state.characters ?? []) {
+    if (!isCharacter(character)) continue;
+    const kept = roster.find((item) => sameName(item.name, character.name));
+    if (kept) {
+      if (kept.id !== character.id) map[character.id] = kept.id;
+      continue;
+    }
+    roster.push(fillCharacter({ ...character }));
+    grew = true;
+  }
+  const next = grew ? { ...project, characters: roster, updatedAt: now } : project;
+  const notes = state.notes.map((note) => {
+    const ids = [...new Set(note.characterIds.map((id) => map[id] ?? id))];
+    return ids.length === note.characterIds.length && ids.every((id, index) => id === note.characterIds[index]) ? note : { ...note, characterIds: ids };
+  });
+  const recast = notes.some((note, index) => note !== state.notes[index]) ? { ...state, notes } : state;
+  return { project: next, state: withRoster(recast, next) };
+}
+
+/** Which other boards of the project have each person on a card: id -> [{ board, cards }]. */
+export function castElsewhere(project, boards, activeBoardId) {
+  const map = {};
+  for (const meta of project.boards) {
+    if (meta.id === activeBoardId) continue;
+    const state = boards[meta.id];
+    if (!state) continue;
+    const counts = {};
+    for (const note of state.notes) for (const id of note.characterIds ?? []) counts[id] = (counts[id] ?? 0) + 1;
+    for (const [id, cards] of Object.entries(counts)) (map[id] ??= []).push({ board: meta.name, boardId: meta.id, cards });
+  }
+  return map;
 }
 
 function touch(project, patch, now) {

package/src/board/readWall.d.ts

@@ -63,11 +63,20 @@ export type WallReading = {
   payoffs: Record<string, string[]>;
   /** Folded cards that pay off on another board of the project (R50): the card and the board. */
   later: { id: string; boardId: string }[];
+  /** The questions the wall asks now. A left one (R53) is not here while its words hold. */
   findings: Finding[];
+  /** Questions the writer has left, for now: the same question, with when it was left. */
+  left: Array<Finding & { since: string }>;
 };
 
 /** Rows top to bottom, cards left to right within a row. */
 export declare function readingOrder(notes: BoardNote[]): BoardNote[];
-export declare function readWall(state: BoardState): WallReading;
+export declare function readWall(
+  state: BoardState,
+  options?: {
+    /** Cast ids on a card of another board of the project (R51): not asked about as uncast here. */
+    elsewhere?: string[];
+  },
+): WallReading;
 export declare function describeRuns(reading: WallReading, state: BoardState): string[];
 export declare function describeSetups(reading: WallReading, state: BoardState): string[];

package/src/board/readWall.js

@@ -110,7 +110,10 @@ function list(notes) {
  * Read the board. Returns the reading and the findings; see readWall.d.ts for
  * the shape. Never mutates the state.
  */
-export function readWall(state) {
+export function readWall(state, options = {}) {
+  // People on a card of another board of the project (R51) are cast, and
+  // are not asked about here.
+  const elsewhere = new Set(Array.isArray(options.elsewhere) ? options.elsewhere : []);
   const order = readingOrder(state.notes);
   const beats = order.filter((note) => note.rank === "beat");
 
@@ -334,6 +337,7 @@ export function readWall(state) {
   for (const character of state.characters ?? []) {
     const scenes = order.filter((note) => note.characterIds?.includes(character.id));
     if (scenes.length === 0) {
+      if (elsewhere.has(character.id)) continue;
       findings.push({
         kind: "uncast",
         ids: [character.id],
@@ -372,6 +376,21 @@ export function readWall(state) {
     }
   }
 
+  // A question the writer has left (R53) is held back while it is still the
+  // same question — same kind, same cards, same words. The moment it would
+  // read differently (a page moved, a headline changed, the median shifted)
+  // it is a new question and is asked. The kernel never decides this; the
+  // reading does, on every read.
+  const left = [];
+  const asked = findings.filter((finding) => {
+    const entry = (state.left ?? []).find(
+      (item) => item.kind === finding.kind && sameList(item.ids, finding.ids) && item.text === finding.text,
+    );
+    if (!entry) return true;
+    left.push({ ...finding, since: entry.since });
+    return false;
+  });
+
   return {
     order: order.map((note) => note.id),
     beats: beats.map((note) => ({ id: note.id, headline: note.headline })),
@@ -379,10 +398,15 @@ export function readWall(state) {
     setups,
     payoffs,
     later,
-    findings,
+    findings: asked,
+    left,
   };
 }
 
+function sameList(a, b) {
+  return a.length === b.length && a.every((id, index) => id === b[index]);
+}
+
 /** The setups as prose lines: what plants what, and how far apart. */
 export function describeSetups(reading, state) {
   const byId = new Map(state.notes.map((note) => [note.id, note]));

package/src/board/reducer.d.ts

@@ -117,10 +117,25 @@ export type BoardState = {
   lock: import("./numbering").Lock | null;
   /** The revision in progress — a name, a colour, a snapshot — or null. */
   revision: import("./numbering").Revision | null;
+  /** Questions the writer has left, for now (R53): kept until the question would read differently. */
+  left: LeftQuestion[];
+};
+
+/** A question the wall asked and the writer left (R53). */
+export type LeftQuestion = {
+  kind: string;
+  ids: string[];
+  /** The question's words when it was left; it comes back when they would differ. */
+  text: string;
+  since: string;
 };
 
 export type Pose = { id: string; x: number; y: number; rotate: number };
 
+export declare function isCharacter(value: unknown): value is { id: string; name: string };
+export declare function fillCharacter(character: { id: string; name: string } & Partial<BoardCharacter>): BoardCharacter;
+export declare function sameName(a: string, b: string): boolean;
+
 export type Command =
   | { type: "set_logline"; logline: string }
   | { type: "set_rank"; ids: string[]; rank: NoteRank }
@@ -170,7 +185,9 @@ export type Command =
   | { type: "lock_numbers"; order?: string[] }
   | { type: "unlock_numbers" }
   | { type: "start_revision"; name: string; color?: string }
-  | { type: "end_revision" };
+  | { type: "end_revision" }
+  | { type: "leave_question"; kind: string; ids: string[]; text: string }
+  | { type: "ask_again"; kind: string; ids?: string[] };
 
 export type CommandResult = {
   state: BoardState;

package/src/board/reducer.js

@@ -33,7 +33,7 @@ import { lockFrom, REVISION_COLORS } from "./numbering.js";
 // same person on every card. Long term the record grows — what they look like,
 // the details a writer needs to pull up — which is why it has an id and
 // timestamps now rather than being a word on a card.
-function isCharacter(value) {
+export function isCharacter(value) {
   return Boolean(value) && typeof value.id === "string" && typeof value.name === "string";
 }
 
@@ -45,7 +45,7 @@ function isCharacter(value) {
 export const CHARACTER_FIELDS = ["looks", "voice", "wants", "needs", "notes"];
 
 /** A roster record with every page field present, so the page never reads undefined. */
-function fillCharacter(character) {
+export function fillCharacter(character) {
   let filled = character;
   for (const field of CHARACTER_FIELDS) {
     if (typeof filled[field] !== "string") {
@@ -93,7 +93,7 @@ export function atPlace(note, place) {
   return Boolean(note.location) && samePlace(note.location, place);
 }
 
-function sameName(a, b) {
+export function sameName(a, b) {
   return a.trim().toLowerCase() === b.trim().toLowerCase();
 }
 
@@ -101,6 +101,19 @@ function sameIds(a, b) {
   return a.length === b.length && a.every((id, index) => id === b[index]);
 }
 
+/** A question the writer has left (R53): its kind, the cards it was about, and the words it had. */
+function isLeftQuestion(value) {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    typeof value.kind === "string" &&
+    Array.isArray(value.ids) &&
+    value.ids.every((id) => typeof id === "string") &&
+    typeof value.text === "string" &&
+    typeof value.since === "string"
+  );
+}
+
 /** Keep only ids that name someone in the roster, once each, in the order given. */
 function knownCast(ids, characters) {
   if (!Array.isArray(ids)) return [];
@@ -213,6 +226,7 @@ export function emptyState() {
     arrows: [],
     lock: null,
     revision: null,
+    left: [],
   };
 }
 
@@ -259,6 +273,7 @@ export function seedState(now = nowIso()) {
     arrows: [],
     lock: null,
     revision: null,
+    left: [],
   };
 }
 
@@ -355,6 +370,10 @@ export function normalizeState(value) {
   // lock and no revision; both are null until a draft goes out.
   const lock = value.lock && typeof value.lock === "object" && value.lock.numbers ? value.lock : null;
   const revision = value.revision && typeof value.revision === "object" && typeof value.revision.name === "string" ? value.revision : null;
+  // Boards written before R53 have no left questions: nothing is left until
+  // the writer leaves it.
+  const left = Array.isArray(value.left) ? value.left.filter(isLeftQuestion) : [];
+  const leftPatched = !Array.isArray(value.left) || left.length !== value.left.length;
   if (
     value.logline === logline &&
     value.targetEighths === targetEighths &&
@@ -362,7 +381,8 @@ export function normalizeState(value) {
     !arrowsPatched &&
     !patched &&
     value.lock === lock &&
-    value.revision === revision
+    value.revision === revision &&
+    !leftPatched
   ) {
     return value;
   }
@@ -375,6 +395,7 @@ export function normalizeState(value) {
     arrows: arrowsPatched ? arrows : value.arrows,
     lock,
     revision,
+    left,
   };
 }
 
@@ -879,6 +900,31 @@ export function applyCommand(state, command, now = nowIso()) {
       return { state: { ...state, revision: null }, changed: true, result: null };
     }
 
+    // Leaving a question (R53): the writer's word on a question the wall
+    // asks, written on the wall as the question's kind, the cards it was
+    // about and the words it had. The reading holds it back while a question
+    // with those words is still what the wall would ask, and asks again on
+    // its own the moment the question would read differently. Never a
+    // dismissal: the kernel records the word; the reading decides.
+    case "leave_question": {
+      const kind = typeof command.kind === "string" ? command.kind : "";
+      const ids = Array.isArray(command.ids) ? command.ids.filter((id) => typeof id === "string") : [];
+      const text = typeof command.text === "string" ? command.text : "";
+      if (!kind || !text) return { state, changed: false };
+      const entry = { kind, ids, text, since: now };
+      const rest = (state.left ?? []).filter((item) => !(item.kind === kind && sameIds(item.ids, ids)));
+      return { state: { ...state, left: [...rest, entry] }, changed: true, result: entry };
+    }
+
+    case "ask_again": {
+      const kind = typeof command.kind === "string" ? command.kind : "";
+      const ids = Array.isArray(command.ids) ? command.ids : null;
+      const gone = (state.left ?? []).filter((item) => item.kind === kind && (!ids || sameIds(item.ids, ids)));
+      if (gone.length === 0) return { state, changed: false };
+      const left = (state.left ?? []).filter((item) => !gone.includes(item));
+      return { state: { ...state, left }, changed: true, result: gone };
+    }
+
     // Where a scene happens (R37): one place on one or more cards; an empty
     // place clears it.
     case "set_location": {