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

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
+	 * `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;
+}
+
+/** 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 set_plan_steps 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);

package/extensions/plan/web-settle.ts

@@ -15,10 +15,12 @@
 export interface SettleDeps {
 	/** The path a write goes to, without its query string. */
 	token(): string;
+	/** The review's mount on the session's server, e.g. `/plan/3f9c21aa`. */
+	base(): string;
 	role(): string;
 	/** The comments this writer may write: her own when she is a reviewer, all when owner. */
-	mine(): readonly unknown[];
-	annotations(): readonly unknown[];
+	mine(): readonly { author?: string }[];
+	annotations(): readonly { author?: string }[];
 	/** Whether the review has already ended, by any of the three routes. */
 	settled(): boolean;
 	setStatus(text: string, kind?: string): void;
@@ -82,9 +84,14 @@ export function submitAnnotations(
 				if (onOk) onOk();
 				deps.updateState();
 				// The server binds a reviewer's name to her link on the first post, so a
-				// second tab of the same link posts under the same name.
+				// second tab of the same link posts under the same name — and it may normalise
+				// what she typed (`@alice` is stored as `alice`). The comments she just posted
+				// are in the file under the bound name, so the page's copy has to say that too:
+				// otherwise they stop being hers to edit, and her next post would replace
+				// markers it never sent.
 				const body = result.body as { author?: unknown } | null;
 				if (deps.role() === "reviewer" && body && typeof body.author === "string" && body.author) {
+					for (const annotation of payload) if (annotation.author !== undefined) annotation.author = body.author;
 					deps.adoptName(body.author);
 				}
 				return { outcome: "ok" as const };
@@ -117,7 +124,7 @@ export function saveReview(deps: SettleDeps): Promise<SettleResult> | null {
 	deps.setStatus("Saving\u2026");
 	return submitAnnotations(
 		deps,
-		"/api/feedback",
+		deps.base() + "/api/feedback",
 		"Saved \u2014 return to Pi to continue.",
 		"Could not save: ",
 		function () {
@@ -140,7 +147,7 @@ export function postReviewComments(deps: SettleDeps): Promise<SettleResult> | nu
 	deps.setStatus("Posting\u2026");
 	return submitAnnotations(
 		deps,
-		"/api/comment",
+		deps.base() + "/api/comment",
 		"Comments posted \u2014 the owner sees them now.",
 		"Could not post: ",
 		null,
@@ -153,7 +160,7 @@ export function approveReview(deps: SettleDeps): Promise<SettleResult> | null {
 	deps.setStatus("Approving\u2026");
 	return submitAnnotations(
 		deps,
-		"/api/approve",
+		deps.base() + "/api/approve",
 		"Approved \u2014 return to Pi to continue.",
 		"Could not approve: ",
 		function () {
@@ -180,7 +187,7 @@ export function cancelReview(deps: SettleDeps): Promise<void> | null {
 	deps.setStatus("Closing\u2026");
 	deps.updateState();
 	return deps
-		.send("/api/cancel?token=" + encodeURIComponent(deps.token()))
+		.send(deps.base() + "/api/cancel?token=" + encodeURIComponent(deps.token()))
 		.catch(function () {})
 		.then(function () {
 			deps.setStatus("Closed \u2014 return to Pi.");