slidemind 0.1.7 → 0.1.8

package/src/builders/review-overlay.js

@@ -120,6 +120,7 @@
     "@keyframes sm-pin-in{from{transform:translate(-50%,-50%) scale(0)}to{transform:translate(-50%,-50%) scale(1)}}" +
     "@keyframes sm-veil-in{from{opacity:0}to{opacity:1}}" +
     "@keyframes sm-rise{from{opacity:0;transform:translateY(14px)}to{opacity:1;transform:none}}" +
+    "@keyframes sm-pulse{0%,100%{opacity:.45}50%{opacity:.85}}" +
     ":root{--sm-bg:var(--deck-chrome-bg,#111113);--sm-surface:var(--deck-chrome-bg-2,#161618);" +
     "--sm-border:var(--deck-chrome-border,#2b2b30);--sm-fg:var(--deck-chrome-fg,#ededed);" +
     "--sm-dim:var(--deck-chrome-dim,#9a9aa0);--sm-accent:#a9c2ff;--sm-success:#2ecc71;--sm-danger:#f87171;" +
@@ -195,6 +196,7 @@
     ".sm-veil .status{display:flex;align-items:center;gap:10px;font-size:18px;font-weight:600;animation:sm-rise .6s .12s cubic-bezier(.2,.7,.2,1) both;}" +
     ".sm-veil .status svg{width:24px;height:24px;color:var(--sm-success);}" +
     ".sm-veil .sub{color:var(--sm-dim);font-size:13.5px;animation:sm-rise .6s .18s cubic-bezier(.2,.7,.2,1) both;}" +
+    ".sm-veil .sub.sm-pulse{animation:sm-rise .6s .18s cubic-bezier(.2,.7,.2,1) both,sm-pulse 2s .9s ease-in-out infinite;}" +
     /* hover box */
     ".sm-hover{position:fixed;z-index:2147483450;pointer-events:none;border-radius:5px;border:2px solid var(--sm-accent);" +
     "box-shadow:0 0 0 1px rgba(0,0,0,.3),0 6px 22px rgba(0,0,0,.28);opacity:0;" +
@@ -676,10 +678,96 @@
     lockHoverBoxToBbox(comment.resolvedTarget && comment.resolvedTarget.bbox);
   }
 
+  // ---------- next-round attention ----------
+  // Same trio as plan-overlay.js: a background tab cannot steal focus (browser
+  // design), but it CAN fire a system notification whose click is allowed to
+  // focus it, and flag itself in the tab bar until it is looked at. The
+  // permission prompt only shows inside a user gesture, so it is requested at
+  // the send-comments click; the "announce" wish survives the reload via
+  // sessionStorage (the reload wipes this JS context).
+  var ROUND_READY_FLAG = "slidemind-review-round-ready";
+  var ATTENTION_TITLE = "● Preview ready — slidemind";
+  var WAITING_TITLE = "⏳ Agent revising slides — slidemind";
+  var notifyPermPromise = null;
+
+  function notifyPermission() {
+    try {
+      return "Notification" in window ? Notification.permission : "unsupported";
+    } catch {
+      return "unsupported";
+    }
+  }
+  function requestNotifyPermission() {
+    try {
+      if (!("Notification" in window)) return Promise.resolve("unsupported");
+      if (Notification.permission !== "default") return Promise.resolve(Notification.permission);
+      return Promise.resolve(Notification.requestPermission());
+    } catch {
+      return Promise.resolve("unsupported");
+    }
+  }
+  function markRoundReadyAndReload() {
+    try {
+      sessionStorage.setItem(ROUND_READY_FLAG, "1");
+    } catch {
+      /* storage blocked — the reload still lands, just without the announce */
+    }
+    location.reload();
+  }
+  function announceNewRound() {
+    var flagged = false;
+    try {
+      flagged = sessionStorage.getItem(ROUND_READY_FLAG) === "1";
+      if (flagged) sessionStorage.removeItem(ROUND_READY_FLAG);
+    } catch {
+      /* no storage — nothing to announce */
+    }
+    if (!flagged) return;
+    try {
+      window.focus(); // best-effort; most browsers ignore it for background tabs
+    } catch {
+      /* ignore */
+    }
+    if (!document.hidden) return; // user is already looking at it
+    var origTitle = document.title;
+    var restore = function () {
+      document.title = origTitle;
+      document.removeEventListener("visibilitychange", onVis);
+      window.removeEventListener("focus", restore);
+    };
+    var onVis = function () {
+      if (!document.hidden) restore();
+    };
+    document.title = ATTENTION_TITLE;
+    document.addEventListener("visibilitychange", onVis);
+    window.addEventListener("focus", restore);
+    try {
+      if (notifyPermission() === "granted") {
+        var n = new Notification("slidemind — preview ready", {
+          body: "The revised slides are ready for another look. Click to jump back to the tab.",
+          tag: "slidemind-review-round",
+        });
+        n.onclick = function () {
+          try {
+            window.focus();
+          } catch {
+            /* ignore */
+          }
+          n.close();
+        };
+      }
+    } catch {
+      /* notification construction can throw on some platforms — title marker stands */
+    }
+  }
+
   // ---------- submit ----------
   function submit(decision) {
     if (submitted) return;
     submitted = true;
+    // Ask for notification permission HERE — the send/approve click is a user
+    // gesture, the only context where the browser will show the prompt.
+    if (decision === "comments") notifyPermPromise = requestNotifyPermission();
     var comments = [];
     Object.keys(commentsBySlide).forEach(function (stem) {
       commentsBySlide[stem].forEach(function (c) {
@@ -695,8 +783,13 @@
       }),
     })
       .then(function () {
-        showDone(decision);
-        requestTabClose();
+        if (decision === "approve") {
+          showDone("approve");
+          requestTabClose();
+        } else {
+          showWaiting();
+          startNextRoundPolling();
+        }
       })
       .catch(function () {
         submitted = false;
@@ -713,24 +806,71 @@
       }
     }, 120);
   }
-  function showDone(decision) {
+  // 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.
+  function startNextRoundPolling() {
+    var startedAt = Date.now();
+    var pollMs = CFG.pollMs || 1000;
+    var ttl = CFG.pollTtlMs || 35 * 60 * 1000;
+    var hb = CFG.heartbeat || "/__review/heartbeat";
+    var timer = setInterval(function () {
+      if (Date.now() - startedAt > ttl) {
+        clearInterval(timer);
+        showSessionEnded();
+        return;
+      }
+      fetch(hb, { 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
+          // 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) {
+            clearInterval(timer);
+            markRoundReadyAndReload();
+          }
+        })
+        .catch(function () { /* server down between rounds — keep polling */ });
+    }, pollMs);
+  }
+  // Shared full-screen veil (logo + wordmark + status + sub). Replaces any veil
+  // already shown rather than stacking a second one, so a comments round's
+  // "waiting" veil can be swapped for "session ended" in place.
+  function showVeil(statusHtml, subText, subPulse) {
     closePopover();
     if (pinLayer) pinLayer.style.display = "none";
     if (bar) bar.style.display = "none";
+    var existing = document.querySelector(".sm-veil[data-sm-overlay]");
+    if (existing && existing.parentNode) existing.parentNode.removeChild(existing);
     var veil = el("div", "sm-o sm-veil");
     veil.setAttribute("data-sm-overlay", "1");
     veil.appendChild(logoNode("sm-logo", "-v"));
     veil.appendChild(el("div", "word", wordmarkHtml()));
-    veil.appendChild(
-      el(
-        "div",
-        "status",
-        ICONS.check + "<span>" + (decision === "approve" ? "Approved" : "Comments sent") + "</span>",
-      ),
-    );
-    veil.appendChild(el("div", "sub", "Returned to your terminal."));
+    veil.appendChild(el("div", "status", statusHtml));
+    veil.appendChild(el("div", "sub" + (subPulse ? " sm-pulse" : ""), subText));
     document.body.appendChild(veil);
   }
+  function showDone() {
+    showVeil(ICONS.check + "<span>Approved</span>", "Returned to your terminal.");
+  }
+  function showWaiting() {
+    document.title = WAITING_TITLE; // the tab label signals the state from the tab bar
+    showVeil(
+      ICONS.check + "<span>Comments sent</span>",
+      "The agent is revising the slides — this tab refreshes automatically when the next round is ready.",
+      true,
+    );
+    (notifyPermPromise || Promise.resolve(notifyPermission())).then(function (perm) {
+      if (perm !== "granted") return;
+      var sub = document.querySelector(".sm-veil[data-sm-overlay] .sub");
+      if (sub) sub.textContent += " You'll get a notification the moment it's ready.";
+    });
+  }
+  function showSessionEnded() {
+    showVeil("<span>Session ended</span>", "You can close this tab.");
+  }
 
   // ---------- slide tracking ----------
   function syncSlideFromNav() {
@@ -826,6 +966,7 @@
     }
     syncSlideFromNav();
     applyStageFit();
+    announceNewRound(); // notification + title marker when this load IS the next round
   }
 
   if (document.readyState === "loading") {

package/src/builders/review.mjs

@@ -16,6 +16,15 @@
 // 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.
 
 import fs from "node:fs";
 import http from "node:http";
@@ -25,6 +34,18 @@ 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,
+  GRACE_MS,
+  POLL_MS,
+  POLL_TTL_MS,
+} from "./gate-server.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -32,21 +53,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 +138,45 @@ export function formatCommentsForHarness(deckDir, comments) {
     out.push(`    Comment: ${c.comment}`);
     out.push("");
   });
-  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)}`,
-  );
+  // 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.
+  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 } = {}) {
+  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.`,
+    "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 +189,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 +209,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 +226,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 +238,7 @@ export async function createReviewServer({
     previousComments,
     overlay,
     logoMark,
+    hb.round,
   );
   const deckRoot = path.resolve(deckDir);
 
@@ -212,7 +261,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,6 +275,14 @@ 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.
+      hb.respond(res);
+      return;
+    }
+
     if (
       pathname === "/" ||
       pathname === "/index.html" ||
@@ -236,29 +293,18 @@ export async function createReviewServer({
       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 +312,11 @@ 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);
+    },
+    waitForDecision(opts = {}) {
+      return gate.waitForDecision(opts);
     },
     close() {
       try {
@@ -289,10 +328,21 @@ 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.
+export function serveAndOpen(server, opts = {}) {
+  return gateServeAndOpen(server, { open: openInBrowser, ...opts });
+}
+
 export async function runReview({
   deckDir,
-  port = 0,
+  port = null,
   timeoutMs = DEFAULT_TIMEOUT_MS,
+  open = openInBrowser,
 } = {}) {
   await buildDeck(deckDir);
   const prev = loadReviewState(deckDir);
@@ -303,21 +353,35 @@ 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).
+  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 {
     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 }));
+      return null;
+    }
+    throw err;
   } finally {
     server.close();
   }
@@ -342,7 +406,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) {