slidemind 0.1.7 → 0.1.9

package/src/builders/review.mjs

@@ -16,6 +16,18 @@
 // previously-materialized bundle (like `slidemind build`) but no open host.
 // Each round's comments persist to <deck>/review.json so the next run shows them
 // as read-only "ghost" pins for 1:1 verification.
+//
+// Port + tab-reuse contract: each run binds a deterministic per-deck port (a
+// hash of the deck path folded into a fixed high band, 40000..40999) so a tab
+// left waiting from the previous round can reconnect to the same URL. A taken
+// port never fails — it falls back to an OS-assigned port with a stderr notice.
+// On a comments round the browser tab does NOT close: it polls
+// /__review/heartbeat and reloads itself once the next run binds the same port
+// (matched by a service marker + a fresh round nonce), so a fresh tab isn't
+// opened every round. Reuse is granted only to a VISIBLE waiting tab — if the
+// tab is buried in a background window (or none is polling), the browser is
+// ALWAYS opened and the stale tab retires itself; the review must never sit
+// invisible while the user thinks nothing happened.
 
 import fs from "node:fs";
 import http from "node:http";
@@ -25,6 +37,20 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { buildDeck, openInBrowser } from "./build.mjs";
 import { resolveSkillForDeck } from "./resolve-skill.mjs";
 import { resolveBrandAsset } from "../bridge/bundle.mjs";
+import {
+  MIME,
+  serveStaticFile,
+  createDecisionGate,
+  createHeartbeat,
+  listenWithFallback,
+  preferredGatePort,
+  serveAndOpen as gateServeAndOpen,
+  pendingBrowserLines,
+  GRACE_MS,
+  OPEN_FAILED_GRACE_MS,
+  POLL_MS,
+  POLL_TTL_MS,
+} from "./gate-server.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,21 +58,6 @@ const OVERLAY_PATH = path.join(__dirname, "review-overlay.js");
 const REVIEW_STATE_FILE = "review.json";
 const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
 
-const MIME = {
-  ".html": "text/html; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-};
-
 function clamp01(n) {
   return n < 0 ? 0 : n > 1 ? 1 : n;
 }
@@ -132,16 +143,57 @@ export function formatCommentsForHarness(deckDir, comments) {
     out.push(`    Comment: ${c.comment}`);
     out.push("");
   });
+  // Imperative, stateful tail (mirrors plan.mjs's formatPlanFeedbackForHarness):
+  // after a comments round the user's tab waits for the NEXT review run — an
+  // agent that ends its turn here deadlocks the session.
+  //
+  // The recovery pointer sits in the TAIL deliberately: when a harness capture
+  // truncates long output it usually drops the TOP, so the pointer to the full
+  // persisted round is what survives.
   out.push(
-    `Address every comment by editing the cited slides/*.jsx file(s) at the given ` +
-      `line, then re-run: slidemind review ${path.basename(deckDir)}`,
+    `This round (all ${n} comment${n === 1 ? "" : "s"}) is also saved verbatim in ` +
+      `${path.join(deckDir, REVIEW_STATE_FILE)} — if this output looks truncated or ` +
+      `you can't see every numbered comment above, read that file for the full list ` +
+      `instead of guessing or asking the user to re-type anything.`,
   );
+  out.push("");
+  out.push("The user's browser tab is still open, waiting for the next round. They are");
+  out.push("waiting on YOU now — do both steps in this same turn:");
+  out.push("  1. Edit the cited slides/*.jsx file(s) at the given lines.");
+  out.push(`  2. Re-run: slidemind review ${path.basename(deckDir)}`);
+  out.push("The re-run rebuilds the preview and reopens their same tab (the prior round");
+  out.push("shows as ghost pins). Do NOT end your turn, do NOT export anything, and do");
+  out.push("NOT send the user back to the browser before step 2.");
   return out.join("\n") + "\n";
 }
 
-function injectReview(html, previousComments, overlayJs, logoMark = null) {
+// Render the no-answer outcome for the harness — same contract as plan.mjs's
+// formatPlanPendingForHarness: an expected state with resume instructions, not
+// a failure and never an implicit approval.
+export function formatReviewPendingForHarness(deckDir, { timeoutMs, pageLoaded, url } = {}) {
+  const mins = Math.max(1, Math.round((timeoutMs ?? DEFAULT_TIMEOUT_MS) / 60000));
+  const base = path.basename(deckDir);
+  return [
+    "DECISION: pending",
+    `No decision yet — the gate waited ${mins} minutes and the user hasn't answered.`,
+    ...pendingBrowserLines({ pageLoaded, url }),
+    "This is NOT an approval and NOT a rejection. Do not push or export anything.",
+    "Close out your turn gracefully:",
+    "  1. Tell the user the preview is still waiting for their review in the browser.",
+    "  2. Tell them that when they're ready, you'll re-open the gate — then, on",
+    `     their go-ahead, re-run: slidemind review ${base}`,
+    "A still-open tab reconnects to the re-run automatically; a closed one just",
+    "gets a fresh window. Nothing is lost by the wait.",
+  ].join("\n") + "\n";
+}
+
+function injectReview(html, previousComments, overlayJs, logoMark = null, round = null) {
   const cfg = safeInlineJson({
     endpoint: "/review",
+    heartbeat: "/__review/heartbeat",
+    round,
+    pollMs: POLL_MS,
+    pollTtlMs: POLL_TTL_MS,
     previousComments,
     logoMark,
   });
@@ -154,12 +206,16 @@ function injectReview(html, previousComments, overlayJs, logoMark = null) {
 
 export function loadReviewState(deckDir) {
   const f = path.join(deckDir, REVIEW_STATE_FILE);
-  if (!fs.existsSync(f)) return { version: 1, comments: [] };
+  if (!fs.existsSync(f)) return { version: 1, decision: null, comments: [] };
   try {
     const data = JSON.parse(fs.readFileSync(f, "utf8"));
-    return { version: 1, comments: Array.isArray(data.comments) ? data.comments : [] };
+    return {
+      version: 1,
+      decision: data.decision ?? null,
+      comments: Array.isArray(data.comments) ? data.comments : [],
+    };
   } catch {
-    return { version: 1, comments: [] };
+    return { version: 1, decision: null, comments: [] };
   }
 }
 
@@ -170,7 +226,15 @@ function saveReviewState(deckDir, state) {
   );
 }
 
-// Start the local review server. Returns { url, port, waitForDecision, close }.
+// Deterministic per-deck port so a tab left waiting from the previous round can
+// reconnect to the same URL. Thin wrapper over the shared gate primitive, salted
+// with this gate's name so the preview and plan gates of one deck get distinct
+// ports and their waiting tabs never sit on each other's URL.
+export function preferredPortForDeck(deckDir) {
+  return preferredGatePort(deckDir, "preview");
+}
+
+// Start the local review server. Returns { url, port, waitForDecision, waitForHeartbeat, close }.
 // presentation.html must already exist in deckDir (build it first).
 export async function createReviewServer({
   deckDir,
@@ -179,10 +243,11 @@ export async function createReviewServer({
   logoMark = null,
   port = 0,
 }) {
-  let resolveDecision;
-  const decisionPromise = new Promise((res) => {
-    resolveDecision = res;
-  });
+  const gate = createDecisionGate();
+  // The heartbeat carries a per-run nonce so a waiting tab can tell a genuinely
+  // NEWER round (different nonce) from this run's own heartbeat (same nonce) and
+  // never self-reload; the service marker guards against a foreign app.
+  const hb = createHeartbeat({ service: "slidemind-review" });
   const overlay =
     overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8");
   const indexHtml = injectReview(
@@ -190,6 +255,7 @@ export async function createReviewServer({
     previousComments,
     overlay,
     logoMark,
+    hb.round,
   );
   const deckRoot = path.resolve(deckDir);
 
@@ -212,7 +278,7 @@ export async function createReviewServer({
         }
         res.writeHead(200, { "Content-Type": MIME[".json"] });
         res.end(JSON.stringify({ ok: true }));
-        resolveDecision({
+        gate.resolve({
           decision: payload.decision === "comments" ? "comments" : "approve",
           comments: Array.isArray(payload.comments) ? payload.comments : [],
         });
@@ -226,39 +292,45 @@ export async function createReviewServer({
       return;
     }
 
+    if (pathname === "/__review/heartbeat") {
+      // The `service` marker is the shape guard: a waiting tab only reloads for
+      // a genuine slidemind review round, never because a foreign app grabbed
+      // the same port. The `round` nonce distinguishes a newer round from self.
+      // `visible`/`round` from the poll drive the reuse-vs-fresh-tab decision:
+      // only a VISIBLE waiting tab may claim reuse (see gate-server.mjs).
+      hb.respond(res, {
+        visible: u.searchParams.get("visible") === "1",
+        tabRound: u.searchParams.get("round"),
+      });
+      return;
+    }
+
     if (
       pathname === "/" ||
       pathname === "/index.html" ||
       pathname === "/presentation.html"
     ) {
+      // A browser fetched the gate page — the end-to-end proof the review
+      // actually opened in front of the user (see gate-server's page-load
+      // tracker; serveAndOpen and the pending contract report from it).
+      hb.notePageLoad();
       res.writeHead(200, { "Content-Type": MIME[".html"] });
       res.end(indexHtml);
       return;
     }
 
-    const normalized = path.resolve(deckRoot, pathname.replace(/^\/+/, ""));
-    if (normalized !== deckRoot && !normalized.startsWith(deckRoot + path.sep)) {
-      res.writeHead(403);
-      res.end("forbidden");
-      return;
-    }
-    fs.readFile(normalized, (err, data) => {
-      if (err) {
-        res.writeHead(404);
-        res.end("not found");
-        return;
-      }
-      const ext = path.extname(normalized).toLowerCase();
-      res.writeHead(200, {
-        "Content-Type": MIME[ext] || "application/octet-stream",
-      });
-      res.end(data);
-    });
+    // Traversal-guarded static serving from the deck root; a miss or an escape
+    // attempt falls through to the caller's 404 (serveStaticFile never writes on
+    // a non-match).
+    if (serveStaticFile({ roots: [deckRoot], pathname, res })) return;
+    res.writeHead(404);
+    res.end("not found");
   });
 
-  await new Promise((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(port, "127.0.0.1", resolve);
+  await listenWithFallback(server, port, "127.0.0.1", (wanted, err) => {
+    process.stderr.write(
+      `review: port ${wanted} unavailable (${err.code}); using an OS-assigned port instead.\n`,
+    );
   });
   const addr = server.address();
   const url = `http://127.0.0.1:${addr.port}/`;
@@ -266,18 +338,20 @@ export async function createReviewServer({
   return {
     url,
     port: addr.port,
-    waitForDecision({ timeoutMs } = {}) {
-      if (!timeoutMs) return decisionPromise;
-      return new Promise((resolve, reject) => {
-        const t = setTimeout(
-          () => reject(new Error("review timed out — no decision received")),
-          timeoutMs,
-        );
-        decisionPromise.then((d) => {
-          clearTimeout(t);
-          resolve(d);
-        });
-      });
+    waitForHeartbeat(ms) {
+      return hb.waitForHeartbeat(ms);
+    },
+    markOpenedFresh() {
+      hb.markFresh();
+    },
+    waitForPageLoad(ms) {
+      return hb.waitForPageLoad(ms);
+    },
+    pageLoaded() {
+      return hb.pageLoaded();
+    },
+    waitForDecision(opts = {}) {
+      return gate.waitForDecision(opts);
     },
     close() {
       try {
@@ -289,10 +363,28 @@ export async function createReviewServer({
   };
 }
 
+// Print the review URL, then decide whether to open a browser. If a tab left
+// waiting from a previous comments round pings /__review/heartbeat within the
+// grace window, reuse it (it reloads itself) instead of opening a duplicate.
+// Returns gate-server's { reused, launched, confirmed, url } status. The
+// testable seam for runReview — a thin wrapper over the shared gate primitive
+// that supplies this gate's browser opener (quiet: the gate's BROWSER: line is
+// the single source of open/failed messaging); the preview-gate message nouns
+// are gate-server's defaults.
+export function serveAndOpen(server, opts = {}) {
+  return gateServeAndOpen(server, {
+    open: (url) => openInBrowser(url, { quiet: true }),
+    ...opts,
+  });
+}
+
 export async function runReview({
   deckDir,
-  port = 0,
+  port = null,
   timeoutMs = DEFAULT_TIMEOUT_MS,
+  // quiet: serveAndOpen's BROWSER: line owns all open/failed messaging.
+  open = (url) => openInBrowser(url, { quiet: true }),
+  openFailedGraceMs = OPEN_FAILED_GRACE_MS,
 } = {}) {
   await buildDeck(deckDir);
   const prev = loadReviewState(deckDir);
@@ -303,21 +395,55 @@ export async function runReview({
   // a plain slide glyph — the CLI no longer re-derives an orb.
   const mark = resolveBrandAsset(deckDir, ["logoMarkDark", "logoMark", "logoMarkLight"]);
   const logoMark = mark ? "/assets/" + mark.filename : null;
+  const wantPort = port == null ? preferredPortForDeck(deckDir) : port;
   const server = await createReviewServer({
     deckDir,
     previousComments: prev.comments || [],
     logoMark,
-    port,
+    port: wantPort,
+  });
+  // A waiting tab can only exist when the previous round ended in comments — so
+  // first runs / post-approve runs open the browser immediately (graceMs 0).
+  const browser = await serveAndOpen(server, {
+    open,
+    graceMs: prev.decision === "comments" ? GRACE_MS : 0,
+    waitLine:
+      `Waiting for the user's decision — this command BLOCKS (up to ${Math.round(
+        timeoutMs / 60000,
+      )} min) while they review. A long quiet wait is normal; do not cancel it.`,
   });
-  process.stderr.write(`Preview review ready at ${server.url}\n`);
-  openInBrowser(server.url);
-  process.stderr.write(
-    "Opened your browser — leave comments or approve, then return here.\n",
-  );
 
   let decision;
   try {
+    if (browser.launched === false) {
+      // The opener chain failed outright: the user can only reach the gate via
+      // the printed URL. Give a manually-opened tab a short window, then bail
+      // out with the pending contract (carrying the failed-open status + link)
+      // instead of blocking the agent for the full timeout on an invisible gate.
+      const loaded = await server.waitForPageLoad(openFailedGraceMs);
+      if (!loaded) {
+        const err = new Error("browser never opened — gate unseen");
+        err.code = "GATE_TIMEOUT";
+        throw err;
+      }
+    }
     decision = await server.waitForDecision({ timeoutMs });
+  } catch (err) {
+    if (err && err.code === "GATE_TIMEOUT") {
+      // Expected outcome, not an error: exit 0 with the pending contract so the
+      // agent wraps up cleanly instead of reading a scary non-zero failure.
+      // pageLoaded is re-checked NOW (not serveAndOpen's early snapshot) so a
+      // tab that opened late still counts as "the user saw the gate".
+      process.stdout.write(
+        formatReviewPendingForHarness(deckDir, {
+          timeoutMs,
+          pageLoaded: server.pageLoaded(),
+          url: server.url,
+        }),
+      );
+      return null;
+    }
+    throw err;
   } finally {
     server.close();
   }
@@ -342,7 +468,9 @@ export async function runReview({
 }
 
 function parseArgs(argv) {
-  const args = { deck: null, port: 0 };
+  // port null ⇒ derive the deterministic per-deck port; an explicit --port
+  // (incl. --port 0 for OS-random) overrides it.
+  const args = { deck: null, port: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--deck" && i + 1 < argv.length) {

package/src/builders/storyboard-markdown.mjs

@@ -0,0 +1,118 @@
+// Storyboard-markdown: segment a plan.md into alternating markdown / storyboard
+// runs, splice an edited storyboard fence back in, and pull the red-thread beats
+// out of the `## Red thread` section. Ported 1:1 from the add-in's
+// src/ui/src/pages/plan-review/storyboard-markdown.ts (TS types dropped; regexes
+// and control flow identical). Ships into the plan gate's browser bundle in one
+// shared IIFE with storyboard-schema and the other plan modules, so module-scope
+// helpers use an `sm` prefix to stay collision-free; exported names match the
+// add-in exactly. The import below is a single line on purpose — the browser
+// bundler strips lines matching `import … from "…";`.
+import { parseStoryboardCanvas, serializeStoryboardCanvas, STORYBOARD_CANVAS_LANG } from "./storyboard-schema.mjs";
+
+const SM_FENCE_RE = /```([^\n`]*)\n([\s\S]*?)```/g;
+const SM_RED_THREAD_HEADING_RE = /^##\s+Red thread\s*$/im;
+const SM_NEXT_H2_RE = /^##\s+/im;
+
+function smCountLines(text) {
+  if (!text) return 0;
+  return text.split("\n").length - 1;
+}
+
+function smNormalizeFenceLang(raw) {
+  return raw.trim().split(/\s+/)[0] ?? "";
+}
+
+function smCleanRedThreadLine(line) {
+  return line
+    .replace(/^\s*(?:[-*]|\d+[.)])\s+/, "")
+    .replace(/^\s*Slide\s+\d+\s*:\s*/i, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function smSplitRedThreadBody(body) {
+  const lines = body.split("\n").map(smCleanRedThreadLine).filter(Boolean);
+  if (lines.length !== 1) return lines;
+  const [line] = lines;
+  if (!line) return [];
+  return line
+    .split(/\s+(?:->|→|=>|↦)\s+/)
+    .map(smCleanRedThreadLine)
+    .filter(Boolean);
+}
+
+/** Absolute bounds of the `## Red thread` section body (after the heading). */
+export function findRedThreadSection(markdown) {
+  const heading = SM_RED_THREAD_HEADING_RE.exec(markdown);
+  if (!heading) return null;
+  const bodyStart = (heading.index ?? 0) + heading[0].length;
+  const rest = markdown.slice(bodyStart);
+  const nextHeading = SM_NEXT_H2_RE.exec(rest);
+  return {
+    bodyStart,
+    bodyEnd: bodyStart + (nextHeading?.index ?? rest.length),
+  };
+}
+
+export function extractRedThreadMessages(markdown) {
+  const section = findRedThreadSection(markdown);
+  if (!section) return [];
+  return smSplitRedThreadBody(markdown.slice(section.bodyStart, section.bodyEnd));
+}
+
+export function splitPlanMarkdownIntoSegments(markdown) {
+  const segments = [];
+  let cursor = 0;
+  let lineOffset = 0;
+
+  for (const match of markdown.matchAll(SM_FENCE_RE)) {
+    const full = match[0] ?? "";
+    const matchStart = match.index ?? 0;
+    const matchEnd = matchStart + full.length;
+    const lang = smNormalizeFenceLang(match[1] ?? "");
+    const body = match[2] ?? "";
+
+    if (lang !== STORYBOARD_CANVAS_LANG) continue;
+
+    if (matchStart > cursor) {
+      const text = markdown.slice(cursor, matchStart);
+      segments.push({ type: "markdown", text, lineOffset });
+      lineOffset += smCountLines(text);
+    }
+
+    const parsed = parseStoryboardCanvas(body.trim());
+    segments.push({
+      type: "storyboard",
+      raw: body,
+      data: parsed.data,
+      error: parsed.error,
+      warnings: parsed.warnings,
+      start: matchStart,
+      end: matchEnd,
+      lineOffset,
+    });
+    lineOffset += smCountLines(full);
+    cursor = matchEnd;
+  }
+
+  if (cursor < markdown.length || segments.length === 0) {
+    segments.push({
+      type: "markdown",
+      text: markdown.slice(cursor),
+      lineOffset,
+    });
+  }
+
+  return segments;
+}
+
+export function replaceStoryboardSegment(markdown, segment, nextData) {
+  const nextBlock = [
+    `\`\`\`${STORYBOARD_CANVAS_LANG}`,
+    serializeStoryboardCanvas(nextData),
+    "```",
+  ].join("\n");
+  return `${markdown.slice(0, segment.start)}${nextBlock}${markdown.slice(
+    segment.end,
+  )}`;
+}

package/src/builders/storyboard-schema.mjs

@@ -0,0 +1,180 @@
+// Storyboard-canvas schema: the defensive parser/serializer for the JSON block a
+// plan.md carries inside each ```storyboard-canvas``` fence. Ported 1:1 from the
+// add-in's src/ui/src/pages/plan-review/storyboard-schema.ts (TS types dropped;
+// every constant, regex, clamp and branch identical). This module also ships into
+// the plan gate's browser bundle, concatenated with the other plan modules into a
+// single IIFE — so module-scope helpers use an `sb`/`SB_` prefix to stay unique
+// across that shared scope, while the exported API names match the add-in exactly.
+
+export const STORYBOARD_CANVAS_LANG = "storyboard-canvas";
+export const STORYBOARD_WIDTH = 1600;
+export const STORYBOARD_HEIGHT = 900;
+
+export const BODY_SAFE_AREA = {
+  x: 80,
+  y: 110,
+  w: 1440,
+  h: 670,
+};
+
+export const MIN_BLOCK_WIDTH = 180;
+export const MIN_BLOCK_HEIGHT = 96;
+export const MAX_BLOCKS = 8;
+const SB_MAX_ID_LENGTH = 64;
+export const MAX_DESIGN_ELEMENT_LENGTH = 56;
+export const MAX_CONTENT_LENGTH = 28;
+const SB_MAX_KEY_MESSAGE_LENGTH = 180;
+const SB_MAX_VISUAL_FAMILY_LENGTH = 64;
+const SB_MAX_DEPTH_NOTES = 6;
+const SB_MAX_DEPTH_NOTE_LENGTH = 220;
+
+function sbIsRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function sbAsTrimmedString(value, maxLength) {
+  if (typeof value !== "string") return "";
+  return value.trim().slice(0, maxLength);
+}
+
+function sbAsFiniteNumber(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function sbClamp(value, min, max) {
+  return Math.min(Math.max(value, min), max);
+}
+
+function sbNormalizeBlock(value, index, warnings) {
+  if (!sbIsRecord(value)) {
+    warnings.push(`Block ${index + 1} is not an object and was ignored.`);
+    return null;
+  }
+
+  const id = sbAsTrimmedString(value.id, SB_MAX_ID_LENGTH) || `block-${index + 1}`;
+  const designElement = sbAsTrimmedString(
+    value.designElement,
+    MAX_DESIGN_ELEMENT_LENGTH,
+  );
+  const content = sbAsTrimmedString(value.content, MAX_CONTENT_LENGTH);
+  if (!designElement || !content) {
+    warnings.push(
+      `Block "${id}" needs both designElement and content and was ignored.`,
+    );
+    return null;
+  }
+
+  const minW = MIN_BLOCK_WIDTH;
+  const minH = MIN_BLOCK_HEIGHT;
+  const maxW = BODY_SAFE_AREA.w;
+  const maxH = BODY_SAFE_AREA.h;
+  const w = sbClamp(sbAsFiniteNumber(value.w, 360), minW, maxW);
+  const h = sbClamp(sbAsFiniteNumber(value.h, 150), minH, maxH);
+  const x = sbClamp(
+    sbAsFiniteNumber(value.x, BODY_SAFE_AREA.x),
+    BODY_SAFE_AREA.x,
+    BODY_SAFE_AREA.x + BODY_SAFE_AREA.w - w,
+  );
+  const y = sbClamp(
+    sbAsFiniteNumber(value.y, BODY_SAFE_AREA.y),
+    BODY_SAFE_AREA.y,
+    BODY_SAFE_AREA.y + BODY_SAFE_AREA.h - h,
+  );
+  const emphasis =
+    value.emphasis === "primary" ||
+    value.emphasis === "secondary" ||
+    value.emphasis === "tertiary"
+      ? value.emphasis
+      : undefined;
+
+  return {
+    id,
+    x,
+    y,
+    w,
+    h,
+    ...(emphasis ? { emphasis } : {}),
+    designElement,
+    content,
+  };
+}
+
+export function parseStoryboardCanvas(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      data: null,
+      warnings: [],
+      error: "Storyboard JSON could not be parsed.",
+    };
+  }
+
+  if (!sbIsRecord(parsed)) {
+    return {
+      data: null,
+      warnings: [],
+      error: "Storyboard data must be a JSON object.",
+    };
+  }
+
+  const warnings = [];
+  if (parsed.version !== 1) {
+    warnings.push("Storyboard version was normalized to 1.");
+  }
+
+  const slide = Math.max(1, Math.round(sbAsFiniteNumber(parsed.slide, 1)));
+  const rawBlocks = Array.isArray(parsed.blocks) ? parsed.blocks : [];
+  if (!Array.isArray(parsed.blocks)) {
+    warnings.push("Storyboard blocks must be an array.");
+  }
+
+  const blocks = rawBlocks
+    .slice(0, MAX_BLOCKS)
+    .map((block, index) => sbNormalizeBlock(block, index, warnings))
+    .filter((block) => block !== null);
+
+  if (rawBlocks.length > MAX_BLOCKS) {
+    warnings.push(`Only the first ${MAX_BLOCKS} storyboard blocks are shown.`);
+  }
+
+  if (blocks.length === 0) {
+    return {
+      data: null,
+      warnings,
+      error: "Storyboard needs at least one valid block.",
+    };
+  }
+
+  const keyMessage = sbAsTrimmedString(parsed.keyMessage, SB_MAX_KEY_MESSAGE_LENGTH);
+  const visualFamily = sbAsTrimmedString(
+    parsed.visualFamily,
+    SB_MAX_VISUAL_FAMILY_LENGTH,
+  );
+  const rawContentNotes = Array.isArray(parsed.contentNotes)
+    ? parsed.contentNotes
+    : parsed.depthNotes;
+  const contentNotes = Array.isArray(rawContentNotes)
+    ? rawContentNotes
+        .slice(0, SB_MAX_DEPTH_NOTES)
+        .map((note) => sbAsTrimmedString(note, SB_MAX_DEPTH_NOTE_LENGTH))
+        .filter(Boolean)
+    : undefined;
+
+  return {
+    data: {
+      version: 1,
+      slide,
+      blocks,
+      ...(visualFamily ? { visualFamily } : {}),
+      ...(keyMessage ? { keyMessage } : {}),
+      ...(contentNotes?.length ? { contentNotes } : {}),
+    },
+    warnings,
+  };
+}
+
+export function serializeStoryboardCanvas(data) {
+  return JSON.stringify(data, null, 2);
+}