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

package/extensions/plan/web-markdown.ts

@@ -1,76 +1,18 @@
 /**
- * The Markdown half of the review client script.
+ * The block half of the plan review's Markdown: tables, fenced code, headings, quotes,
+ * and lists.
  *
  * It is a fragment of the same IIFE `web-client.ts` ships (`WEB_MARKDOWN_JS` is
  * interpolated into `REVIEW_CLIENT_JS`), kept in its own module so the client's
- * event wiring and its document rendering are read one at a time. Every value it
- * writes is a DOM text node: plan and comment text never becomes markup, and the
- * only HTML it copies is the server's own `tok-*` spans.
+ * event wiring and its document rendering are read one at a time. The text inside a
+ * block is rendered by `renderInline`, which crosses from `lib/web/markdown.ts` with
+ * the board's card notes — one inline grammar and one link policy for both pages.
+ *
+ * Every value it writes is a DOM text node: plan and comment text never becomes markup,
+ * and the only HTML it copies is the server's own `tok-*` spans.
  */
 
-export const WEB_MARKDOWN_JS = String.raw`  // A link is rendered only for an http(s) or mailto target. Resolving against
-  // the review origin is what catches a target that only looks relative: the
-  // URL parser strips a tab or newline, so "/\t/evil.com" is cross-origin once
-  // it is parsed, and a disguised target must stay text.
-  function safeHref(url, base) {
-    var trimmed = String(url).trim();
-    if (!trimmed || /^\/\//.test(trimmed)) return null;
-    var resolved;
-    try { resolved = new URL(trimmed, base); } catch (error) { return null; }
-    if (resolved.protocol === "mailto:") return trimmed;
-    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") return null;
-    if (resolved.username || resolved.password) return null;
-    if (resolved.origin === new URL(base).origin) return resolved.href;
-    return /^https?:\/\//i.test(trimmed) ? resolved.href : null;
-  }
-
-  // Inline token order matters: code, emphasis, and links are matched before a
-  // bare URL, so a URL inside a link target or a code span is never re-split.
-  var INLINE = /(\x60[^\x60]+\x60|\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)]+\)|(?:https?:\/\/|www\.)[^\s<]+)/g;
-
-  function renderInline(container, text) {
-    String(text).split(INLINE).forEach(function (part) {
-      if (!part) return;
-      var match;
-      if ((match = /^\x60([^\x60]+)\x60$/.exec(part))) {
-        var code = el("code"); code.textContent = match[1]; container.appendChild(code); return;
-      }
-      if ((match = /^\*\*([^*]+)\*\*$/.exec(part))) {
-        var strong = el("strong"); strong.textContent = match[1]; container.appendChild(strong); return;
-      }
-      if ((match = /^\*([^*]+)\*$/.exec(part))) {
-        var em = el("em"); em.textContent = match[1]; container.appendChild(em); return;
-      }
-      if ((match = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(part))) {
-        var href = safeHref(match[2], location.href);
-        if (!href) { container.appendChild(document.createTextNode(part)); return; }
-        var link = el("a"); link.textContent = match[1]; link.href = href; link.target = "_blank"; link.rel = "noreferrer noopener";
-        container.appendChild(link); return;
-      }
-      // GFM extended autolink: a bare http(s) or www. URL in running text.
-      if ((match = /^(?:https?:\/\/|www\.)[^\s<]+$/.exec(part))) {
-        var url = match[0].replace(/[.,;:!?*_~]+$/, "");
-        while (url.charAt(url.length - 1) === ")" && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
-          url = url.slice(0, -1).replace(/[.,;:!?*_~]+$/, "");
-        }
-        var dot = url.indexOf(".");
-        var target = /^www\./i.test(url) ? "http://" + url : url;
-        var safe = dot > 0 && /\.[^./]/.test(url.slice(dot)) ? safeHref(target, location.href) : null;
-        if (safe) {
-          var auto = el("a");
-          auto.textContent = url;
-          auto.href = safe;
-          auto.target = "_blank";
-          auto.rel = "noreferrer noopener";
-          container.appendChild(auto);
-          return;
-        }
-      }
-      container.appendChild(document.createTextNode(part));
-    });
-  }
-
-  // Copy only text and tok-* spans out of server-highlighted HTML, so a code
+export const WEB_MARKDOWN_JS = String.raw`  // Copy only text and tok-* spans out of server-highlighted HTML, so a code
   // line can never introduce markup even though it arrives as a string.
   function copyTokens(from, to) {
     Array.prototype.forEach.call(from.childNodes, function (node) {
@@ -199,7 +141,7 @@ export const WEB_MARKDOWN_JS = String.raw`  // A link is rendered only for an ht
         var markerText = match[2];
         var rest = match[3];
         var box = /^\[([ xX])\]\s*(.*)$/.exec(rest);
-        var marker = el("span", "marker");
+        var marker = el("span", "bf-block__marker");
         if (box) {
           var done = box[1].toLowerCase() === "x";
           markerText = done ? "\u2713" : "\u2610";

package/extensions/plan/web-outline.ts

@@ -23,6 +23,8 @@ export interface OutlineEntry {
 	line: number;
 	text: string;
 	changed?: boolean;
+	/** Content blocks this section no longer holds, when the baseline can say so. */
+	removed?: number;
 }
 
 /** What the browser's `IntersectionObserver` answers for a section watcher. */
@@ -73,6 +75,14 @@ export function renderOutline(list: ClientNode | null, entries: readonly Outline
 			dot.title = "Changed since your last review";
 			link.appendChild(dot);
 		}
+		if (item.removed !== undefined && item.removed > 0) {
+			// A block that left cannot be drawn where it was, so the count is the fact the
+			// page can still give: how much shorter this section has become.
+			link.title =
+				item.removed === 1
+					? "1 block removed since your last review"
+					: item.removed + " blocks removed since your last review";
+		}
 		const count = el("span", "review-nav__count");
 		count.hidden = true;
 		link.appendChild(count);
@@ -137,6 +147,8 @@ export function observeSections(
 /** One review comment, as the facts need it: the line it is anchored to. */
 export interface AnchoredComment {
 	anchor: number;
+	/** A settled note counts in the section's thread but not among the open ones. */
+	resolved?: true;
 }
 
 /** What a plan's step list says: the numbers the server counted. */
@@ -170,9 +182,17 @@ export function renderFacts(
 	const fill = doc.getElementById("step-fill");
 	if (fill) fill.style.width = (steps.total > 0 ? Math.round((steps.done / steps.total) * 100) : 0) + "%";
 	const count = doc.getElementById("step-count");
-	if (count) count.textContent = steps.done + "/" + steps.total;
+	// Named for what it counts: before approval these ticks are the plan's ambition, not
+	// work done, and after it completion belongs to `todo`.
+	if (count) count.textContent = steps.total === 0 ? "" : steps.done + "/" + steps.total + " ticked";
 	const total = doc.getElementById("comment-total");
-	if (total) total.textContent = String(comments.length);
+	if (total) {
+		// Open first, because a settled note is history: "3 open · 2 resolved" says what is
+		// left to answer, and the resolved half stays because the file keeps it.
+		const settled = comments.filter((comment) => comment.resolved === true).length;
+		const open = comments.length - settled;
+		total.textContent = settled === 0 ? String(open) : open + " open · " + settled + " resolved";
+	}
 	for (const line of Object.keys(counters)) {
 		const node = counters[Number(line)];
 		if (node) node.hidden = true;

package/extensions/plan/web-page.ts

@@ -14,6 +14,7 @@
  */
 
 import {
+	baseAttribute,
 	brandLockup,
 	docHead,
 	type KeyHint,
@@ -26,69 +27,14 @@ import {
 	WEB_LAYOUT_CSS,
 	WEB_THEME_CSS,
 } from "../../lib/web/index.ts";
-import type { PlanBlock } from "./blocks.ts";
-import type { PlanAnnotation } from "./feedback.ts";
+import { keyRows, type KeySurface } from "./web-keys.ts";
 import type { ReviewRole } from "./types.ts";
-import type { ShareState } from "./web-share.ts";
+import type { ReviewPageData } from "./web-payload.ts";
 
-/** A heading the outline can jump to. */
-export interface ReviewOutlineItem {
-	/** DOM id the client gives the heading. */
-	id: string;
-	/** 0-based source line. */
-	line: number;
-	/** Heading level, 1-6. */
-	level: number;
-	/** Heading text. */
-	text: string;
-	/** True when this section changed since the previous review of the plan. */
-	changed?: boolean;
-}
-
-/** Everything the browser needs to render one plan review. */
-export interface ReviewPageData {
-	/** Plan title: the document's H1, or the file-name slug when it has none. */
-	title: string;
-	/** Source-line blocks of the feedback-stripped plan. */
-	blocks: PlanBlock[];
-	/** Feedback already stored in the file. */
-	annotations: PlanAnnotation[];
-	/** Section outline, in document order. */
-	outline: ReviewOutlineItem[];
-	/**
-	 * The plan's step progress, from the same `extractPlanSteps` the approval and
-	 * `set_plan_steps` use: the `Steps` section when there is one, so the page
-	 * agrees with what approval seeds rather than counting every checkbox.
-	 */
-	steps: { done: number; total: number };
-	/** Highlighted HTML per line, keyed by the code block's 0-based start line. */
-	code: Record<string, string[]>;
-	/**
-	 * The caps the server enforces, so the page does not retype them: comment
-	 * count, comment length, and quote length, from `feedback.ts`.
-	 */
-	limits: { comments: number; comment: number; quote: number };
-	/** Whether the review may approve the plan (only the `exit_plan_mode` flow). */
-	canApprove: boolean;
-	/** Who is looking: `owner` may approve, `reviewer` may only comment. */
-	role: ReviewRole;
-	/**
-	 * The name a reviewer's link posts under, once it has been bound. Absent for the
-	 * owner and for a reviewer that has not written yet, which is what tells the page
-	 * whether its name control is still a choice.
-	 */
-	author?: string;
-	/** A running share, so a reload re-renders the link the owner already minted. */
-	share?: ShareState;
-	/** Per-session secret the client echoes on every request. */
-	token: string;
-	/**
-	 * A short digest of the plan text the page rendered. It keys the unsaved draft a
-	 * tab keeps for itself, so a reload restores the comments this writer has not
-	 * saved yet, and a plan that changed underneath drops them instead.
-	 */
-	rev: string;
-}
+// The island's two types live with the code that builds it (`web-payload.ts`); they are
+// re-exported here because a page's data and the page's markup are read from the same
+// imports in every caller, and two declarations of one island is how its halves drift.
+export type { ReviewOutlineItem, ReviewPageData } from "./web-payload.ts";
 
 /** Page styles: the shared base + theme + shell + components, then the review. */
 export const REVIEW_CSS = `${WEB_BASE_CSS}
@@ -117,16 +63,24 @@ ${WEB_COMPONENTS_CSS}
 .review-status{flex:0 0 auto;max-width:42ch;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
 .review-status:empty{display:none}
 .review-controls{display:inline-flex;align-items:center;gap:var(--space-2);flex:0 0 auto}
+.review-caption{margin:0;color:var(--muted);font-size:var(--fs-xs);line-height:var(--lh-snug)}
 .review-progress{position:absolute;left:0;right:0;bottom:-1px;height:2px;overflow:hidden}
 .review-progress__fill{display:block;height:100%;width:0;background:var(--accent);transition:width var(--motion-fast) linear}
 /* Review panel: the plan's review facts, the section outline, then the keys. */
 .bf-app__body--single{grid-template-columns:minmax(0,1fr)}
 .review-panel{display:flex;flex-direction:column;gap:var(--space-3);padding:var(--space-4) var(--space-4) var(--space-2)}
 .review-facts{display:flex;flex-direction:column;gap:var(--space-2);padding-bottom:var(--space-3);border-bottom:1px solid var(--border)}
-.review-fact{display:flex;align-items:center;justify-content:space-between;gap:var(--space-3);font-size:var(--fs-sm);color:var(--muted)}
+.review-fact{display:flex;flex-wrap:wrap;align-items:center;justify-content:space-between;gap:var(--space-3);font-size:var(--fs-sm);color:var(--muted)}
+/* The label is one word or two, never a column: squeezed by the value beside it, it broke
+   "Plan steps" over two lines. It holds its line, and the value wraps below instead. */
+.review-fact>span:first-child{white-space:nowrap}
 .review-fact .bf-progress{color:var(--text)}
 .review-fact .bf-progress__track{width:96px}
 .review-fact__value{color:var(--text);font-family:var(--font-mono);font-variant-numeric:tabular-nums}
+.review-view{display:flex;gap:2px;padding:2px;border:1px solid var(--border);border-radius:var(--radius-md)}
+.review-view .bf-btn{flex:1 1 auto;justify-content:center;padding:3px 8px;font-size:var(--fs-xs);border:0;background:none}
+.review-view .bf-btn[aria-pressed="true"]{background:var(--accent-soft);color:var(--accent);font-weight:var(--fw-semibold)}
+.review-view .bf-btn:disabled{opacity:.5;cursor:default}
 .review-nav{min-width:0}
 .review-nav__title{margin:0;font:var(--fw-semibold) var(--fs-xs) var(--font-mono);color:var(--muted);text-transform:uppercase;letter-spacing:.06em}
 .review-nav ul{list-style:none;margin:0;padding:0}
@@ -149,6 +103,10 @@ ${WEB_COMPONENTS_CSS}
 .bf-block__add:hover{border-color:var(--accent);color:var(--accent)}
 .bf-block:hover .bf-block__add,.bf-block:focus-within .bf-block__add,.bf-block--active .bf-block__add,.bf-block--commented .bf-block__add{opacity:1}
 .bf-block__count{display:inline-flex;align-items:center;justify-content:center;min-width:20px;height:20px;padding:0 5px;border-radius:var(--radius-pill);background:var(--accent-soft);color:var(--accent);font:var(--fw-semibold) var(--fs-xs)/1 var(--font-mono)}
+/* A block the last review did not hold: the one mark that says "read this line again". The
+   rule sits at the text edge, inside the gutter the rail already reserves, so it cannot
+   reflow the measure or collide with a comment badge. */
+.bf-block[data-changed]{box-shadow:inset 2px 0 0 var(--accent)}
 .bf-block:hover,.bf-block--active{background:var(--surface)}
 .bf-block--active{box-shadow:inset 0 0 0 1px var(--border)}
 .bf-block h1,.bf-block h2,.bf-block h3,.bf-block h4,.bf-block h5,.bf-block h6{margin:24px 0 8px;line-height:var(--lh-tight)}
@@ -183,6 +141,9 @@ ${WEB_COMPONENTS_CSS}
 /* A note a refinement carried off its own block: muted, because the complaint is the guess, not the text. */
 .bf-comment__moved{font:var(--fw-medium) var(--fs-xs) var(--font-mono);color:var(--muted);text-transform:uppercase;letter-spacing:.06em;border:1px solid var(--border);border-radius:var(--radius-sm);padding:0 6px}
 .bf-comment__spacer{flex:1 1 auto}
+/* A settled note keeps its quote and loses its body: the record stays, the eye moves on. */
+.bf-comment--resolved{border-left-color:var(--success);opacity:.72}
+.bf-comment__resolved{font:var(--fw-medium) var(--fs-xs) var(--font-mono);color:var(--success);text-transform:uppercase;letter-spacing:.06em}
 .bf-comment__actions{display:flex;gap:4px}
 .bf-comment__actions .bf-btn{padding:1px 8px;font-size:var(--fs-xs)}
 .bf-comment__quote{margin-bottom:6px;padding-left:8px;border-left:2px solid var(--border);color:var(--muted);font-size:var(--fs-sm);overflow-wrap:anywhere}
@@ -225,7 +186,12 @@ ${WEB_COMPONENTS_CSS}
 @media print{
 .bf-review{padding:0}
 .bf-review>.bf-block{max-width:none;padding:0 0 6px}
-.bf-block__rail,.bf-composer,.bf-block__add,.review-progress{display:none}
+.bf-block__rail,.bf-composer,.bf-block__add,.review-progress,.review-view{display:none}
+/* A printed review is the whole plan, never the view the reader had on screen: the
+   base layer's hidden rule is !important, so the un-hide has to be too, and a thread
+   the filter hid on screen goes back under its block. */
+.bf-block[hidden]{display:block!important}
+.bf-comments[hidden]{display:flex!important}
 .bf-block:hover,.bf-block--active{background:none;box-shadow:none}
 .bf-comments{padding-left:0}
 .bf-comment{break-inside:avoid}
@@ -237,28 +203,19 @@ ${WEB_COMPONENTS_CSS}
  * not have to grow every time a binding is added.
  */
 function reviewHints(role: ReviewRole, canApprove: boolean): string {
-	const approve = canApprove ? `, <kbd class="bf-kbd">a</kbd> to approve` : "";
-	const save = role === "owner" ? "save" : "post";
-	return `<p class="review-hints">Press <kbd class="bf-kbd">j</kbd>/<kbd class="bf-kbd">k</kbd> to move, <kbd class="bf-kbd">c</kbd> to comment${approve}, <kbd class="bf-kbd">s</kbd> to ${save}, <kbd class="bf-kbd">?</kbd> for all shortcuts.</p>`;
+	const surface: KeySurface = { role, canApprove, hasCommentWalk: true, hasViewCycle: true };
+	const parts = keyRows(surface)
+		.filter((row) => row.hint !== undefined)
+		.map(
+			(row) => `${row.keys.map((key) => `<kbd class="bf-kbd">${key}</kbd>`).join("/")} ${row.hint?.(surface) ?? ""}`,
+		);
+	return `<p class="review-hints">Press ${parts.join(", ")}.</p>`;
 }
 
-/** The shortcut sheet's rows: the review's own keys, led by approve when offered. */
+/** The shortcut sheet's rows: the same table the handler dispatches through. */
 function reviewKeys(role: ReviewRole, canApprove: boolean): KeyHint[] {
-	const rows: KeyHint[] = [];
-	if (canApprove) rows.push({ keys: "a", label: "Approve and run the plan" });
-	rows.push(
-		{ keys: ["j", "k"], label: "Next and previous block" },
-		{ keys: "c", label: "Comment on the current block" },
-		{ keys: "Enter", label: "Add the comment you are writing" },
-		role === "owner"
-			? { keys: "s", label: "Save feedback and return to Pi" }
-			: { keys: "s", label: "Post your comments to the plan" },
-		role === "owner"
-			? { keys: "Esc", label: "Close the composer, the sheet, or the review" }
-			: { keys: "Esc", label: "Close the composer or this sheet" },
-		{ keys: "?", label: "Toggle this sheet" },
-	);
-	return rows;
+	const surface: KeySurface = { role, canApprove, hasCommentWalk: true, hasViewCycle: true };
+	return keyRows(surface).map((row) => ({ keys: [...row.keys], label: row.label(surface) }));
 }
 
 /**
@@ -311,13 +268,26 @@ function nameDialog(): string {
  */
 export function renderReviewPage(data: ReviewPageData): string {
 	const island = JSON.stringify(data).replace(/</g, "\\u003c");
+	// One sentence saying what the two decisions do, because the buttons are the same weight
+	// and the difference was only ever in the docs. It sits in the panel, not the sticky
+	// header: a taller header would hide the section an outline link just jumped to.
+	const caption =
+		data.role === "owner"
+			? "Approving runs the plan and returns these comments; saving keeps planning."
+			: "Your comments are signed with your name and returned to the plan.";
 	const hasOutline = data.outline.length > 0;
 	const bodyClass = hasOutline ? "bf-app__body" : "bf-app__body bf-app__body--single";
 	const outlinePanel = hasOutline
 		? `<details class="bf-app__sidebar review-outline" open>
 <summary class="bf-panel__summary">Sections</summary>
 <div class="bf-panel review-panel">
+<p class="review-caption">${caption}</p>
 ${reviewFacts()}
+<div class="review-view" role="group" aria-label="What to show" id="review-view">
+<button type="button" class="bf-btn" data-view="all" aria-pressed="true">All</button>
+<button type="button" class="bf-btn" data-view="changed" aria-pressed="false">Changed</button>
+<button type="button" class="bf-btn" data-view="comments" aria-pressed="false">Comments</button>
+</div>
 <nav class="review-nav" aria-labelledby="outline-title"><p class="review-nav__title" id="outline-title">Sections</p><ul id="outline-list"></ul></nav>
 ${reviewHints(data.role, data.canApprove)}
 </div>
@@ -342,9 +312,9 @@ ${reviewHints(data.role, data.canApprove)}
 		? `<button type="button" class="bf-btn" id="share">Share</button>`
 		: `<button type="button" class="bf-btn" id="reviewer-name" hidden></button>`;
 	return `<!doctype html>
-<html lang="en">
+<html lang="en"${baseAttribute(data.base)}>
 <head>
-${docHead({ title: tabTitle("plan review", data.title), css: REVIEW_CSS })}
+${docHead({ title: tabTitle("plan review", data.title), css: REVIEW_CSS, base: data.base })}
 </head>
 <body class="bf-app">
 <a class="skip" href="#plan">Skip to the plan</a>
@@ -367,7 +337,7 @@ ${keysSheet(reviewKeys(data.role, data.canApprove))}
 ${data.canApprove ? approveDialog() : ""}
 ${data.role === "owner" ? shareDialog() : nameDialog()}
 <script type="application/json" id="review-data">${island}</script>
-<script src="/client.js" defer></script>
+<script src="${data.base}/client.js" defer></script>
 </body>
 </html>
 `;
@@ -379,7 +349,7 @@ ${data.role === "owner" ? shareDialog() : nameDialog()}
  */
 function reviewFacts(): string {
 	return `<div class="review-facts" id="review-facts">
-<div class="review-fact" id="step-fact"><span>Steps</span><span class="bf-progress"><span class="bf-progress__track"><span class="bf-progress__fill" id="step-fill"></span></span><span class="review-fact__value" id="step-count">0/0</span></span></div>
+<div class="review-fact" id="step-fact"><span>Plan steps</span><span class="bf-progress"><span class="bf-progress__track"><span class="bf-progress__fill" id="step-fill"></span></span><span class="review-fact__value" id="step-count">0/0</span></span></div>
 <div class="review-fact"><span>Comments</span><span class="review-fact__value" id="comment-total">0</span></div>
 </div>`;
 }

package/extensions/plan/web-payload.ts

@@ -0,0 +1,188 @@
+/**
+ * The review page's island: every fact the browser renders, built from one read of the
+ * plan.
+ *
+ * The page's markup is `web-page.ts` and its lifetime is `web.ts`; this module is the
+ * data between them, so a fact the page grows — a per-block change mark, a count, a
+ * flag — is added here and in one client module rather than inside the server's start
+ * closure. Everything below is pure: the plan text, the baseline, and who is asking come
+ * in, the island goes out.
+ */
+
+import { basename } from "node:path";
+import { fenceLanguage, highlightLines } from "../../lib/highlight.ts";
+import { codeBody, fenceInfo, type PlanBlock } from "./blocks.ts";
+import {
+	MAX_ANNOTATIONS,
+	MAX_COMMENT_LENGTH,
+	MAX_QUOTE_LENGTH,
+	readFeedback,
+	type PlanAnnotation,
+} from "./feedback.ts";
+import { sanitizePlanText } from "./plan-text.ts";
+import { blockChangeMarks, changedSections, planDigest, type SectionDigest } from "./plan-text.ts";
+import { extractPlanSteps } from "./steps.ts";
+import { planTitle } from "./plans.ts";
+import type { ReviewCaller, ReviewRole } from "./types.ts";
+import type { ShareState } from "./web-share.ts";
+
+/** A heading the outline can jump to. */
+export interface ReviewOutlineItem {
+	/** DOM id the client gives the heading. */
+	id: string;
+	/** 0-based source line. */
+	line: number;
+	/** Heading level, 1-6. */
+	level: number;
+	/** Heading text. */
+	text: string;
+	/** True when this section changed since the previous review of the plan. */
+	changed?: boolean;
+	/** Content blocks this section no longer holds, when the baseline can say so. */
+	removed?: number;
+}
+
+/** Everything the browser needs to render one plan review. */
+export interface ReviewPageData {
+	/** The mount prefix the review answers under, so its own script is named from there. */
+	base: string;
+	/** Plan title: the document's H1, or the file-name slug when it has none. */
+	title: string;
+	/** Source-line blocks of the feedback-stripped plan. */
+	blocks: PlanBlock[];
+	/** Absolute start lines of the blocks that are new or edited since the previous review. */
+	changed?: number[];
+	/** Whether the previous review's baseline carried block digests, so `changed` means something. */
+	blockMarks?: boolean;
+	/** Feedback already stored in the file. */
+	annotations: PlanAnnotation[];
+	/** Section outline, in document order. */
+	outline: ReviewOutlineItem[];
+	/**
+	 * The plan's step progress, from the same `extractPlanSteps` the approval and
+	 * the `steps` action use: the `Steps` section when there is one, so the page
+	 * agrees with what approval seeds rather than counting every checkbox.
+	 */
+	steps: { done: number; total: number };
+	/** Highlighted HTML per line, keyed by the code block's 0-based start line. */
+	code: Record<string, string[]>;
+	/**
+	 * The caps the server enforces, so the page does not retype them: comment
+	 * count, comment length, and quote length, from `feedback.ts`.
+	 */
+	limits: { comments: number; comment: number; quote: number };
+	/** Whether the review may approve the plan (only the `plan` tool's `exit` flow). */
+	canApprove: boolean;
+	/** Who is looking: `owner` may approve, `reviewer` may only comment. */
+	role: ReviewRole;
+	/**
+	 * The name a reviewer's link posts under, once it has been bound. Absent for the
+	 * owner and for a reviewer that has not written yet, which is what tells the page
+	 * whether its name control is still a choice.
+	 */
+	author?: string;
+	/** A running share, so a reload re-renders the link the owner already minted. */
+	share?: ShareState;
+	/** Per-session secret the client echoes on every request. */
+	token: string;
+	/**
+	 * A short digest of the plan text the page rendered. It keys the unsaved draft a
+	 * tab keeps for itself, so a reload restores the comments this writer has not
+	 * saved yet, and a plan that changed underneath drops them instead.
+	 */
+	rev: string;
+}
+
+/** What one island build reads. */
+export interface ReviewPayloadInput {
+	/** The mount prefix the review answers under, e.g. `/plan/3f9c21aa`. */
+	base: string;
+	/** The plan's path, for the title's file-name fallback. */
+	path: string;
+	/** The plan as stored, feedback markers included. */
+	content: string;
+	/** The section digests the previous review showed, so this page can mark what moved. */
+	baseline?: readonly SectionDigest[];
+	/** Who is asking; the role decides what the page offers. */
+	caller: ReviewCaller;
+	/** The session secret the page echoes on every request. */
+	token: string;
+	/** Whether this review may approve the plan. */
+	canApprove: boolean;
+	/** The running share, read lazily: sharing can start after the page is first served. */
+	share: () => ShareState | undefined;
+}
+
+/**
+ * Build the island for one page request.
+ *
+ * The plan is read once, and the blocks, the comments, and the outline all come out of
+ * that same parse: an annotation names a block from this read, so the island cannot mark
+ * a comment onto a line the page never rendered.
+ */
+export function reviewPageData(input: ReviewPayloadInput): ReviewPageData {
+	const { caller } = input;
+	const role = caller.role;
+	// Normalized the way the baseline is, so a block's digest here is the one the baseline
+	// wrote: the page and the baseline must read the plan the same way, or every tabbed plan
+	// would come back marked as changed. Not stripped, because the comments have to survive
+	// for `readFeedback` to parse them.
+	const read = readFeedback(sanitizePlanText(input.content));
+	const current = read.body;
+	const blocks = read.blocks;
+	// Per-section change marks, each carrying its own section: the same shape the
+	// terminal review renders, so a heading and its mark cannot be paired wrongly.
+	const marks = changedSections(input.baseline, current);
+	// Which blocks moved, in the document's own numbering: the page draws these, and a
+	// section's shrinkage is the half of a diff a document cannot place in the flow.
+	const blockMarks = blockChangeMarks(input.baseline, current);
+	const outline = marks.flatMap(({ section, changed }) =>
+		section.title === ""
+			? []
+			: [
+					{
+						id: `s-${section.line}`,
+						line: section.line,
+						level: section.level,
+						text: section.title,
+						...(changed ? { changed: true } : {}),
+						...(blockMarks.removed[section.line] === undefined ? {} : { removed: blockMarks.removed[section.line] }),
+					},
+				],
+	);
+	// The same step list approval seeds and the `steps` action indexes, so the page's
+	// progress cannot disagree with the todo list.
+	const stepList = extractPlanSteps(current);
+	// Highlight code blocks once, at the boundary: the client copies only the tok-*
+	// spans out of the server-escaped HTML.
+	const code: Record<string, string[]> = {};
+	for (const block of blocks) {
+		if (block.kind !== "code") continue;
+		const language = fenceLanguage(fenceInfo(block.lines[0] ?? ""));
+		if (language) code[String(block.start)] = highlightLines(codeBody(block), language);
+	}
+	return {
+		base: input.base,
+		// The document's own H1 reads better than the file-name slug, and the slug is
+		// still the fallback for a plan that starts with something else.
+		title: marks.find((mark) => mark.section.level === 1)?.section.title || planTitle(basename(input.path)),
+		blocks,
+		...(blockMarks.starts.length === 0 ? {} : { changed: blockMarks.starts }),
+		...(blockMarks.compared ? { blockMarks: true } : {}),
+		annotations: read.annotations,
+		outline,
+		steps: {
+			done: stepList.filter((step) => step.status === "completed").length,
+			total: stepList.length,
+		},
+		code,
+		limits: { comments: MAX_ANNOTATIONS, comment: MAX_COMMENT_LENGTH, quote: MAX_QUOTE_LENGTH },
+		token: input.token,
+		role,
+		// What the page keys this tab's unsaved draft on: same plan text, same draft.
+		rev: planDigest(current),
+		...(caller.name === undefined ? {} : { author: caller.name }),
+		canApprove: role === "owner" && input.canApprove,
+		share: role === "owner" ? input.share() : undefined,
+	};
+}

package/extensions/plan/web-plan.ts

@@ -37,11 +37,15 @@ export interface PlanRenderDeps {
 	/** The element that had focus before this frame, or null when nothing did. */
 	focused: ClientNode | null;
 	blocks(): readonly IslandBlock[];
+	/** Whether this block is new or edited since the previous review; absent means no marks. */
+	changed?(line: number): boolean;
 	annotations(): readonly { anchor: number }[];
 	activeIndex(): number;
 	setActiveIndex(index: number): void;
 	pendingQuote(): PendingQuote | null;
 	clearPendingQuote(): void;
+	/** Whether the review has ended, so the rail offers no new comment. */
+	settled?(): boolean;
 	/** The composer lifecycle, for the close a repaint begins with. */
 	composer(): ComposerDeps;
 	/** The block's content, from the Markdown half. */
@@ -87,24 +91,30 @@ export function renderPlanFrame(
 		const wrap = el("div", "bf-block");
 		wrap.setAttribute("data-line", String(block.start));
 		wrap.setAttribute("data-kind", String(block.kind));
+		// The one mark that says "read this line again": a block the last review did not have.
+		if (deps.changed?.(block.start) === true) wrap.setAttribute("data-changed", "1");
 		if (block.kind === "heading") wrap.id = "s-" + block.start;
 		deps.renderBlock(wrap, block);
 		const mine = deps.annotations().filter((annotation) => annotation.anchor === block.start);
 		if (mine.length > 0) wrap.classList.add("bf-block--commented");
 		const rail = el("div", "bf-block__rail");
-		const add = el("button", "bf-block__add");
-		add.type = "button";
-		add.textContent = "+";
-		add.setAttribute("aria-label", "Comment on this block");
-		add.addEventListener("click", function () {
-			// Read at click time, not at render time: a selection made after this frame is
-			// the quote the reader means.
-			const waiting = deps.pendingQuote();
-			const quoted = waiting && waiting.wrap === wrap ? waiting.quote : deps.selectionIn(wrap);
-			deps.clearPendingQuote();
-			deps.open(wrap, block, quoted);
-		});
-		rail.appendChild(add);
+		// A settled review takes no new comment: this control would open a composer whose
+		// note could never be saved, so it is not drawn rather than drawn and refused.
+		if (deps.settled?.() !== true) {
+			const add = el("button", "bf-block__add");
+			add.type = "button";
+			add.textContent = "+";
+			add.setAttribute("aria-label", "Comment on this block");
+			add.addEventListener("click", function () {
+				// Read at click time, not at render time: a selection made after this frame is
+				// the quote the reader means.
+				const waiting = deps.pendingQuote();
+				const quoted = waiting && waiting.wrap === wrap ? waiting.quote : deps.selectionIn(wrap);
+				deps.clearPendingQuote();
+				deps.open(wrap, block, quoted);
+			});
+			rail.appendChild(add);
+		}
 		if (mine.length > 0) {
 			const badge = el("span", "bf-block__count");
 			badge.textContent = String(mine.length);