slidemind 0.1.8 → 0.1.9

package/src/builders/plan.mjs

@@ -55,7 +55,9 @@ import {
   listenWithFallback,
   preferredGatePort,
   serveAndOpen,
+  pendingBrowserLines,
   GRACE_MS,
+  OPEN_FAILED_GRACE_MS,
   POLL_MS,
   POLL_TTL_MS,
 } from "./gate-server.mjs";
@@ -65,6 +67,14 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const OVERLAY_PATH = path.join(__dirname, "plan-overlay.js");
 const PLAN_MD_PATH = path.join(__dirname, "plan-md.mjs");
+// The storyboard/red-thread plan-review modules, bundled into the browser page
+// alongside plan-md.mjs (see bundlePlanModules). Order matters: each file's
+// inter-module imports are stripped, so a module must be concatenated AFTER the
+// module whose exports it references (schema ← storyboard-markdown ← backbone).
+const STORYBOARD_SCHEMA_PATH = path.join(__dirname, "storyboard-schema.mjs");
+const STORYBOARD_MARKDOWN_PATH = path.join(__dirname, "storyboard-markdown.mjs");
+const RED_THREAD_BACKBONE_PATH = path.join(__dirname, "red-thread-backbone.mjs");
+const PLAN_MARKDOWN_EDIT_PATH = path.join(__dirname, "plan-markdown-edit.mjs");
 const PLAN_STATE_FILE = "plan-review.json";
 const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
 
@@ -149,6 +159,14 @@ export function formatPlanFeedbackForHarness(deckDir, comment, { edited = false
     out.push("(No written feedback — their direct edits to plan.md are the change.)");
     out.push("");
   }
+  // Recovery pointer in the tail (truncated captures usually lose the TOP):
+  // the round is persisted before this prints, so a lost capture is recoverable.
+  out.push(
+    `This round (decision + feedback) is also saved verbatim in ` +
+      `${path.join(deckDir, PLAN_STATE_FILE)} — if this output looks truncated, read ` +
+      `that file instead of guessing.`,
+  );
+  out.push("");
   out.push(
     "The user's browser tab is still open, on a waiting spinner that says you are",
   );
@@ -165,12 +183,13 @@ export function formatPlanFeedbackForHarness(deckDir, comment, { edited = false
 // Render the no-answer outcome for the harness. A timed-out gate is an EXPECTED
 // state (the user stepped away), not a failure — the agent must neither treat
 // it as approval nor abort the task; it wraps up with clear resume instructions.
-export function formatPlanPendingForHarness(deckDir, { timeoutMs } = {}) {
+export function formatPlanPendingForHarness(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 author anything.",
     "Close out your turn gracefully:",
     "  1. Tell the user their plan is still waiting for sign-off in the browser.",
@@ -181,6 +200,82 @@ export function formatPlanPendingForHarness(deckDir, { timeoutMs } = {}) {
   ].join("\n") + "\n";
 }
 
+// ---------------------------------------------------------------------------
+// browser bundle
+// ---------------------------------------------------------------------------
+
+// The exact set of names the bundled IIFE hangs off window.__SLIDEMIND_PLAN__ —
+// this is the contract the overlay (plan-overlay.js) reads. Every name here must
+// resolve to a top-level binding in one of the five concatenated modules.
+const PLAN_NAMESPACE_EXPORTS = [
+  "renderPlanMarkdown",
+  "addEditableAttributes",
+  "isEditableKind",
+  "replaceRenderedMarkdownBlock",
+  "splitPlanMarkdownIntoSegments",
+  "replaceStoryboardSegment",
+  "extractRedThreadMessages",
+  "findRedThreadSection",
+  "parseStoryboardCanvas",
+  "serializeStoryboardCanvas",
+  "backboneFromMessages",
+  "parsePlanBackbone",
+  "applyPlanBackbone",
+  "stageStoryIteration",
+  "STORYBOARD_WIDTH",
+  "STORYBOARD_HEIGHT",
+  "BODY_SAFE_AREA",
+  "MIN_BLOCK_WIDTH",
+  "MIN_BLOCK_HEIGHT",
+  "MAX_BLOCKS",
+  "MAX_DESIGN_ELEMENT_LENGTH",
+  "MAX_CONTENT_LENGTH",
+];
+
+// Turn a dependency-free ESM module's source into plain browser JS that runs
+// inside a shared IIFE scope: drop single-line `import … from "…";` statements
+// (all inter-module imports across the plan-review modules are single-line) and
+// strip the leading `export ` keyword from declarations. The imported names are
+// provided by an earlier module in the concatenation, so removing the import
+// line just leaves the reference resolving to that earlier top-level binding.
+export function stripModuleSyntax(src) {
+  return String(src || "")
+    .replace(/^\s*import\s+[^;]*?from\s*["'][^"']+["'];?\s*$/gm, "")
+    .replace(/^export\s+/gm, "");
+}
+
+// Bundle the five plan-review modules into one IIFE for the browser page, in
+// dependency order (schema → storyboard-markdown → backbone → edit → plan-md).
+// The IIFE exposes window.__SLIDEMIND_RENDER_MD__ (back-compat with the old
+// preview) and window.__SLIDEMIND_PLAN__ (the full namespace the overlay reads).
+// Exported so a test can evaluate the output against a stub window and catch a
+// strip-regex miss or a top-level name collision for real.
+export function bundlePlanModules({ schema, storyboardMd, backbone, edit, planMd } = {}) {
+  const body = [schema, storyboardMd, backbone, edit, planMd]
+    .map(stripModuleSyntax)
+    .join("\n");
+  return (
+    "(function () {\n" +
+    body +
+    "\nwindow.__SLIDEMIND_RENDER_MD__ = renderPlanMarkdown;\n" +
+    "window.__SLIDEMIND_PLAN__ = { " +
+    PLAN_NAMESPACE_EXPORTS.join(", ") +
+    " };\n})();\n"
+  );
+}
+
+// Read the five module sources off disk and bundle them. Split from
+// bundlePlanModules so the pure string→string step stays unit-testable.
+export function bundlePlanModulesFromDisk() {
+  return bundlePlanModules({
+    schema: fs.readFileSync(STORYBOARD_SCHEMA_PATH, "utf8"),
+    storyboardMd: fs.readFileSync(STORYBOARD_MARKDOWN_PATH, "utf8"),
+    backbone: fs.readFileSync(RED_THREAD_BACKBONE_PATH, "utf8"),
+    edit: fs.readFileSync(PLAN_MARKDOWN_EDIT_PATH, "utf8"),
+    planMd: fs.readFileSync(PLAN_MD_PATH, "utf8"),
+  });
+}
+
 // ---------------------------------------------------------------------------
 // page
 // ---------------------------------------------------------------------------
@@ -224,17 +319,16 @@ display:block;overflow-x:auto;}
 
 // Build the standalone plan-review page: the rendered markdown in #plan-root
 // (the no-JS fallback and the preview's initial state), the injected overlay
-// config, the markdown renderer for the live preview, then the overlay script
-// itself. `planMdJs` is the raw plan-md.mjs source — a dependency-free ESM
-// module, so stripping its `export ` keywords makes it plain browser JS; it is
-// wrapped in an IIFE that exposes window.__SLIDEMIND_RENDER_MD__ for the
-// overlay's live re-render. Kept a pure function of its inputs so it's
-// unit-testable without a server.
+// config, the bundled plan-review modules, then the overlay script itself.
+// `planModulesJs` is the prebundled IIFE from bundlePlanModules — it already
+// exposes window.__SLIDEMIND_RENDER_MD__ and window.__SLIDEMIND_PLAN__, so this
+// only inlines it verbatim (with the </script> break-out guard). Kept a pure
+// function of its inputs so it's unit-testable without a server.
 export function buildPlanPage({
   bodyHtml,
   previousComment,
   overlayJs,
-  planMdJs,
+  planModulesJs,
   logoMark,
   planBody,
   bodyStartLine,
@@ -252,14 +346,8 @@ export function buildPlanPage({
     bodyStartLine: bodyStartLine ?? 1,
   });
   const overlay = String(overlayJs || "").replace(/<\/script>/g, "<\\/script>");
-  const rendererSrc = String(planMdJs || "")
-    .replace(/^export\s+/gm, "")
-    .replace(/<\/script>/g, "<\\/script>");
-  const rendererBlock = rendererSrc
-    ? "<script>\n(function () {\n" +
-      rendererSrc +
-      "\nwindow.__SLIDEMIND_RENDER_MD__ = renderPlanMarkdown;\n})();\n</script>\n"
-    : "";
+  const modulesSrc = String(planModulesJs || "").replace(/<\/script>/g, "<\\/script>");
+  const rendererBlock = modulesSrc ? "<script>\n" + modulesSrc + "\n</script>\n" : "";
   return (
     "<!doctype html>\n" +
     '<html lang="en">\n' +
@@ -293,7 +381,7 @@ export async function createPlanReviewServer({
   bodyStartLine,
   previousComment = null,
   overlayJs,
-  planMdJs,
+  planModulesJs,
   logoMark = null,
   brandAssetPath = null,
   port = 0,
@@ -305,13 +393,13 @@ export async function createPlanReviewServer({
   // NEXT plan round — never into the preview gate or a foreign app on the port.
   const hb = createHeartbeat({ service: "slidemind-plan" });
   const overlay = overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8");
-  const planMd = planMdJs ?? fs.readFileSync(PLAN_MD_PATH, "utf8");
+  const planModules = planModulesJs ?? bundlePlanModulesFromDisk();
   const bodyHtml = renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 });
   const indexHtml = buildPlanPage({
     bodyHtml,
     previousComment,
     overlayJs: overlay,
-    planMdJs: planMd,
+    planModulesJs: planModules,
     logoMark,
     planBody: body,
     bodyStartLine,
@@ -355,11 +443,20 @@ export async function createPlanReviewServer({
     }
 
     if (pathname === "/__plan/heartbeat") {
-      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;
     }
 
     if (pathname === "/" || pathname === "/index.html") {
+      // A browser fetched the gate page — the end-to-end proof the plan 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;
@@ -401,6 +498,9 @@ export async function createPlanReviewServer({
     url,
     port: addr.port,
     waitForHeartbeat: (ms) => hb.waitForHeartbeat(ms),
+    markOpenedFresh: () => hb.markFresh(),
+    waitForPageLoad: (ms) => hb.waitForPageLoad(ms),
+    pageLoaded: () => hb.pageLoaded(),
     waitForDecision: (opts) => gate.waitForDecision(opts),
     close() {
       try {
@@ -430,7 +530,9 @@ export async function runPlanReview({
   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,
 } = {}) {
   const base = path.basename(deckDir);
   const planPath = path.join(deckDir, "plan.md");
@@ -467,13 +569,12 @@ export async function runPlanReview({
   });
   // 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,
     readyLabel: "Plan review",
     reuseNoun: "plan tab",
-    openedLine:
-      "Opened your browser — edit the plan or tell the agent what to change; approving starts the build.",
+    gateNoun: "plan review",
     waitLine:
       `Waiting for the user's decision — this command BLOCKS (up to ${Math.round(
         timeoutMs / 60000,
@@ -482,12 +583,32 @@ export async function runPlanReview({
 
   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(formatPlanPendingForHarness(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(
+        formatPlanPendingForHarness(deckDir, {
+          timeoutMs,
+          pageLoaded: server.pageLoaded(),
+          url: server.url,
+        }),
+      );
       return null;
     }
     throw err;

package/src/builders/red-thread-backbone.mjs

@@ -0,0 +1,194 @@
+/**
+ * Red-thread backbone editing.
+ *
+ * The red thread is the structural backbone of the plan: one presentation
+ * move per slide, mirrored by one `### Slide N` storyboard subsection. This
+ * module maps a user-edited backbone (renamed, reordered, added, or removed
+ * slides) back onto the plan markdown in one pass: it rewrites the
+ * `## Red thread` bullets and restructures the per-slide sections to match —
+ * reordering, renumbering headings and storyboard `slide` fields, dropping
+ * removed slides, and inserting placeholder sections for new ones.
+ *
+ * Pure string logic — no React, no Office (unit-testable).
+ *
+ * 1:1 port of the add-in's red-thread-backbone.ts. Top-level helpers are
+ * prefixed `rt…` so the browser bundle (one IIFE across five modules) has no
+ * name collisions; exported API names match the add-in verbatim.
+ */
+
+import { extractRedThreadMessages, findRedThreadSection } from "./storyboard-markdown.mjs";
+
+/**
+ * One slide in the user-edited backbone draft:
+ *   { key: string, originalIndex: number | null, message: string }
+ * `originalIndex` is the index into the original plan's slide sections, or
+ * null for a new slide.
+ */
+export function backboneFromMessages(messages) {
+  return messages.map((message, index) => ({
+    key: `slide-${index}`,
+    originalIndex: index,
+    message,
+  }));
+}
+
+const RT_SLIDE_HEADING_RE = /^###\s+Slide\s+\d+.*$/gim;
+const RT_NEXT_H2_IN_SECTION_RE = /^##\s/m;
+
+function rtFindSlideSections(markdown) {
+  const starts = [];
+  for (const match of markdown.matchAll(RT_SLIDE_HEADING_RE)) {
+    starts.push(match.index ?? 0);
+  }
+  return starts.map((start, index) => {
+    let end = starts[index + 1] ?? markdown.length;
+    // A later `## ` heading closes the storyboard area before the doc ends;
+    // search after the section's own heading line.
+    const headingLineEnd = markdown.indexOf("\n", start);
+    const searchFrom =
+      headingLineEnd === -1 ? end : Math.min(headingLineEnd + 1, end);
+    const followUp = RT_NEXT_H2_IN_SECTION_RE.exec(markdown.slice(searchFrom, end));
+    if (followUp) end = searchFrom + followUp.index;
+    return { start, end, text: markdown.slice(start, end) };
+  });
+}
+
+/**
+ * The backbone is editable only when the red-thread moves and the slide
+ * sections line up one-to-one — otherwise a positional restructure could
+ * attach the wrong storyboard to a move.
+ *
+ * Returns { messages, sectionCount } or null.
+ */
+export function parsePlanBackbone(markdown) {
+  const messages = extractRedThreadMessages(markdown);
+  if (!messages.length) return null;
+  if (!findRedThreadSection(markdown)) return null;
+  const sections = rtFindSlideSections(markdown);
+  if (sections.length !== messages.length) return null;
+  return { messages, sectionCount: sections.length };
+}
+
+function rtSanitizeMessage(message) {
+  return message.replace(/\s+/g, " ").trim();
+}
+
+function rtRenumberSection(text, slideNumber, editedMessage) {
+  let next = text.replace(/^###\s+Slide\s+\d+/, `### Slide ${slideNumber}`);
+  if (editedMessage) {
+    next = next.replace(
+      /^(###\s+Slide\s+\d+)(?::[^\n]*)?$/m,
+      `$1: ${editedMessage}`,
+    );
+  }
+  return next.replace(/("slide"\s*:\s*)\d+/, `$1${slideNumber}`);
+}
+
+const RT_NEW_SLIDE_CONTENT_MAX = 28;
+
+function rtPlaceholderSection(message, slideNumber) {
+  const content =
+    message.slice(0, RT_NEW_SLIDE_CONTENT_MAX).trim() || `Slide ${slideNumber}`;
+  const storyboard = {
+    version: 1,
+    slide: slideNumber,
+    blocks: [
+      {
+        id: "block-1",
+        x: 80,
+        y: 110,
+        w: 1440,
+        h: 300,
+        designElement: "Open canvas",
+        content,
+      },
+    ],
+    keyMessage: message,
+  };
+  return [
+    `### Slide ${slideNumber}: ${message}`,
+    "",
+    `Core message: ${message}`,
+    "",
+    "```storyboard-canvas",
+    JSON.stringify(storyboard, null, 2),
+    "```",
+  ].join("\n");
+}
+
+/**
+ * Turns a staged backbone draft into the feedback round that asks the agent
+ * to build it: the restructured plan markdown plus a feedback message naming
+ * each added/renamed slide. Returns null when the draft cannot be applied or
+ * contains no content-affecting change.
+ *
+ * Returns { feedback, editedPlanMarkdown } or null.
+ */
+export function stageStoryIteration(markdown, slides) {
+  const editedPlanMarkdown = applyPlanBackbone(markdown, slides);
+  if (!editedPlanMarkdown) return null;
+  const committed = extractRedThreadMessages(markdown);
+  const changes = [];
+  slides.forEach((slide, index) => {
+    const position = index + 1;
+    if (slide.originalIndex === null) {
+      changes.push(`Added slide ${position} for the move "${slide.message}".`);
+    } else if (committed[slide.originalIndex] !== slide.message) {
+      changes.push(`Renamed slide ${position}'s move to "${slide.message}".`);
+    }
+  });
+  if (!changes.length) return null;
+  const feedback = [
+    "I edited the red thread.",
+    ...changes,
+    "Build the storyboards and slide content for the new moves and adapt any renamed moves so the deck stays coherent, keeping the other slides intact.",
+  ].join(" ");
+  return { feedback, editedPlanMarkdown };
+}
+
+/**
+ * Rewrites the plan markdown to match the edited backbone. Returns null when
+ * the plan's structure cannot be edited safely (see `parsePlanBackbone`).
+ */
+export function applyPlanBackbone(markdown, slides) {
+  const cleaned = slides
+    .map((slide) => ({ ...slide, message: rtSanitizeMessage(slide.message) }))
+    .filter((slide) => slide.message.length > 0);
+  if (!cleaned.length) return null;
+
+  const backbone = parsePlanBackbone(markdown);
+  const redThread = findRedThreadSection(markdown);
+  if (!backbone || !redThread) return null;
+  const sections = rtFindSlideSections(markdown);
+
+  const firstSection = sections[0];
+  const lastSection = sections[sections.length - 1];
+  if (!firstSection || !lastSection) return null;
+  if (firstSection.start < redThread.bodyEnd) return null;
+
+  const newRedThreadBody = `\n\n${cleaned
+    .map((slide) => `- ${slide.message}`)
+    .join("\n")}\n\n`;
+
+  const newSections = cleaned.map((slide, index) => {
+    const slideNumber = index + 1;
+    if (slide.originalIndex === null) {
+      return rtPlaceholderSection(slide.message, slideNumber);
+    }
+    const section = sections[slide.originalIndex];
+    if (!section) return rtPlaceholderSection(slide.message, slideNumber);
+    const originalMessage = backbone.messages[slide.originalIndex] ?? "";
+    const edited =
+      rtSanitizeMessage(originalMessage) !== slide.message ? slide.message : null;
+    return rtRenumberSection(section.text.trimEnd(), slideNumber, edited);
+  });
+
+  return [
+    markdown.slice(0, redThread.bodyStart),
+    newRedThreadBody,
+    markdown.slice(redThread.bodyEnd, firstSection.start),
+    newSections.join("\n\n"),
+    "\n",
+    markdown.slice(lastSection.end),
+  ].join("");
+}

package/src/builders/review-overlay.js

@@ -144,6 +144,9 @@
     ".sm-meta{display:flex;flex-direction:column;gap:2px;}" +
     ".sm-meta .t{font-weight:600;font-size:13px;}" +
     ".sm-meta .h{font-size:11.5px;color:var(--sm-dim);}" +
+    ".sm-note{max-width:min(560px,38vw);font-size:10.5px;line-height:1.35;color:#c7c7cf;" +
+    "border-left:2px solid var(--sm-accent);padding-left:10px;}" +
+    ".sm-note b{font-weight:600;color:#f4f4f5;}" +
     ".sm-bar~.deck__rail,.deck__rail{top:var(--deck-chrome-h,62px);}" +
     ".sm-grow{flex:1;}" +
     ".sm-count{font-size:12px;color:var(--sm-dim);font-variant-numeric:tabular-nums;}" +
@@ -319,7 +322,7 @@
   }
 
   // ---------- chrome (top bar) ----------
-  var bar, sendBtn, countLabel;
+  var bar, sendBtn, approveBtn, countLabel;
   function buildChrome() {
     bar = el("div", "sm-o sm-bar");
     bar.setAttribute("data-sm-overlay", "1");
@@ -335,6 +338,13 @@
     meta.appendChild(el("div", "h", "Click any element to comment · ← → to switch slide"));
     bar.appendChild(meta);
 
+    var note = el(
+      "div",
+      "sm-note",
+      "<b>Ask for slide changes here.</b> Direct PowerPoint edits after approval are not tracked and may be overwritten. HTML preview may differ slightly from final PowerPoint.",
+    );
+    bar.appendChild(note);
+
     bar.appendChild(el("div", "sm-grow"));
 
     countLabel = el("div", "sm-count");
@@ -347,8 +357,9 @@
     };
     bar.appendChild(sendBtn);
 
-    var approveBtn = mkButton("Approve & continue", "primary", "check");
+    approveBtn = mkButton("Approve & continue", "primary", "check");
     approveBtn.onclick = function () {
+      if (totalComments() > 0) return;
       submit("approve");
     };
     bar.appendChild(approveBtn);
@@ -362,6 +373,11 @@
     sendBtn.querySelector("span").textContent =
       n > 0 ? "Send " + n + " comment" + (n === 1 ? "" : "s") : "Send comments";
     sendBtn.classList.toggle("is-off", n === 0);
+    approveBtn.disabled = n > 0;
+    approveBtn.setAttribute("aria-disabled", n > 0 ? "true" : "false");
+    approveBtn.classList.toggle("is-off", n > 0);
+    approveBtn.title =
+      n > 0 ? "Send or delete active comments before approving." : "Approve and continue.";
   }
 
   // ---------- hover box (mirrors the add-in's hit-region-overlay) ----------
@@ -808,7 +824,12 @@
   }
   // After a comments round the tab stays open and polls the heartbeat so the
   // NEXT run (which binds the same deterministic port) reloads this tab instead
-  // of opening a fresh browser window.
+  // of opening a fresh browser window. The poll reports this tab's round nonce
+  // and its visibility: only a VISIBLE tab may claim the next round for reuse —
+  // a tab buried in a background window must not swallow the round invisibly,
+  // so the server opens a fresh browser tab instead and answers `action:
+  // "close"` here, which retires this tab with a notice rather than reloading
+  // it into a hidden duplicate.
   function startNextRoundPolling() {
     var startedAt = Date.now();
     var pollMs = CFG.pollMs || 1000;
@@ -820,17 +841,26 @@
         showSessionEnded();
         return;
       }
-      fetch(hb, { cache: "no-store" })
+      var visible = document.visibilityState === "visible" ? "1" : "0";
+      var url = hb + (hb.indexOf("?") < 0 ? "?" : "&") +
+        "round=" + encodeURIComponent(CFG.round || "") + "&visible=" + visible;
+      fetch(url, { cache: "no-store" })
         .then(function (r) { return r.ok ? r.json() : null; })
         .then(function (data) {
-          // Reload only for a genuine NEWER slidemind review round: shape-guard the
+          // Act only on a genuine NEWER slidemind review round: shape-guard the
           // service marker (a foreign app may have taken the port) and require a
           // different nonce (same nonce = this run's own orphan — never self-reload).
           if (!data || data.service !== "slidemind-review" || !data.round) return;
-          if (data.round !== CFG.round) {
+          if (data.round === CFG.round) return;
+          if (data.action === "close") {
+            // The new round opened in a fresh browser tab — this one is stale.
             clearInterval(timer);
-            markRoundReadyAndReload();
+            showSuperseded();
+            return;
           }
+          if (data.action === "wait") return; // grace window still deciding — keep polling
+          clearInterval(timer);
+          markRoundReadyAndReload();
         })
         .catch(function () { /* server down between rounds — keep polling */ });
     }, pollMs);
@@ -871,6 +901,13 @@
   function showSessionEnded() {
     showVeil("<span>Session ended</span>", "You can close this tab.");
   }
+  function showSuperseded() {
+    document.title = "Review moved — slidemind";
+    showVeil(
+      "<span>Continued in a new tab</span>",
+      "The next review round opened in a fresh browser tab — you can close this one.",
+    );
+  }
 
   // ---------- slide tracking ----------
   function syncSlideFromNav() {