slidemind 0.2.3 → 0.3.0

package/src/builders/gate-session.js

@@ -0,0 +1,355 @@
+// Shared browser-side session machinery for the CLI's two blocking gates —
+// the plan sign-off gate (plan-overlay.js) and the spatial preview gate
+// (review-overlay.js). Both overlays used to carry byte-identical copies of the
+// sessionStorage ledger, the backlog flush, the round-transition detection, the
+// round-ready announcement and the heartbeat poll; a fix landed in one and not
+// the other is exactly how the two drifted apart. This module is the ONE copy.
+//
+// It is plain dependency-free ESM so a test can `import` it directly, and the
+// gates inline it into their page (import-free, `export ` stripped) as
+// window.__SLIDEMIND_GATE__ — see bundleGateSession() in gate-server.mjs.
+//
+// STATE OWNERSHIP: the overlay owns its `ledger` array and its UI mode flags;
+// this module owns the STORAGE and the wire. Every function takes the ledger it
+// operates on, so nothing here has to be kept in sync with the overlay's vars.
+//
+// ROUND TRANSITION: driven by the server's per-run nonce (CFG.round, minted by
+// gate-server's createHeartbeat), NOT by a content hash. A content hash is not
+// a reliable round marker — hashRender() returns "" when slides/ can't be read,
+// and a revision round that changed no file produces an identical hash — so a
+// hash-driven transition silently fails to flip "sent" rows to "addressed" and
+// (with the old approve guard) permanently disabled Approve. Content hashes are
+// still fine for the COSMETIC "updated" badges, which is all the plan gate uses
+// its cached previous body for.
+
+// The wire shape each gate's server persists and prints. Per-gate because the
+// anchors differ (spatial pin vs. slide-anchored comment), shared here because
+// flushBacklog posts it and the gate's normalizer has to accept it.
+const WIRE = {
+  // Preview pins carry FULL-PRECISION 0..1 fractions. Rounding to whole percent
+  // on the wire cost ±6px on a 1280px stage and collapsed sub-1% offsets; the
+  // harness output is the only place a percent is the right unit.
+  review(c) {
+    return {
+      id: c.id,
+      round: c.round,
+      jsxPath: c.jsxPath,
+      resolvedTarget: c.resolvedTarget,
+      x: c.x,
+      y: c.y,
+      text: c.text,
+      status: "sent",
+      at: c.at,
+    };
+  },
+  plan(c) {
+    return {
+      id: c.id,
+      round: c.round,
+      scope: c.scope,
+      slideIndex: c.slideIndex,
+      slideHeading: c.slideHeading,
+      text: c.text,
+      at: c.at,
+    };
+  },
+};
+
+// How long an unsent draft may sit un-persisted. The draft write used to run on
+// every keystroke; with the plan body split out of the context blob the payload
+// is tiny, but a debounce still keeps typing off the storage path entirely.
+const DRAFT_DEBOUNCE_MS = 300;
+
+export function createGateSession(cfg) {
+  const name = cfg.name; // "review" | "plan" — storage prefix + wire shape
+  const deck = cfg.deck || "";
+  const store = cfg.storage;
+  const doFetch = cfg.fetch;
+  const wire = cfg.wire || WIRE[name];
+  // Deck-scoped, NOT round-scoped: the rows carry their own round, and keying
+  // the store by the round would strand the queue on exactly the reload that
+  // has to flush it (a new round's key differs by definition).
+  const LEDGER_KEY = "slidemind-" + name + "-ledger:" + deck;
+  const CTX_KEY = "slidemind-" + name + "-ctx:" + deck;
+  const ROUND_READY_FLAG = "slidemind-" + name + "-round-ready";
+  let draftTimer = null;
+  let pollTimer = null;
+
+  function read(key, fallback) {
+    try {
+      const raw = store.getItem(key);
+      return raw ? JSON.parse(raw) : fallback;
+    } catch {
+      return fallback; // private mode / storage blocked — degrade to in-memory
+    }
+  }
+  function write(key, value) {
+    try {
+      store.setItem(key, JSON.stringify(value));
+    } catch {
+      /* storage blocked — the session just doesn't survive a reload */
+    }
+  }
+  function saveLedger(ledger) {
+    write(LEDGER_KEY, ledger);
+  }
+  // The context the NEXT round restores from. The server nonce rides along as
+  // the round marker; everything else is the caller's (selection, draft, slide).
+  // Deliberately SMALL — anything page-sized (the plan body) belongs in its own
+  // key written once per page load, not in the blob a keystroke rewrites.
+  function saveCtx(extra) {
+    if (draftTimer) {
+      clearTimeout(draftTimer);
+      draftTimer = null;
+    }
+    write(CTX_KEY, Object.assign({ nonce: cfg.round || "" }, extra || {}));
+  }
+  // Same write, coalesced — for the per-keystroke callers.
+  function saveCtxSoon(extra) {
+    if (draftTimer) clearTimeout(draftTimer);
+    draftTimer = setTimeout(function () {
+      draftTimer = null;
+      write(CTX_KEY, Object.assign({ nonce: cfg.round || "" }, extra || {}));
+    }, DRAFT_DEBOUNCE_MS);
+  }
+
+  // The backlog: written in this tab, not yet delivered to any gate run.
+  function queued(ledger) {
+    return (ledger || []).filter(function (c) {
+      return c.status === "queued";
+    });
+  }
+
+  // Restore this tab's session and work out whether THIS load is a new round.
+  // Returns the ledger plus the round state; the caller applies its own ctx
+  // fields from the returned `ctx` and its own round-arrival cosmetics.
+  function restore(seed) {
+    let ledger = read(LEDGER_KEY, []) || [];
+    if (!Array.isArray(ledger)) ledger = [];
+    let ctx = read(CTX_KEY, null);
+    if (!ctx || typeof ctx !== "object") ctx = null;
+    let roundNo = ctx && typeof ctx.round === "number" ? ctx.round : 1;
+    // A different SERVER nonce = a genuinely newer run served this page, i.e. a
+    // new round. Same nonce = a plain refresh of the round already on screen.
+    const newRound = !!(ctx && ctx.nonce && cfg.round && ctx.nonce !== cfg.round);
+    if (newRound) {
+      roundNo += 1;
+      ledger.forEach(function (c) {
+        if (c.status === "sent") {
+          c.status = "addressed";
+          c.addressedInRound = roundNo;
+        }
+      });
+    }
+    // Seed a tab with no session of its own (a fresh window) from the deck's
+    // persisted round. These are the rows the agent has JUST been handed — they
+    // are "sent", not "addressed": nothing has answered them yet, and labelling
+    // them addressed claimed a fix that never happened. Session rows win: they
+    // carry live status.
+    (seed || []).forEach(function (s) {
+      if (!s || !s.id) return;
+      for (let i = 0; i < ledger.length; i++) if (ledger[i].id === s.id) return;
+      const row = {};
+      for (const k in s) row[k] = s[k];
+      row.status = s.status === "addressed" ? "addressed" : "sent";
+      ledger.push(row);
+    });
+    // Queued rows mean the agent is still working on the round they were
+    // written against — this load is a drain round, not a park.
+    return { ledger, roundNo, working: queued(ledger).length > 0, newRound, ctx };
+  }
+
+  // POST the queued backlog to the gate. A non-empty backlog resolves that run
+  // at once (drain round), so the rows flip to "sent". A failure (the command
+  // already exited) leaves them queued for the next run — nothing is dropped.
+  function flushBacklog(ledger) {
+    const pending = queued(ledger);
+    if (!pending.length) return Promise.resolve(false);
+    return doFetch(cfg.backlogEndpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ comments: pending.map(wire) }),
+    })
+      .then(function (r) {
+        return r.ok ? r.json() : null;
+      })
+      .then(function (data) {
+        if (!data || data.state !== "drained") return false;
+        pending.forEach(function (c) {
+          c.status = "sent";
+        });
+        saveLedger(ledger);
+        return true;
+      })
+      .catch(function () {
+        return false; // gate gone — the rows stay queued for the next run
+      });
+  }
+
+  // Where a row stands, for the ledger rail / sidebar chip.
+  function statusLabel(c) {
+    if (c.status === "queued") return "queued";
+    if (c.status === "addressed") {
+      return "addressed" + (c.addressedInRound ? " · round " + c.addressedInRound : "");
+    }
+    return cfg.roundInSentLabel ? "sent · round " + c.round : "sent";
+  }
+
+  // ---------- next-round attention ----------
+  // A background tab cannot steal focus (browser design), but it CAN fire a
+  // system notification whose click is allowed to focus it, and flag itself in
+  // the tab bar until it is looked at. The permission prompt only shows inside
+  // a user gesture, so it is requested at the send click; the "announce" wish
+  // survives the reload via sessionStorage (the reload wipes the JS context).
+  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");
+    }
+  }
+  function markRoundReadyAndReload() {
+    try {
+      store.setItem(ROUND_READY_FLAG, "1");
+    } catch {
+      /* storage blocked — the reload still lands, just without the announce */
+    }
+    location.reload();
+  }
+  // Always consumed at boot (a drain round must not leave the flag armed for a
+  // later parked load), but only ACTED on when this round parks.
+  function consumeRoundFlag() {
+    try {
+      const flagged = store.getItem(ROUND_READY_FLAG) === "1";
+      if (flagged) store.removeItem(ROUND_READY_FLAG);
+      return flagged;
+    } catch {
+      return false; // no storage — nothing to announce
+    }
+  }
+  function announceNewRound(flagged) {
+    if (!flagged) return;
+    try {
+      window.focus(); // best-effort; most browsers ignore it for background tabs
+    } catch {
+      /* ignore */
+    }
+    if (!document.hidden) return; // user is already looking at it
+    const origTitle = document.title;
+    const restoreTitle = function () {
+      document.title = origTitle;
+      document.removeEventListener("visibilitychange", onVis);
+      window.removeEventListener("focus", restoreTitle);
+    };
+    const onVis = function () {
+      if (!document.hidden) restoreTitle();
+    };
+    document.title = cfg.attentionTitle;
+    document.addEventListener("visibilitychange", onVis);
+    window.addEventListener("focus", restoreTitle);
+    try {
+      if (notifyPermission() === "granted") {
+        const n = new Notification(cfg.notifyTitle, {
+          body: cfg.notifyBody,
+          tag: "slidemind-" + name + "-round",
+        });
+        n.onclick = function () {
+          try {
+            window.focus();
+          } catch {
+            /* ignore */
+          }
+          n.close();
+        };
+      }
+    } catch {
+      /* notification construction can throw on some platforms — title stands */
+    }
+  }
+
+  // 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 and answers `action: "close"` here,
+  // which retires this tab rather than reloading it into a hidden duplicate.
+  function startNextRoundPolling(handlers) {
+    if (pollTimer) return; // one poll per page life (working mode can re-enter)
+    const startedAt = Date.now();
+    const ttl = cfg.pollTtlMs || 35 * 60 * 1000;
+    const hb = cfg.heartbeat;
+    const timer = setInterval(function () {
+      if (Date.now() - startedAt > ttl) {
+        clearInterval(timer);
+        pollTimer = null;
+        handlers.onEnded();
+        return;
+      }
+      const visible = document.visibilityState === "visible" ? "1" : "0";
+      const url =
+        hb +
+        (hb.indexOf("?") < 0 ? "?" : "&") +
+        "round=" +
+        encodeURIComponent(cfg.round || "") +
+        "&visible=" +
+        visible;
+      doFetch(url, { cache: "no-store" })
+        .then(function (r) {
+          return r.ok ? r.json() : null;
+        })
+        .then(function (data) {
+          // Act only on a genuine NEWER round of THIS gate: shape-guard the
+          // service marker (a foreign app may have taken the port) and require
+          // a different nonce (same nonce = this run's own orphan).
+          if (!data || data.service !== cfg.service || !data.round) return;
+          if (data.round === cfg.round) return;
+          if (data.action === "close") {
+            clearInterval(timer);
+            pollTimer = null;
+            handlers.onSuperseded();
+            return;
+          }
+          if (data.action === "wait") return; // grace window deciding — keep polling
+          clearInterval(timer);
+          pollTimer = null;
+          markRoundReadyAndReload();
+        })
+        .catch(function () {
+          /* server down between rounds — keep polling */
+        });
+    }, cfg.pollMs || 1000);
+    pollTimer = timer;
+  }
+
+  return {
+    LEDGER_KEY,
+    CTX_KEY,
+    ROUND_READY_FLAG,
+    wire,
+    read,
+    write,
+    saveLedger,
+    saveCtx,
+    saveCtxSoon,
+    queued,
+    restore,
+    flushBacklog,
+    statusLabel,
+    notifyPermission,
+    requestNotifyPermission,
+    markRoundReadyAndReload,
+    consumeRoundFlag,
+    announceNewRound,
+    startNextRoundPolling,
+  };
+}