slidemind 0.3.5 → 0.3.12

package/src/builders/review-overlay.js

@@ -9,34 +9,32 @@
 //   - Click anywhere on the stage -> resolve the innermost element under the
 //     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.
+//   - Saving a pin keeps it as an unsent DRAFT in this tab (editable, deletable).
+//     "Send N comments" in the header submits the whole batch: the gate resolves
+//     and the `slidemind review` command returns with it (the add-in's
+//     "Submit N comments").
 //   - Approve -> POST to the local server, which unblocks the command with the
-//     sign-off. No copy-paste.
+//     sign-off. Refused while drafts exist — send or delete them first, exactly
+//     the add-in's rule.
 //
 // 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.
+//   - PARKED (the command is blocking on this tab): pinning, sending and
+//     approving are live.
+//   - WORKING (the agent is fixing the slides): the preview stays browsable and
+//     the ledger stays visible, but no new pins are taken and Approve is off —
+//     the displayed render is already superseded. A status strip says so. The
+//     tab polls the heartbeat and reloads itself when the agent's next
+//     `slidemind review` run presents the new round. Nothing is queued behind
+//     the agent's back (add-in parity: rounds are synchronous).
 //
 // 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.
+// draft (saved here, not yet sent) -> 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).
@@ -54,15 +52,15 @@
   var SIDEBAR_W = 316; // panel + gaps reserved on the right when comments exist
   // 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).
+  // identity across draft -> 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 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 working = false; // the agent is fixing → no new pins, no approve
+  var workingNote = null; // extra line for the working strip (superseded)
   var sidebarEl = null;
   var sidebarOpen = false;
   var hoverBox = null;
@@ -70,8 +68,8 @@
 
   // 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.
+  // 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 || "",
@@ -82,7 +80,6 @@
     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
@@ -195,6 +192,8 @@
     ".sm-note{max-width:min(560px,38vw);font-size:10.5px;line-height:1.35;color:#c7c7cf;" +
     "border-left:2px solid var(--sm-accent);padding-left:10px;}" +
     ".sm-note b{font-weight:600;color:#f4f4f5;}" +
+    ".sm-chart-note{display:none;border-left-color:#fbbf24;}" +
+    ".sm-chart-note.on{display:block;}" +
     ".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;}" +
@@ -226,7 +225,7 @@
     "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) /
+    /* draft (saved here, not sent 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);}" +
@@ -287,7 +286,7 @@
     /* 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="draft"]{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 ----------
@@ -322,12 +321,17 @@
   function activeComments() {
     return commentsForStem(currentStem);
   }
-  // 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.
+  // Outstanding = written but not yet answered by a render (the header count).
   function openComments() {
     return ledger.filter(function (c) {
-      return c.status === "queued" || c.status === "sent";
+      return c.status === "draft" || c.status === "sent";
+    });
+  }
+  // Saved here, not sent: the batch "Send comments" submits, and the reason
+  // Approve is off while any exist.
+  function draftComments() {
+    return ledger.filter(function (c) {
+      return c.status === "draft";
     });
   }
   function el(tag, cls, html) {
@@ -393,15 +397,10 @@
     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.
+  // marker, added by the shared session), which slide the reviewer was on, and
+  // whether this round was already sent (so a plain refresh stays in WORKING).
   function saveCtx() {
-    SES.saveCtx({ round: roundNo, stem: currentStem });
-  }
-  function queuedComments() {
-    return SES.queued(ledger);
-  }
-  function flushBacklog() {
-    return SES.flushBacklog(ledger);
+    SES.saveCtx({ round: roundNo, stem: currentStem, working: working });
   }
 
   // Restore this tab's session and work out whether THIS load is a new round.
@@ -418,7 +417,7 @@
   }
 
   // ---------- chrome (top bar) ----------
-  var bar, approveBtn, countLabel, statusEl;
+  var bar, approveBtn, sendBtn, countLabel, statusEl, chartNoteEl;
   function buildChrome() {
     bar = el("div", "sm-o sm-bar");
     bar.setAttribute("data-sm-overlay", "1");
@@ -446,11 +445,27 @@
     );
     bar.appendChild(note);
 
+    // Add-in parity: a slide holding a <Chart> shows a stand-in, never
+    // PowerPoint's render — warn on exactly those slides.
+    chartNoteEl = el(
+      "div",
+      "sm-note sm-chart-note",
+      "<b>Preview only</b> — the chart may look different in PowerPoint.",
+    );
+    bar.appendChild(chartNoteEl);
+
     bar.appendChild(el("div", "sm-grow"));
 
     countLabel = el("div", "sm-count");
     bar.appendChild(countLabel);
 
+    // The add-in's footer: "Submit N comments" appears once drafts exist and is
+    // the ONLY way forward while they do; Approve is the exclusive alternative.
+    sendBtn = mkButton("Send comments", "ghost", "arrow");
+    sendBtn.onclick = sendComments;
+    sendBtn.style.display = "none";
+    bar.appendChild(sendBtn);
+
     approveBtn = mkButton("Approve & continue", "primary", "check");
     approveBtn.onclick = approve;
     bar.appendChild(approveBtn);
@@ -459,45 +474,38 @@
     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.
+  // superseded) or while DRAFTS exist — the add-in's rule: submit or delete them
+  // first. It is NOT refused for already-delivered ("sent") pins: a sent pin
+  // only clears on a round transition, so guarding on it deadlocked a round
+  // that touched no file.
   function refreshChrome() {
     if (!countLabel) return;
     var open = openComments().length;
-    var q = queuedComments().length;
+    var d = draftComments().length;
     countLabel.textContent =
       ledger.length === 0
         ? "no comments yet"
         : open + " open · " + ledger.length + " total";
-    var off = working || q > 0;
+    sendBtn.style.display = !working && d > 0 ? "" : "none";
+    sendBtn.querySelector("span").textContent =
+      "Send " + d + (d === 1 ? " comment" : " comments");
+    var off = working || d > 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."
+      : d > 0
+        ? "Send or delete your comments before approving."
         : "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 =
+      txt.appendChild(el("div", null, "<b>The agent is working through your comments</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.");
+        "This tab refreshes with the next round — comment again then.";
       statusEl.appendChild(txt);
     }
   }
@@ -570,11 +578,11 @@
       y: sr.top + fy(c) * sr.height,
     };
   }
-  // Only a QUEUED pin is still the reviewer's to change; once it is with the
-  // agent it is read-only history.
+  // Only a DRAFT 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 (c.status === "queued") openEditor(c, p.x, p.y);
+    if (c.status === "draft") openEditor(c, p.x, p.y);
     else openGhost(c, p.x, p.y);
   }
   function statusLabel(c) {
@@ -691,7 +699,7 @@
     });
   }
   function pinVariant(c) {
-    if (c.status === "queued") return "sm-pin-active";
+    if (c.status === "draft") return "sm-pin-active";
     if (c.status === "sent") return "sm-pin-sent";
     return "sm-pin-ghost";
   }
@@ -757,9 +765,8 @@
     });
   }
 
-  // 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.
+  // Saving a pin keeps it as a DRAFT; the header's "Send comments" submits the
+  // batch (the add-in's "Save comment" → "Submit N comments").
   function openDraft(point, region, px, py) {
     var pop = makePopover(px, py);
     pop.appendChild(head(targetLabel(region), !!region));
@@ -768,12 +775,12 @@
     var row = el("div", "sm-row end");
     var cancel = mkButton("Cancel", "ghost", "close");
     cancel.onclick = closePopover;
-    var save = mkButton(working ? "Queue comment" : "Send comment", "primary", "check");
+    var save = mkButton("Save comment", "primary", "check");
     function doSave() {
       var text = ta.value.trim();
       if (!text) return;
       closePopover();
-      sendComment({
+      addDraft({
         id: genId(),
         round: roundNo,
         jsxPath: "slides/" + currentStem + ".jsx",
@@ -781,7 +788,7 @@
         x: clamp01(point.x),
         y: clamp01(point.y),
         text: text,
-        status: "queued",
+        status: "draft",
         at: new Date().toISOString(),
       });
     }
@@ -795,8 +802,8 @@
     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.
+  // Only reachable for a DRAFT (openCommentAt routes the rest to the read-only
+  // view): until it is sent, 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));
@@ -849,18 +856,19 @@
   var WAITING_TITLE = "⏳ Agent revising slides — slidemind";
 
   // ---------- submit ----------
-  // 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) {
+  function addDraft(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.
+  }
+  // "Send N comments": the whole draft batch resolves the gate as one comments
+  // round, the drafts flip to "sent" and the tab enters working mode.
+  function sendComments() {
+    if (approved || working) return;
+    var batch = draftComments();
+    if (!batch.length) return;
+    // Ask for notification permission HERE — the click is a user gesture, the
+    // only context where the browser will show the prompt.
     SES.requestNotifyPermission();
     fetch(CFG.endpoint, {
       method: "POST",
@@ -869,7 +877,8 @@
     })
       .then(function (res) {
         if (res.status === 409) {
-          // The gate already drained a backlog this run — this round is stale.
+          // Another tab already decided this run. The drafts stay drafts — the
+          // next round reloads this tab and the reviewer can send them then.
           enterWorking("Round superseded.");
           return;
         }
@@ -881,13 +890,12 @@
         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.");
+        // The command is gone (killed / timed out). The drafts stay in the tab.
+        alert("Could not reach the slidemind review server — is the terminal command still running?");
       });
   }
   function approve() {
-    if (approved || working || queuedComments().length) return;
+    if (approved || working || draftComments().length) return;
     approved = true;
     fetch(CFG.endpoint, {
       method: "POST",
@@ -896,7 +904,7 @@
     })
       .then(function (res) {
         if (res.status === 409) {
-          // A backlog drained this run: the render being approved is superseded.
+          // Another tab already decided this run: the render is superseded.
           approved = false;
           enterWorking("Round superseded.");
           return;
@@ -910,15 +918,17 @@
       });
   }
   // ---------- 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.
+  // The tab neither veils over nor freezes: the stage stays browsable and the
+  // ledger stays visible; pinning and Approve go away until the next round.
+  // 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();
+    hideHoverBox();
+    saveCtx(); // a plain refresh of this round stays in working mode
     renderAll();
     startNextRoundPolling();
   }
@@ -932,15 +942,16 @@
       }
     }, 120);
   }
-  // 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).
+  // The shared heartbeat poll (gate-session.js) with this gate's two endings.
   function startNextRoundPolling() {
     SES.startNextRoundPolling({
       onEnded: showSessionEnded,
+      // A retired tab still holding unsent drafts must not discard them: the
+      // fresh window that replaced it has its own (empty) sessionStorage, so
+      // this tab reloads into the new round instead and flags itself.
       onSuperseded: function () {
-        flushBacklog().then(showSuperseded, showSuperseded);
+        if (draftComments().length) SES.markRoundReadyAndReload();
+        else showSuperseded();
       },
     });
   }
@@ -989,6 +1000,14 @@
       renderPins();
       saveCtx(); // the slide the reviewer is on survives the round reload
     }
+    refreshChartNote();
+  }
+  // The chart stand-in stamps its spec on its root as data-sm-chart.
+  function refreshChartNote() {
+    if (!chartNoteEl) return;
+    var st = stage();
+    var hasChart = !!(st && st.querySelector("[data-sm-chart]"));
+    chartNoteEl.classList.toggle("on", hasChart);
   }
 
   // ---------- wire up ----------
@@ -1020,8 +1039,8 @@
       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.
+    // Session first: it decides the MODE this page renders in (a refresh of an
+    // already-sent round stays in working mode) and the round-transition state.
     var flagged = SES.consumeRoundFlag();
     restoreSession();
 
@@ -1035,10 +1054,10 @@
     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.
+    // Pinnable only while PARKED: while the agent is fixing, the render on
+    // screen is superseded and the strip says to comment on the next round.
     st.addEventListener("click", function (e) {
-      if (approved) return;
+      if (approved || working) return;
       if (e.target.closest("[data-sm-overlay]")) return;
       var sr = st.getBoundingClientRect();
       var x = (e.clientX - sr.left) / sr.width;
@@ -1050,7 +1069,7 @@
 
     // Hover-box: outline the element under the cursor (the add-in's affordance).
     st.addEventListener("pointermove", function (e) {
-      if (approved || locked) return;
+      if (approved || working || locked) return;
       if (e.target.closest("[data-sm-overlay]")) {
         hideHoverBox();
         return;
@@ -1083,11 +1102,9 @@
     renderAll();
 
     if (working) {
-      // Drain round: hand the backlog over, stay in working mode, stay silent —
-      // the reviewer already knows the agent is mid-fix.
+      // A refresh of a round the reviewer already sent: keep waiting quietly.
       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);