slidemind 0.1.8 → 0.2.0

package/src/builders/gate-server.mjs

@@ -164,25 +164,86 @@ export function listenWithFallback(server, port, host, onFallback) {
 }
 
 // Per-run heartbeat state for one gate server. The gate mounts `respond` under
-// its own heartbeat path; a waiting tab polls it and reloads only when BOTH the
-// service marker matches its own gate (a foreign app or the other gate on this
-// port must never trigger a reload) AND the round nonce differs from the one it
-// was served with (same nonce = this run's own orphan — never self-reload).
-// `waitForHeartbeat(ms)` is the server side of the open-browser grace window.
+// its own heartbeat path; a waiting tab polls it with its own round nonce and
+// visibility state, and the response's service marker + round nonce + `action`
+// tell it what to do (a foreign app or the other gate on this port must never
+// trigger a reload; same nonce = this run's own orphan — never a waiter).
+//
+// The gate must ALWAYS end up visibly open in front of the user, so tab reuse
+// is granted only to a waiting tab that reports itself VISIBLE (`visible: true`,
+// from the overlay's document.visibilityState) inside the grace window. A tab
+// buried in a background window must not silently swallow the round — it keeps
+// polling (`action: "wait"`) until the grace window decides, then either
+// reloads (`"reload"`, a visible tab won reuse — every waiter follows it into
+// the new round) or is told the round opened in a fresh browser tab and it
+// should retire (`"close"`).
+//
+// `waitForHeartbeat(ms)` is the server side of the open-browser grace window:
+// it resolves true the moment a visible waiter claims reuse, false when the
+// grace expires with none. The gate then calls `markFresh()` before opening a
+// new browser tab so late pollers get `action: "close"` instead of reloading
+// into a duplicate.
+//
+// `notePageLoad()` / `waitForPageLoad(ms)` / `pageLoaded()` track whether the
+// gate PAGE was ever actually fetched: the gate's request handler calls
+// `notePageLoad()` whenever it serves the root page, and serveAndOpen waits on
+// it after launching the opener — the only end-to-end proof that a browser
+// really opened the gate (a spawned opener exiting 0 proves nothing on a box
+// with a broken default-browser association). `pageLoaded()` is re-checked at
+// decision-timeout time so the DECISION: pending contract can tell the agent
+// whether the user ever saw the gate at all.
 export function createHeartbeat({ service }) {
   const round = crypto.randomUUID();
-  let seen = false;
+  // null = undecided (grace window running), "reuse" = a visible waiting tab
+  // reloads into this round, "fresh" = a new browser tab was opened for it.
+  let mode = null;
   const waiters = [];
+  let pageSeen = false;
+  const pageWaiters = [];
   return {
     round,
-    respond(res) {
-      seen = true;
-      while (waiters.length) waiters.shift()();
+    notePageLoad() {
+      pageSeen = true;
+      while (pageWaiters.length) pageWaiters.shift()();
+    },
+    pageLoaded() {
+      return pageSeen;
+    },
+    waitForPageLoad(ms) {
+      if (pageSeen) return Promise.resolve(true);
+      if (!(ms > 0)) return Promise.resolve(false);
+      return new Promise((resolve) => {
+        const t = setTimeout(() => resolve(false), ms);
+        pageWaiters.push(() => {
+          clearTimeout(t);
+          resolve(true);
+        });
+      });
+    },
+    respond(res, { visible = false, tabRound = null } = {}) {
+      // A poll carrying THIS run's nonce is our own page (or an orphan of this
+      // run) — never a previous-round waiter, never a reuse claim.
+      const isWaiter = tabRound !== round;
+      if (isWaiter && mode === null && visible) {
+        mode = "reuse";
+        while (waiters.length) waiters.shift()();
+      }
+      const action = !isWaiter
+        ? "none"
+        : mode === "reuse"
+          ? "reload"
+          : mode === "fresh"
+            ? "close"
+            : "wait";
       res.writeHead(200, { "Content-Type": MIME[".json"], "Cache-Control": "no-store" });
-      res.end(JSON.stringify({ ok: true, service, round }));
+      res.end(JSON.stringify({ ok: true, service, round, action }));
+    },
+    markFresh() {
+      if (mode === null) mode = "fresh";
     },
     waitForHeartbeat(ms) {
-      if (seen) return Promise.resolve(true);
+      if (mode === "reuse") return Promise.resolve(true);
+      if (mode === "fresh" || !(ms > 0)) return Promise.resolve(false);
       return new Promise((resolve) => {
         const t = setTimeout(() => resolve(false), ms);
         waiters.push(() => {
@@ -194,30 +255,110 @@ export function createHeartbeat({ service }) {
   };
 }
 
-// Print the gate URL, then decide whether to open a browser. If a tab left
-// waiting from a previous comments round pings the gate's heartbeat within the
-// grace window, reuse it (it reloads itself) instead of opening a duplicate.
-// Returns true if an existing tab was reused. `open` is required — gates pass
-// their browser opener so this module stays dependency-light and tests inject
-// a fake. The message strings are per-gate; defaults speak the preview gate's.
+// Browser-status lines for a gate's DECISION: pending output, shared by both
+// gates so the wording is identical. A pending decision has two very different
+// stories: the user saw the gate and hasn't answered (benign — just wait), or
+// no tab ever loaded it (the browser open failed and they never saw anything —
+// the agent must hand them the link). `pageLoaded` comes from the server's
+// page-load tracker re-checked at timeout time, so a tab that opened late still
+// counts. Returns [] when the caller has no status to report (url unknown),
+// keeping older call sites and tests valid.
+export function pendingBrowserLines({ pageLoaded = null, url = null } = {}) {
+  if (!url) return [];
+  if (pageLoaded) {
+    return [
+      `Browser status: the gate DID open in the user's browser (a tab loaded ${url})`,
+      "— they just haven't decided yet.",
+    ];
+  }
+  return [
+    "Browser status: NO tab ever loaded the gate — the browser most likely FAILED",
+    "to open on the user's machine, so they never saw it. When you tell the user,",
+    `give them the gate link to open manually once you re-run: ${url}`,
+    "(the re-run binds the same address when its port is free, and prints it again).",
+  ];
+}
+
+// How long serveAndOpen waits, after launching the opener, for the fresh tab
+// to actually fetch the gate page before reporting the open as unconfirmed.
+// Generous enough for a cold browser start; the gate blocks on the decision
+// anyway, so this delay only defers one status line.
+export const OPEN_CONFIRM_MS = 8000;
+
+// When the opener chain FAILED outright, the user will never see the gate on
+// their own — blocking the agent for the full decision timeout helps nobody.
+// The gates instead give a manually-opened tab this long to appear (the URL was
+// printed, the user may click it from the terminal), then return the pending
+// contract early so the agent can hand the user the link.
+export const OPEN_FAILED_GRACE_MS = 90 * 1000;
+
+// Print the gate URL, then decide whether to open a browser. If a VISIBLE tab
+// left waiting from a previous comments round pings the gate's heartbeat within
+// the grace window, reuse it (it reloads itself) instead of opening a duplicate.
+// In every other case — first run, no waiting tab, or only hidden/background
+// tabs polling — the browser is ALWAYS opened, and `markOpenedFresh` retires
+// the hidden waiters so they don't reload into a duplicate.
+//
+// Opening a browser from a CLI is error-prone, so the outcome is REPORTED, not
+// assumed: the opener's own result says whether anything launched, and the
+// server's page-load tracker (`waitForPageLoad`, fed by the gate serving its
+// root page) is the end-to-end proof a tab really opened. Every branch prints
+// one agent-facing `BROWSER:` line that (a) says explicitly whether the gate
+// auto-opened and (b) always carries the URL, so the agent can either tell the
+// user "it's on your screen" or hand them the link to open manually.
+//
+// Returns { reused, launched, confirmed, url }: `launched` = an opener
+// plausibly ran (null when reused — nothing was launched); `confirmed` = a tab
+// provably fetched the gate page (null when the server exposes no
+// waitForPageLoad, i.e. unknown). `open` is required — gates pass their browser
+// opener so this module stays dependency-light and tests inject a fake; a
+// legacy/fake opener returning undefined counts as launched (only an explicit
+// `false` means the chain failed). The message nouns are per-gate; defaults
+// speak the preview gate's.
 export async function serveAndOpen(server, {
   open,
   graceMs = GRACE_MS,
+  openConfirmMs = OPEN_CONFIRM_MS,
   readyLabel = "Preview review",
   reuseNoun = "review tab",
-  openedLine = "Opened your browser — leave comments or approve, then return here.",
+  gateNoun = "review",
   waitLine = null,
 } = {}) {
   process.stderr.write(`${readyLabel} ready at ${server.url}\n`); // URL always printed first
   const reused = await server.waitForHeartbeat(graceMs);
+  let launched = null;
+  let confirmed = null;
   if (reused) {
-    process.stderr.write(`Reusing your open ${reuseNoun} — no new browser window.\n`);
+    process.stderr.write(
+      `BROWSER: reused the user's already-open ${reuseNoun} at ${server.url} — it reloaded into this round; no new window was opened.\n`,
+    );
+    confirmed = true;
   } else {
-    open(server.url);
-    process.stderr.write(`${openedLine}\n`);
+    if (server.markOpenedFresh) server.markOpenedFresh();
+    launched = (await open(server.url)) !== false;
+    if (launched && server.waitForPageLoad) {
+      confirmed = await server.waitForPageLoad(openConfirmMs);
+    }
+    if (!launched) {
+      process.stderr.write(
+        `BROWSER: could NOT be opened automatically (no opener worked on this machine). ` +
+          `The user must open the ${gateNoun} themselves — give them this link: ${server.url}\n`,
+      );
+    } else if (confirmed === false) {
+      process.stderr.write(
+        `BROWSER: open was attempted but NO tab has loaded the ${gateNoun} yet — it may not have opened. ` +
+          `If the user doesn't see it, give them this link to open manually: ${server.url}\n`,
+      );
+    } else {
+      // confirmed === true (a tab fetched the page) or null (server can't track
+      // page loads — trust the opener's success).
+      process.stderr.write(
+        `BROWSER: opened automatically — the ${gateNoun} is on the user's screen at ${server.url}.\n`,
+      );
+    }
   }
   // Spoken to the AGENT running this command: blocking here is the designed
   // behavior, not a hang — don't kill the call because it sits quiet.
   if (waitLine) process.stderr.write(`${waitLine}\n`);
-  return reused;
+  return { reused, launched, confirmed, url: server.url };
 }

package/src/builders/plan-markdown-edit.mjs

@@ -0,0 +1,120 @@
+/**
+ * Inline-edit round-trip for the plan gate's rendered markdown blocks.
+ *
+ * The plan preview renders each `contenteditable` block stamped with its
+ * on-disk source line (`data-md-line`, 1-based, from plan-md.mjs) and kind
+ * (`data-md-kind`). When the user commits an edit, `replaceRenderedMarkdownBlock`
+ * maps the block's edited innerText back into the markdown source at that
+ * line, preserving list markers, heading levels, and blockquote prefixes.
+ * `addEditableAttributes` injects the `contenteditable`/`spellcheck` attributes
+ * onto the editable block kinds only.
+ *
+ * Pure string logic — no DOM, no Office (unit-testable).
+ *
+ * 1:1 port of the add-in's plan-markdown-edit.ts. Top-level helpers are
+ * prefixed `pme…` to keep the single-IIFE browser bundle collision-free;
+ * exported API names match the add-in verbatim.
+ */
+
+export function isEditableKind(kind) {
+  return (
+    kind === "p" ||
+    kind === "li" ||
+    kind === "blockquote" ||
+    /^h[1-6]$/.test(kind)
+  );
+}
+
+function pmeIsBlockStart(line) {
+  return (
+    /^\s*$/.test(line) ||
+    /^(#{1,6})\s+/.test(line) ||
+    /^\s*```/.test(line) ||
+    /^\s*>/.test(line) ||
+    /^\s*(?:[-*]\s+|\d+[.)]\s+)/.test(line) ||
+    (line.includes("|") && /^\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?$/.test(line))
+  );
+}
+
+function pmeGetParagraphRange(lines, index) {
+  let end = index + 1;
+  while (end < lines.length && !pmeIsBlockStart(lines[end] ?? "")) {
+    end++;
+  }
+  return { start: index, end };
+}
+
+function pmeNormalizeEditableText(text) {
+  return text
+    .replace(/\u00a0/g, " ")
+    .replace(/[ \t]+\n/g, "\n")
+    .trim();
+}
+
+function pmeMarkdownForEdit(kind, existingLine, text) {
+  const normalized = pmeNormalizeEditableText(text);
+  if (!normalized) return null;
+
+  const heading = normalized.match(/^(#{1,6})\s+(.*)$/);
+  if (heading) {
+    return `${heading[1]} ${(heading[2] ?? "").trim()}`;
+  }
+
+  const list = normalized.match(/^((?:[-*])|\d+[.)])\s+(.*)$/);
+  if (list) {
+    return `${list[1]} ${(list[2] ?? "").trim()}`;
+  }
+
+  if (/^h[1-6]$/.test(kind)) {
+    const current = existingLine.match(/^(#{1,6})\s+/)?.[1] ?? "##";
+    return `${current} ${normalized}`;
+  }
+
+  if (kind === "li") {
+    const marker = existingLine.match(/^\s*((?:[-*])|\d+[.)])\s+/)?.[1] ?? "-";
+    return `${marker} ${normalized}`;
+  }
+
+  if (kind === "blockquote") {
+    return normalized
+      .split("\n")
+      .map((line) => `> ${line.trim()}`)
+      .join("\n");
+  }
+
+  return normalized;
+}
+
+/**
+ * Maps an edited rendered block's innerText back into the markdown source at
+ * the stamped 1-based line. Options: { markdown, line, kind, text }.
+ * No-op for non-editable kinds or out-of-range lines.
+ */
+export function replaceRenderedMarkdownBlock(options) {
+  const { markdown, line, kind, text } = options;
+  if (!isEditableKind(kind)) return markdown;
+
+  const lines = markdown.split("\n");
+  const index = line - 1;
+  if (index < 0 || index >= lines.length) return markdown;
+
+  const existingLine = lines[index] ?? "";
+  const range =
+    kind === "p"
+      ? pmeGetParagraphRange(lines, index)
+      : { start: index, end: index + 1 };
+  const replacement = pmeMarkdownForEdit(kind, existingLine, text);
+  const nextLines = [
+    ...lines.slice(0, range.start),
+    ...(replacement === null ? [] : replacement.split("\n")),
+    ...lines.slice(range.end),
+  ];
+  return nextLines.join("\n");
+}
+
+export function addEditableAttributes(html) {
+  return html.replace(
+    /data-md-kind="(h[1-6]|p|li|blockquote)"/g,
+    'data-md-kind="$1" contenteditable="true" spellcheck="true"',
+  );
+}