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

package/extensions/plan/web-outline.ts

@@ -0,0 +1,212 @@
+/**
+ * The review page's outline: the section list in the sidebar, and the one rule that says
+ * which section a source line belongs to.
+ *
+ * Written as ordinary TypeScript and exported as source — `WEB_OUTLINE_JS` — because the
+ * review client is a template literal no compiler sees. The two functions are given what
+ * they read rather than closing over the bundle's variables, which is what makes them
+ * testable here: `renderOutline` returns the per-line counters it built instead of
+ * assigning the client's `outlineItems`, and `sectionFor` takes the outline it searches.
+ *
+ * `el` is the client runtime's builder, declared here because this source is spliced into
+ * the same bundle it lives in: the declaration emits nothing, so the body calls the one
+ * builder. The nodes are reached through a structural type because this project compiles
+ * without a DOM lib; the annotations are erased before the source is spliced.
+ */
+
+import type { ClientNode } from "../../lib/web/client-runtime.ts";
+
+/** One entry of the page's `outline` island: a heading, its line, and whether it moved. */
+export interface OutlineEntry {
+	id: string;
+	level: number;
+	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. */
+export interface SectionWatcher {
+	observe(target: ClientNode): void;
+	disconnect(): void;
+}
+
+/** What `el` has to answer for an outline. Spliced beside it; declared for the checker. */
+type Build = (tag: string, className?: string, text?: string | null) => ClientNode;
+declare const el: Build;
+
+/**
+ * The section a source line belongs to: the last heading at or before it.
+ *
+ * `null` when the line sits above the first heading, which is how a preamble renders
+ * without a section of its own.
+ */
+export function sectionFor(entries: readonly OutlineEntry[], line: number): OutlineEntry | null {
+	let found: OutlineEntry | null = null;
+	for (const item of entries) if (item.line <= line) found = item;
+	return found;
+}
+
+/**
+ * Draw the section list and return the counter each line owns.
+ *
+ * The caller keeps the returned map because the counters are updated later, when the
+ * comments are counted per section; returning it is what lets this function be a pure
+ * build with no handle on the client's state.
+ */
+export function renderOutline(list: ClientNode | null, entries: readonly OutlineEntry[]): Record<number, ClientNode> {
+	const counters: Record<number, ClientNode> = {};
+	if (!list) return counters;
+	list.replaceChildren();
+	for (const item of entries) {
+		const li = el("li", "lvl-" + item.level);
+		const link = el("a");
+		link.href = "#" + item.id;
+		link.setAttribute("data-id", item.id);
+		const label = el("span", "review-nav__link");
+		label.textContent = item.text;
+		link.appendChild(label);
+		if (item.changed) {
+			const dot = el("span", "review-changed");
+			dot.setAttribute("role", "img");
+			dot.setAttribute("aria-label", "Changed since your last review");
+			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);
+		li.appendChild(link);
+		list.appendChild(li);
+		counters[item.line] = count;
+	}
+	return counters;
+}
+
+/**
+ * Watch the blocks and mark the section the reader is in, replacing any previous watcher.
+ *
+ * The observer is returned rather than stored, so the client owns the one handle it has to
+ * disconnect and this function owns the rule: the last block still in the document the
+ * observer was built over wins, and a page with no headings needs no watcher at all.
+ */
+export function observeSections(
+	planEl: ClientNode | null,
+	list: ClientNode | null,
+	previous: SectionWatcher | null,
+): SectionWatcher | null {
+	if (previous) previous.disconnect();
+	if (!planEl || !list) return null;
+	const Observer = (
+		globalThis as unknown as {
+			IntersectionObserver?: new (
+				callback: (entries: ArrayLike<{ isIntersecting: boolean; target: { id: string } }>) => void,
+				options: Record<string, unknown>,
+			) => SectionWatcher;
+		}
+	).IntersectionObserver;
+	if (!Observer) return null;
+	const links: Record<string, ClientNode> = {};
+	const anchors = list.querySelectorAll("a");
+	for (let i = 0; i < anchors.length; i++) {
+		const link = anchors[i];
+		if (link) links[link.getAttribute("data-id") ?? ""] = link;
+	}
+	const headings = planEl.querySelectorAll(".bf-block[id]");
+	if (headings.length === 0) return null;
+	const watcher = new Observer(
+		(entries) => {
+			for (let i = 0; i < entries.length; i++) {
+				const entry = entries[i];
+				if (!entry || !entry.isIntersecting) continue;
+				const all = list.querySelectorAll("a");
+				for (let j = 0; j < all.length; j++) all[j]?.removeAttribute("aria-current");
+				const link = links[entry.target.id];
+				if (link) link.setAttribute("aria-current", "true");
+			}
+		},
+		{ rootMargin: "-88px 0px -68% 0px", threshold: 0 },
+	);
+	for (let i = 0; i < headings.length; i++) {
+		const heading = headings[i];
+		if (heading) watcher.observe(heading);
+	}
+	return watcher;
+}
+
+/** 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. */
+export interface StepProgress {
+	done: number;
+	total: number;
+}
+
+/**
+ * Paint the review facts: the plan's step progress, the comment total, and one count per
+ * section in the outline.
+ *
+ * The counters are the ones `renderOutline` returned, so the two functions agree by
+ * construction; a section a comment cannot be placed in is skipped rather than counted
+ * against the first heading, which is what "not attached to a current block" means.
+ */
+export function renderFacts(
+	steps: StepProgress,
+	comments: readonly AnchoredComment[],
+	counters: Record<number, ClientNode>,
+	entries: readonly OutlineEntry[],
+): void {
+	const doc = (
+		globalThis as unknown as {
+			document: { getElementById(id: string): ClientNode | null };
+		}
+	).document;
+	// A plan with no Steps section has no progress to show; 0/0 is noise.
+	const fact = doc.getElementById("step-fact");
+	if (fact) fact.hidden = steps.total === 0;
+	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");
+	// 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) {
+		// 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;
+	}
+	for (const comment of comments) {
+		const section = sectionFor(entries, comment.anchor);
+		if (!section) continue;
+		const node = counters[section.line];
+		if (!node) continue;
+		const value = node.hidden ? 0 : Number(node.textContent);
+		node.textContent = String(value + 1);
+		node.hidden = false;
+	}
+}
+
+/** The section list, the facts beside it, and the watcher that marks where the reader is. */
+export const WEB_OUTLINE_JS = [sectionFor, renderOutline, observeSections, renderFacts].map(String).join("\n\n");

package/extensions/plan/web-page.ts

@@ -14,80 +14,27 @@
  */
 
 import {
+	baseAttribute,
 	brandLockup,
 	docHead,
 	type KeyHint,
 	keysSheet,
 	SIDEBAR_COLLAPSE_MAX,
+	tabTitle,
 	themeToggle,
 	WEB_BASE_CSS,
 	WEB_COMPONENTS_CSS,
 	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}
@@ -116,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}
@@ -148,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)}
@@ -179,7 +138,12 @@ ${WEB_COMPONENTS_CSS}
 .bf-comment__label{font:var(--fw-semibold) var(--fs-xs) var(--font-mono);color:var(--warn);text-transform:uppercase;letter-spacing:.06em}
 /* A reviewer's name is a name, not a label: keep its own capitalisation. */
 .bf-comment__label--author{text-transform:none;letter-spacing:0}
+/* 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}
@@ -222,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}
@@ -234,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) }));
 }
 
 /**
@@ -308,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>
@@ -339,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: "Plan review", 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>
@@ -364,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>
 `;
@@ -376,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,
+	};
+}