slidemind 0.2.3 → 0.3.0

package/src/builders/review-overlay.js

@@ -7,11 +7,36 @@
 //   - Every intrinsic element carries data-sm-loc="slides/<f>.jsx:line:col"
 //     (stamped by build.mjs's Babel plugin).
 //   - Click anywhere on the stage -> resolve the innermost element under the
-//     click via closest('[data-sm-loc]') and its ancestor chain, drop a pin,
-//     capture a note. Slide-level notes (empty-area clicks) carry no element.
-//   - Previous round's comments render as read-only ghost pins.
-//   - Approve, or Send comments -> POST to the local server, which unblocks the
-//     `slidemind review` command so the harness proceeds. No copy-paste.
+//     click via closest('[data-sm-loc]'), drop a pin, capture a note.
+//     Slide-level notes (empty-area clicks) carry no element.
+//   - Saving a pin SENDS it (there is no batch "submit" button): the gate
+//     resolves at once and the `slidemind review` command returns with it.
+//   - Approve -> POST to the local server, which unblocks the command with the
+//     sign-off. No copy-paste.
+//
+// TWO MODES, not "reviewing vs. veiled over":
+//   - PARKED (the command is blocking on this tab): saving a pin resolves the
+//     gate right now, carrying any queued stragglers with it; Approve is live
+//     while nothing is outstanding.
+//   - WORKING (the agent is fixing the slides): the preview stays FULLY
+//     browsable and pinnable — saved pins QUEUE in sessionStorage (ledger
+//     status "queued") instead of hitting the server — and only Approve is off
+//     (the displayed render is already superseded). A status strip says so.
+//
+// Queued pins are never lost: the tab polls the heartbeat, and when the agent's
+// next `slidemind review` run claims it the reload's boot POSTs the whole
+// backlog to /review/backlog — which resolves that run immediately as a drain
+// round, so the tab simply stays in working mode with the ledger flipped to
+// "sent". A tab superseded by a fresh window flushes before retiring, likewise.
+//
+// ONE LEDGER, three statuses. Every pin is {id, round, jsxPath, resolvedTarget,
+// x, y, text, status} (x/y are full-precision 0..1 fractions of the slide):
+// queued (typed here, not yet delivered) -> sent (the agent has it) ->
+// addressed (a newer gate run served this page — the server's round nonce
+// changed). Addressed pins are the read-only GHOST pins of previous rounds —
+// there is no separate previous-round channel. A tab with no session of its own
+// seeds the ledger from CFG.ledgerSeed (the deck's persisted review.json) as
+// SENT rows: the agent has just been handed them, nothing has answered them.
 //
 // Branding (lifted from the add-in's product identity):
 //   - The embossed "raised slide" logo (public/logo.svg).
@@ -27,16 +52,45 @@
   var STAGE_SEL = "#stage";
   var HEADER_H = 62;
   var SIDEBAR_W = 316; // panel + gaps reserved on the right when comments exist
-  var commentsBySlide = {}; // stem -> [comment]   (this round, editable)
-  var previousBySlide = {}; // stem -> [comment]   (last round, read-only ghosts)
+  // The ledger IS the state: one flat list of this session's pins. Pins, sidebar
+  // rows and the approve guard are all derived from it, so a comment keeps its
+  // identity across queued -> sent -> addressed (and across the round reload).
+  var ledger = [];
+  var roundNo = 1; // this tab's round counter (sessionStorage, not server state)
   var currentStem = null;
+  var pendingStem = null; // the slide to re-anchor on after a round reload
   var draftPopover = null;
-  var submitted = false;
+  var approved = false; // approve latch — the only thing that ends the session
+  var working = false; // the agent is fixing → pins queue instead of resolving
+  var workingNote = null; // extra line for the working strip (queued / superseded)
   var sidebarEl = null;
   var sidebarOpen = false;
   var hoverBox = null;
   var locked = false; // hover box pinned to a popover's target
 
+  // The shared gate session (src/builders/gate-session.js, inlined into the page
+  // as window.__SLIDEMIND_GATE__): the deck-keyed sessionStorage ledger, the
+  // backlog flush, the server-nonce round transition, the round-ready announce
+  // and the heartbeat poll — one implementation, shared with the plan gate.
+  var SES = window.__SLIDEMIND_GATE__.createGateSession({
+    name: "review",
+    deck: CFG.deck || "",
+    storage: sessionStorage,
+    fetch: function (u, o) {
+      return fetch(u, o);
+    },
+    round: CFG.round || "",
+    service: "slidemind-review",
+    heartbeat: CFG.heartbeat || "/__review/heartbeat",
+    backlogEndpoint: CFG.backlogEndpoint || "/review/backlog",
+    pollMs: CFG.pollMs,
+    pollTtlMs: CFG.pollTtlMs,
+    roundInSentLabel: true, // "sent · round N" — a pin names the render it sits on
+    attentionTitle: "● Preview ready — slidemind",
+    notifyTitle: "slidemind — preview ready",
+    notifyBody: "The revised slides are ready for another look. Click to jump back to the tab.",
+  });
+
   // UI accent for the hover box + focus rings (product chrome). The brand
   // colour now lives entirely in the orb PNG (CFG.logoMark) served from the
   // bundle — the CLI no longer re-derives an orb from the CD's colours.
@@ -46,12 +100,6 @@
   // the sidebar jump to any slide by synthesising the deck's arrow-key nav.
   var slideOrder = [];
 
-  (CFG.previousComments || []).forEach(function (c) {
-    var stem = stemOf(c && c.jsxPath);
-    if (!stem) return;
-    (previousBySlide[stem] = previousBySlide[stem] || []).push(c);
-  });
-
   // ---------- brand assets ----------
   // The add-in's embossed "raised slide" mark (src/ui/public/logo.svg), inlined.
   var LOGO_SVG =
@@ -150,6 +198,15 @@
     ".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;}" +
+    /* working strip: the agent is fixing — the preview stays live behind it */
+    ".sm-status{display:none;align-items:center;gap:9px;max-width:min(420px,32vw);padding:7px 12px;border-radius:10px;" +
+    "border:1px solid color-mix(in srgb,var(--sm-accent) 32%,transparent);" +
+    "background:color-mix(in srgb,var(--sm-accent) 10%,transparent);font-size:11.5px;line-height:1.4;color:#d7d7de;}" +
+    ".sm-status.on{display:flex;}" +
+    ".sm-status b{display:block;font-weight:600;font-size:12px;color:#f4f4f5;}" +
+    ".sm-spin{width:11px;height:11px;flex-shrink:0;border-radius:50%;border:2px solid var(--sm-accent);" +
+    "border-top-color:transparent;animation:sm-spin 0.9s linear infinite;}" +
+    "@keyframes sm-spin{to{transform:rotate(360deg)}}" +
     /* buttons */
     ".sm-btn{display:inline-flex;align-items:center;gap:7px;border:1px solid transparent;border-radius:9px;" +
     "padding:8px 14px;font-family:var(--sm-font);font-weight:600;font-size:12.5px;cursor:pointer;" +
@@ -169,7 +226,10 @@
     "font:600 12px var(--sm-font);cursor:pointer;display:flex;align-items:center;justify-content:center;" +
     "pointer-events:auto;animation:sm-pin-in .26s cubic-bezier(.2,1.5,.4,1);transition:filter .12s;}" +
     ".sm-pin:hover{filter:brightness(1.12);}" +
+    /* queued (typed here, not delivered yet) / sent (the agent has it) /
+       addressed (answered by a newer render — the read-only ghost) */
     ".sm-pin-active{background:#161618;color:#fff;border:2px solid rgba(255,255,255,.92);box-shadow:0 2px 9px rgba(0,0,0,.55);}" +
+    ".sm-pin-sent{background:#161618;color:var(--sm-accent);border:2px dashed var(--sm-accent);box-shadow:0 2px 9px rgba(0,0,0,.45);}" +
     ".sm-pin-ghost{background:rgba(20,20,22,.72);color:#a1a1aa;border:1.5px dashed #71717a;}" +
     /* popover */
     ".sm-pop{position:fixed;z-index:2147483646;width:272px;padding:13px;background:var(--sm-surface);" +
@@ -223,7 +283,12 @@
     "font-size:10px;font-weight:600;margin-top:1px;background:#161618;color:#fff;border:1.5px solid rgba(255,255,255,.85);}" +
     ".sm-side-chip.ghost{background:rgba(20,20,22,.6);color:#a1a1aa;border:1.5px dashed #71717a;}" +
     ".sm-side-txt{font-size:12.5px;line-height:1.4;color:#e4e4e7;word-break:break-word;}" +
-    ".sm-side-loc{font-size:10.5px;color:var(--sm-dim);font-family:ui-monospace,SFMono-Regular,Menlo,monospace;margin-top:2px;word-break:break-all;}";
+    ".sm-side-loc{font-size:10.5px;color:var(--sm-dim);font-family:ui-monospace,SFMono-Regular,Menlo,monospace;margin-top:2px;word-break:break-all;}" +
+    /* ledger status chip — where each pin stands, per row */
+    ".sm-side-state{display:inline-block;margin-top:4px;padding:1px 7px;border-radius:999px;font-size:9.5px;font-weight:600;" +
+    "letter-spacing:.05em;text-transform:uppercase;border:1px solid var(--sm-border);color:var(--sm-dim);}" +
+    '.sm-side-state[data-state="queued"]{border-color:color-mix(in srgb,var(--sm-accent) 45%,transparent);color:var(--sm-accent);}' +
+    '.sm-side-state[data-state="sent"]{border-color:color-mix(in srgb,var(--sm-accent) 30%,transparent);color:#c6d4f5;}';
 
   // ---------- helpers ----------
   function stemOf(jsxPath) {
@@ -239,15 +304,31 @@
   function stage() {
     return document.querySelector(STAGE_SEL);
   }
+  // Click position, a FULL-PRECISION 0..1 fraction of the slide end to end —
+  // on the wire and in review.json. Whole percent is a display unit only (the
+  // harness output rounds); persisting it drifted a pin by up to 6px on a
+  // 1280px stage and collapsed every sub-1% offset to the edge.
+  function fx(c) {
+    return clamp01(Number(c.x) || 0);
+  }
+  function fy(c) {
+    return clamp01(Number(c.y) || 0);
+  }
+  function commentsForStem(stem) {
+    return ledger.filter(function (c) {
+      return stemOf(c.jsxPath) === stem;
+    });
+  }
   function activeComments() {
-    return commentsBySlide[currentStem] || [];
+    return commentsForStem(currentStem);
   }
-  function totalComments() {
-    var n = 0;
-    Object.keys(commentsBySlide).forEach(function (k) {
-      n += commentsBySlide[k].length;
+  // Outstanding = written but not yet answered by a render. This is the approve
+  // guard: signing off while something is outstanding would approve slides the
+  // agent has been told to change.
+  function openComments() {
+    return ledger.filter(function (c) {
+      return c.status === "queued" || c.status === "sent";
     });
-    return n;
   }
   function el(tag, cls, html) {
     var e = document.createElement(tag);
@@ -278,18 +359,12 @@
     b.innerHTML = (iconName ? ICONS[iconName] : "") + "<span>" + label + "</span>";
     return b;
   }
-  function mkButton(label, variant, iconName) {
-    var b = el("button", "sm-btn sm-btn-" + variant);
-    b.innerHTML = (iconName ? ICONS[iconName] : "") + "<span>" + label + "</span>";
-    return b;
-  }
 
-  // Build the resolvedTarget HitRegion + ancestor locs for an element, in the
-  // same shape the add-in's preview-review uses, so the harness-side formatter
-  // ports verbatim.
+  // Build the resolvedTarget HitRegion for an element, in the same shape the
+  // add-in's preview-review uses, so the harness-side formatter ports verbatim.
   function describeTarget(elx) {
     var st = stage();
-    if (!elx || !st) return { region: null, ancestors: [] };
+    if (!elx || !st) return null;
     var sr = st.getBoundingClientRect();
     var r = elx.getBoundingClientRect();
     var cls =
@@ -298,31 +373,52 @@
         : elx.getAttribute("class") || "";
     var depth = 0;
     for (var q = elx.parentElement; q && q !== st; q = q.parentElement) depth++;
-    var ancestors = [];
-    for (var p = elx.parentElement; p && p !== st; p = p.parentElement) {
-      var aloc = p.getAttribute && p.getAttribute("data-sm-loc");
-      if (aloc) ancestors.push(aloc);
-    }
     return {
-      region: {
-        loc: elx.getAttribute("data-sm-loc"),
-        tag: elx.tagName.toLowerCase(),
-        className: cls,
-        textSnippet: (elx.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80),
-        bbox: {
-          x: (r.left - sr.left) / sr.width,
-          y: (r.top - sr.top) / sr.height,
-          w: r.width / sr.width,
-          h: r.height / sr.height,
-        },
-        depth: depth,
+      loc: elx.getAttribute("data-sm-loc"),
+      tag: elx.tagName.toLowerCase(),
+      className: cls,
+      textSnippet: (elx.textContent || "").replace(/\s+/g, " ").trim().slice(0, 80),
+      bbox: {
+        x: (r.left - sr.left) / sr.width,
+        y: (r.top - sr.top) / sr.height,
+        w: r.width / sr.width,
+        h: r.height / sr.height,
       },
-      ancestors: ancestors,
+      depth: depth,
     };
   }
 
+  // ---------- session (shared with the plan gate via gate-session.js) ----------
+  function saveLedger() {
+    SES.saveLedger(ledger);
+  }
+  // The context the NEXT round restores from: the server nonce (the round
+  // marker, added by the shared session) plus which slide the reviewer was on.
+  function saveCtx() {
+    SES.saveCtx({ round: roundNo, stem: currentStem });
+  }
+  function queuedComments() {
+    return SES.queued(ledger);
+  }
+  function flushBacklog() {
+    return SES.flushBacklog(ledger);
+  }
+
+  // Restore this tab's session and work out whether THIS load is a new round.
+  // Runs before the first render so the chrome is built in the right mode.
+  function restoreSession() {
+    var st = SES.restore(CFG.ledgerSeed);
+    ledger = st.ledger;
+    roundNo = st.roundNo;
+    working = st.working;
+    // Reviewer context survives the round: come back to the same slide.
+    if (st.ctx && typeof st.ctx.stem === "string" && st.ctx.stem) pendingStem = st.ctx.stem;
+    saveLedger();
+    saveCtx();
+  }
+
   // ---------- chrome (top bar) ----------
-  var bar, sendBtn, approveBtn, countLabel;
+  var bar, approveBtn, countLabel, statusEl;
   function buildChrome() {
     bar = el("div", "sm-o sm-bar");
     bar.setAttribute("data-sm-overlay", "1");
@@ -338,10 +434,15 @@
     meta.appendChild(el("div", "h", "Click any element to comment · ← → to switch slide"));
     bar.appendChild(meta);
 
+    // The working strip: shown instead of the old full-screen waiting veil, so
+    // the preview behind it stays readable and pinnable while the agent fixes.
+    statusEl = el("div", "sm-o sm-status");
+    bar.appendChild(statusEl);
+
     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.",
+      "<b>Ask for slide changes here.</b> Direct PowerPoint edits after approval are not tracked and may be overwritten. Preview may differ slightly from final PowerPoint.",
     );
     bar.appendChild(note);
 
@@ -350,34 +451,55 @@
     countLabel = el("div", "sm-count");
     bar.appendChild(countLabel);
 
-    sendBtn = mkButton("Send comments", "ghost", "message");
-    sendBtn.onclick = function () {
-      if (totalComments() === 0) return;
-      submit("comments");
-    };
-    bar.appendChild(sendBtn);
-
     approveBtn = mkButton("Approve & continue", "primary", "check");
-    approveBtn.onclick = function () {
-      if (totalComments() > 0) return;
-      submit("approve");
-    };
+    approveBtn.onclick = approve;
     bar.appendChild(approveBtn);
 
     document.body.appendChild(bar);
     refreshChrome();
   }
+  // Approve is refused while the agent is fixing (the render on screen is
+  // superseded) or while pins are QUEUED here — sending them is the reviewer's
+  // own next action, and approving would drop them. It is NOT refused for
+  // already-delivered ("sent") pins: the same rule the plan gate uses. Guarding
+  // on those deadlocked the gate — a sent pin only clears on a round transition,
+  // so a round that touched no file left Approve off for the rest of the session.
   function refreshChrome() {
-    var n = totalComments();
-    countLabel.textContent = n === 0 ? "no comments yet" : n + (n === 1 ? " comment" : " comments");
-    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.";
+    if (!countLabel) return;
+    var open = openComments().length;
+    var q = queuedComments().length;
+    countLabel.textContent =
+      ledger.length === 0
+        ? "no comments yet"
+        : open + " open · " + ledger.length + " total";
+    var off = working || q > 0;
+    approveBtn.disabled = off;
+    approveBtn.setAttribute("aria-disabled", off ? "true" : "false");
+    approveBtn.classList.toggle("is-off", off);
+    approveBtn.title = working
+      ? "The agent is fixing the slides — approve once the next round arrives."
+      : q > 0
+        ? "Send your queued comments first."
+        : "Approve and continue.";
+    statusEl.classList.toggle("on", working);
+    if (working) {
+      statusEl.innerHTML = '<div class="sm-spin"></div>';
+      var txt = el("div");
+      txt.appendChild(el("div", null, "<b>The agent is fixing the slides</b>"));
+      txt.appendChild(
+        el(
+          "div",
+          null,
+          "",
+        ),
+      ).textContent =
+        (workingNote ? workingNote + " " : "") +
+        (q
+          ? q + (q === 1 ? " comment is" : " comments are") +
+            " queued — they're delivered with the next round."
+          : "Keep browsing and keep commenting — new pins are picked up automatically.");
+      statusEl.appendChild(txt);
+    }
   }
 
   // ---------- hover box (mirrors the add-in's hit-region-overlay) ----------
@@ -440,38 +562,45 @@
     renderPins();
   }
 
-  // ---------- sidebar (the add-in's comment list) ----------
+  // ---------- ledger rail (the add-in's comment list, with status) ----------
   function commentScreenPoint(c) {
     var sr = stage().getBoundingClientRect();
     return {
-      x: sr.left + clamp01(c.point.x) * sr.width,
-      y: sr.top + clamp01(c.point.y) * sr.height,
+      x: sr.left + fx(c) * sr.width,
+      y: sr.top + fy(c) * sr.height,
     };
   }
-  function openCommentAt(c, ghost) {
+  // Only a QUEUED pin is still the reviewer's to change; once it is with the
+  // agent it is read-only history.
+  function openCommentAt(c) {
     var p = commentScreenPoint(c);
-    if (ghost) openGhost(c, p.x, p.y);
-    else openEditor(c, p.x, p.y);
+    if (c.status === "queued") openEditor(c, p.x, p.y);
+    else openGhost(c, p.x, p.y);
+  }
+  function statusLabel(c) {
+    return SES.statusLabel(c);
   }
-  function sideRow(stem, c, num, ghost) {
+  function sideRow(stem, c, num) {
     var r = el("div", "sm-side-row");
-    var chip = el("div", "sm-side-chip" + (ghost ? " ghost" : ""));
+    var chip = el("div", "sm-side-chip" + (c.status === "addressed" ? " ghost" : ""));
     chip.textContent = String(num);
     var txt = el("div");
-    txt.appendChild(el("div", "sm-side-txt", "")).textContent = c.comment;
+    txt.appendChild(el("div", "sm-side-txt", "")).textContent = c.text;
     var locStr = c.resolvedTarget && c.resolvedTarget.loc ? c.resolvedTarget.loc : "slide-level note";
     txt.appendChild(el("div", "sm-side-loc", "")).textContent = locStr;
+    var state = txt.appendChild(el("div", "sm-side-state", ""));
+    state.setAttribute("data-state", c.status);
+    state.textContent = statusLabel(c);
     r.appendChild(chip);
     r.appendChild(txt);
     r.onclick = function () {
       goToStem(stem);
-      openCommentAt(c, ghost);
+      openCommentAt(c);
     };
     return r;
   }
   function updateSidebar() {
-    var show = totalComments() > 0;
-    if (!show) {
+    if (!ledger.length) {
       if (sidebarEl) {
         sidebarEl.remove();
         sidebarEl = null;
@@ -488,36 +617,44 @@
       applyStageFit();
     }
     sidebarEl.innerHTML = "";
-    var n = totalComments();
     var head = el(
       "div",
       "sm-side-head",
-      ICONS.message + "<span>Comments</span><span class=\"n\">" + n + "</span>",
+      ICONS.message +
+        "<span>Comments</span><span class=\"n\">" +
+        openComments().length +
+        " open</span>",
     );
     var body = el("div", "sm-side-body");
-    var stems = slideOrder.length
-      ? slideOrder
-      : Object.keys(commentsBySlide); // fallback if order unknown
+    var seen = {};
+    var stems = slideOrder.slice();
+    // A pin whose slide is not in the play order (renamed file) still gets a
+    // group — the ledger never silently drops a comment the user wrote.
+    ledger.forEach(function (c) {
+      var s = stemOf(c.jsxPath);
+      if (s && stems.indexOf(s) < 0) stems.push(s);
+    });
     stems.forEach(function (stem) {
-      var act = commentsBySlide[stem] || [];
-      var gh = previousBySlide[stem] || [];
-      if (!act.length && !gh.length) return;
+      if (!stem || seen[stem]) return;
+      seen[stem] = true;
+      var rows = commentsForStem(stem);
+      if (!rows.length) return;
       var grp = el("div", "sm-side-grp");
       grp.appendChild(el("div", "sm-side-grp-h", "")).textContent = stem;
-      act.forEach(function (c, i) {
-        grp.appendChild(sideRow(stem, c, i + 1, false));
+      rows.forEach(function (c, i) {
+        grp.appendChild(sideRow(stem, c, i + 1));
       });
-      if (gh.length) {
-        grp.appendChild(el("div", "sm-side-sub", "Previous round"));
-        gh.forEach(function (c, i) {
-          grp.appendChild(sideRow(stem, c, i + 1, true));
-        });
-      }
       body.appendChild(grp);
     });
     sidebarEl.appendChild(head);
     sidebarEl.appendChild(body);
   }
+  // One repaint of everything the ledger drives.
+  function renderAll() {
+    renderPins();
+    refreshChrome();
+    updateSidebar();
+  }
 
   // Jump the deck to a slide by synthesising its arrow-key navigation.
   function goToStem(stem) {
@@ -541,32 +678,35 @@
     pinLayer.setAttribute("data-sm-overlay", "1");
     document.body.appendChild(pinLayer);
   }
+  // Every pin of this slide, whatever its status — the addressed ones ARE the
+  // ghost pins of earlier rounds (numbering matches the sidebar rows).
   function renderPins() {
     if (!pinLayer) return;
     pinLayer.innerHTML = "";
     var st = stage();
     if (!st) return;
     var sr = st.getBoundingClientRect();
-    (previousBySlide[currentStem] || []).forEach(function (c, i) {
-      pinLayer.appendChild(makePin(c, sr, i + 1, true));
-    });
     activeComments().forEach(function (c, i) {
-      pinLayer.appendChild(makePin(c, sr, i + 1, false));
+      pinLayer.appendChild(makePin(c, sr, i + 1));
     });
   }
-  function makePin(c, sr, num, ghost) {
-    var pin = el("button", "sm-pin " + (ghost ? "sm-pin-ghost" : "sm-pin-active"));
+  function pinVariant(c) {
+    if (c.status === "queued") return "sm-pin-active";
+    if (c.status === "sent") return "sm-pin-sent";
+    return "sm-pin-ghost";
+  }
+  function makePin(c, sr, num) {
+    var pin = el("button", "sm-pin " + pinVariant(c));
     pin.setAttribute("data-sm-overlay", "1");
     pin.textContent = String(num);
-    pin.title = c.comment || "";
-    pin.style.left = sr.left + clamp01(c.point.x) * sr.width + "px";
-    pin.style.top = sr.top + clamp01(c.point.y) * sr.height + "px";
+    pin.title = c.text || "";
+    var px = sr.left + fx(c) * sr.width;
+    var py = sr.top + fy(c) * sr.height;
+    pin.style.left = px + "px";
+    pin.style.top = py + "px";
     pin.onclick = function (e) {
       e.stopPropagation();
-      var px = sr.left + clamp01(c.point.x) * sr.width;
-      var py = sr.top + clamp01(c.point.y) * sr.height;
-      if (ghost) openGhost(c, px, py);
-      else openEditor(c, px, py);
+      openCommentAt(c);
     };
     return pin;
   }
@@ -595,12 +735,15 @@
     document.body.appendChild(pop);
     return pop;
   }
+  // The label is TEXT, not markup: targetLabel returns "<h1.hero>", which the
+  // browser would otherwise parse into an actual (empty) element — the pinned
+  // element's name simply vanished from the popover header.
   function head(text, isElement) {
-    return el(
-      "div",
-      "sm-pop-head",
-      ICONS.pin + '<span class="' + (isElement ? "mono" : "") + '">' + text + "</span>",
-    );
+    var h = el("div", "sm-pop-head", ICONS.pin);
+    var span = el("span", isElement ? "mono" : null);
+    span.textContent = text;
+    h.appendChild(span);
+    return h;
   }
   function targetLabel(region) {
     if (!region) return "Slide-level note";
@@ -614,7 +757,10 @@
     });
   }
 
-  function openDraft(point, region, ancestors, px, py) {
+  // Saving a pin SENDS it — there is no batch submit. The button label says so
+  // in each mode, because the consequence differs: parked resolves the gate now,
+  // working queues for the agent's next run.
+  function openDraft(point, region, px, py) {
     var pop = makePopover(px, py);
     pop.appendChild(head(targetLabel(region), !!region));
     var ta = el("textarea", "sm-ta");
@@ -622,22 +768,22 @@
     var row = el("div", "sm-row end");
     var cancel = mkButton("Cancel", "ghost", "close");
     cancel.onclick = closePopover;
-    var save = mkButton("Add comment", "primary", "check");
+    var save = mkButton(working ? "Queue comment" : "Send comment", "primary", "check");
     function doSave() {
       var text = ta.value.trim();
       if (!text) return;
-      (commentsBySlide[currentStem] = commentsBySlide[currentStem] || []).push({
+      closePopover();
+      sendComment({
         id: genId(),
+        round: roundNo,
         jsxPath: "slides/" + currentStem + ".jsx",
-        point: point,
         resolvedTarget: region,
-        ancestors: ancestors,
-        comment: text,
+        x: clamp01(point.x),
+        y: clamp01(point.y),
+        text: text,
+        status: "queued",
+        at: new Date().toISOString(),
       });
-      closePopover();
-      renderPins();
-      refreshChrome();
-      updateSidebar();
     }
     save.onclick = doSave;
     pop.appendChild(ta);
@@ -649,31 +795,31 @@
     bindTextareaKeys(ta, doSave);
   }
 
+  // Only reachable for a QUEUED pin (openCommentAt routes the rest to the
+  // read-only view): until it is delivered, the reviewer can still fix or drop it.
   function openEditor(comment, px, py) {
     var pop = makePopover(px, py);
     pop.appendChild(head(targetLabel(comment.resolvedTarget), !!comment.resolvedTarget));
     var ta = el("textarea", "sm-ta");
-    ta.value = comment.comment;
+    ta.value = comment.text;
     var row = el("div", "sm-row split");
     var del = mkButton("Delete", "danger", "trash");
     function doDelete() {
-      var list = commentsBySlide[currentStem] || [];
-      var idx = list.indexOf(comment);
-      if (idx >= 0) list.splice(idx, 1);
+      var idx = ledger.indexOf(comment);
+      if (idx >= 0) ledger.splice(idx, 1);
       closePopover();
-      renderPins();
-      refreshChrome();
-      updateSidebar();
+      saveLedger();
+      renderAll();
     }
     del.onclick = doDelete;
     var save = mkButton("Save", "primary", "check");
     function doSave() {
       var text = ta.value.trim();
       if (!text) return doDelete();
-      comment.comment = text;
+      comment.text = text;
       closePopover();
-      renderPins();
-      updateSidebar();
+      saveLedger();
+      renderAll();
     }
     save.onclick = doSave;
     pop.appendChild(ta);
@@ -688,130 +834,94 @@
   function openGhost(comment, px, py) {
     var pop = makePopover(px, py);
     pop.appendChild(
-      head("Previous round · " + targetLabel(comment.resolvedTarget), !!comment.resolvedTarget),
+      head(
+        "Round " + comment.round + " · " + statusLabel(comment) + " · " +
+          targetLabel(comment.resolvedTarget),
+        !!comment.resolvedTarget,
+      ),
     );
-    pop.appendChild(el("div", "sm-ghost-body", "")).textContent = comment.comment;
+    pop.appendChild(el("div", "sm-ghost-body", "")).textContent = comment.text;
     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";
+  // The tab label while the agent works — the one attention string that is not
+  // the shared session's (it is set by this overlay's own mode switch).
   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) {
-        comments.push(c);
+  // A saved pin. WORKING → it queues locally (the agent is mid-round; it rides
+  // along on the next run). PARKED → it resolves the gate right now, carrying
+  // any queued stragglers from a flush that couldn't reach the server, and the
+  // tab enters working mode instead of veiling over.
+  function sendComment(c) {
+    ledger.push(c);
+    saveLedger();
+    renderAll();
+    if (working) return;
+    var batch = queuedComments();
+    // Ask for notification permission HERE — the save click is a user gesture,
+    // the only context where the browser will show the prompt.
+    SES.requestNotifyPermission();
+    fetch(CFG.endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ decision: "comments", comments: batch.map(SES.wire) }),
+    })
+      .then(function (res) {
+        if (res.status === 409) {
+          // The gate already drained a backlog this run — this round is stale.
+          enterWorking("Round superseded.");
+          return;
+        }
+        if (!res.ok) throw new Error("gate refused the decision");
+        batch.forEach(function (x) {
+          x.status = "sent";
+        });
+        saveLedger();
+        enterWorking();
+      })
+      .catch(function () {
+        // The command is gone (killed / timed out). The pin stays QUEUED and is
+        // delivered by the next run — the reviewer's words are never dropped.
+        enterWorking("Couldn't reach the terminal command.");
       });
-    });
+  }
+  function approve() {
+    if (approved || working || queuedComments().length) return;
+    approved = true;
     fetch(CFG.endpoint, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        decision: decision,
-        comments: decision === "comments" ? comments : [],
-      }),
+      body: JSON.stringify({ decision: "approve", comments: [] }),
     })
-      .then(function () {
-        if (decision === "approve") {
-          showDone("approve");
-          requestTabClose();
-        } else {
-          showWaiting();
-          startNextRoundPolling();
+      .then(function (res) {
+        if (res.status === 409) {
+          // A backlog drained this run: the render being approved is superseded.
+          approved = false;
+          enterWorking("Round superseded.");
+          return;
         }
+        showDone();
+        requestTabClose();
       })
       .catch(function () {
-        submitted = false;
+        approved = false;
         alert("Could not reach the slidemind review server — is the terminal command still running?");
       });
   }
+  // ---------- working mode (the agent is fixing) ----------
+  // The tab neither veils over nor freezes: the stage stays browsable and
+  // pinnable, the ledger stays visible, and only Approve goes away. Heartbeat
+  // polling waits for the agent's next `slidemind review` run, which reloads
+  // this same tab with the new render.
+  function enterWorking(note) {
+    working = true;
+    workingNote = note || null;
+    document.title = WAITING_TITLE; // the tab label signals the state from the tab bar
+    closePopover();
+    renderAll();
+    startNextRoundPolling();
+  }
   function requestTabClose() {
     setTimeout(function () {
       try {
@@ -822,48 +932,17 @@
       }
     }, 120);
   }
-  // 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. 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.
+  // The shared heartbeat poll (gate-session.js) with this gate's two endings:
+  // a retired tab hands its backlog over FIRST — the fresh window that replaces
+  // it starts with an empty sessionStorage, so anything still queued here would
+  // otherwise be lost (the handover also drains the new run immediately).
   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;
-      }
-      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) {
-          // 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) return;
-          if (data.action === "close") {
-            // The new round opened in a fresh browser tab — this one is stale.
-            clearInterval(timer);
-            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);
+    SES.startNextRoundPolling({
+      onEnded: showSessionEnded,
+      onSuperseded: function () {
+        flushBacklog().then(showSuperseded, showSuperseded);
+      },
+    });
   }
   // Shared full-screen veil (logo + wordmark + status + sub). Replaces any veil
   // already shown rather than stacking a second one, so a comments round's
@@ -882,22 +961,11 @@
     veil.appendChild(el("div", "sub" + (subPulse ? " sm-pulse" : ""), subText));
     document.body.appendChild(veil);
   }
+  // The veil is now ONLY for states where the review is over (approved, session
+  // expired, superseded). A comments round no longer veils: see enterWorking.
   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.");
   }
@@ -919,6 +987,7 @@
       currentStem = stem;
       closePopover();
       renderPins();
+      saveCtx(); // the slide the reviewer is on survives the round reload
     }
   }
 
@@ -951,6 +1020,11 @@
       setTimeout(init, 50);
       return;
     }
+    // Session first: it decides the MODE this page renders in (a queued backlog
+    // means the agent is still working) and the round-transition state.
+    var flagged = SES.consumeRoundFlag();
+    restoreSession();
+
     injectAssets();
     st.style.cursor = "crosshair";
     // Slide play order, for the sidebar's jump-to-slide.
@@ -961,21 +1035,22 @@
     buildPinLayer();
     buildHoverBox();
 
+    // Pinnable in BOTH modes — a pin dropped while the agent is fixing queues
+    // instead of resolving the gate. Only an approved session stops taking pins.
     st.addEventListener("click", function (e) {
-      if (submitted) return;
+      if (approved) return;
       if (e.target.closest("[data-sm-overlay]")) return;
       var sr = st.getBoundingClientRect();
       var x = (e.clientX - sr.left) / sr.width;
       var y = (e.clientY - sr.top) / sr.height;
       if (x < 0 || x > 1 || y < 0 || y > 1) return;
       var hit = e.target.closest("[data-sm-loc]");
-      var desc = describeTarget(hit);
-      openDraft({ x: clamp01(x), y: clamp01(y) }, desc.region, desc.ancestors, e.clientX, e.clientY);
+      openDraft({ x: clamp01(x), y: clamp01(y) }, describeTarget(hit), e.clientX, e.clientY);
     });
 
     // Hover-box: outline the element under the cursor (the add-in's affordance).
     st.addEventListener("pointermove", function (e) {
-      if (submitted || locked) return;
+      if (approved || locked) return;
       if (e.target.closest("[data-sm-overlay]")) {
         hideHoverBox();
         return;
@@ -1002,8 +1077,21 @@
       });
     }
     syncSlideFromNav();
+    // Round transition: come back to the slide the reviewer was reading.
+    if (pendingStem && pendingStem !== currentStem) goToStem(pendingStem);
     applyStageFit();
-    announceNewRound(); // notification + title marker when this load IS the next round
+    renderAll();
+
+    if (working) {
+      // Drain round: hand the backlog over, stay in working mode, stay silent —
+      // the reviewer already knows the agent is mid-fix.
+      document.title = WAITING_TITLE;
+      startNextRoundPolling();
+      flushBacklog().then(renderAll); // rows flip queued → sent
+    } else {
+      // Parked round: the agent is waiting on the reviewer — announce it.
+      SES.announceNewRound(flagged);
+    }
   }
 
   if (document.readyState === "loading") {