slidemind 0.1.8 → 0.1.9

package/src/builders/review.mjs

@@ -24,7 +24,10 @@
 // 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.
+// 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";
@@ -42,7 +45,9 @@ import {
   listenWithFallback,
   preferredGatePort,
   serveAndOpen as gateServeAndOpen,
+  pendingBrowserLines,
   GRACE_MS,
+  OPEN_FAILED_GRACE_MS,
   POLL_MS,
   POLL_TTL_MS,
 } from "./gate-server.mjs";
@@ -141,6 +146,17 @@ export function formatCommentsForHarness(deckDir, comments) {
   // 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(
+    `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.");
@@ -154,12 +170,13 @@ export function formatCommentsForHarness(deckDir, comments) {
 // 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 } = {}) {
+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.",
@@ -279,7 +296,12 @@ export async function createReviewServer({
       // 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.
-      hb.respond(res);
+      // `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;
     }
 
@@ -288,6 +310,10 @@ export async function createReviewServer({
       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;
@@ -315,6 +341,15 @@ export async function createReviewServer({
     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);
     },
@@ -331,18 +366,25 @@ 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 true if an existing tab was reused. The testable seam for runReview —
-// a thin wrapper over the shared gate primitive that supplies this gate's
-// browser opener; the preview-gate message strings are gate-server's defaults.
+// 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: openInBrowser, ...opts });
+  return gateServeAndOpen(server, {
+    open: (url) => openInBrowser(url, { quiet: true }),
+    ...opts,
+  });
 }
 
 export async function runReview({
   deckDir,
   port = null,
   timeoutMs = DEFAULT_TIMEOUT_MS,
-  open = openInBrowser,
+  // 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);
@@ -362,7 +404,7 @@ export async function runReview({
   });
   // 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).
-  await serveAndOpen(server, {
+  const browser = await serveAndOpen(server, {
     open,
     graceMs: prev.decision === "comments" ? GRACE_MS : 0,
     waitLine:
@@ -373,12 +415,32 @@ export async function runReview({
 
   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.
-      process.stdout.write(formatReviewPendingForHarness(deckDir, { timeoutMs }));
+      // 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;

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);
+}

package/src/builders/visual-families.mjs

@@ -0,0 +1,32 @@
+import { splitPlanMarkdownIntoSegments } from "./storyboard-markdown.mjs";
+
+/**
+ * Split a per-slide concept batch into the dependency waves expected by the
+ * add-in: independent slides and family anchors first, family variants second.
+ */
+export function conceptGenerationWaves(planMarkdown, slideCount) {
+  const groups = new Map();
+  for (const segment of splitPlanMarkdownIntoSegments(planMarkdown)) {
+    if (segment.type !== "storyboard" || !segment.data) continue;
+    const family = segment.data.visualFamily?.trim();
+    const slide = segment.data.slide;
+    if (!family || !Number.isFinite(slide)) continue;
+    groups.set(family, [...(groups.get(family) ?? []), slide]);
+  }
+
+  const variants = new Set();
+  for (const unsorted of groups.values()) {
+    const members = [...new Set(unsorted)].sort((a, b) => a - b);
+    if (members.length < 2) continue;
+    for (const slide of members.slice(1)) variants.add(slide);
+  }
+
+  const remaining = Array.from(
+    { length: Math.max(0, slideCount - 1) },
+    (_, index) => index + 2,
+  );
+  return {
+    firstWave: remaining.filter((slide) => !variants.has(slide)),
+    variants: remaining.filter((slide) => variants.has(slide)),
+  };
+}