plotcoder-board 0.1.0

package/src/board/fountain.js

@@ -0,0 +1,246 @@
+// Fountain out (R23, slice a; roadmap item 8).
+//
+// The wall as a Fountain document: a plain-text screenplay a writer can open
+// in any Fountain editor and paginate. One card is one scene, in wall order:
+// a forced scene heading from the place (or the headline when the card has
+// no place), the headline as a synopsis, the change line as action, and the
+// cast and the fold as notes. Beats open sections, so an outline view shows
+// the story's turns. Nothing here is a page yet: this is the stepping stone
+// from the wall to a document, in the wall's own words.
+//
+// Fountain marks used: `Title:` block; `# ` section; `.` forced heading;
+// `= ` synopsis; `[[ ]]` note. All of them are invisible on the printed page
+// except the heading and the action.
+
+import { formatPages, boardEighths } from "./reducer.js";
+import { readingOrder } from "./readWall.js";
+
+function upper(text) {
+  return text.trim().replace(/\s+/g, " ").toUpperCase();
+}
+
+/** A forced scene heading: the place, or the headline when the card has none. */
+export function sceneHeading(note) {
+  const place = typeof note.location === "string" ? note.location.trim() : "";
+  const words = place || note.headline || "UNTITLED";
+  return `.${upper(words)}`;
+}
+
+/** The title page block. `titles` is what the writer would put above the script. */
+export function titlePage({ title, credit, author, draftDate, notes }) {
+  const lines = [];
+  if (title) lines.push(`Title: ${title}`);
+  if (credit) lines.push(`Credit: ${credit}`);
+  if (author) lines.push(`Author: ${author}`);
+  if (draftDate) lines.push(`Draft date: ${draftDate}`);
+  if (notes && notes.length) {
+    lines.push("Notes:");
+    for (const line of notes) lines.push(`\t${line}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * The whole wall as Fountain text.
+ *
+ * @param state the board
+ * @param options.title the board's name; options.project the project's name
+ *   (a series title); options.premise; options.draftDate an ISO date string
+ */
+export function toFountain(state, options = {}) {
+  const nameOf = new Map((state.characters ?? []).map((character) => [character.id, character.name]));
+  const order = readingOrder(state.notes);
+  const beats = order.filter((note) => note.rank === "beat").length;
+
+  const notes = [];
+  if (options.premise) notes.push(`Premise: ${options.premise}`);
+  if (state.logline) notes.push(`Logline: ${state.logline}`);
+  notes.push(
+    `From the wall: ${order.length} card${order.length === 1 ? "" : "s"}, ${beats} beat${beats === 1 ? "" : "s"}, about ${formatPages(boardEighths(state))} of ${formatPages(state.targetEighths)} pages.`,
+  );
+
+  const head = titlePage({
+    title: options.title || "Untitled",
+    credit: options.project && options.project !== options.title ? `An episode of ${options.project}` : undefined,
+    author: options.author,
+    draftDate: options.draftDate ? options.draftDate.slice(0, 10) : undefined,
+    notes,
+  });
+
+  const body = [];
+  let beat = 0;
+  for (const note of order) {
+    if (note.rank === "beat") {
+      beat += 1;
+      body.push(`# ${beat}. ${note.headline || "Untitled beat"}`);
+      body.push("");
+    }
+    body.push(sceneHeading(note));
+    body.push("");
+    if (note.headline && sceneHeading(note) !== `.${upper(note.headline)}`) {
+      body.push(`= ${note.headline}`);
+      body.push("");
+    }
+    const marks = [];
+    const cast = (note.characterIds ?? []).map((id) => nameOf.get(id)).filter(Boolean);
+    if (cast.length) marks.push(`with ${cast.join(", ")}`);
+    if (note.plants) marks.push("plants something to pay off later");
+    if (marks.length) {
+      body.push(`[[${marks.join(" · ")}]]`);
+      body.push("");
+    }
+    // The scene's text when it is written; the change line stands in until then.
+    body.push(note.text && note.text.trim() ? note.text.trim() : note.change || "");
+    body.push("");
+  }
+
+  return `${head}\n\n${body.join("\n").trimEnd()}\n`;
+}
+
+// --- Fountain in (R23, slice b) ---------------------------------------------
+
+const HEADING = /^(\.(?!\.)\s*(.+)|(?:INT|EXT|EST|INT\.?\/EXT|I\/E)[.\s].*)$/i;
+
+/**
+ * A Fountain document as scenes: heading, synopsis, section, and the body
+ * lines under the heading. Title-page keys, sections (`#`), synopses (`=`),
+ * notes (`[[ ]]`) and boneyards (slash-star comments) are read and kept out
+ * of the body, so what comes back onto a card is the writing.
+ */
+export function fromFountain(text) {
+  const lines = text.replace(/\r\n?/g, "\n").split("\n");
+  const titles = {};
+  let i = 0;
+  // Title page: `Key: value` lines (values may continue on indented lines) up to the first blank line.
+  if (/^[A-Za-z][A-Za-z ]*:/.test(lines[0] ?? "")) {
+    let key = null;
+    while (i < lines.length && lines[i].trim() !== "") {
+      const match = /^([A-Za-z][A-Za-z ]*):\s*(.*)$/.exec(lines[i]);
+      if (match && !/^\s/.test(lines[i])) {
+        key = match[1].trim().toLowerCase();
+        titles[key] = match[2].trim();
+      } else if (key) {
+        titles[key] = `${titles[key]}${titles[key] ? "\n" : ""}${lines[i].trim()}`;
+      }
+      i += 1;
+    }
+  }
+  const scenes = [];
+  let current = null;
+  let section = null;
+  let inBoneyard = false;
+  for (; i < lines.length; i += 1) {
+    const raw = lines[i];
+    const line = raw.trim();
+    if (inBoneyard) {
+      if (line.includes("*/")) inBoneyard = false;
+      continue;
+    }
+    if (line.startsWith("/*")) {
+      if (!line.includes("*/")) inBoneyard = true;
+      continue;
+    }
+    if (line.startsWith("#")) {
+      section = line.replace(/^#+\s*/, "");
+      continue;
+    }
+    const heading = HEADING.exec(line);
+    if (heading) {
+      current = {
+        heading: (heading[2] ?? line).trim().replace(/\s+/g, " "),
+        forced: line.startsWith("."),
+        synopsis: "",
+        section,
+        notes: [],
+        body: [],
+      };
+      scenes.push(current);
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("=")) {
+      current.synopsis = `${current.synopsis}${current.synopsis ? " " : ""}${line.replace(/^=+\s*/, "")}`.trim();
+      continue;
+    }
+    if (line.startsWith("[[") && line.endsWith("]]")) {
+      current.notes.push(line.slice(2, -2).trim());
+      continue;
+    }
+    current.body.push(raw.replace(/\s+$/, ""));
+  }
+  for (const scene of scenes) {
+    while (scene.body.length && scene.body[0].trim() === "") scene.body.shift();
+    while (scene.body.length && scene.body.at(-1).trim() === "") scene.body.pop();
+    scene.text = scene.body.join("\n");
+    delete scene.body;
+  }
+  return { titles, scenes };
+}
+
+function sameWords(a, b) {
+  return a.trim().replace(/\s+/g, " ").toLowerCase() === b.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+/**
+ * Lay a parsed document onto the wall: the commands that write each scene's
+ * text onto the card with the same heading (its place, or its headline) in
+ * order, and create a card for a scene the wall does not have, after the
+ * last matched one. Never deletes; a card the document does not mention keeps
+ * its text. Returns commands for the kernel, so every door applies the same.
+ */
+export function mergeFountain(state, parsed) {
+  const order = readingOrder(state.notes);
+  const used = new Set();
+  const commands = [];
+  let cursor = 0; // where in the wall's order the last match was
+  const matched = [];
+  for (const scene of parsed.scenes) {
+    const headingOf = (note) => sceneHeading(note).slice(1);
+    const wanted = scene.heading.toUpperCase();
+    // First: the same heading at or after the cursor; then anywhere unused;
+    // then a card whose headline is the synopsis.
+    let found =
+      order.slice(cursor).find((note) => !used.has(note.id) && sameWords(headingOf(note), wanted)) ??
+      order.find((note) => !used.has(note.id) && sameWords(headingOf(note), wanted)) ??
+      (scene.synopsis ? order.find((note) => !used.has(note.id) && sameWords(note.headline, scene.synopsis)) : undefined);
+    if (found) {
+      used.add(found.id);
+      cursor = order.indexOf(found) + 1;
+      // A scene whose body is the card's own change line is the export of an
+      // unwritten card coming back: still unwritten, not a page.
+      const standIn = !(found.text ?? "").trim() && sameWords(scene.text, found.change ?? "");
+      if ((found.text ?? "") !== scene.text && !standIn) {
+        commands.push({ type: "set_text", id: found.id, text: scene.text });
+      }
+      matched.push({ id: found.id, heading: scene.heading, created: false });
+      continue;
+    }
+    // A new card, after the last matched one on the wall.
+    const anchor = order[cursor - 1] ?? order.at(-1);
+    const headline = scene.synopsis || titleCase(scene.heading);
+    const isPlace = scene.forced && Boolean(scene.synopsis);
+    const id = `scene-${Math.random().toString(36).slice(2, 8)}`;
+    commands.push({
+      type: "create_note",
+      id,
+      headline,
+      change: scene.text ? firstSentence(scene.text) : "What changes?",
+      location: isPlace ? titleCase(scene.heading) : "",
+      text: scene.text,
+      x: anchor ? anchor.x + 40 : 140,
+      y: anchor ? anchor.y + 40 : 140,
+    });
+    used.add(id);
+    matched.push({ id, heading: scene.heading, created: true });
+  }
+  return { commands, matched };
+}
+
+function titleCase(words) {
+  return words.toLowerCase().replace(/(^|\s)([a-z])/g, (m) => m.toUpperCase());
+}
+
+function firstSentence(text) {
+  const first = text.trim().split(/(?<=[.!?])\s+/)[0] ?? "";
+  return first.slice(0, 120);
+}

package/src/board/numbering.d.ts

@@ -0,0 +1,13 @@
+// Type surface for numbering.js — locked scene numbers and revision marks (Roadmap 2, item 8).
+
+import type { BoardNote } from "./reducer";
+
+export type Lock = { at: string; numbers: Record<string, string> };
+export type Snapshot = { headline: string; change: string; location: string; text: string };
+export type Revision = { name: string; color: string; since: string; snapshot: Record<string, Snapshot> };
+
+export declare function sceneNumbers(order: ReadonlyArray<Pick<BoardNote, "id">>, lock: Lock | null | undefined): Map<string, string>;
+export declare function lockFrom(order: ReadonlyArray<Pick<BoardNote, "id">>, existing: Lock | null | undefined, at: string): Lock;
+export declare function revisedLines(text: string | undefined, snapshotText: string | null | undefined): number[];
+export declare function isRevised(note: BoardNote, snapshot: Snapshot | undefined): boolean;
+export declare const REVISION_COLORS: readonly string[];

package/src/board/numbering.js

@@ -0,0 +1,89 @@
+// Locked scene numbers and revision marks (Roadmap 2, item 8; question 23).
+//
+// Until a draft goes out, scene numbers follow the wall's order. Lock them
+// and they stop moving: every scene keeps the number it had, a scene added
+// between 14 and 15 is 14A (then 14B), one added before the first is A1, and
+// moving cards never renumbers what is locked. A revision is a name and a
+// colour over a snapshot of the scenes; a line that differs from the snapshot
+// is marked, so the changed lines print in the revision's colour with a star.
+// All pure: the kernel holds the lock and the snapshot, this module reads them.
+
+const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+function letter(index) {
+  return index < LETTERS.length ? LETTERS[index] : `${LETTERS[Math.floor(index / LETTERS.length) - 1]}${LETTERS[index % LETTERS.length]}`;
+}
+
+/**
+ * Scene numbers for cards in wall order. `lock` is the board's lock, or null:
+ * { numbers: { [noteId]: "14" } }. Returns a Map of id → number as printed.
+ */
+export function sceneNumbers(order, lock) {
+  const numbers = new Map();
+  if (!lock || !lock.numbers) {
+    order.forEach((note, index) => numbers.set(note.id, String(index + 1)));
+    return numbers;
+  }
+  let lastLocked = null;
+  let sinceLocked = 0;
+  const leading = [];
+  for (const note of order) {
+    const locked = lock.numbers[note.id];
+    if (locked) {
+      // Scenes before the first locked one count backwards from it: A1, B1…
+      if (lastLocked === null && leading.length) {
+        leading.forEach((id, index) => numbers.set(id, `${letter(index)}${locked}`));
+        leading.length = 0;
+      }
+      numbers.set(note.id, locked);
+      lastLocked = locked;
+      sinceLocked = 0;
+      continue;
+    }
+    if (lastLocked === null) {
+      leading.push(note.id);
+      continue;
+    }
+    numbers.set(note.id, `${lastLocked}${letter(sinceLocked)}`);
+    sinceLocked += 1;
+  }
+  // Nothing locked came after: the leading scenes run on from a lock of none.
+  leading.forEach((id, index) => numbers.set(id, `A${index + 1}`));
+  return numbers;
+}
+
+/** The lock to store: every scene's number as it stands, by wall order. */
+export function lockFrom(order, existing, at) {
+  const current = sceneNumbers(order, existing);
+  const numbers = {};
+  for (const note of order) numbers[note.id] = current.get(note.id);
+  return { at, numbers };
+}
+
+/**
+ * The lines of a scene's text that are not in its snapshot: those are the
+ * revised ones. A scene with no snapshot is wholly new, and every line is.
+ */
+export function revisedLines(text, snapshotText) {
+  const now = (text ?? "").replace(/\r\n?/g, "\n").split("\n");
+  if (snapshotText === undefined || snapshotText === null) return now.map((_line, index) => index);
+  const before = new Set(snapshotText.replace(/\r\n?/g, "\n").split("\n").map((line) => line.trim()));
+  const revised = [];
+  now.forEach((line, index) => {
+    if (line.trim() && !before.has(line.trim())) revised.push(index);
+  });
+  return revised;
+}
+
+/** True when anything on the card — headline, change, place, text — differs from the snapshot. */
+export function isRevised(note, snapshot) {
+  if (!snapshot) return true;
+  return (
+    note.headline !== snapshot.headline ||
+    note.change !== snapshot.change ||
+    (note.location ?? "") !== (snapshot.location ?? "") ||
+    (note.text ?? "") !== (snapshot.text ?? "")
+  );
+}
+
+export const REVISION_COLORS = ["white", "blue", "pink", "yellow", "green", "goldenrod", "buff", "salmon", "cherry"];

package/src/board/organize.d.ts

@@ -0,0 +1,24 @@
+// Type surface for organize.js — Organize along the arrows (R34).
+
+import type { BoardState, Pose } from "./reducer";
+
+export declare const ROW_CARDS: number;
+export declare const GAP: number;
+/** A row is five cards wide on the wall, on any screen. */
+export declare const ROW_WIDTH: number;
+
+/**
+ * The cards in story order: "follows" arrows first, reading order to break
+ * ties and cycles. Restricted to `ids` when given.
+ */
+export declare function arrowOrder(state: BoardState, ids?: ReadonlyArray<string>): string[];
+
+/**
+ * Poses for Organize. With beats in scope, a row per beat with long runs
+ * wrapped under themselves; otherwise rows wrapped by width. Groups travel as
+ * blocks. A selection is laid out from its own top-left.
+ */
+export declare function organizePoses(
+  state: BoardState,
+  options?: { onlyIds?: ReadonlyArray<string> },
+): Pose[];

package/src/board/organize.js

@@ -0,0 +1,151 @@
+// Organize along the arrows (R34).
+//
+// Organize was written before an arrow existed and tidied by reading order,
+// which left the arrows pointing every way across a neat grid. Now reading
+// order is the base and each "follows" arrow pulls its source in front of its
+// target, so a card is never placed before something that points at it and a
+// wall with no arrows keeps its order. A two-way pair is a tie on purpose.
+// Setups are not sequence and do not order anything.
+//
+// Two layouts, one Organize: with beats on the wall, each beat starts a row and
+// the scenes that follow it fill the row to its right, wrapping under
+// themselves when a run is long; with no beats yet, rows wrap by width. Groups
+// travel as blocks to where their first card falls. A row is five cards wide
+// on the wall, on any screen (open question 21, closed).
+//
+// Pure and DOM-free like the kernel: the app and the MCP server both call it,
+// and it returns poses for apply_poses rather than touching anything.
+
+import { readingOrder } from "./readWall.js";
+import { NOTE_HEIGHT, NOTE_WIDTH } from "./reducer.js";
+
+export const ROW_CARDS = 5;
+export const GAP = 28;
+export const ROW_WIDTH = ROW_CARDS * NOTE_WIDTH + (ROW_CARDS - 1) * GAP;
+const ORIGIN_X = 88;
+const ORIGIN_Y = 110;
+const STEP_X = NOTE_WIDTH + GAP;
+const STEP_Y = NOTE_HEIGHT + GAP;
+
+/**
+ * The cards in story order. Reading order — the same rows-then-left-to-right
+ * order read the wall uses — is the base; each "follows" arrow pulls its
+ * source in front of its target. So a wall with no arrows keeps its order, and
+ * an arrow moves only what it has to. A two-way pair is a tie and reading
+ * order keeps it; a longer cycle is cut where reading order says. Only the ids
+ * given (or every card) take part; arrows to cards outside are ignored.
+ */
+export function arrowOrder(state, ids) {
+  const scope = ids ? new Set(ids) : null;
+  const notes = state.notes.filter((note) => !scope || scope.has(note.id));
+  const reading = readingOrder(notes).map((note) => note.id);
+  const rank = new Map(reading.map((id, index) => [id, index]));
+  const preds = new Map(reading.map((id) => [id, []]));
+  for (const arrow of state.arrows) {
+    if (arrow.kind === "setup") continue;
+    if (!rank.has(arrow.from) || !rank.has(arrow.to)) continue;
+    preds.get(arrow.to).push(arrow.from);
+  }
+  for (const list of preds.values()) list.sort((a, b) => rank.get(a) - rank.get(b));
+
+  const placed = new Set();
+  const visiting = new Set();
+  const order = [];
+  function visit(id) {
+    if (placed.has(id) || visiting.has(id)) return;
+    visiting.add(id);
+    for (const from of preds.get(id)) {
+      // A pair pointing both ways is a tie: reading order keeps it.
+      if (preds.get(from).includes(id)) continue;
+      visit(from);
+    }
+    visiting.delete(id);
+    placed.add(id);
+    order.push(id);
+  }
+  for (const id of reading) visit(id);
+  return order;
+}
+
+/** Pull each group's members up to its first member, keeping their order. */
+function keepGroupsTogether(order, groups) {
+  const groupOf = new Map();
+  groups.forEach((group, index) => group.noteIds.forEach((id) => groupOf.set(id, index)));
+  const placed = new Set();
+  const result = [];
+  for (const id of order) {
+    if (placed.has(id)) continue;
+    const group = groupOf.get(id);
+    if (group === undefined) {
+      result.push(id);
+      placed.add(id);
+      continue;
+    }
+    for (const member of order) {
+      if (groupOf.get(member) === group && !placed.has(member)) {
+        result.push(member);
+        placed.add(member);
+      }
+    }
+  }
+  return result;
+}
+
+function wrapRows(order, originX, originY) {
+  const poses = [];
+  let x = originX;
+  let y = originY;
+  for (const id of order) {
+    if (x > originX && x + NOTE_WIDTH > originX + ROW_WIDTH) {
+      x = originX;
+      y += STEP_Y;
+    }
+    poses.push({ id, x, y, rotate: 0 });
+    x += STEP_X;
+  }
+  return poses;
+}
+
+function beatRows(order, byId, originX, originY) {
+  const poses = [];
+  let x = originX;
+  let y = originY - STEP_Y;
+  let started = false;
+  for (const id of order) {
+    const note = byId.get(id);
+    if (note.rank === "beat" || !started) {
+      // A beat owns the left edge of its row; the opening scenes get a row too.
+      y += STEP_Y;
+      x = originX;
+      started = true;
+    } else if (x + NOTE_WIDTH > originX + ROW_WIDTH) {
+      // A long run wraps under itself, indented one card, never under the beat.
+      y += STEP_Y;
+      x = originX + STEP_X;
+    }
+    poses.push({ id, x, y, rotate: 0 });
+    x += STEP_X;
+  }
+  return poses;
+}
+
+/**
+ * Poses for Organize: every card, or only `onlyIds` when a selection is being
+ * tidied, in which case the layout starts where the selection's top-left is.
+ */
+export function organizePoses(state, options = {}) {
+  const wanted = options.onlyIds ? new Set(options.onlyIds) : null;
+  const scope = state.notes.filter((note) => !wanted || wanted.has(note.id));
+  if (scope.length === 0) return [];
+  const byId = new Map(scope.map((note) => [note.id, note]));
+  const scopeIds = new Set(byId.keys());
+  const groups = state.groups
+    .map((group) => ({ ...group, noteIds: group.noteIds.filter((id) => scopeIds.has(id)) }))
+    .filter((group) => group.noteIds.length >= 2);
+
+  const order = keepGroupsTogether(arrowOrder(state, [...scopeIds]), groups);
+  const originX = wanted ? Math.min(...scope.map((note) => note.x)) : ORIGIN_X;
+  const originY = wanted ? Math.min(...scope.map((note) => note.y)) : ORIGIN_Y;
+  const hasBeats = scope.some((note) => note.rank === "beat");
+  return hasBeats ? beatRows(order, byId, originX, originY) : wrapRows(order, originX, originY);
+}

package/src/board/paginate.d.ts

@@ -0,0 +1,51 @@
+// Type surface for paginate.js — the paginator (R23, slice c1).
+
+export declare const LINES_PER_PAGE: number;
+export declare const WIDTH: Record<string, number>;
+export declare const TRANSITION: RegExp;
+
+export type Element =
+  | { kind: "action" | "transition" | "centered"; text: string; at: number }
+  | { kind: "break"; at: number }
+  | { kind: "speech"; name: string; dual: boolean; at: number; parts: Array<{ kind: "dialogue" | "parenthetical"; text: string; at?: number }> };
+
+export type LineKind = "blank" | "action" | "character" | "parenthetical" | "dialogue" | "transition" | "centered" | "break" | "note";
+export declare function classifyLines(text: string): LineKind[];
+
+export type Line = {
+  kind: "heading" | "action" | "character" | "parenthetical" | "dialogue" | "transition" | "centered" | "more" | "blank" | "dual";
+  text?: string;
+  sceneNumber?: number | string | null;
+  noteId?: string;
+  /** The source line of the scene's text this printed line came from; -1 for the heading. */
+  src?: number;
+  left?: Line;
+  right?: Line;
+};
+
+export type Block = {
+  kind: string;
+  name?: string;
+  parts?: Array<{ kind: "dialogue" | "parenthetical"; text: string }>;
+  width?: number;
+  lines: Line[];
+};
+export type Page = { number: number; lines: Line[] };
+
+export declare function wrap(text: string, width: number): string[];
+export declare function parseScene(text: string): Element[];
+export declare function layoutScene(elements: Element[], heading: string | null, sceneNumber: number | null): Block[];
+export declare function paginateBlocks(scenes: Array<{ id: string; blocks: Block[] }>): {
+  pages: Page[];
+  placement: Map<string, { page: number; endPage: number }>;
+};
+export declare function splitSpeech(block: Block, space: number): { head: Line[]; tail: Line[] } | null;
+export declare function sceneLineCount(text: string | undefined): number;
+
+export type SceneInput = { id: string; heading: string; text: string; change: string; written: boolean; number?: string | number };
+export type Pagination = {
+  pages: Page[];
+  scenes: Array<{ id: string; number: number | string; page: number; endPage: number }>;
+  pageCount: number;
+};
+export declare function paginate(scenes: SceneInput[]): Pagination;