plotcoder-board 0.1.0

package/src/board/paginate.js

@@ -0,0 +1,375 @@
+// The paginator (R23, slice c1).
+//
+// A scene's Fountain text becomes screenplay elements, the elements become
+// lines at Courier 12 widths, and the lines become pages of fifty-five with
+// the four rules that do most of the work:
+//   - a heading keeps at least two lines of its scene with it, or moves;
+//   - dialogue breaks between sentences, with (MORE) under and NAME (CONT'D) over;
+//   - dual dialogue (^) sets two speakers side by side;
+//   - scene numbers follow wall order and print in both margins.
+// Nothing here is stored: the card holds Fountain, and every break, (MORE),
+// (CONT'D) and number is computed each time. Pure and DOM-free, so the panel,
+// the print, the strip, read the wall and the MCP server all count the same.
+
+export const LINES_PER_PAGE = 55;
+
+// Columns at ten characters to the inch, US Letter, the industry's margins.
+export const WIDTH = {
+  heading: 60, // 1.5" to 7.5"
+  action: 60,
+  character: 38, // cue at 3.7"
+  parenthetical: 25, // 3.1" to 5.6"
+  dialogue: 35, // 2.5" to 6.0"
+  transition: 60,
+  centered: 60,
+  dual: 28, // each column of a pair
+};
+
+export const TRANSITION = /^(?:[A-Z][A-Z .]*TO:|FADE (?:IN|OUT)[.:]?|CUT TO BLACK[.:]?|SMASH CUT[.:]?|DISSOLVE[.:]?)$/;
+
+/** Wrap words to a width; a word longer than the width stands alone. */
+export function wrap(text, width) {
+  const lines = [];
+  for (const raw of text.split("\n")) {
+    const words = raw.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0) {
+      lines.push("");
+      continue;
+    }
+    let line = "";
+    for (const word of words) {
+      if (!line) line = word;
+      else if (line.length + 1 + word.length <= width) line = `${line} ${word}`;
+      else {
+        lines.push(line);
+        line = word;
+      }
+    }
+    lines.push(line);
+  }
+  return lines;
+}
+
+/**
+ * A scene's Fountain body as elements: action, character, parenthetical,
+ * dialogue, transition, centered, page break. Character cues are lines in
+ * capitals followed by dialogue; `^` after a cue marks dual dialogue; `!`
+ * forces action; `>` forces a transition or, with `<`, centres; notes,
+ * synopses, sections and boneyards are not on the page.
+ */
+export function parseScene(text) {
+  const src = (text ?? "").replace(/\r\n?/g, "\n");
+  const lines = src.split("\n");
+  const elements = [];
+  let inBoneyard = false;
+  let i = 0;
+  const blankBefore = (index) => index === 0 || lines[index - 1].trim() === "";
+  const blankAfter = (index) => index >= lines.length - 1 || lines[index + 1].trim() === "";
+  while (i < lines.length) {
+    const raw = lines[i];
+    const line = raw.trim();
+    if (inBoneyard) {
+      if (line.includes("*/")) inBoneyard = false;
+      i += 1;
+      continue;
+    }
+    if (line.startsWith("/*")) {
+      if (!line.includes("*/")) inBoneyard = true;
+      i += 1;
+      continue;
+    }
+    if (/^={3,}$/.test(line)) {
+      elements.push({ kind: "break", at: i });
+      i += 1;
+      continue;
+    }
+    if (!line || line.startsWith("[[") || line.startsWith("=") || line.startsWith("#")) {
+      i += 1;
+      continue;
+    }
+    if (/^>.*<$/.test(line)) {
+      elements.push({ kind: "centered", text: line.slice(1, -1).trim(), at: i });
+      i += 1;
+      continue;
+    }
+    if (line.startsWith(">") || (TRANSITION.test(line) && blankBefore(i) && blankAfter(i))) {
+      elements.push({ kind: "transition", text: line.replace(/^>\s*/, ""), at: i });
+      i += 1;
+      continue;
+    }
+    if (line.startsWith("!")) {
+      elements.push({ kind: "action", text: line.slice(1), at: i });
+      i += 1;
+      continue;
+    }
+    // A character cue: capitals (with an optional extension in brackets), a
+    // blank line before, something after that is not blank.
+    const cue = /^@?([^a-z]+?)(\s*\(.*\))?(\s*\^)?$/.exec(line);
+    if (cue && blankBefore(i) && !blankAfter(i) && /[A-Z]/.test(line) && !TRANSITION.test(line)) {
+      const dual = Boolean(cue[3]);
+      const name = `${cue[1].replace(/^@/, "").trim()}${cue[2] ? ` ${cue[2].trim()}` : ""}`;
+      const at = i;
+      const speech = [];
+      i += 1;
+      while (i < lines.length && lines[i].trim() !== "") {
+        const part = lines[i].trim();
+        if (/^\(.*\)$/.test(part)) speech.push({ kind: "parenthetical", text: part, at: i });
+        else speech.push({ kind: "dialogue", text: part, at: i });
+        i += 1;
+      }
+      elements.push({ kind: "speech", name, dual, parts: mergeDialogue(speech), at });
+      continue;
+    }
+    // Action: consecutive non-blank lines are one paragraph, line breaks kept.
+    const at = i;
+    const paragraph = [raw.replace(/\s+$/, "")];
+    i += 1;
+    while (i < lines.length && lines[i].trim() !== "") {
+      paragraph.push(lines[i].replace(/\s+$/, ""));
+      i += 1;
+    }
+    elements.push({ kind: "action", text: paragraph.join("\n"), at });
+  }
+  return elements;
+}
+
+/**
+ * The kind of each source line of a scene, for an editor that keeps the
+ * writer's lines as they are and only styles them: the same rules as
+ * parseScene, line by line — "blank", "action", "character", "parenthetical",
+ * "dialogue", "transition", "centered", "break", "note".
+ */
+export function classifyLines(text) {
+  const lines = (text ?? "").replace(/\r\n?/g, "\n").split("\n");
+  const kinds = lines.map(() => "action");
+  const elements = parseScene(text);
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i].trim();
+    if (!line) kinds[i] = "blank";
+    else if (line.startsWith("[[") || line.startsWith("=") || line.startsWith("#") || line.startsWith("/*")) kinds[i] = "note";
+  }
+  for (const element of elements) {
+    if (element.kind === "break") kinds[element.at] = "break";
+    else if (element.kind === "centered" || element.kind === "transition") kinds[element.at] = element.kind;
+    else if (element.kind === "speech") {
+      kinds[element.at] = "character";
+      for (const part of element.parts) if (typeof part.at === "number") kinds[part.at] = part.kind;
+      // merged dialogue lines: every non-blank line after the cue until a blank
+      for (let j = element.at + 1; j < lines.length && lines[j].trim() !== ""; j += 1) {
+        if (kinds[j] === "action") kinds[j] = /^\(.*\)$/.test(lines[j].trim()) ? "parenthetical" : "dialogue";
+      }
+    }
+  }
+  return kinds;
+}
+
+function mergeDialogue(parts) {
+  const merged = [];
+  for (const part of parts) {
+    const last = merged.at(-1);
+    if (part.kind === "dialogue" && last && last.kind === "dialogue") last.text = `${last.text} ${part.text}`;
+    else merged.push({ ...part });
+  }
+  return merged;
+}
+
+/**
+ * Elements as lines with a kind each, blank lines between blocks as the
+ * page has them. A speech is one block: cue, then its parts. Dual pairs are
+ * folded into one block of paired lines.
+ */
+export function layoutScene(elements, heading, sceneNumber) {
+  const blocks = [];
+  if (heading) blocks.push({ kind: "heading", lines: wrap(heading, WIDTH.heading).map((text) => ({ kind: "heading", text, sceneNumber, src: -1 })) });
+  for (let index = 0; index < elements.length; index += 1) {
+    const element = elements[index];
+    if (element.kind === "break") {
+      blocks.push({ kind: "break", lines: [] });
+      continue;
+    }
+    if (element.kind === "action" || element.kind === "transition" || element.kind === "centered") {
+      blocks.push({ kind: element.kind, lines: wrap(element.text, WIDTH[element.kind]).map((text) => ({ kind: element.kind, text, src: element.at })) });
+      continue;
+    }
+    if (element.kind === "speech") {
+      const next = elements[index + 1];
+      if (next && next.kind === "speech" && next.dual) {
+        const left = speechLines(element, WIDTH.dual);
+        const right = speechLines(next, WIDTH.dual);
+        const lines = [];
+        for (let row = 0; row < Math.max(left.length, right.length); row += 1) {
+          lines.push({ kind: "dual", left: left[row] ?? { kind: "blank", text: "" }, right: right[row] ?? { kind: "blank", text: "" } });
+        }
+        blocks.push({ kind: "dual", lines });
+        index += 1;
+        continue;
+      }
+      blocks.push({
+        kind: "speech",
+        name: element.name,
+        parts: element.parts,
+        width: WIDTH.dialogue,
+        lines: speechLines(element, WIDTH.dialogue),
+      });
+    }
+  }
+  return blocks;
+}
+
+function speechLines(speech, dialogueWidth) {
+  const lines = [{ kind: "character", text: speech.name.toUpperCase(), src: speech.at }];
+  for (const part of speech.parts) {
+    const width = part.kind === "parenthetical" ? WIDTH.parenthetical : dialogueWidth;
+    for (const text of wrap(part.text, width)) lines.push({ kind: part.kind, text, src: part.at ?? speech.at });
+  }
+  return lines;
+}
+
+/**
+ * Break blocks into pages. A block is preceded by one blank line unless it
+ * opens a page. A speech that does not fit is split between sentences of its
+ * dialogue, with (MORE) closing the page and NAME (CONT'D) opening the next;
+ * a speech too short to split moves whole. A heading moves unless two lines
+ * of its scene fit under it.
+ */
+export function paginateBlocks(scenes) {
+  const pages = [];
+  let page = { number: 1, lines: [] };
+  const placement = new Map(); // noteId -> { page, endPage }
+  const flush = () => {
+    pages.push(page);
+    page = { number: pages.length + 1, lines: [] };
+  };
+  const room = () => LINES_PER_PAGE - page.lines.length;
+  const place = (noteId) => {
+    const at = placement.get(noteId);
+    if (!at) placement.set(noteId, { page: page.number, endPage: page.number });
+    else at.endPage = page.number;
+  };
+
+  for (const scene of scenes) {
+    const blocks = scene.blocks;
+    for (let b = 0; b < blocks.length; b += 1) {
+      const block = blocks[b];
+      if (block.kind === "break") {
+        if (page.lines.length) flush();
+        continue;
+      }
+      const gap = page.lines.length ? 1 : 0;
+      let need = gap + block.lines.length;
+      if (block.kind === "heading") {
+        // Two lines of the scene must fit under the heading: the gap and two lines of the next block.
+        const following = blocks[b + 1];
+        const under = following ? 1 + Math.min(2, following.lines.length) : 0;
+        need += under;
+        if (need > room() && page.lines.length) flush();
+        push(page, block.lines, gap && page.lines.length ? 1 : 0, scene.id);
+        place(scene.id);
+        continue;
+      }
+      if (need <= room()) {
+        push(page, block.lines, gap, scene.id);
+        place(scene.id);
+        continue;
+      }
+      if (block.kind === "speech") {
+        const split = splitSpeech(block, room() - gap);
+        if (split) {
+          push(page, split.head, gap, scene.id);
+          place(scene.id);
+          flush();
+          push(page, split.tail, 0, scene.id);
+          place(scene.id);
+          continue;
+        }
+      }
+      if (block.kind === "action" && block.lines.length > 1 && room() - gap >= 2) {
+        const take = room() - gap;
+        push(page, block.lines.slice(0, take), gap, scene.id);
+        place(scene.id);
+        flush();
+        push(page, block.lines.slice(take), 0, scene.id);
+        place(scene.id);
+        continue;
+      }
+      if (page.lines.length) flush();
+      push(page, block.lines.slice(0, LINES_PER_PAGE), 0, scene.id);
+      place(scene.id);
+      for (let rest = LINES_PER_PAGE; rest < block.lines.length; rest += LINES_PER_PAGE) {
+        flush();
+        push(page, block.lines.slice(rest, rest + LINES_PER_PAGE), 0, scene.id);
+        place(scene.id);
+      }
+    }
+  }
+  if (page.lines.length || pages.length === 0) pages.push(page);
+  return { pages, placement };
+}
+
+function push(page, lines, gap, noteId) {
+  if (gap) page.lines.push({ kind: "blank", text: "", noteId });
+  for (const line of lines) page.lines.push({ ...line, noteId });
+}
+
+/**
+ * Split a speech so `head` fits in `space` lines including (MORE), breaking
+ * between sentences of its dialogue and re-wrapping each side, never after a
+ * bare cue or a parenthetical. Returns null when no clean split leaves at
+ * least one sentence on each page.
+ */
+export function splitSpeech(block, space) {
+  const budget = space - 2; // the cue and the (MORE) line
+  if (budget < 1 || !block.parts || !block.parts.length) return null;
+  const partLines = (part) => wrap(part.text, part.kind === "parenthetical" ? WIDTH.parenthetical : block.width);
+  let best = null;
+  let before = 0;
+  for (let p = 0; p < block.parts.length; p += 1) {
+    const part = block.parts[p];
+    if (part.kind === "dialogue") {
+      const sentences = part.text.match(/[^.!?…]+[.!?…]+["')]*\s*|[^.!?…]+$/g) ?? [part.text];
+      for (let cut = 1; cut < sentences.length; cut += 1) {
+        const headText = sentences.slice(0, cut).join("").trim();
+        if (before + wrap(headText, block.width).length <= budget) best = { p, cut, sentences };
+      }
+    }
+    before += partLines(part).length;
+    if (before > budget) break;
+  }
+  if (!best) return null;
+  const headParts = [...block.parts.slice(0, best.p), { kind: "dialogue", text: best.sentences.slice(0, best.cut).join("").trim() }];
+  const tailParts = [{ kind: "dialogue", text: best.sentences.slice(best.cut).join("").trim() }, ...block.parts.slice(best.p + 1)];
+  const toLines = (parts) => parts.flatMap((part) => partLines(part).map((text) => ({ kind: part.kind, text })));
+  const cue = block.lines[0];
+  return {
+    head: [cue, ...toLines(headParts), { kind: "more", text: "(MORE)" }],
+    tail: [{ kind: "character", text: `${cue.text} (CONT'D)` }, ...toLines(tailParts)],
+  };
+}
+
+/** Lines a scene's text runs to on the page, cue and gaps included; 0 when unwritten. */
+export function sceneLineCount(text) {
+  if (typeof text !== "string" || !text.trim()) return 0;
+  const blocks = layoutScene(parseScene(text), null, null);
+  let count = 0;
+  for (const block of blocks) count += block.lines.length + (count ? 1 : 0);
+  return count;
+}
+
+/**
+ * The whole wall as pages. `scenes` is the wall in reading order as
+ * { id, heading, text, change, written }; an unwritten scene sets its change
+ * line as action so the document is always the whole story.
+ */
+export function paginate(scenes) {
+  const laid = scenes.map((scene, index) => ({
+    id: scene.id,
+    number: scene.number ?? index + 1,
+    blocks: layoutScene(parseScene(scene.written ? scene.text : scene.change || ""), scene.heading, scene.number ?? index + 1),
+  }));
+  const { pages, placement } = paginateBlocks(laid);
+  return {
+    pages,
+    scenes: laid.map((scene) => ({ id: scene.id, number: scene.number, ...(placement.get(scene.id) ?? { page: 1, endPage: 1 }) })),
+    pageCount: pages.length,
+  };
+}

package/src/board/project.d.ts

@@ -0,0 +1,72 @@
+// Type surface for project.js — the project record (R35).
+
+import type { BoardNote } from "./reducer";
+
+export declare const PROJECT_VERSION: number;
+export declare const DEFAULT_PROJECT_NAME: string;
+
+export type BoardMeta = {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+/** A project: many boards under one premise. Board states live elsewhere, one per id. */
+export type ProjectRecord = {
+  version: number;
+  id: string;
+  name: string;
+  premise: string;
+  boards: BoardMeta[];
+  activeBoardId: string;
+  /** A writer's own structures, saved from a wall's beats (Roadmap 2, item 7). */
+  structures?: OwnStructure[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type OwnStructure = { id: string; name: string; beats: Array<{ name: string; prompt: string; at: number }> };
+export declare function structureBeats(
+  notes: ReadonlyArray<BoardNote>,
+  order: ReadonlyArray<string>,
+): OwnStructure["beats"];
+export declare function addStructure(
+  project: ProjectRecord,
+  name: string,
+  beats: Array<{ name: string; prompt: string; at: number }>,
+  now?: string,
+): { project: ProjectRecord; structure: OwnStructure };
+export declare function removeStructure(project: ProjectRecord, id: string, now?: string): ProjectRecord;
+
+export declare function newBoardMeta(name: string, now?: string): BoardMeta;
+export declare function emptyProject(now?: string): ProjectRecord;
+export declare function isProjectRecord(value: unknown): value is ProjectRecord;
+export declare function normalizeProject(value: unknown, now?: string): ProjectRecord;
+export declare function addBoard(
+  project: ProjectRecord,
+  name: string,
+  now?: string,
+): { project: ProjectRecord; board: BoardMeta };
+export declare function renameBoard(
+  project: ProjectRecord,
+  id: string,
+  name: string,
+  now?: string,
+): ProjectRecord;
+export declare function removeBoard(project: ProjectRecord, id: string, now?: string): ProjectRecord;
+export declare function moveBoard(
+  project: ProjectRecord,
+  id: string,
+  delta: number,
+  now?: string,
+): ProjectRecord;
+export declare function setActiveBoard(project: ProjectRecord, id: string, now?: string): ProjectRecord;
+export declare function renameProject(project: ProjectRecord, name: string, now?: string): ProjectRecord;
+export declare function setPremise(project: ProjectRecord, premise: string, now?: string): ProjectRecord;
+export declare function boardById(project: ProjectRecord, id: string): BoardMeta | null;
+export declare function findBoard(project: ProjectRecord, key: string): BoardMeta | null;
+export declare function reidentifyProject(
+  project: ProjectRecord,
+  now?: string,
+): ProjectRecord & { renamed: Record<string, string> };

package/src/board/project.js

@@ -0,0 +1,236 @@
+// The project record (R35).
+//
+// A project holds many boards: a writer's several stories, or a season's
+// episodes, with the premise (D17) above them. This is the record — name,
+// premise, an ordered list of boards, which one is open — and the pure
+// operations on it. Board states themselves are BoardState records kept
+// separately, one per board id; this module never touches them.
+//
+// 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";
+
+export const PROJECT_VERSION = 2;
+export const DEFAULT_PROJECT_NAME = "Untitled project";
+
+function trimmed(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+export function newBoardMeta(name, now = nowIso()) {
+  return { id: newId(), name: trimmed(name, "Board"), createdAt: now, updatedAt: now };
+}
+
+export function emptyProject(now = nowIso()) {
+  const board = newBoardMeta("Board 1", now);
+  return {
+    version: PROJECT_VERSION,
+    id: newId(),
+    name: DEFAULT_PROJECT_NAME,
+    premise: "",
+    boards: [board],
+    activeBoardId: board.id,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+function isBoardMeta(value) {
+  return Boolean(value) && typeof value.id === "string" && typeof value.name === "string";
+}
+
+/** True for a record this module wrote (any version): boards and an id. */
+export function isProjectRecord(value) {
+  return (
+    Boolean(value) &&
+    typeof value === "object" &&
+    typeof value.id === "string" &&
+    Array.isArray(value.boards)
+  );
+}
+
+/**
+ * Repair a record to the current shape: a name, a premise, at least one board
+ * with an id and a name, and an open board that exists. Anything else is left
+ * as it was, so a field added later survives a load through an older build.
+ */
+export function normalizeProject(value, now = nowIso()) {
+  if (!isProjectRecord(value)) return emptyProject(now);
+  const boards = value.boards.filter(isBoardMeta).map((board) => ({
+    ...board,
+    name: trimmed(board.name, "Board"),
+    createdAt: typeof board.createdAt === "string" ? board.createdAt : now,
+    updatedAt: typeof board.updatedAt === "string" ? board.updatedAt : now,
+  }));
+  if (boards.length === 0) boards.push(newBoardMeta("Board 1", now));
+  const activeBoardId = boards.some((board) => board.id === value.activeBoardId)
+    ? value.activeBoardId
+    : boards[0].id;
+  // A writer's own structures (Roadmap 2, item 7): saved from a wall's beats.
+  const structures = Array.isArray(value.structures)
+    ? value.structures.filter(
+        (item) => item && typeof item.id === "string" && typeof item.name === "string" && Array.isArray(item.beats),
+      )
+    : [];
+  // `renamed` is reidentifyProject's map for the store, never part of the record.
+  const { renamed: _renamed, ...rest } = value;
+  return {
+    ...rest,
+    version: PROJECT_VERSION,
+    name: trimmed(value.name, DEFAULT_PROJECT_NAME),
+    premise: typeof value.premise === "string" ? value.premise.trim() : "",
+    boards,
+    activeBoardId,
+    structures,
+    createdAt: typeof value.createdAt === "string" ? value.createdAt : now,
+    updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : now,
+  };
+}
+
+function touch(project, patch, now) {
+  return { ...project, ...patch, updatedAt: now };
+}
+
+/** Add a board after the others and open it. Returns the project and the new board. */
+export function addBoard(project, name, now = nowIso()) {
+  const fallback = `Board ${project.boards.length + 1}`;
+  const board = newBoardMeta(trimmed(name, fallback), now);
+  return {
+    project: touch(project, { boards: [...project.boards, board], activeBoardId: board.id }, now),
+    board,
+  };
+}
+
+export function renameBoard(project, id, name, now = nowIso()) {
+  const next = trimmed(name, "");
+  if (!next) return project;
+  let changed = false;
+  const boards = project.boards.map((board) => {
+    if (board.id !== id || board.name === next) return board;
+    changed = true;
+    return { ...board, name: next, updatedAt: now };
+  });
+  return changed ? touch(project, { boards }, now) : project;
+}
+
+/**
+ * Remove a board. The last board cannot go — a project always has a wall. If
+ * the open board goes, the one before it (or the first) opens.
+ */
+export function removeBoard(project, id, now = nowIso()) {
+  const index = project.boards.findIndex((board) => board.id === id);
+  if (index === -1 || project.boards.length <= 1) return project;
+  const boards = project.boards.filter((board) => board.id !== id);
+  const activeBoardId =
+    project.activeBoardId === id ? boards[Math.max(0, index - 1)].id : project.activeBoardId;
+  return touch(project, { boards, activeBoardId }, now);
+}
+
+/** Move a board up (-1) or down (+1) the order. Off the ends is a no-op. */
+export function moveBoard(project, id, delta, now = nowIso()) {
+  const index = project.boards.findIndex((board) => board.id === id);
+  const target = index + delta;
+  if (index === -1 || target < 0 || target >= project.boards.length || delta === 0) return project;
+  const boards = [...project.boards];
+  const [board] = boards.splice(index, 1);
+  boards.splice(target, 0, board);
+  return touch(project, { boards }, now);
+}
+
+export function setActiveBoard(project, id, now = nowIso()) {
+  if (project.activeBoardId === id || !project.boards.some((board) => board.id === id)) {
+    return project;
+  }
+  return touch(project, { activeBoardId: id }, now);
+}
+
+export function renameProject(project, name, now = nowIso()) {
+  const next = trimmed(name, "");
+  if (!next || next === project.name) return project;
+  return touch(project, { name: next }, now);
+}
+
+export function setPremise(project, premise, now = nowIso()) {
+  const next = typeof premise === "string" ? premise.trim() : "";
+  if (next === project.premise) return project;
+  return touch(project, { premise: next }, now);
+}
+
+export function boardById(project, id) {
+  return project.boards.find((board) => board.id === id) ?? null;
+}
+
+/** Find a board by id, or by name (case-insensitive), or by its 1-based number. */
+export function findBoard(project, key) {
+  const wanted = String(key ?? "").trim();
+  if (!wanted) return null;
+  const byId = boardById(project, wanted);
+  if (byId) return byId;
+  const lower = wanted.toLowerCase();
+  const byName = project.boards.find((board) => board.name.trim().toLowerCase() === lower);
+  if (byName) return byName;
+  const number = Number(wanted);
+  if (Number.isInteger(number) && number >= 1 && number <= project.boards.length) {
+    return project.boards[number - 1];
+  }
+  return null;
+}
+
+/**
+ * The same project under fresh ids — its own and every board's (R40). Used
+ * when this device's project is pushed to an account as a new one: the ids it
+ * carried may already be someone else's — every page under the dev bridge
+ * shares them, and a project file carries its author's — and a project's ids
+ * must be its own. The result carries `renamed`, old board id to new, which
+ * normalizeProject drops.
+ */
+export function reidentifyProject(project, now = nowIso()) {
+  const ids = new Map(project.boards.map((board) => [board.id, newId()]));
+  return {
+    ...project,
+    id: newId(),
+    boards: project.boards.map((board) => ({ ...board, id: ids.get(board.id), updatedAt: now })),
+    activeBoardId: ids.get(project.activeBoardId) ?? project.activeBoardId,
+    updatedAt: now,
+    /** Old board id → new, so a store can move each board's state along. */
+    renamed: Object.fromEntries(ids),
+  };
+}
+
+/**
+ * A structure's beats from a wall (Roadmap 2, item 7): each beat card in
+ * reading order, its headline as the beat's name, its change line as the
+ * prompt, and where it falls as a share of the wall's length. Empty when the
+ * wall has no beats — there is nothing to save then.
+ */
+export function structureBeats(notes, order) {
+  const byId = new Map(notes.map((note) => [note.id, note]));
+  const ordered = order.map((id) => byId.get(id)).filter(Boolean);
+  const total = ordered.reduce((sum, note) => sum + noteEighths(note), 0) || 1;
+  let cursor = 0;
+  const beats = [];
+  for (const note of ordered) {
+    if (note.rank === "beat") {
+      beats.push({
+        name: note.headline || "Untitled beat",
+        prompt: note.change || "What turns here?",
+        at: Math.round((cursor / total) * 100) / 100,
+      });
+    }
+    cursor += noteEighths(note);
+  }
+  return beats;
+}
+
+/** Save a structure on the project: a name and beats { name, prompt, at }. */
+export function addStructure(project, name, beats, now = nowIso()) {
+  const structure = { id: newId(), name: trimmed(name, "My structure"), beats: beats.map((beat) => ({ ...beat })) };
+  return { project: { ...project, structures: [...(project.structures ?? []), structure], updatedAt: now }, structure };
+}
+
+export function removeStructure(project, id, now = nowIso()) {
+  const structures = (project.structures ?? []).filter((item) => item.id !== id);
+  if (structures.length === (project.structures ?? []).length) return project;
+  return { ...project, structures, updatedAt: now };
+}