slidemind 0.2.3 → 0.3.0

package/src/builders/plan.mjs

@@ -10,20 +10,32 @@
 // (plan-md.mjs), shipped inline to the browser as window.__SLIDEMIND_RENDER_MD__.
 // Opens the browser and BLOCKS until the user approves the plan or requests
 // changes. The browser POSTs the decision to /plan-review, which unblocks this
-// command — no copy-paste round-trip. On a comments round the tab stays open
-// and readable (spinner in the composer) and reloads itself when the next
-// round binds the same port. The verdict is printed to stdout for the harness:
+// command — no copy-paste round-trip. The verdict is printed to stdout for the
+// harness:
 //   - approved  -> "DECISION: approved" (the agent then authors the slides;
 //                  an edit-and-approve rewrites plan.md first and tells the
 //                  agent to re-read it — the user's words are the plan).
-//   - comments  -> the user's overall feedback (the agent revises plan.md to
-//                  address it and re-runs).
+//   - comments  -> the user's slide-anchored comments (the agent revises
+//                  plan.md to address them and re-runs).
+//
+// ASYNC REVIEW (the drain loop). A comments round no longer freezes the tab:
+// once the decision is sent the page enters WORKING mode — still readable and
+// navigable, composer still live — and further comments 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
+// /plan-review/backlog. A non-empty backlog resolves the gate AT ONCE with
+// those comments (a "drain round": the command prints DECISION: comments and
+// 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, exactly as before. Approve is refused once a backlog arrived in this
+// run — that round is already superseded.
 //
 // Host-free: the plan gate runs BEFORE any slide exists, so it needs no bundle
 // and no open host. A per-brand orb PNG is used when a bundle happens to be
 // materialized (dark variant preferred); otherwise the overlay falls back to
-// its inline embossed slide glyph. Each round's feedback persists to
-// <deck>/plan-review.json so the next run shows it as a read-only note.
+// its inline embossed slide glyph. Each round persists to
+// <deck>/plan-review.json (v3, one row per anchored comment) as the harness's
+// recovery copy of the output.
 //
 // Port + tab-reuse contract (shared with the preview gate via gate-server.mjs):
 // each run binds a deterministic per-deck plan port (a hash of the deck path,
@@ -48,10 +60,16 @@ import { openInBrowser } from "./build.mjs";
 import { renderPlanMarkdown } from "./plan-md.mjs";
 import { splitPlanFrontmatter } from "./resolve-skill.mjs";
 import {
+  FAVICON_LINK,
   MIME,
   serveStaticFile,
   createDecisionGate,
   createHeartbeat,
+  bundleGateSession,
+  normalizeGateComments,
+  serveBacklogPost,
+  serveDecisionPost,
+  stripModuleSyntax,
   listenWithFallback,
   preferredGatePort,
   serveAndOpen,
@@ -86,37 +104,50 @@ function safeInlineJson(data) {
 }
 
 // ---------------------------------------------------------------------------
-// plan-review.json round-trip (previous-round feedback source)
+// plan-review.json round-trip (the harness's recovery copy of a round)
 // ---------------------------------------------------------------------------
 
+const EMPTY_STATE = { version: 3, decision: null, comments: [] };
+
+// Normalize the browser's comment array into the persisted/printed row shape.
+// Every row is anchored (scope "slide" carries the slide number + the beat
+// heading it was written against); the shared core adds identity (`id` dedupes
+// a client retry of the same batch) and drops text-less rows — an empty row
+// would print as a bullet the agent cannot act on.
+export function normalizePlanComments(raw) {
+  return normalizeGateComments(raw, (c) => {
+    const scope = c.scope === "slide" ? "slide" : "story";
+    return {
+      scope,
+      slideIndex: scope === "slide" && Number.isFinite(c.slideIndex) ? Number(c.slideIndex) : null,
+      slideHeading:
+        scope === "slide" && typeof c.slideHeading === "string" && c.slideHeading
+          ? c.slideHeading
+          : null,
+    };
+  });
+}
+
+// v3 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 runPlanReview (a waiting tab can only
+// exist after a prior comments round).
 export function loadPlanState(deckDir) {
   const f = path.join(deckDir, PLAN_STATE_FILE);
-  // decision drives the grace-window logic in runPlanReview (a waiting tab can
-  // only exist after a prior comments round), so a fresh/garbage state must
-  // still carry an explicit decision: null — same shape review.mjs uses.
-  if (!fs.existsSync(f)) return { version: 2, decision: null, comment: null };
+  if (!fs.existsSync(f)) return { ...EMPTY_STATE };
   try {
     const data = JSON.parse(fs.readFileSync(f, "utf8"));
-    // v1 files carried a per-block comments array; fold it into one feedback
-    // text so an old round still shows up as the previous-round note.
-    let comment = typeof data.comment === "string" ? data.comment : null;
-    if (comment == null && Array.isArray(data.comments)) {
-      const joined = data.comments
-        .map((c) => c && c.comment)
-        .filter(Boolean)
-        .join("\n");
-      comment = joined || null;
-    }
+    if (!data || data.version !== 3) return { ...EMPTY_STATE };
     return {
-      version: 2,
+      version: 3,
       decision: data.decision ?? null,
-      comment,
+      comments: normalizePlanComments(data.comments),
       edited: data.edited ?? false,
       planHash: data.planHash ?? null,
       at: data.at ?? null,
     };
   } catch {
-    return { version: 2, decision: null, comment: null };
+    return { ...EMPTY_STATE };
   }
 }
 
@@ -131,52 +162,69 @@ export function savePlanState(deckDir, state) {
 // harness output
 // ---------------------------------------------------------------------------
 
-// Render the feedback round for the harness — the plan analog of review.mjs's
-// formatCommentsForHarness, on ONE overall comment instead of per-block pins.
+// One anchored bullet per comment: `- [Slide 3: "Align the next outcome"] text`
+// or `- [Whole story] text`. Continuation lines are indented under the bullet so
+// a multi-line note can't be mistaken for a second comment.
+function commentBullet(c) {
+  const anchor =
+    c.scope === "slide"
+      ? `Slide ${c.slideIndex ?? "?"}${c.slideHeading ? `: "${c.slideHeading}"` : ""}`
+      : "Whole story";
+  const [first, ...rest] = String(c.text).split("\n");
+  return [`- [${anchor}] ${first}`, ...rest.map((l) => `  ${l}`)].join("\n");
+}
+
+// Render the comments round for the harness — the plan analog of review.mjs's
+// formatCommentsForHarness, on slide-anchored comments instead of spatial pins.
 //
-// The tail is deliberately imperative and stateful: after a comments round the
-// user's browser tab sits on a waiting spinner that ONLY the next `slidemind
-// plan` run releases, so an agent that ends its turn here (or redirects the
-// user "back to the browser") deadlocks the session — the tab waits for the
-// agent while the agent waits for the tab. Spell the next actions out as
-// short, own-line steps so no instruction hides at the end of a long path.
-export function formatPlanFeedbackForHarness(deckDir, comment, { edited = false } = {}) {
+// The tail is deliberately imperative: the reviewer's tab is LIVE while the
+// agent revises (they can keep reading and keep queueing comments), and those
+// queued comments are only delivered by the next `slidemind plan` run. An agent
+// that ends its turn here strands them, so the re-run instruction says "same
+// turn" and says why more comments may follow.
+export function formatPlanCommentsForHarness(
+  deckDir,
+  comments,
+  { edited = false, drained = false } = {},
+) {
+  const rows = normalizePlanComments(comments);
   const out = [];
   out.push("DECISION: comments");
   out.push("The user requested changes to the plan. Nothing was authored.");
+  if (drained) {
+    out.push(
+      "(These comments were queued while you were revising and arrived with this " +
+        "run — that is why the gate returned immediately instead of waiting.)",
+    );
+  }
   if (edited) {
     out.push(
       "The user also edited plan.md directly — re-read it before revising; the " +
-        "feedback below is on top of their edits.",
+        "comments below are on top of their edits.",
     );
   }
   out.push("");
-  if (comment) {
-    out.push("Feedback:");
-    for (const line of String(comment).split("\n")) out.push(`  ${line}`);
-    out.push("");
+  if (rows.length) {
+    for (const c of rows) out.push(commentBullet(c));
   } else if (edited) {
-    out.push("(No written feedback — their direct edits to plan.md are the change.)");
-    out.push("");
+    out.push("(No written comments — their direct edits to plan.md are the change.)");
   }
+  out.push("");
+  out.push("Revise plan.md to address ALL comments — change only what the feedback");
+  out.push("requires; keep unaffected slides verbatim.");
+  out.push(`Then run \`slidemind plan ${path.basename(deckDir)}\` again in the same turn.`);
+  out.push("The reviewer may queue further comments while you revise; they are");
+  out.push("delivered on that next run (it can return immediately with them — that is");
+  out.push("normal, not an error). Do NOT end your turn and do NOT send the user back");
+  out.push("to the browser before you re-run the gate.");
+  out.push("");
   // Recovery pointer in the tail (truncated captures usually lose the TOP):
   // the round is persisted before this prints, so a lost capture is recoverable.
   out.push(
-    `This round (decision + feedback) is also saved verbatim in ` +
+    `This round (decision + comments) is also saved verbatim in ` +
       `${path.join(deckDir, PLAN_STATE_FILE)} — if this output looks truncated, read ` +
       `that file instead of guessing.`,
   );
-  out.push("");
-  out.push(
-    "The user's browser tab is still open, on a waiting spinner that says you are",
-  );
-  out.push("revising the plan. They are waiting on YOU now — do both steps in this");
-  out.push("same turn:");
-  out.push(`  1. Edit ${deckDir}/plan.md to address the feedback.`);
-  out.push(`  2. Re-run: slidemind plan ${path.basename(deckDir)}`);
-  out.push("The re-run reopens their same tab with the revised plan. Do NOT end your");
-  out.push("turn and do NOT send the user back to the browser before step 2 — nothing");
-  out.push("happens until the gate runs again.");
   return out.join("\n") + "\n";
 }
 
@@ -232,17 +280,10 @@ const PLAN_NAMESPACE_EXPORTS = [
   "MAX_CONTENT_LENGTH",
 ];
 
-// Turn a dependency-free ESM module's source into plain browser JS that runs
-// inside a shared IIFE scope: drop single-line `import … from "…";` statements
-// (all inter-module imports across the plan-review modules are single-line) and
-// strip the leading `export ` keyword from declarations. The imported names are
-// provided by an earlier module in the concatenation, so removing the import
-// line just leaves the reference resolving to that earlier top-level binding.
-export function stripModuleSyntax(src) {
-  return String(src || "")
-    .replace(/^\s*import\s+[^;]*?from\s*["'][^"']+["'];?\s*$/gm, "")
-    .replace(/^export\s+/gm, "");
-}
+// stripModuleSyntax now lives in gate-server.mjs (both gates bundle browser
+// modules through it); re-exported here because the plan bundle is its oldest
+// caller and the module tests reach for it on this path.
+export { stripModuleSyntax };
 
 // Bundle the five plan-review modules into one IIFE for the browser page, in
 // dependency order (schema → storyboard-markdown → backbone → edit → plan-md).
@@ -326,40 +367,54 @@ display:block;overflow-x:auto;}
 // function of its inputs so it's unit-testable without a server.
 export function buildPlanPage({
   bodyHtml,
-  previousComment,
   overlayJs,
   planModulesJs,
   logoMark,
   planBody,
   bodyStartLine,
   round,
+  deck,
+  ledgerSeed,
 }) {
   const cfg = safeInlineJson({
     endpoint: "/plan-review",
+    backlogEndpoint: "/plan-review/backlog",
     heartbeat: "/__plan/heartbeat",
     round: round ?? null,
     pollMs: POLL_MS,
     pollTtlMs: POLL_TTL_MS,
-    previousComment: previousComment ?? null,
     logoMark: logoMark ?? null,
     planBody: planBody ?? "",
     bodyStartLine: bodyStartLine ?? 1,
+    // deck: the sessionStorage namespace for this deck's comment ledger.
+    // ledgerSeed: the previous round's persisted comments — a FRESH tab (no
+    // session of its own) renders its ledger rail from these instead of coming
+    // up blank. The ROUND identity is the heartbeat nonce in `round`, not a
+    // content hash: the page's cached plan body is only used for the cosmetic
+    // "updated" badges.
+    deck: deck ?? "",
+    ledgerSeed: ledgerSeed ?? [],
   });
   const overlay = String(overlayJs || "").replace(/<\/script>/g, "<\\/script>");
   const modulesSrc = String(planModulesJs || "").replace(/<\/script>/g, "<\\/script>");
   const rendererBlock = modulesSrc ? "<script>\n" + modulesSrc + "\n</script>\n" : "";
+  // The shared gate session goes in before the overlay, which reads it at boot.
+  const gateBlock = "<script>\n" + bundleGateSession().replace(/<\/script>/g, "<\\/script>") + "\n</script>\n";
   return (
     "<!doctype html>\n" +
     '<html lang="en">\n' +
     "<head>\n" +
     '<meta charset="utf-8">\n' +
     '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
-    "<title>Plan review</title>\n" +
+    "<title>Plan review — slidemind</title>\n" +
+    FAVICON_LINK +
+    "\n" +
     `<style>${PAGE_CSS}</style>\n` +
     "</head>\n" +
     "<body>\n" +
     `<div id="plan-root">${bodyHtml}</div>\n` +
     `<script>window.__SLIDEMIND_PLAN_REVIEW__ = ${cfg};</script>\n` +
+    gateBlock +
     rendererBlock +
     `<script>\n${overlay}\n</script>\n` +
     "</body>\n" +
@@ -379,11 +434,11 @@ export async function createPlanReviewServer({
   deckDir,
   body,
   bodyStartLine,
-  previousComment = null,
   overlayJs,
   planModulesJs,
   logoMark = null,
   brandAssetPath = null,
+  ledgerSeed = [],
   port = 0,
 }) {
   const gate = createDecisionGate({
@@ -397,13 +452,14 @@ export async function createPlanReviewServer({
   const bodyHtml = renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 });
   const indexHtml = buildPlanPage({
     bodyHtml,
-    previousComment,
     overlayJs: overlay,
     planModulesJs: planModules,
     logoMark,
     planBody: body,
     bodyStartLine,
     round: hb.round,
+    deck: path.basename(path.resolve(deckDir)),
+    ledgerSeed: normalizePlanComments(ledgerSeed),
   });
   const deckRoot = path.resolve(deckDir);
 
@@ -411,27 +467,35 @@ export async function createPlanReviewServer({
     const u = new URL(req.url, "http://127.0.0.1");
     const pathname = decodeURIComponent(u.pathname);
 
-    if (req.method === "POST" && pathname === "/plan-review") {
-      let raw = "";
-      req.on("data", (chunk) => {
-        raw += chunk;
-        if (raw.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 === "/plan-review/backlog") {
+      serveBacklogPost(req, res, {
+        normalize: normalizePlanComments,
+        isSuperseded: () => gate.settled(),
+        onDrained: (comments) => {
+          gate.resolve({ decision: "comments", comments, editedPlan: null, drained: true });
+        },
       });
-      req.on("end", () => {
-        let payload;
-        try {
-          payload = JSON.parse(raw || "{}");
-        } catch {
-          payload = {};
-        }
-        res.writeHead(200, { "Content-Type": MIME[".json"] });
-        res.end(JSON.stringify({ ok: true }));
-        const commentRaw = typeof payload.comment === "string" ? payload.comment.trim() : "";
-        gate.resolve({
-          decision: payload.decision === "comments" ? "comments" : "approve",
-          comment: commentRaw || null,
-          editedPlan: typeof payload.editedPlan === "string" ? payload.editedPlan : null,
-        });
+      return;
+    }
+
+    if (req.method === "POST" && pathname === "/plan-review") {
+      serveDecisionPost(req, res, {
+        normalize: normalizePlanComments,
+        isSuperseded: () => gate.settled(),
+        onDecision: (decision, payload, comments) => {
+          gate.resolve({
+            decision,
+            comments,
+            editedPlan: typeof payload.editedPlan === "string" ? payload.editedPlan : null,
+            drained: false,
+          });
+        },
       });
       return;
     }
@@ -526,6 +590,12 @@ export function applyPlanEdit({ planPath, frontmatterRaw, body, editedPlan }) {
   return { edited: true };
 }
 
+// Persisted with the decision as this round's plan fingerprint (the round
+// TRANSITION a reloaded tab detects is the server's heartbeat nonce, not this).
+function hashPlan(planPath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(planPath)).digest("hex");
+}
+
 export async function runPlanReview({
   deckDir,
   port = null,
@@ -562,9 +632,11 @@ export async function runPlanReview({
     deckDir,
     body,
     bodyStartLine,
-    previousComment: prev.comment ?? null,
     logoMark,
     brandAssetPath,
+    // A fresh tab renders the previous round's comments from the persisted file
+    // (the plan gate's analogue of review.json's ghost pins).
+    ledgerSeed: prev.comments || [],
     port: wantPort,
   });
   // A waiting tab can only exist when the previous round ended in comments — so
@@ -623,16 +695,13 @@ export async function runPlanReview({
     editedPlan: decision.editedPlan,
   });
 
-  const planHash = crypto
-    .createHash("sha256")
-    .update(fs.readFileSync(planPath))
-    .digest("hex");
+  const comments = normalizePlanComments(decision.comments);
   savePlanState(deckDir, {
-    version: 2,
+    version: 3,
     decision: decision.decision,
-    comment: decision.comment ?? null,
+    comments,
     edited,
-    planHash,
+    planHash: hashPlan(planPath),
     at: new Date().toISOString(),
   });
 
@@ -651,7 +720,9 @@ export async function runPlanReview({
       );
     }
   } else {
-    process.stdout.write(formatPlanFeedbackForHarness(deckDir, decision.comment, { edited }));
+    process.stdout.write(
+      formatPlanCommentsForHarness(deckDir, comments, { edited, drained: !!decision.drained }),
+    );
   }
   return decision;
 }

package/src/builders/resolve-skill.mjs

@@ -68,8 +68,11 @@ function firstExistingOr(candidates, fallback) {
   return firstExisting(candidates) ?? fallback;
 }
 
-export function resolveSkillForDeck(deckDir) {
+export function resolveSkillForDeck(deckDir, opts = {}) {
   const planMeta = readPlanFrontmatter(deckDir);
+  if (opts.packDir) {
+    return resolveTemplatePack(opts.packDir, planMeta, { deckDir });
+  }
   const skillName = planMeta.skill || DEFAULT_SKILL;
   const bundleDir = deckDir ? resolveBundleDirForDeck(deckDir) : null;
   return resolveSkill(skillName, planMeta, { deckDir, bundleDir });
@@ -80,7 +83,12 @@ export function resolveSkillForDeck(deckDir) {
 // fill-template) must not pay resolveSkill's design-root requirement — a
 // compose deck with an unmaterialized bundle self-heals inside the render
 // path, and an early resolver throw here would break that.
-export function resolveDeckMode(deckDir) {
+export function resolveDeckMode(deckDir, opts = {}) {
+  if (opts.packDir) {
+    const planMeta = readPlanFrontmatter(deckDir);
+    const pack = resolveTemplatePack(opts.packDir, planMeta, { deckDir });
+    return { skillName: pack.skillName, mode: pack.mode, skillDir: pack.skillDir };
+  }
   try {
     const planMeta = readPlanFrontmatter(deckDir);
     const skillName = planMeta.skill || DEFAULT_SKILL;
@@ -92,6 +100,60 @@ export function resolveDeckMode(deckDir) {
   }
 }
 
+// Resolve a runtime template pack from an explicit directory. This path is
+// deliberately independent of agent/harness installation and of the compose
+// design-bundle resolver below. A plugin can locate its own pack and pass this
+// path to the CLI without the CLI knowing the plugin exists.
+export function resolveTemplatePack(packDir, planMeta = {}, opts = {}) {
+  const skillDir = path.resolve(String(packDir));
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    throw new Error(`template pack directory does not exist: ${skillDir}`);
+  }
+  const manifest = readManifest(skillDir);
+  if (!manifest || typeof manifest !== "object" || !manifest.mode) {
+    throw new Error(`template pack ${skillDir} has no valid skill.json manifest`);
+  }
+
+  let templateKey = null;
+  let templatePath = null;
+  if (manifest.templates) {
+    templateKey =
+      planMeta.template ||
+      manifest.defaultTemplate ||
+      Object.keys(manifest.templates)[0];
+    const rel = templateKey ? manifest.templates[templateKey] : null;
+    if (rel) {
+      const candidate = path.resolve(skillDir, rel);
+      const relative = path.relative(skillDir, candidate);
+      if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`template path escapes pack directory: ${rel}`);
+      }
+      if (fs.existsSync(candidate)) templatePath = candidate;
+    }
+  }
+
+  return {
+    skillName: manifest.name || path.basename(skillDir),
+    skillDir,
+    manifest,
+    mode: manifest.mode || "compose",
+    // Fill-template callers only need the pack payload. These legacy design
+    // fields remain null so callers can distinguish this path from compose
+    // skill resolution without paying a design-root requirement.
+    cssFile: null,
+    layoutsDir: null,
+    layoutsCssFile: null,
+    assetsDir: opts.deckDir ? path.join(opts.deckDir, "assets") : null,
+    brand: null,
+    templateKey,
+    templatePath,
+    locale: planMeta.locale || null,
+    planMeta,
+    packageRoot: PACKAGE_ROOT,
+    bundleDir: opts.deckDir ? resolveBundleDirForDeck(opts.deckDir) : null,
+  };
+}
+
 // Skill packs can live outside the npm package: private, org-internal packs
 // (templates, brand-specific assets) are distributed on their own and this
 // package never carries them. Lookup order: