@gavin-hu/my-pi-agent 0.20.0 → 0.22.0

package/extensions/plan/web-client.ts

@@ -19,7 +19,14 @@
  * saved back to the server.
  */
 
-import { CLIENT_RUNTIME_JS, dialogScript, keysDialogScript, THEME_TOGGLE_JS } from "../../lib/web/index.ts";
+import {
+	CLIENT_BASE_JS,
+	CLIENT_RUNTIME_JS,
+	dialogScript,
+	INLINE_MARKDOWN_JS,
+	keysDialogScript,
+	THEME_TOGGLE_JS,
+} from "../../lib/web/index.ts";
 import { WEB_CHROME_JS } from "./web-chrome.ts";
 import { WEB_COMMENTS_JS } from "./web-comments.ts";
 import { WEB_COLLAB_JS } from "./web-collab.ts";
@@ -34,6 +41,7 @@ import { WEB_SETTLE_JS } from "./web-settle.ts";
 
 export const REVIEW_CLIENT_JS = String.raw`(function () {
   "use strict";
+${CLIENT_BASE_JS}
 
   var dataNode = document.getElementById("review-data");
   // The caps come from the island, which takes them from the server's own
@@ -67,12 +75,19 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   var sectionObserver = null;
   var pendingQuote = null;
   var activeIndex = -1;
+  /** What the reader asked the plan to show: every block, the changed ones, or the annotated. */
+  var view = "all";
   var outlineItems = {};
   /** The island's blocks, or none: one place the client reads them for navigation. */
   function blocks() {
     return Array.isArray(data.blocks) ? data.blocks : [];
   }
 
+  /** The island's changed blocks, or none: the whole list is scanned, because it is short. */
+  function changedBlocks() {
+    return Array.isArray(data.changed) ? data.changed : [];
+  }
+
   /** The island's outline, or none: the one place the client reads it for the outline. */
   function outlineEntries() {
     return Array.isArray(data.outline) ? data.outline : [];
@@ -111,6 +126,8 @@ ${WEB_COMMENTS_JS}
 
 ${WEB_COLLAB_JS}
 
+${INLINE_MARKDOWN_JS}
+
 ${WEB_MARKDOWN_JS}
 
   // Review facts: the plan's step progress, and the comments per section.
@@ -132,6 +149,7 @@ ${WEB_MARKDOWN_JS}
       planEl: planEl,
       statusEl: statusEl,
       refusal: DRAFT_REFUSAL,
+      settled: function () { return saved || approved || closed; },
       setStatus: setStatus,
       saveDraft: saveDraft,
       open: openComposer,
@@ -159,11 +177,13 @@ ${WEB_MARKDOWN_JS}
       outlineList: outlineList,
       focused: document.activeElement,
       blocks: blocks,
+      changed: function (line) { return changedBlocks().indexOf(line) >= 0; },
       annotations: function () { return annotations; },
       activeIndex: function () { return activeIndex; },
       setActiveIndex: function (index) { activeIndex = index; },
       pendingQuote: function () { return pendingQuote; },
       clearPendingQuote: function () { pendingQuote = null; },
+      settled: function () { return saved || approved || closed; },
       composer: composer,
       renderBlock: renderBlockContent,
       renderComments: renderComments,
@@ -175,8 +195,72 @@ ${WEB_MARKDOWN_JS}
     };
   }
 
+  /**
+   * Apply the current view and say what it hides.
+   *
+   * The count goes on the status line rather than into the document: a filtered plan with
+   * no note reads as a shorter plan, and the count is the one fact that undoes that.
+   */
+  function syncView() {
+    var counts = applyView(planEl, view);
+    var buttons = document.querySelectorAll("[data-view]");
+    for (var i = 0; i < buttons.length; i++) {
+      var button = buttons[i];
+      var name = button.getAttribute("data-view");
+      button.setAttribute("aria-pressed", name === view ? "true" : "false");
+      // Nothing to compare against is not an empty view: the button says why it is off.
+      if (name === "changed") {
+        var comparable = data.blockMarks === true;
+        button.disabled = !comparable;
+        button.title = comparable ? "Only what this review changed" : "No earlier review of this plan to compare against";
+      }
+    }
+    // The page's own wrapper owns the element: the shared paint takes the node first, so
+    // the sentence goes through setStatus rather than being handed over as one. A settled
+    // review's status line carries how it ended, not the filter's count.
+    if (counts.hidden > 0 && !saved && !approved && !closed)
+      setStatus("Showing " + counts.shown + " of " + (counts.shown + counts.hidden) + " blocks — the rest hidden");
+  }
+
+  /**
+   * Walk from the active block to the next one that carries a comment.
+   *
+   * The block order is the document's, so "next" means further down the plan, not the next
+   * comment by arrival: a reader walking notes is reading the document. A filtered view can
+   * hide a commented block, and a hidden one is not a place to send the reader, so the step
+   * skips it the way the block walk does. Nothing repaints, so no draft is at risk.
+   */
+  function moveComment(delta) {
+    var list = blockElements(planEl);
+    var start = activeIndex >= 0 ? activeIndex : delta > 0 ? -1 : list.length;
+    for (var step = start + delta; step >= 0 && step < list.length; step += delta) {
+      var block = list[step];
+      if (!block || block.hidden === true) continue;
+      if ((block.className || "").split(" ").indexOf("bf-block--commented") < 0) continue;
+      var next = setActive(planEl, step);
+      if (next !== null) activeIndex = next;
+      if (block.scrollIntoView) block.scrollIntoView({ block: "center" });
+      return;
+    }
+  }
+
+  /**
+   * Cycle the panel's views, skipping the one this page cannot offer.
+   *
+   * The repaint closes the composer, so a half-written comment refuses first, the way the
+   * view buttons do.
+   */
+  function cycleView() {
+    if (confirmNoDraft()) return;
+    var order = data.blockMarks === true ? ["all", "changed", "comments"] : ["all", "comments"];
+    var at = order.indexOf(view);
+    view = order[(at + 1) % order.length] || "all";
+    renderAll();
+  }
+
   function renderAll() {
     sectionObserver = renderPlanFrame(planFrame(), closeOpenComposer, observeSections, sectionObserver);
+    syncView();
   }
 
   // Save, approve, and post share the same POST shape; what differs is whether
@@ -199,6 +283,7 @@ ${WEB_MARKDOWN_JS}
   function settlement() {
     return {
       token: function () { return token; },
+      base: pageBase,
       role: function () { return role; },
       mine: function () { return annotations.filter(isMine); },
       annotations: function () { return annotations; },
@@ -319,6 +404,8 @@ ${WEB_MARKDOWN_JS}
         var next = moveActive(planEl, activeIndex, delta);
         if (next !== null) activeIndex = next;
       },
+      moveComment: moveComment,
+      cycleView: cycleView,
       commentOnActive: function () { activeIndex = commentOnActive(composer(), activeIndex, blocks()); },
       askApprove: askApprove,
       save: save,
@@ -329,6 +416,19 @@ ${WEB_MARKDOWN_JS}
     };
   }
 
+  var viewButtons = document.querySelectorAll("[data-view]");
+  for (var v = 0; v < viewButtons.length; v++) {
+    viewButtons[v].addEventListener("click", function (event) {
+      var next = event.target && event.target.getAttribute ? event.target.getAttribute("data-view") : null;
+      if (next !== "all" && next !== "changed" && next !== "comments") return;
+      // The filter repaints the document, which closes the composer: a half-written
+      // comment would go with it, so the click refuses the way the ways off the page do.
+      if (confirmNoDraft()) return;
+      view = next;
+      renderAll();
+    });
+  }
+
   document.addEventListener("keydown", function (event) {
     handleKey(event, keyActions());
   });
@@ -344,7 +444,7 @@ ${WEB_MARKDOWN_JS}
   if (planEl) planEl.addEventListener("scroll", updateProgress);
 
   try {
-    stream = new EventSource("/events?token=" + encodeURIComponent(token));
+    stream = new EventSource(pageBase() + "/events?token=" + encodeURIComponent(token));
     stream.addEventListener("open", function () { connected = true; everConnected = true; updateState(); });
     stream.addEventListener("message", function (event) { refreshFromServer(event); });
     stream.addEventListener("error", function () {

package/extensions/plan/web-collab.ts

@@ -88,19 +88,19 @@ export const WEB_COLLAB_JS = String.raw`  /**
   }
 
   function shareNow() {
-    shareAction("/api/share", null, "Could not share: ");
+    shareAction(pageBase() + "/api/share", null, "Could not share: ");
   }
 
   function newLink() {
-    shareAction("/api/share/link", null, "Could not mint a link: ");
+    shareAction(pageBase() + "/api/share/link", null, "Could not mint a link: ");
   }
 
   function revokeLink(id) {
-    shareAction("/api/share/revoke", { id: id }, "Could not revoke that link: ");
+    shareAction(pageBase() + "/api/share/revoke", { id: id }, "Could not revoke that link: ");
   }
 
   function stopSharing() {
-    fetch("/api/share/stop?token=" + encodeURIComponent(token), { method: "POST" })
+    fetch(pageBase() + "/api/share/stop?token=" + encodeURIComponent(token), { method: "POST" })
       .then(function (response) { return response.json(); })
       .then(function (payload) {
         if (payload && payload.share) showShare(payload.share, null);

package/extensions/plan/web-comments.ts

@@ -19,6 +19,8 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
     var next = wrap.nextElementSibling;
     if (next && next.classList && next.classList.contains("bf-comments")) return next;
     var box = el("div", "bf-comments");
+    // The line it belongs to, so a filtered view can hide the thread with its block.
+    box.setAttribute("data-line", wrap.getAttribute("data-line") || "");
     wrap.insertAdjacentElement("afterend", box);
     return box;
   }
@@ -112,6 +114,10 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
   }
 
   function openComposer(wrap, block, quote, initial) {
+    // One composer at a time, and the open one holds text the page has not committed:
+    // replacing it would drop that text without a word. A restored draft passes its text
+    // as the initial value, because it is the thing being reopened, not a draft to protect.
+    if (!initial && guardDraft(planEl, statusEl, DRAFT_REFUSAL, paintStatus)) return;
     closeOpenComposer();
     wrap.classList.add("bf-block--composing");
     var composer = el("div", "bf-composer");
@@ -135,7 +141,9 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
     cancel.addEventListener("click", closeOpenComposer);
     var add = el("button"); add.type = "button"; add.className = "bf-btn bf-btn--primary"; add.textContent = "Add comment";
     var submit = function () {
-      if (closed) { setStatus("The review is closed; this comment was not added.", "error"); return; }
+      // A settled review takes no new comment: the note could never reach the plan, so
+      // adding it would report "Comment added" about something nobody will read.
+      if (saved || approved || closed) { setStatus("This review has ended; the comment was not added.", "error"); return; }
       if (role === "reviewer" && !reviewerName) { askName(); return; }
       var comment = area.value.replace(/\s+/g, " ").trim();
       if (!comment) { area.focus(); return; }
@@ -232,10 +240,12 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
   function renderCommentCards(box, list) {
     list.forEach(function (annotation) {
       var index = annotations.indexOf(annotation);
-      var card = el("div", "bf-comment");
+      var card = el("div", annotation.resolved ? "bf-comment bf-comment--resolved" : "bf-comment");
       var head = el("div", "bf-comment__head");
-      var label = el("span", annotation.author ? "bf-comment__label bf-comment__label--author" : "bf-comment__label");
-      label.textContent = annotation.author ? "@" + annotation.author : "Review";
+      // Every card names a person: "Review" was a category, and on a reviewer's page it
+      // could be anybody — including the reader.
+      var label = el("span", "bf-comment__label bf-comment__label--author");
+      label.textContent = annotation.author ? "@" + annotation.author : role === "owner" ? "You" : "The owner";
       head.appendChild(label);
       if (annotation.moved) {
         // A refinement carried this note off the text it was written on: the placement is
@@ -247,14 +257,31 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
           "Written on an earlier revision. The block it was on changed, so it sits here now: check it still refers to the text below.";
         head.appendChild(moved);
       }
+      if (annotation.resolved) {
+        // Settled notes keep their thread and their quote, and lose their body: the record
+        // stays, the reader's eye lands on what is still open.
+        var settled = el("span", "bf-comment__resolved");
+        settled.textContent = "\u2713 settled";
+        settled.title = "Settled: kept in the plan as the record of the question";
+        head.appendChild(settled);
+      }
       head.appendChild(el("span", "bf-comment__spacer"));
       if (isMine(annotation)) {
         var actions = el("div", "bf-comment__actions");
         var edit = el("button"); edit.type = "button"; edit.className = "bf-btn"; edit.textContent = "Edit";
         edit.addEventListener("click", function () { startEdit(card, index); });
+        var settle = el("button"); settle.type = "button"; settle.className = "bf-btn";
+        settle.textContent = annotation.resolved ? "Reopen" : "Resolve";
+        settle.addEventListener("click", function () {
+          if (annotation.resolved) delete annotation.resolved;
+          else annotation.resolved = true;
+          markDirty();
+          renderAll();
+          setStatus(annotation.resolved ? "Comment resolved." : "Comment reopened.");
+        });
         var remove = el("button"); remove.type = "button"; remove.className = "bf-btn"; remove.textContent = "Delete";
         remove.addEventListener("click", function () { removeComment(index); });
-        actions.appendChild(edit); actions.appendChild(remove); head.appendChild(actions);
+        actions.appendChild(settle); actions.appendChild(edit); actions.appendChild(remove); head.appendChild(actions);
       }
       card.appendChild(head);
       if (annotation.quote) {
@@ -262,9 +289,11 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
         quote.textContent = "\u201c" + annotation.quote + "\u201d";
         card.appendChild(quote);
       }
-      var body = el("div", "bf-comment__body");
-      body.textContent = annotation.comment;
-      card.appendChild(body);
+      if (!annotation.resolved) {
+        var body = el("div", "bf-comment__body");
+        body.textContent = annotation.comment;
+        card.appendChild(body);
+      }
       box.appendChild(card);
     });
   }
@@ -273,6 +302,8 @@ export const WEB_COMMENTS_JS = String.raw`  function selectionIn(wrap) {
     var mine = annotations.filter(function (annotation) { return annotation.anchor === anchor; });
     if (mine.length === 0) return;
     var box = el("div", "bf-comments");
+    // The block this thread hangs under, as a line: the view filter hides the two together.
+    box.setAttribute("data-line", String(anchor));
     renderCommentCards(box, mine);
     container.appendChild(box);
   }

package/extensions/plan/web-composer.ts

@@ -21,16 +21,22 @@ export interface ComposerDeps {
 	statusEl: ClientNode | null;
 	/** The sentence that names a half-written comment, so a stale one can be cleared. */
 	refusal: string;
+	/** Whether the review has ended, so a key opens no composer for it. */
+	settled?(): boolean;
 	setStatus(text: string, kind?: string): void;
 	saveDraft(): void;
 	open: OpenComposer;
 }
 
 /**
- * Close the composer, and let the stored draft follow it.
+ * Close the composer, and drop the text it was holding.
  *
- * A close with nothing open must not rewrite — and so drop — a draft a reload restored, so
- * the draft is saved only when a composer was actually there.
+ * A close is the reader's Cancel or Esc, or the commit that turned the text into a
+ * comment: either way the composer is not somewhere to resume from, so the draft does not
+ * keep it. What protects a half-written comment is the guards on the ways out — a repaint
+ * that would close a composer asks first (`guardDraft`), the view control included — not
+ * this function. A close with nothing open must not rewrite, and so drop, a draft a reload
+ * restored.
  */
 export function closeComposer(deps: ComposerDeps): void {
 	const open = deps.planEl ? deps.planEl.querySelector(".bf-composer") : null;
@@ -40,6 +46,8 @@ export function closeComposer(deps: ComposerDeps): void {
 	// The only status a composer leaves behind is the refusal to leave it; once the draft is
 	// gone that sentence is stale.
 	if (deps.statusEl && deps.statusEl.textContent === deps.refusal) deps.setStatus("");
+	// The composer is gone, so recomputing the draft now is what forgets the text it held —
+	// a close is not a pause — while the comments this writer added stay in it.
 	if (open) deps.saveDraft();
 }
 
@@ -67,6 +75,9 @@ export function reopenComposer(
  * navigation, and the block the reader lands on is the block they are commenting on.
  */
 export function commentOnActive(deps: ComposerDeps, activeIndex: number, blocks: readonly IslandBlock[]): number {
+	// A settled review takes no new comment, so the key opens nothing rather than a
+	// composer whose note could never be saved.
+	if (deps.settled?.() === true) return activeIndex;
 	if (blockElements(deps.planEl).length === 0) return activeIndex;
 	const index = activeIndex < 0 ? (setActive(deps.planEl, 0) ?? activeIndex) : activeIndex;
 	const wrap = blockElements(deps.planEl)[Math.max(0, index)];

package/extensions/plan/web-keys.ts

@@ -17,6 +17,7 @@
  */
 
 import type { ClientNode } from "../../lib/web/client-runtime.ts";
+import type { ReviewRole } from "./types.ts";
 
 /** What a key may do: one callback per action the page owns. */
 export interface KeyDeps {
@@ -30,6 +31,10 @@ export interface KeyDeps {
 	toggleSheet(): void;
 	/** Walk the blocks by one, in the direction the key names. */
 	moveActive(delta: number): void;
+	/** Walk the blocks that carry a comment, in the direction the key names. */
+	moveComment?(delta: number): void;
+	/** Cycle what the page shows: everything, the changes, the comments. */
+	cycleView?(): void;
 	/** Comment on the block the keyboard is on. */
 	commentOnActive(): void;
 	/** Approve, through its confirmation; and the two writes `s` can stand for. */
@@ -53,11 +58,142 @@ export interface KeyEvent {
 	preventDefault(): void;
 }
 
+/** What the page offers, for the rows whose sentence or availability depends on it. */
+export interface KeySurface {
+	/** Whose page it is: the owner saves and closes, a reviewer posts. */
+	role: ReviewRole;
+	/** Whether this review may approve the plan. */
+	canApprove: boolean;
+	/** Whether the page wired the comment walk (`n`/`N`), so the sheet may name it. */
+	hasCommentWalk: boolean;
+	/** Whether the page wired the view cycle (`v`). */
+	hasViewCycle: boolean;
+}
+
+/**
+ * One key the page answers and documents.
+ *
+ * The bindings, the shortcut sheet and the sidebar hint all read this table, because
+ * three hand-kept lists of the same keys is how a sheet comes to name a key the page no
+ * longer answers. The two layer keys — `Esc` and `?` — carry no `run`: they are handled
+ * before the table, because they work while a composer or the sheet owns the keyboard,
+ * and they are listed so the sheet documents them with the rest.
+ */
+export interface WebKey {
+	/** Stable id: the sheet's order, and what a test names. */
+	id: "approve" | "blocks" | "comments" | "comment" | "add" | "view" | "settle" | "close" | "sheet";
+	/** The keys as the sheet prints them; the same strings the handler matches. */
+	keys: readonly string[];
+	/** The sheet's sentence on this page. */
+	label(surface: KeySurface): string;
+	/** The words the sidebar hint adds after the key, if it names the key at all. */
+	hint?(surface: KeySurface): string;
+	/** Whether the page offers it; a key nobody can press is not documented. */
+	offered?(surface: KeySurface): boolean;
+	/** What the key does, for the keys this handler owns; `key` is which binding fired. */
+	run?(deps: KeyDeps, key: string): void;
+}
+
+/**
+ * The page's keys, in the order the sheet lists them.
+ *
+ * A function rather than a constant because the bundle carries it the way it carries
+ * every other rule here: `String()` of a body. A table spliced from data would lose the
+ * closures on `label`, `hint`, `offered`, and `run`, and a table the bundle does not
+ * carry is a keymap that throws on the first press.
+ */
+export function webKeys(): readonly WebKey[] {
+	return [
+		{
+			id: "approve",
+			keys: ["a"],
+			offered: (surface) => surface.canApprove,
+			label: () => "Approve and run the plan",
+			hint: () => "to approve",
+			run: (deps) => deps.askApprove(),
+		},
+		{
+			id: "blocks",
+			keys: ["j", "k"],
+			label: () => "Next and previous block",
+			hint: () => "to move",
+			// The block keys share a row: `j` walks forward, `k` back.
+			run: (deps, key) => deps.moveActive(key === "k" ? -1 : 1),
+		},
+		{
+			id: "comments",
+			keys: ["n", "N"],
+			// Offered only when the page wired the walk: a documented key that does nothing is
+			// worse than a key the sheet leaves out. No `hint`: the sidebar line names what a
+			// reader reaches for first and leaves the rest to the sheet, or it grows forever.
+			offered: (surface) => surface.hasCommentWalk,
+			label: () => "Next and previous block with a comment",
+			run: (deps, key) => deps.moveComment?.(key === "N" ? -1 : 1),
+		},
+		{
+			id: "comment",
+			keys: ["c"],
+			label: () => "Comment on the current block",
+			hint: () => "to comment",
+			run: (deps) => deps.commentOnActive(),
+		},
+		{
+			id: "add",
+			keys: ["Enter"],
+			label: () => "Add the comment you are writing",
+		},
+		{
+			id: "view",
+			keys: ["v"],
+			offered: (surface) => surface.hasViewCycle,
+			label: () => "Show everything, what changed, or the comments",
+			run: (deps) => deps.cycleView?.(),
+		},
+		{
+			id: "settle",
+			keys: ["s"],
+			label: (surface) =>
+				surface.role === "owner" ? "Save feedback and return to Pi" : "Post your comments to the plan",
+			hint: (surface) => (surface.role === "owner" ? "to save" : "to post"),
+			run: (deps) => (deps.hasSaveControl() ? deps.save() : deps.postComments()),
+		},
+		{
+			id: "close",
+			keys: ["Esc"],
+			label: (surface) =>
+				surface.role === "owner" ? "Close the composer, the sheet, or the review" : "Close the composer or this sheet",
+		},
+		{
+			id: "sheet",
+			keys: ["?"],
+			label: () => "Toggle this sheet",
+			hint: () => "for all shortcuts",
+		},
+	];
+}
+
+/** The rows this page offers, in sheet order. */
+export function keyRows(surface: KeySurface): WebKey[] {
+	return webKeys().filter((row) => row.offered === undefined || row.offered(surface));
+}
+
+/** The surface a handler sees, read off the callbacks and controls it was given. */
+function surfaceOf(deps: KeyDeps): KeySurface {
+	return {
+		role: deps.hasSaveControl() ? "owner" : "reviewer",
+		canApprove: deps.hasApproveControl(),
+		hasCommentWalk: deps.moveComment !== undefined,
+		hasViewCycle: deps.cycleView !== undefined,
+	};
+}
+
 /**
  * Handle one keydown.
  *
  * A modified key is never a shortcut: `ctrl+s` belongs to the browser. A field owns the
- * keyboard while it has focus, and so does the shortcut sheet while it is open.
+ * keyboard while it has focus, and so does the shortcut sheet while it is open. The
+ * content keys come from {@link webKeys}, so the key that acts and the key the sheet
+ * documents cannot part company.
  */
 export function handleKey(event: KeyEvent, deps: KeyDeps): void {
 	if (event.key === "Escape") {
@@ -78,31 +214,13 @@ export function handleKey(event: KeyEvent, deps: KeyDeps): void {
 	}
 	// While the shortcut sheet is open it owns the keyboard.
 	if (deps.sheetOpen()) return;
-	if (event.key === "j") {
-		event.preventDefault();
-		deps.moveActive(1);
-		return;
-	}
-	if (event.key === "k") {
+	const surface = surfaceOf(deps);
+	for (const row of keyRows(surface)) {
+		if (row.run === undefined || !row.keys.includes(event.key)) continue;
 		event.preventDefault();
-		deps.moveActive(-1);
+		row.run(deps, event.key);
 		return;
 	}
-	if (event.key === "c") {
-		event.preventDefault();
-		deps.commentOnActive();
-		return;
-	}
-	if (event.key === "a" && deps.hasApproveControl()) {
-		event.preventDefault();
-		deps.askApprove();
-		return;
-	}
-	if (event.key === "s") {
-		event.preventDefault();
-		if (deps.hasSaveControl()) deps.save();
-		else deps.postComments();
-	}
 }
 
 /** What remembering a selection reads, and where it puts it. */
@@ -130,5 +248,11 @@ export function rememberSelection(target: unknown, deps: QuoteDeps): void {
 	deps.setPending(wrap && quote ? { wrap, quote } : null);
 }
 
-/** The keymap and the quote rule as source, for the client bundle. */
-export const WEB_KEYS_JS = [handleKey, rememberSelection].map(String).join("\n\n");
+/**
+ * The keymap and the quote rule as source, for the client bundle.
+ *
+ * Every name `handleKey` reads has to travel with it — the table, the rows it offers,
+ * and the surface those rows are offered for — or the first press throws instead of
+ * matching a row.
+ */
+export const WEB_KEYS_JS = [handleKey, surfaceOf, keyRows, webKeys, rememberSelection].map(String).join("\n\n");

package/extensions/plan/web-lazy.ts

@@ -0,0 +1,53 @@
+/**
+ * The plan review server, loaded when a review first asks for it.
+ *
+ * The browser review owns `lib/http`, the web kit, and the plan page; none of it
+ * is needed to register `/plan` or the plan tools. `index.ts`, `commands.ts`, and
+ * `tools.ts` therefore share this proxy over `lib/lazy`: the first review loads
+ * `web.ts` once, and `closeAll` on shutdown only closes a review that was already
+ * opened, so a session that never reviewed a plan imports none of the server.
+ *
+ * The synchronous reads (`current`, `shareState`) answer `undefined` until the
+ * module is loaded, which is the truth: no review can be open before a load.
+ */
+
+import { lazy } from "../../lib/lazy.ts";
+import type { PlanStore } from "./plans.ts";
+import type { PlanWebReview, PlanWebReviewDeps } from "./web.ts";
+
+/** The review module, as the proxy loads it. */
+export type PlanWebModule = typeof import("./web.ts");
+
+/** How the proxy reaches the review module; production uses the dynamic import. */
+export type PlanWebLoader = () => Promise<PlanWebModule>;
+
+/**
+ * The deps a caller that injects its own review leaves out.
+ *
+ * A review needs a place on the session's server, so a caller with no wiring says so
+ * rather than binding a socket of its own: the start is refused with a sentence.
+ */
+export const NO_SERVER_DEPS: PlanWebReviewDeps = {
+	mount: async () => ({ kind: "refused", reason: "this review has no server wired" }),
+	session: () => "",
+};
+
+export function createLazyPlanWebReview(
+	store: PlanStore,
+	deps: PlanWebReviewDeps,
+	load: PlanWebLoader = () => import("./web.ts"),
+): PlanWebReview {
+	const review = lazy(async () => (await load()).createPlanWebReview(store, deps));
+	return {
+		start: async (cwd, plan, options) => (await review.get()).start(cwd, plan, options),
+		current: () => review.peek()?.current(),
+		share: async () => (await review.get()).share(),
+		stopSharing: async () => (await review.get()).stopSharing(),
+		shareState: () => review.peek()?.shareState(),
+		// Shutdown must not start a load: a review that never opened has nothing to close.
+		closeAll: async () => {
+			const opened = review.peek();
+			if (opened !== undefined) await opened.closeAll();
+		},
+	};
+}