slidemind 0.2.3 → 0.3.0

package/src/builders/review.mjs

@@ -8,14 +8,27 @@
 // copy-paste round-trip. The verdict is printed to stdout for the harness:
 //   - approve  -> "DECISION: approved" (the agent then runs the export the user
 //                  asked for: slidemind push / build-pptx).
-//   - comments -> each comment with its slides/<f>.jsx:line:col, the source line,
+//   - comments -> each pin with its slides/<f>.jsx:line:col, the source line,
 //                  the click position, and a readonly-layout note where relevant
 //                  (the agent edits the cited files and re-runs review).
 //
+// ASYNC REVIEW (the drain loop, shared with the plan gate). Saving a pin sends
+// it AT ONCE and the tab does not veil over: the preview stays fully browsable
+// and pinnable in WORKING mode, and further pins queue in the tab's
+// sessionStorage. When the agent re-runs this command the waiting tab reloads
+// (heartbeat claim) and its boot script POSTs that backlog to /review/backlog.
+// A non-empty backlog resolves the gate immediately with those pins (a "drain
+// round": DECISION: comments prints and the command exits without ever
+// parking), so several consecutive comment rounds are the normal shape of a
+// review. An empty backlog never POSTs and the run parks and blocks as before.
+// Approve is refused once a backlog arrived in this run — that render is
+// already superseded by pins the agent has been told to fix.
+//
 // Host-free: it reviews the HTML preview BEFORE any .pptx render, so it needs a
 // previously-materialized bundle (like `slidemind build`) but no open host.
-// Each round's comments persist to <deck>/review.json so the next run shows them
-// as read-only "ghost" pins for 1:1 verification.
+// Each round persists to <deck>/review.json (v2, one row per anchored pin) as
+// the harness's recovery copy AND as the ledger seed a fresh tab renders the
+// previous round's read-only "ghost" pins from.
 //
 // Port + tab-reuse contract: each run binds a deterministic per-deck port (a
 // hash of the deck path folded into a fixed high band, 40000..40999) so a tab
@@ -42,6 +55,10 @@ import {
   serveStaticFile,
   createDecisionGate,
   createHeartbeat,
+  bundleGateSession,
+  normalizeGateComments,
+  serveBacklogPost,
+  serveDecisionPost,
   listenWithFallback,
   preferredGatePort,
   serveAndOpen as gateServeAndOpen,
@@ -104,31 +121,67 @@ function readSourceLine(deckDir, parsed) {
   }
 }
 
+// Normalize the browser's pin array into the persisted/printed v2 row shape.
+// Every row keeps its spatial anchor (jsxPath + resolvedTarget.loc + the click
+// position as FULL-PRECISION 0..1 fractions of the slide); the shared core adds
+// identity (`id` dedupes a client retry, `round` says which render the pin was
+// dropped on — a queued pin is delivered a round later, so the two can differ)
+// and drops text-less rows.
+//
+// x/y are deliberately NOT quantized. Whole percent was ±6px of ghost-pin drift
+// on a 1280px stage and collapsed every sub-1% offset; percent is a DISPLAY
+// unit, applied once in formatCommentsForHarness.
+export function normalizeReviewComments(raw) {
+  return normalizeGateComments(raw, (c) => ({
+    jsxPath: typeof c.jsxPath === "string" ? c.jsxPath : "",
+    resolvedTarget:
+      c.resolvedTarget && typeof c.resolvedTarget === "object" ? c.resolvedTarget : null,
+    x: clamp01(Number(c.x) || 0),
+    y: clamp01(Number(c.y) || 0),
+    // The status a delivered pin carries: the agent is about to work it. A
+    // later run serves these back as the ledger seed, where they stay "sent" —
+    // the agent has them, but nothing has answered them yet.
+    status: c.status === "queued" || c.status === "addressed" ? c.status : "sent",
+  }));
+}
+
 // Render the comment round for the harness — ports the add-in's
 // formatPreviewCommentsForLlm, adapted to CLI commands.
-export function formatCommentsForHarness(deckDir, comments) {
-  const n = comments.length;
+export function formatCommentsForHarness(deckDir, comments, { drained = false } = {}) {
+  const rows = normalizeReviewComments(comments);
+  const n = rows.length;
   const out = [];
   out.push("DECISION: comments");
   out.push(
     `The user left ${n} comment${n === 1 ? "" : "s"} on the preview. Nothing was exported.`,
   );
+  if (drained) {
+    out.push(
+      "(These were queued while you were fixing and arrived with this run — that is " +
+        "why the gate returned immediately instead of waiting.)",
+    );
+  }
   out.push("");
-  comments.forEach((c, i) => {
+  rows.forEach((c, i) => {
     const region = c.resolvedTarget || null;
     const parsed = region ? parseLoc(region.loc) : null;
-    const head = `[${i + 1}] ${c.jsxPath} — `;
+    // The round tag is load-bearing: a pin queued during a fix names the render
+    // it was dropped on, which may be one behind the files you are looking at.
+    const head = `[${i + 1}, round ${c.round}] ${c.jsxPath} — `;
+    // Percent is the unit the AGENT reads; the stored anchor stays full precision.
+    const x = clamp01(c.x);
+    const y = clamp01(c.y);
     if (region && parsed) {
       const cls = region.className ? ` class="${region.className}"` : "";
       out.push(`${head}element <${region.tag}${cls}> at ${region.loc}`);
       const srcLine = readSourceLine(deckDir, parsed);
       if (srcLine) out.push(`    Source line ${parsed.line}: ${srcLine}`);
       const b = region.bbox || { x: 0, y: 0, w: 0, h: 0 };
-      const exX = b.w > 0 ? pct((c.point.x - b.x) / b.w) : 50;
-      const exY = b.h > 0 ? pct((c.point.y - b.y) / b.h) : 50;
+      const exX = b.w > 0 ? pct((x - b.x) / b.w) : 50;
+      const exY = b.h > 0 ? pct((y - b.y) / b.h) : 50;
       out.push(
         `    Click position: ${exX}%/${exY}% within the element, ` +
-          `${pct(c.point.x)}%/${pct(c.point.y)}% of the slide.`,
+          `${pct(x)}%/${pct(y)}% of the slide.`,
       );
       if (parsed.jsxPath.startsWith("layouts/")) {
         out.push(
@@ -139,17 +192,13 @@ export function formatCommentsForHarness(deckDir, comments) {
       }
     } else {
       out.push(
-        `${head}slide-level note at ${pct(c.point.x)}%/${pct(c.point.y)}% ` +
+        `${head}slide-level note at ${pct(x)}%/${pct(y)}% ` +
           `of the slide (no specific element).`,
       );
     }
-    out.push(`    Comment: ${c.comment}`);
+    out.push(`    Comment: ${c.text}`);
     out.push("");
   });
-  // Imperative, stateful tail (mirrors plan.mjs's formatPlanFeedbackForHarness):
-  // after a comments round the user's tab waits for the NEXT review run — an
-  // agent that ends its turn here deadlocks the session.
-  //
   // The recovery pointer sits in the TAIL deliberately: when a harness capture
   // truncates long output it usually drops the TOP, so the pointer to the full
   // persisted round is what survives.
@@ -160,12 +209,19 @@ export function formatCommentsForHarness(deckDir, comments) {
       `instead of guessing or asking the user to re-type anything.`,
   );
   out.push("");
-  out.push("The user's browser tab is still open, waiting for the next round. They are");
-  out.push("waiting on YOU now — do both steps in this same turn:");
+  // Imperative, stateful tail (mirrors plan.mjs's formatPlanCommentsForHarness):
+  // the reviewer's tab is LIVE while you fix — they keep browsing the preview and
+  // keep dropping pins — and those pins are only delivered by the next
+  // `slidemind review` run. An agent that ends its turn here strands them.
+  out.push("Fix exactly what the comments ask for at the cited lines — a pin may");
+  out.push("reference the PREVIOUS render (see its round tag), so read the file before");
+  out.push("you edit. Then re-run the gate in the same turn:");
   out.push("  1. Edit the cited slides/*.jsx file(s) at the given lines.");
   out.push(`  2. Re-run: slidemind review ${path.basename(deckDir)}`);
-  out.push("The re-run rebuilds the preview and reopens their same tab (the prior round");
-  out.push("shows as ghost pins). Do NOT end your turn, do NOT export anything, and do");
+  out.push("The re-run rebuilds the preview and reopens their same tab (addressed pins");
+  out.push("show as ghost pins). The user may queue further comments while you fix; they");
+  out.push("are delivered on that next run, which can return immediately with them — that");
+  out.push("is normal, not an error. Do NOT end your turn, do NOT export anything, and do");
   out.push("NOT send the user back to the browser before step 2.");
   return out.join("\n") + "\n";
 }
@@ -190,35 +246,47 @@ export function formatReviewPendingForHarness(deckDir, { timeoutMs, pageLoaded,
   ].join("\n") + "\n";
 }
 
-function injectReview(html, previousComments, overlayJs, logoMark = null, round = null) {
+function injectReview(html, cfgExtra, overlayJs, logoMark = null, round = null) {
   const cfg = safeInlineJson({
     endpoint: "/review",
+    backlogEndpoint: "/review/backlog",
     heartbeat: "/__review/heartbeat",
     round,
     pollMs: POLL_MS,
     pollTtlMs: POLL_TTL_MS,
-    previousComments,
     logoMark,
+    ...cfgExtra,
   });
   const overlay = overlayJs.replace(/<\/script>/g, "<\\/script>");
+  // The shared gate session goes in FIRST — the overlay reads it at boot.
+  const gateJs = bundleGateSession().replace(/<\/script>/g, "<\\/script>");
   const block =
     `<script>window.__SLIDEMIND_REVIEW__ = ${cfg};</script>\n` +
+    `<script>\n${gateJs}\n</script>\n` +
     `<script>\n${overlay}\n</script>\n</body>`;
   return html.includes("</body>") ? html.replace("</body>", block) : html + block;
 }
 
+const EMPTY_STATE = { version: 2, decision: null, comments: [] };
+
+// v2 only — the file is ephemeral per-deck round state, so older shapes are not
+// read (clean break, no compat shim). `decision` must always be explicit: it
+// drives the tab-reuse grace window in runReview (a waiting tab can only exist
+// after a prior comments round).
 export function loadReviewState(deckDir) {
   const f = path.join(deckDir, REVIEW_STATE_FILE);
-  if (!fs.existsSync(f)) return { version: 1, decision: null, comments: [] };
+  if (!fs.existsSync(f)) return { ...EMPTY_STATE };
   try {
     const data = JSON.parse(fs.readFileSync(f, "utf8"));
+    if (!data || data.version !== 2) return { ...EMPTY_STATE };
     return {
-      version: 1,
+      version: 2,
       decision: data.decision ?? null,
-      comments: Array.isArray(data.comments) ? data.comments : [],
+      comments: normalizeReviewComments(data.comments),
+      at: data.at ?? null,
     };
   } catch {
-    return { version: 1, decision: null, comments: [] };
+    return { ...EMPTY_STATE };
   }
 }
 
@@ -241,7 +309,7 @@ export function preferredPortForDeck(deckDir) {
 // presentation.html must already exist in deckDir (build it first).
 export async function createReviewServer({
   deckDir,
-  previousComments = [],
+  ledgerSeed = [],
   overlayJs,
   logoMark = null,
   port = 0,
@@ -255,7 +323,17 @@ export async function createReviewServer({
     overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8");
   const indexHtml = injectReview(
     fs.readFileSync(path.join(deckDir, "presentation.html"), "utf8"),
-    previousComments,
+    {
+      // deck: the sessionStorage namespace for this deck's pin ledger.
+      // ledgerSeed: the previous round's pins — a FRESH tab (no session) renders
+      // them as delivered-but-unanswered rows; a reused tab merges them by id
+      // under its own. The ROUND identity is the heartbeat nonce (hb.round), not
+      // a content hash: a fix round that edited nothing hashes identically, and
+      // an unreadable slides/ dir hashed to "" — both made the transition
+      // undetectable, which stranded pins in "sent" forever.
+      deck: path.basename(path.resolve(deckDir)),
+      ledgerSeed: normalizeReviewComments(ledgerSeed),
+    },
     overlay,
     logoMark,
     hb.round,
@@ -266,25 +344,30 @@ export async function createReviewServer({
     const u = new URL(req.url, "http://127.0.0.1");
     const pathname = decodeURIComponent(u.pathname);
 
-    if (req.method === "POST" && pathname === "/review") {
-      let body = "";
-      req.on("data", (chunk) => {
-        body += chunk;
-        if (body.length > 5e6) req.destroy();
+    // Both POST routes are gate-server's shared handlers: the backlog drain and
+    // the decision + 409 guard behave identically in both gates. `gate.settled()`
+    // guards BOTH: once one tab's drain or decision resolved this run, a late
+    // POST from another waiting tab is refused instead of being acked and
+    // silently dropped (every waiter reloads into a new round, so two tabs
+    // posting into one run is the normal multi-window case, not an anomaly).
+    if (req.method === "POST" && pathname === "/review/backlog") {
+      serveBacklogPost(req, res, {
+        normalize: normalizeReviewComments,
+        isSuperseded: () => gate.settled(),
+        onDrained: (comments) => {
+          gate.resolve({ decision: "comments", comments, drained: true });
+        },
       });
-      req.on("end", () => {
-        let payload;
-        try {
-          payload = JSON.parse(body || "{}");
-        } catch {
-          payload = {};
-        }
-        res.writeHead(200, { "Content-Type": MIME[".json"] });
-        res.end(JSON.stringify({ ok: true }));
-        gate.resolve({
-          decision: payload.decision === "comments" ? "comments" : "approve",
-          comments: Array.isArray(payload.comments) ? payload.comments : [],
-        });
+      return;
+    }
+
+    if (req.method === "POST" && pathname === "/review") {
+      serveDecisionPost(req, res, {
+        normalize: normalizeReviewComments,
+        isSuperseded: () => gate.settled(),
+        onDecision: (decision, _payload, comments) => {
+          gate.resolve({ decision, comments, drained: false });
+        },
       });
       return;
     }
@@ -401,7 +484,7 @@ export async function runReview({
   const wantPort = port == null ? preferredPortForDeck(deckDir) : port;
   const server = await createReviewServer({
     deckDir,
-    previousComments: prev.comments || [],
+    ledgerSeed: prev.comments || [],
     logoMark,
     port: wantPort,
   });
@@ -451,10 +534,11 @@ export async function runReview({
     server.close();
   }
 
+  const comments = normalizeReviewComments(decision.comments);
   saveReviewState(deckDir, {
-    version: 1,
+    version: 2,
     decision: decision.decision,
-    comments: decision.comments,
+    comments,
     at: new Date().toISOString(),
   });
 
@@ -465,7 +549,9 @@ export async function runReview({
         "for (slidemind push / slidemind build-pptx). One approval covers the task.\n",
     );
   } else {
-    process.stdout.write(formatCommentsForHarness(deckDir, decision.comments));
+    process.stdout.write(
+      formatCommentsForHarness(deckDir, comments, { drained: !!decision.drained }),
+    );
   }
   return decision;
 }