slidemind 0.2.4 → 0.3.1

package/src/builders/plan-overlay.js

@@ -14,23 +14,44 @@
 // alongside window.__SLIDEMIND_RENDER_MD__ by plan.mjs).
 //
 // The decision lives in ONE always-visible chat-style composer bar pinned at
-// the bottom: a feedback input, a round send button (a "story iteration" pill
-// while storyline edits are staged) and — fused to its right — the Approve
-// button, whose sub-label says the agent builds the slides next. The previous
-// round's feedback shows as a read-only note above the input.
-//   - send      → decision "comments" with the overall comment (plus, when the
-//                 red thread was restructured, a generated story-iteration
-//                 instruction + the edited plan markdown). The tab does NOT
-//                 veil over: the surface locks read-only and the composer bar
-//                 becomes a spinner + wait note while heartbeat polling waits
-//                 for the agent's next `slidemind plan` round, which reloads
-//                 this same tab.
-//   - Approve   → decision "approve" (unsent feedback arm-confirms first),
-//                 then the full-screen brand animation — logo + drifting
-//                 wordmark + "the agent is building your slides" — before the
-//                 tab closes itself.
-// Both POST {decision, comment, editedPlan} to the local server so the
-// `slidemind plan` command unblocks.
+// the bottom: a scope control (This slide / Whole story), a comment input, a
+// round send button (a "story iteration" pill while storyline edits are staged)
+// and — fused to its right — the Approve button, whose sub-label says the agent
+// builds the slides next. Above it, the LEDGER rail lists every comment of this
+// session with its anchor and status (queued → sent → addressed).
+//
+// TWO MODES, not "reviewing vs. locked out":
+//   - PARKED (the command is blocking on this tab): everything is live. Send
+//     resolves the gate at once (decision "comments", carrying the anchored
+//     comment plus any queued stragglers); Approve resolves it as "approve";
+//     direct edits and story iteration are allowed.
+//   - WORKING (the agent is revising): the plan stays readable and the strip
+//     stays navigable, and the composer stays LIVE — sent comments QUEUE in
+//     sessionStorage (ledger status "queued") instead of hitting the server.
+//     Direct edits, story iteration and Approve are off (the displayed round is
+//     already superseded). A status strip says so.
+//
+// Queued comments are never lost: the tab polls the heartbeat, and when the
+// agent's next `slidemind plan` run claims it the reload's boot POSTs the whole
+// backlog to /plan-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 that is superseded by a fresh window flushes its backlog
+// before retiring, for the same reason.
+//
+// A round transition is detected from the SERVER's per-run nonce (CFG.round):
+// a different nonce means a newer `slidemind plan` run served this page. It
+// flips "sent" ledger rows to "addressed", restores the selected tab + the
+// unsent draft, shows a transient banner, and diffs the cached previous plan
+// body per slide to badge the changed tabs "updated" — the body diff is
+// COSMETIC only; it never decides whether a round arrived. The web notification
+// fires ONLY when the arriving round PARKS — drain rounds land silently.
+//
+// A fresh window (no session of its own) seeds its ledger from CFG.ledgerSeed,
+// the deck's persisted plan-review.json round, so the reviewer still sees the
+// comments the agent is currently working.
+//
+// The decision POSTs {decision, comments[], editedPlan} to the local server so
+// the `slidemind plan` command unblocks.
 //
 // Branding is lifted verbatim from review-overlay.js: the embossed "raised
 // slide" logo (inline-SVG fallback when no per-brand orb PNG is bundled), the
@@ -49,17 +70,48 @@
   var PLAN = window.__SLIDEMIND_PLAN__ || {};
 
   var APPROVE_CLOSE_DELAY_MS = 2400; // long enough to read the build animation
-  var ROUND_READY_FLAG = "slidemind-plan-round-ready"; // sessionStorage marker across the reload
-  var ATTENTION_TITLE = "● Plan ready — slidemind";
   var WAITING_TITLE = "⏳ Agent revising — slidemind";
+  // The plan body of the round that is on screen, cached for the NEXT round's
+  // per-slide diff. Its own key on purpose: it is ~60 KB and never changes
+  // during a page's life, so it is written ONCE at boot — the round context
+  // (selection, unsent draft) is the small blob a keystroke may rewrite.
+  var BODY_KEY = "slidemind-plan-body:" + (CFG.deck || "");
+
+  // 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 preview gate.
+  var SES = window.__SLIDEMIND_GATE__.createGateSession({
+    name: "plan",
+    deck: CFG.deck || "",
+    storage: sessionStorage,
+    fetch: function (u, o) {
+      return fetch(u, o);
+    },
+    round: CFG.round || "",
+    service: "slidemind-plan",
+    heartbeat: CFG.heartbeat || "/__plan/heartbeat",
+    backlogEndpoint: CFG.backlogEndpoint || "/plan-review/backlog",
+    pollMs: CFG.pollMs,
+    pollTtlMs: CFG.pollTtlMs,
+    attentionTitle: "● Plan ready — slidemind",
+    notifyTitle: "slidemind — plan ready",
+    notifyBody: "The revised plan is ready for your review. Click to jump back to the tab.",
+  });
+  var BANNER_MS = 7000; // how long the "Updated · Round N" banner stays
   var BEAT_DRAG_THRESHOLD = 4; // px before a tab press becomes a drag
   var BLOCK_DRAG_THRESHOLD = 3; // px before a block press becomes a drag
 
   // ---------- state ----------
   var submitted = false;
   var approveArmed = false; // inline "discard unsent feedback?" confirm state
-  var waiting = false; // comments round sent → the surface locks read-only
+  var working = false; // the agent is revising → edits off, comments queue
   var baseline = CFG.planBody || ""; // the served plan body; edits diff against it
+  var ledger = []; // every comment of this session: {…, status:queued|sent|addressed}
+  var roundNo = 1; // this tab's round counter (sessionStorage, not server state)
+  var changedSlides = {}; // 1-based tab position → true ("updated" badges this round)
+  var bannerText = null; // transient round-arrival banner, null once dismissed
+  var commentScope = "slide"; // composer scope control: "slide" | "story"
 
   // The single source of truth the whole overlay renders from. `value` is the
   // frontmatter-less plan body (edits index into it); `selectedIndex` is the
@@ -68,19 +120,21 @@
   var S = { value: baseline, selectedIndex: 0, storyDraft: null };
 
   var feedbackText = ""; // the composer input, kept across composer rebuilds
-  var pendingComment = null; // resolved comment/editedPlan for the next submit
-  var pendingEdited = null;
   var editingKey = null; // the beat whose move text is in rename mode
   var newSlideCounter = 0; // unique keys for inserted slides
   var focusAfterRender = null; // an element to focus once a render settles
 
   var bar, wsEl, surfaceEl, composerEl, commentEl;
-  var editedBadge, approveBtn, sendBtn;
-  var waitTextEl = null;
+  var editedBadge, approveBtn, sendBtn, hintEl;
+  var workingNote = null; // headline of the working status strip
+  var pendingComments = []; // the batch the next decision POST carries
+  var pendingEdited = null; // the edited plan markdown riding with it
   var notifyPermPromise = null; // resolved Notification permission, asked at the send gesture
 
+  // Read-only surface: working mode is the ONLY thing that locks the plan text.
+  // Navigation (tab selection) and the composer stay live regardless.
   function locked() {
-    return waiting;
+    return working;
   }
 
   // ---------- brand assets (identical to review-overlay.js) ----------
@@ -129,8 +183,6 @@
   var ICONS = {
     check:
       '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>',
-    ghost:
-      '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 11a9 9 0 0 1 18 0v10l-3-2-3 2-3-2-3 2-3-2-3 2Z"/><path d="M9 11h.01"/><path d="M15 11h.01"/></svg>',
     send:
       '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m22 2-7 20-4-9-9-4Z"/><path d="M22 2 11 13"/></svg>',
     sparkles:
@@ -196,7 +248,16 @@
     ".sm-ws{position:fixed;left:0;right:0;top:var(--deck-chrome-h,62px);bottom:0;z-index:2147483540;" +
     "display:flex;flex-direction:column;background:var(--sm-bg);}" +
     ".sm-ws-surface{flex:1;min-height:0;overflow-y:auto;background:var(--sm-bg);padding:22px 22px 30px;}" +
-    ".sm-ws.is-waiting .sm-ws-surface{pointer-events:none;opacity:.62;}" +
+    /* working mode: read-only, NOT locked out — the surface stays scrollable and
+       the strip stays clickable; the dashed frame is the read-only signal */
+    ".sm-ws.is-waiting .plan-dossier{border-style:dashed;}" +
+    /* round-arrival banner */
+    ".sm-round-banner{display:flex;align-items:center;gap:9px;max-width:1120px;margin:0 auto 14px;padding:9px 13px;" +
+    "border:1px solid color-mix(in srgb,var(--sm-accent) 35%,transparent);border-radius:10px;" +
+    "background:color-mix(in srgb,var(--sm-accent) 9%,transparent);color:var(--sm-dim);font-size:12.5px;line-height:1.5;" +
+    "animation:sm-rise .45s cubic-bezier(.2,.7,.2,1) both;}" +
+    ".sm-round-banner svg{width:15px;height:15px;flex-shrink:0;color:var(--sm-accent);}" +
+    ".sm-round-banner b{color:var(--sm-fg);font-weight:600;}" +
     /* markdown document (Mode A + the storyboard headings share this scale) */
     ".plan-md-root{max-width:min(1120px,100%);margin:0 auto;line-height:1.65;font-size:15.5px;color:var(--sm-fg);}" +
     ".plan-md-root--storyboards{max-width:100%;display:flex;flex-direction:column;gap:0;}" +
@@ -254,6 +315,11 @@
     "font-weight:500;line-height:1.35;-webkit-box-orient:vertical;-webkit-line-clamp:2;}" +
     ".plan-storyline-beat--active .plan-storyline-beat-text{color:var(--sm-fg);font-weight:600;}" +
     ".plan-storyline-beat-text[contenteditable=\"true\"]{display:block;border-radius:4px;cursor:text;outline:none;-webkit-line-clamp:unset;}" +
+    /* "updated" badge — this slide changed in the round that just arrived */
+    ".plan-storyline-beat-updated{position:absolute;top:-6px;left:6px;border-radius:999px;padding:0 6px;" +
+    "background:color-mix(in srgb,var(--sm-accent) 22%,var(--sm-bg));color:var(--sm-accent);" +
+    "border:1px solid color-mix(in srgb,var(--sm-accent) 45%,transparent);" +
+    "font-size:8.5px;font-weight:700;letter-spacing:.08em;text-transform:uppercase;line-height:1.6;}" +
     ".plan-storyline-gap{position:relative;display:flex;flex:none;align-items:center;justify-content:center;width:22px;}" +
     ".plan-storyline-gap[data-active=\"true\"]::before{position:absolute;top:18%;bottom:18%;left:50%;width:3px;border-radius:2px;background:var(--plan-story);content:\"\";transform:translateX(-50%);}" +
     ".plan-storyline-insert{position:relative;display:flex;align-items:center;justify-content:center;width:18px;height:18px;" +
@@ -345,11 +411,26 @@
     ".sm-story-discard{flex-shrink:0;border:0;background:transparent;color:var(--sm-dim);font-family:var(--sm-font);font-weight:500;" +
     "font-size:12px;padding:4px 8px;border-radius:6px;cursor:pointer;transition:background .12s,color .12s;}" +
     ".sm-story-discard:hover{background:var(--sm-muted);color:var(--sm-fg);}" +
-    ".sm-prev-note{display:flex;align-items:flex-start;gap:8px;font-size:12px;color:var(--sm-dim);line-height:1.5;" +
+    /* comment ledger rail (supersedes the old single "previous round" note) */
+    ".sm-ledger{display:flex;flex-direction:column;gap:3px;max-height:118px;overflow-y:auto;" +
     "padding:7px 10px;border:1px dashed #3a3a40;border-radius:9px;background:var(--sm-muted);}" +
-    ".sm-prev-note svg{width:14px;height:14px;flex-shrink:0;margin-top:2px;color:#71717a;}" +
-    ".sm-prev-note .lbl{font-weight:600;color:#a1a1aa;white-space:nowrap;}" +
-    ".sm-prev-note .txt{white-space:pre-wrap;word-break:break-word;color:#b9b9be;}" +
+    ".sm-ledger-row{display:flex;align-items:baseline;gap:8px;font-size:12px;line-height:1.45;color:#b9b9be;}" +
+    ".sm-ledger-anchor{flex:none;font-weight:600;color:#a1a1aa;white-space:nowrap;}" +
+    ".sm-ledger-text{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}" +
+    ".sm-ledger-status{flex:none;border-radius:999px;padding:1px 8px;font-size:10px;font-weight:600;" +
+    "letter-spacing:.04em;text-transform:uppercase;border:1px solid var(--sm-border);color:var(--sm-dim);}" +
+    ".sm-ledger-status[data-state=\"queued\"]{color:var(--sm-warn);border-color:rgba(246,196,84,.4);}" +
+    ".sm-ledger-status[data-state=\"sent\"]{color:var(--sm-accent);border-color:rgba(169,194,255,.4);}" +
+    ".sm-ledger-status[data-state=\"addressed\"]{color:var(--sm-success);border-color:rgba(46,204,113,.4);}" +
+    /* scope control */
+    ".sm-composer-meta{display:flex;align-items:center;gap:9px;font-size:11.5px;color:var(--sm-dim);}" +
+    ".sm-scope-label{font-weight:600;letter-spacing:.04em;text-transform:uppercase;font-size:9.5px;}" +
+    ".sm-scope{display:inline-flex;gap:2px;padding:2px;border:1px solid var(--sm-border);border-radius:999px;background:#0c0c0e;}" +
+    ".sm-scope-btn{border:0;border-radius:999px;padding:3px 11px;background:transparent;color:var(--sm-dim);" +
+    "font-family:var(--sm-font);font-size:11.5px;font-weight:500;cursor:pointer;max-width:220px;overflow:hidden;" +
+    "text-overflow:ellipsis;white-space:nowrap;transition:background .12s,color .12s;}" +
+    ".sm-scope-btn:hover{color:var(--sm-fg);}" +
+    ".sm-scope-btn.is-on{background:var(--sm-accent);color:#0f1220;font-weight:600;}" +
     ".sm-composer-row{display:flex;align-items:flex-end;gap:10px;}" +
     ".sm-chat-ta{flex:1;min-height:40px;max-height:150px;resize:none;background:#0c0c0e;color:var(--sm-fg);" +
     "border:1px solid var(--sm-border);border-radius:14px;padding:10px 15px;font:13px/1.5 var(--sm-font);outline:none;transition:border-color .15s;}" +
@@ -443,6 +524,86 @@
     }
   }
 
+  // ---------- session (shared with the preview gate via gate-session.js) ------
+  function saveLedger() {
+    SES.saveLedger(ledger);
+  }
+  // The small round context the NEXT round restores from: the selected tab and
+  // the unsent draft (the server nonce is added by the shared session). The
+  // plan body is NOT in here — see BODY_KEY.
+  function ctxFields() {
+    return { round: roundNo, selectedIndex: S.selectedIndex, draft: feedbackText };
+  }
+  function saveCtx() {
+    SES.saveCtx(ctxFields());
+  }
+  // Typing path: coalesced, so a keystroke never serializes anything.
+  function saveDraftSoon() {
+    SES.saveCtxSoon(ctxFields());
+  }
+  function queuedComments() {
+    return SES.queued(ledger);
+  }
+  function flushBacklog() {
+    return SES.flushBacklog(ledger);
+  }
+
+  // Per-slide segment diff between the previous round's plan body and this one,
+  // keyed by the slide NUMBER the `### Slide N` heading declares — never by the
+  // heading's position. Real decks number non-contiguously (2,3,4,7,8,9), so a
+  // positional key badged the wrong tab. Each chunk also STOPS at the next `## `
+  // section, so trailing prose (`## Design language`, `## Quellen`) can't be
+  // swept into the last slide and badge it for an unrelated edit.
+  function slideChunks(md) {
+    var out = {};
+    String(md || "")
+      .split(/^(?=###\s+Slide\b)/m)
+      .forEach(function (part) {
+        var m = /^###\s+Slide\s+(\d+)/.exec(part);
+        if (!m) return;
+        // Cut at the next level-2 heading (the chunk's own `###` line is at
+        // index 0, so only a later `## ` can match).
+        var stop = part.search(/\n##\s+/);
+        var body = stop > 0 ? part.slice(0, stop) : part;
+        out[Number(m[1])] = body.trim();
+      });
+    return out;
+  }
+  function diffSlides(prevBody, nextBody) {
+    var before = slideChunks(prevBody);
+    var after = slideChunks(nextBody);
+    var changed = {};
+    for (var no in after) {
+      if (before[no] !== after[no]) changed[no] = true;
+    }
+    return changed;
+  }
+
+  // Restore this tab's session and work out whether THIS load is a new round.
+  // Runs before the first render so the surface is built in the right mode.
+  function restoreSession() {
+    var prevBody = SES.read(BODY_KEY, null);
+    var st = SES.restore(CFG.ledgerSeed);
+    ledger = st.ledger;
+    roundNo = st.roundNo;
+    working = st.working;
+    if (st.newRound) {
+      // Cosmetics only: WHICH slides moved is a content question, so it stays a
+      // body diff — the round transition itself came from the server nonce.
+      changedSlides = diffSlides(prevBody, baseline);
+      bannerText = "Updated · Round " + roundNo;
+    }
+    // Reviewer context survives the round (invariant 6): selection + draft.
+    if (st.ctx) {
+      if (typeof st.ctx.selectedIndex === "number") S.selectedIndex = st.ctx.selectedIndex;
+      if (typeof st.ctx.draft === "string") feedbackText = st.ctx.draft;
+    }
+    saveLedger();
+    saveCtx();
+    // Once per page load — the served body never changes while this page lives.
+    SES.write(BODY_KEY, baseline);
+  }
+
   // ---------- chrome (top bar) ----------
   function buildChrome() {
     bar = el("div", "sm-o sm-bar");
@@ -461,13 +622,8 @@
     editedBadge.style.display = "none";
     title.appendChild(editedBadge);
     meta.appendChild(title);
-    meta.appendChild(
-      el(
-        "div",
-        "h",
-        "Shape the red thread and storyboards below · drag to reorder, rename moves, edit blocks · decide when it reads right",
-      ),
-    );
+    hintEl = el("div", "h");
+    meta.appendChild(hintEl);
     bar.appendChild(meta);
     bar.appendChild(el("div", "sm-grow"));
 
@@ -475,15 +631,41 @@
   }
   function refreshChrome() {
     if (editedBadge) editedBadge.style.display = planWasEdited() ? "" : "none";
+    if (hintEl) {
+      hintEl.textContent = working
+        ? "The agent is revising · read on, browse the strip, keep commenting — editing resumes with the next round"
+        : "Shape the red thread and storyboards below · drag to reorder, rename moves, edit blocks · decide when it reads right";
+    }
 
     var hasFeedback = commentText().length > 0;
-    var canSend = !!S.storyDraft || hasFeedback;
+    var canSend = (!working && !!S.storyDraft) || hasFeedback;
     if (sendBtn) sendBtn.classList.toggle("is-off", !canSend);
 
     if (approveBtn) {
       var main = approveBtn.querySelector(".main span");
       var sub = approveBtn.querySelector(".sub");
-      if (S.storyDraft) {
+      if (working) {
+        // Approve applies to exactly the displayed round; while the agent is
+        // revising, that round is already superseded (server refuses it too).
+        approveArmed = false;
+        approveBtn.classList.remove("is-armed");
+        approveBtn.classList.add("is-off");
+        if (main) main.textContent = "Approve plan";
+        if (sub) {
+          sub.style.display = "";
+          sub.textContent = "The agent is revising — approve the next round";
+        }
+      } else if (queuedComments().length) {
+        // Only reachable when a backlog flush failed: approving would drop them.
+        approveArmed = false;
+        approveBtn.classList.remove("is-armed");
+        approveBtn.classList.add("is-off");
+        if (main) main.textContent = "Approve plan";
+        if (sub) {
+          sub.style.display = "";
+          sub.textContent = "Send your queued comments first";
+        }
+      } else if (S.storyDraft) {
         // Approve is blocked until the staged storyline is sent or discarded.
         approveArmed = false;
         approveBtn.classList.remove("is-armed");
@@ -583,6 +765,7 @@
     if (!surfaceEl) return;
     surfaceEl.innerHTML = "";
     focusAfterRender = null;
+    if (bannerText) surfaceEl.appendChild(roundBanner());
     var segments = PLAN.splitPlanMarkdownIntoSegments(S.value);
     var hasStoryboards = segments.some(function (s) {
       return s.type === "storyboard";
@@ -595,6 +778,28 @@
     }
   }
 
+  // Transient "Updated · Round N" banner. It states the round arrived and how
+  // many slides changed; the per-tab badges say WHICH. Self-dismisses so it
+  // can't be mistaken for a permanent state.
+  function roundBanner() {
+    var count = Object.keys(changedSlides).length;
+    var node = el("div", "sm-round-banner");
+    node.innerHTML =
+      ICONS.sparkles +
+      "<span><b>" +
+      bannerText +
+      "</b> " +
+      (count
+        ? count + (count === 1 ? " slide changed" : " slides changed") + " — marked “updated” on the strip."
+        : "The plan was revised.") +
+      "</span>";
+    setTimeout(function () {
+      bannerText = null;
+      if (node.parentNode) node.parentNode.removeChild(node);
+    }, BANNER_MS);
+    return node;
+  }
+
   function renderModeA(segments) {
     var root = el("div", "plan-md-root");
     segments.forEach(function (seg) {
@@ -608,6 +813,28 @@
     surfaceEl.appendChild(root);
   }
 
+  // The story beats on the strip: the `## Red thread` moves — but only when
+  // they match the boards one-to-one, so a drifted red thread (more moves than
+  // slides) never renders phantom slide tabs — otherwise each board's key
+  // message (read-only tabs then). Each beat carries the slide number its board
+  // declares, which is what a "This slide" comment is anchored to (so the agent
+  // reads the same number the reviewer saw).
+  function planBeats() {
+    var boards = PLAN.splitPlanMarkdownIntoSegments(S.value).filter(function (s) {
+      return s.type === "storyboard";
+    });
+    var messages = PLAN.extractRedThreadMessages(S.value);
+    if (messages.length !== boards.length) {
+      messages = boards.map(function (seg, i) {
+        return (seg.data && seg.data.keyMessage) || "Slide " + ((seg.data && seg.data.slide) || i + 1);
+      });
+    }
+    return messages.map(function (message, i) {
+      var data = boards[i] && boards[i].data;
+      return { message: message, slide: (data && data.slide) || i + 1 };
+    });
+  }
+
   // ---------- dossier (storyboard mode) ----------
   function renderDossier(segments) {
     var storyboardSegments = segments.filter(function (s) {
@@ -618,14 +845,9 @@
         return s.data;
       })
       .filter(Boolean);
-    var redThreadMessages = PLAN.extractRedThreadMessages(S.value);
-    // Tabs need a beat per board even without a `## Red thread` section — fall
-    // back to each board's key message (read-only tabs then).
-    var beatMessages = redThreadMessages.length
-      ? redThreadMessages
-      : storyboardSegments.map(function (seg, i) {
-          return (seg.data && seg.data.keyMessage) || "Slide " + ((seg.data && seg.data.slide) || i + 1);
-        });
+    var beatMessages = planBeats().map(function (b) {
+      return b.message;
+    });
     var committed = PLAN.backboneFromMessages(beatMessages);
     var slides = S.storyDraft || committed;
     var backboneEditable = PLAN.parsePlanBackbone(S.value) !== null;
@@ -828,6 +1050,17 @@
       slideNo.textContent = numeral;
       li.appendChild(slideNo);
 
+      // "updated" badge: this tab's slide changed in the round that just landed.
+      // Keyed by the SLIDE NUMBER shown on the tab (`numeral`, straight off the
+      // board data) — the same source the diff keys by, so non-contiguous decks
+      // (2,3,4,7,8,9) badge the tab that actually moved. A staged storyline
+      // renumbers positionally, so badges are suppressed while one is open.
+      if (!S.storyDraft && changedSlides[numeral]) {
+        var upd = el("span", "plan-storyline-beat-updated", "updated");
+        upd.title = "This slide changed in the latest round";
+        li.appendChild(upd);
+      }
+
       var textEl = el("div", "plan-storyline-beat-text");
       textEl.setAttribute("role", "textbox");
       textEl.textContent = item.message;
@@ -929,8 +1162,12 @@
         if (moved) {
           if (gap !== null) reorderTo(idx, gap);
         } else if (idx !== activeIndex) {
+          // Selection stays live in working mode (reading + navigating are never
+          // blocked) and is remembered for the next round.
           S.selectedIndex = idx;
+          saveCtx();
           renderSurface();
+          renderComposer(); // the scope control names the newly selected slide
         } else if (canEdit) {
           editingKey = key;
           renderSurface();
@@ -1396,15 +1633,95 @@
     return figure;
   }
 
+  // ---------- comment ledger ----------
+  // The anchor a comment written right now would carry. "This slide" reads the
+  // SELECTED strip tab; without a storyboard strip there is nothing to anchor
+  // to, so everything is whole-story.
+  function currentAnchor() {
+    var beats = planBeats();
+    if (!beats.length || commentScope !== "slide") {
+      return { scope: "story", slideIndex: null, slideHeading: null };
+    }
+    var i = clamp(S.selectedIndex, 0, beats.length - 1);
+    return { scope: "slide", slideIndex: beats[i].slide, slideHeading: beats[i].message };
+  }
+  function newId() {
+    try {
+      return crypto.randomUUID();
+    } catch {
+      return "c-" + Date.now() + "-" + Math.random().toString(16).slice(2);
+    }
+  }
+  function newComment(text, forceScope) {
+    var a = forceScope === "story" ? { scope: "story", slideIndex: null, slideHeading: null } : currentAnchor();
+    return {
+      id: newId(),
+      round: roundNo,
+      scope: a.scope,
+      slideIndex: a.slideIndex,
+      slideHeading: a.slideHeading,
+      text: text,
+      at: new Date().toISOString(),
+      status: "queued",
+    };
+  }
+  function anchorLabel(c) {
+    if (c.scope !== "slide") return "Whole story";
+    return "Slide " + (c.slideIndex == null ? "?" : c.slideIndex);
+  }
+  function statusLabel(c) {
+    return SES.statusLabel(c);
+  }
+  // The rail: every comment of this session, newest last, with its anchor and
+  // where it stands. This is what replaced the single "previous round" note —
+  // it survives rounds and shows the queue the reviewer built up.
+  function ledgerRail() {
+    var rail = el("div", "sm-ledger");
+    ledger.forEach(function (c) {
+      var row = el("div", "sm-ledger-row");
+      row.appendChild(el("span", "sm-ledger-anchor", anchorLabel(c)));
+      var txt = el("span", "sm-ledger-text");
+      txt.textContent = c.text;
+      row.appendChild(txt);
+      var chip = el("span", "sm-ledger-status");
+      chip.setAttribute("data-state", c.status);
+      chip.textContent = statusLabel(c);
+      row.appendChild(chip);
+      rail.appendChild(row);
+    });
+    return rail;
+  }
+
   // ---------- chat composer bar ----------
-  // Rebuilt on structural state changes (a storyline draft staged / discarded),
-  // NOT on every keystroke (keystrokes only call refreshChrome). The typed
-  // feedback survives a rebuild via feedbackText.
+  // Rebuilt on structural state changes (a storyline draft staged / discarded,
+  // a mode or selection change), NOT on every keystroke (keystrokes only call
+  // refreshChrome). The typed feedback survives a rebuild via feedbackText.
   function renderComposer() {
-    if (!composerEl || waiting) return;
+    if (!composerEl) return;
     composerEl.innerHTML = "";
 
-    if (S.storyDraft) {
+    if (working) {
+      var status = el("div", "sm-wait");
+      status.appendChild(el("div", "sm-spin"));
+      var note = el("div");
+      note.innerHTML =
+        "<b>" +
+        (workingNote || "Comments sent.") +
+        "</b> The agent is revising the plan — this tab updates itself when the " +
+        "next round lands. Keep reading and navigating; anything you send now is " +
+        "queued and delivered with that round.";
+      status.appendChild(note);
+      composerEl.appendChild(status);
+      // The permission prompt was raised at the send click (a user gesture, the
+      // only context a browser shows it in); once granted, say so.
+      (notifyPermPromise || Promise.resolve(SES.notifyPermission())).then(function (perm) {
+        if (perm === "granted") {
+          note.innerHTML += " You'll get a notification when the next round needs you.";
+        }
+      });
+    }
+
+    if (!working && S.storyDraft) {
       var banner = el("div", "sm-story-banner");
       banner.innerHTML =
         ICONS.sparkles +
@@ -1422,25 +1739,47 @@
       composerEl.appendChild(banner);
     }
 
-    if (CFG.previousComment) {
-      var prev = el("div", "sm-prev-note");
-      prev.innerHTML = ICONS.ghost + '<span class="lbl">Previous round</span>';
-      var txt = el("span", "txt");
-      txt.textContent = CFG.previousComment;
-      prev.appendChild(txt);
-      composerEl.appendChild(prev);
+    if (ledger.length) composerEl.appendChild(ledgerRail());
+
+    // Scope control — "This slide" reads the selected strip tab. Hidden when
+    // there is no strip to anchor to (plain-markdown plans).
+    var beats = planBeats();
+    if (!beats.length) commentScope = "story";
+    if (beats.length) {
+      var meta = el("div", "sm-composer-meta");
+      meta.appendChild(el("span", "sm-scope-label", "Comment on"));
+      var scopeBox = el("div", "sm-scope");
+      var active = clamp(S.selectedIndex, 0, beats.length - 1);
+      [
+        { key: "slide", label: "Slide " + beats[active].slide },
+        { key: "story", label: "Whole story" },
+      ].forEach(function (opt) {
+        var b = el("button", "sm-scope-btn" + (commentScope === opt.key ? " is-on" : ""), opt.label);
+        b.type = "button";
+        b.onclick = function () {
+          commentScope = opt.key;
+          renderComposer();
+          if (commentEl) commentEl.focus();
+        };
+        scopeBox.appendChild(b);
+      });
+      meta.appendChild(scopeBox);
+      composerEl.appendChild(meta);
     }
 
     var row = el("div", "sm-composer-row");
     commentEl = el("textarea", "sm-chat-ta");
     commentEl.rows = 1;
-    commentEl.placeholder = "What should change? Leave a note, or edit the plan directly.";
+    commentEl.placeholder = working
+      ? "Keep commenting — this goes to the agent with the next round."
+      : "What should change? Leave a note, or edit the plan directly.";
     commentEl.value = feedbackText;
     commentEl.addEventListener("input", function () {
       feedbackText = commentEl.value;
       approveArmed = false; // typing more feedback disarms a pending approve-confirm
       commentEl.style.height = "auto";
       commentEl.style.height = Math.min(commentEl.scrollHeight, 150) + "px";
+      saveDraftSoon(); // an unsent draft survives the next round's reload
       refreshChrome();
     });
     commentEl.addEventListener("keydown", function (e) {
@@ -1448,7 +1787,7 @@
     });
     row.appendChild(commentEl);
 
-    if (S.storyDraft) {
+    if (!working && S.storyDraft) {
       // The round is sendable as-is — "send" grows the story-iteration label.
       sendBtn = el("button", "sm-send-pill", ICONS.sparkles + "<span>Iterate on the story</span>");
       sendBtn.type = "button";
@@ -1456,8 +1795,8 @@
     } else {
       sendBtn = el("button", "sm-send", ICONS.send);
       sendBtn.type = "button";
-      sendBtn.title = "Send feedback";
-      sendBtn.setAttribute("aria-label", "Send feedback");
+      sendBtn.title = working ? "Queue for the next round" : "Send feedback";
+      sendBtn.setAttribute("aria-label", sendBtn.title);
     }
     sendBtn.onclick = requestChanges;
     row.appendChild(sendBtn);
@@ -1472,6 +1811,7 @@
       "<span>Approve plan</span></span>" +
       '<span class="sub">the agent builds the slides next</span>';
     approveBtn.onclick = function () {
+      if (working || queuedComments().length) return; // superseded round / unsent queue
       if (S.storyDraft) return; // blocked while a storyline draft is staged
       // Approving with unsent feedback in the input discards it — confirm inline.
       if (commentText() && !approveArmed) {
@@ -1487,137 +1827,66 @@
     refreshChrome();
   }
 
-  // ---------- waiting state (comments sent) ----------
-  // The tab does NOT veil over on a comments round: the plan stays readable, the
-  // surface locks, and the composer becomes the wait signal until the agent's
-  // next `slidemind plan` round reloads this tab (heartbeat polling).
-  function enterWaiting() {
-    waiting = true;
+  // ---------- working mode (the agent is revising) ----------
+  // The tab neither veils over nor freezes: the plan stays readable, the strip
+  // stays navigable, the composer stays live (comments queue), and only the
+  // editing affordances + Approve go away. Heartbeat polling waits for the
+  // agent's next `slidemind plan` round, which reloads this same tab.
+  function enterWorking(note) {
+    working = true;
+    workingNote = note || null;
     if (wsEl) wsEl.classList.add("is-waiting");
-    renderSurface(); // rebuild the surface read-only (no contenteditable attrs)
     document.title = WAITING_TITLE; // the tab label signals the state from the tab bar
-    if (composerEl) {
-      composerEl.innerHTML = "";
-      var w = el("div", "sm-wait");
-      w.appendChild(el("div", "sm-spin"));
-      waitTextEl = el(
-        "div",
-        null,
-        "<b>Feedback sent.</b> The agent is revising the plan — this tab refreshes " +
-          "automatically when the next round is ready. Feel free to keep reading, " +
-          "or come back later.",
-      );
-      w.appendChild(waitTextEl);
-      composerEl.appendChild(w);
-    }
-    // The permission prompt was raised at the send click (a user gesture, so the
-    // browser shows it); once granted, tell the user a notification will come.
-    (notifyPermPromise || Promise.resolve(notifyPermission())).then(function (perm) {
-      if (perm === "granted" && waitTextEl) {
-        waitTextEl.innerHTML += " You'll get a notification the moment it's ready.";
-      }
-    });
-  }
-
-  // ---------- next-round attention ----------
-  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");
-    }
-  }
-  // The reload wipes this JS context, so the "announce the new round" wish is
-  // parked in sessionStorage and honoured by the NEXT page load.
-  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();
-    } 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 — plan ready", {
-          body: "The revised plan is ready for your review. Click to jump back to the tab.",
-          tag: "slidemind-plan-round",
-        });
-        n.onclick = function () {
-          try {
-            window.focus();
-          } catch {
-            /* ignore */
-          }
-          n.close();
-        };
-      }
-    } catch {
-      /* notification construction can throw on some platforms — title marker stands */
-    }
+    renderSurface(); // rebuild the surface read-only (no contenteditable attrs)
+    renderComposer();
+    startNextRoundPolling();
   }
 
   // ---------- submit ----------
+  // Send. WORKING → the comment is queued 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.
   function requestChanges() {
-    if (waiting) return;
+    var typed = commentText();
+    if (working) {
+      if (!typed) return;
+      ledger.push(newComment(typed));
+      saveLedger();
+      clearDraft();
+      renderComposer();
+      return;
+    }
+    var batch = queuedComments();
     if (S.storyDraft) {
       var staged = PLAN.stageStoryIteration(S.value, S.storyDraft);
       if (!staged) return;
-      var typed = commentText();
-      pendingComment = typed ? staged.feedback + "\n\n" + typed : staged.feedback;
+      // A storyline restructure is a whole-story instruction by construction.
+      batch = batch.concat([
+        newComment(typed ? staged.feedback + "\n\n" + typed : staged.feedback, "story"),
+      ]);
       pendingEdited = staged.editedPlanMarkdown;
     } else {
-      if (!commentText()) return;
-      pendingComment = commentText();
+      if (!typed) return;
+      batch = batch.concat([newComment(typed)]);
       pendingEdited = planWasEdited() ? S.value : null;
     }
+    pendingComments = batch;
     // Ask for notification permission HERE — the click is a user gesture, the
     // only context where the browser will actually show the prompt.
-    notifyPermPromise = requestNotifyPermission();
+    notifyPermPromise = SES.requestNotifyPermission();
     submit("comments");
   }
+  function clearDraft() {
+    feedbackText = "";
+    if (commentEl) commentEl.value = "";
+    saveCtx();
+  }
   function submit(decision) {
     if (submitted) return;
     submitted = true;
     var payload = {
       decision: decision,
-      comment: decision === "comments" ? pendingComment : null,
+      comments: decision === "comments" ? pendingComments.map(SES.wire) : [],
       editedPlan: decision === "comments" ? pendingEdited : planWasEdited() ? S.value : null,
     };
     fetch(CFG.endpoint, {
@@ -1625,13 +1894,44 @@
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(payload),
     })
-      .then(function () {
+      .then(function (res) {
+        if (res.status === 409) {
+          // The gate already drained a backlog this run — this round is stale.
+          // Park the batch in the ledger as QUEUED (the next claim flushes it),
+          // clear the input so it isn't typed twice, and disarm the submit
+          // latch — leaving it armed made every later send a silent no-op.
+          // A staged story restructure survives only as its instruction TEXT:
+          // its editedPlanMarkdown was computed against the superseded plan and
+          // applying it to the next round would corrupt it, so it is dropped
+          // deliberately (same call the add-in dialog makes on round arrival).
+          if (decision === "comments") {
+            pendingComments.forEach(function (c) {
+              c.status = "queued";
+              if (ledger.indexOf(c) < 0) ledger.push(c);
+            });
+            saveLedger();
+            clearDraft();
+            S.storyDraft = null;
+          }
+          submitted = false;
+          enterWorking("Round superseded.");
+          return;
+        }
+        if (!res.ok) throw new Error("gate refused the decision");
         if (decision === "approve") {
           showApproved();
-        } else {
-          enterWaiting();
-          startNextRoundPolling();
+          return;
         }
+        pendingComments.forEach(function (c) {
+          c.status = "sent";
+          if (ledger.indexOf(c) < 0) ledger.push(c);
+        });
+        saveLedger();
+        clearDraft();
+        // The staged restructure is now the agent's job — keeping it staged
+        // would show the reviewer a storyline the served plan no longer claims.
+        S.storyDraft = null;
+        enterWorking("Comments sent.");
       })
       .catch(function () {
         submitted = false;
@@ -1648,53 +1948,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 || "/__plan/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) {
-          if (!data || data.service !== "slidemind-plan" || !data.round) return;
-          if (data.round === CFG.round) return;
-          if (data.action === "close") {
-            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);
+      },
+    });
   }
 
   // ---------- done veil ----------
@@ -1764,10 +2028,28 @@
     var stale = document.getElementById("plan-root");
     if (stale && stale.parentNode) stale.parentNode.removeChild(stale);
 
+    // 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();
     buildChrome();
     buildWorkspace();
-    announceNewRound(); // notification + title marker when this load IS the next round
+
+    if (working) {
+      // Drain round: hand the backlog over, stay in working mode, stay silent —
+      // the reviewer already knows they're mid-round.
+      if (wsEl) wsEl.classList.add("is-waiting");
+      document.title = WAITING_TITLE;
+      startNextRoundPolling();
+      flushBacklog().then(function () {
+        renderComposer(); // rows flip queued → sent
+      });
+    } else {
+      // Parked round: the agent is waiting on the reviewer — announce it.
+      SES.announceNewRound(flagged);
+    }
   }
 
   if (document.readyState === "loading") {