@linxiraos/pi-tui 1.2.1 → 1.3.1

package/src/overlays/annotation-overlay.ts

@@ -40,17 +40,10 @@ import {
 } from "../chrome/overlay-box";
 import { appExternalEditorKey, matchesAppExternalEditor } from "../keybinding-matchers";
 import type { KeyName } from "../key-hint-format";
-import { item, keyed, node, row as rowNode, span, text } from "../native/describe";
+import type { TspSpan } from "@linxiraos/pi-wire";
+import { col, item, keyed, node, row as rowNode, span, text } from "../native/describe";
 import { leafKey, type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
-import {
-	escCloseButton,
-	hintsRow,
-	itemIndex,
-	type NativeHint,
-	noteSpans,
-	overlayCard,
-	selectList,
-} from "../native/overlay";
+import { actionButton, hintsRow, itemIndex, type NativeHint, selectList } from "../native/overlay";
 
 function fit(text: string, width: number): string {
 	if (width <= 0) return "";
@@ -158,6 +151,65 @@ function isTextSource(value: readonly ReviewDiffFile[] | TextReviewSource): valu
 	return !Array.isArray(value);
 }
 
+/** The native sheet: full-pane glass, titled by the review kind with what is under review after it. */
+interface NativeSheet {
+	readonly role: "zeta.overlay.codeReview" | "zeta.overlay.annotateText";
+	readonly size: "full";
+	readonly head: TspSpan[];
+}
+const DIFF_SHEET_TITLE = "Code review";
+const TEXT_SHEET_TITLE = "Annotate text";
+
+const NOTE_PLACEHOLDER = "Write a note…";
+
+type FileStatus = "added" | "deleted" | "renamed" | "modified";
+const FILE_STATUS_ICON: Record<FileStatus, string> = {
+	added: "file-plus",
+	deleted: "trash",
+	renamed: "forward",
+	modified: "file",
+};
+const FILE_STATUS_TONE: Record<FileStatus, "success" | "error" | "info" | undefined> = {
+	added: "success",
+	deleted: "error",
+	renamed: "info",
+	modified: undefined,
+};
+const kFileStatus = Symbol("annotation.fileStatus");
+
+/** How a file changed, read from its diff header (memoized on the frozen file). */
+function fileStatus(file: ReviewDiffFile & { [kFileStatus]?: FileStatus }): FileStatus {
+	let status = file[kFileStatus];
+	if (status) return status;
+	const hunk = file.rawDiff.indexOf("\n@@");
+	const header = file.rawDiff.slice(0, hunk < 0 ? 4096 : hunk);
+	status = /^new file mode/m.test(header)
+		? "added"
+		: /^deleted file mode/m.test(header)
+			? "deleted"
+			: file.oldPath !== undefined && file.newPath !== undefined && file.oldPath !== file.newPath
+				? "renamed"
+				: "modified";
+	file[kFileStatus] = status;
+	return status;
+}
+
+/** `src/ui/app.ts` → `{ dir: "src/ui", leaf: "app.ts" }`. */
+function splitPath(path: string): { dir: string; leaf: string } {
+	const slash = path.lastIndexOf("/");
+	return slash < 0 ? { dir: "", leaf: path } : { dir: path.slice(0, slash), leaf: path.slice(slash + 1) };
+}
+
+/** `3 files`, `1 note`. */
+function plural(count: number, noun: string): string {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** A review mode line, muted, with its `backticked` refs as code chips. */
+function modeSpans(mode: string): TspSpan[] {
+	return mode.split("`").flatMap((part, index) => (part ? [span(part, index % 2 === 1 ? "code" : "muted")] : []));
+}
+
 /** A fullscreen, annotated diff picker that only relies on public OMP APIs. */
 export class AnnotationOverlay implements Focusable {
 	focused = false;
@@ -196,6 +248,7 @@ export class AnnotationOverlay implements Focusable {
 	#nativeRoot: NativeNode | undefined;
 	/** Body the memoized root was built from. */
 	#nativeRootBody: NativeBody | undefined;
+	#nativeSheet: NativeSheet | undefined;
 
 	readonly #tui: TUI;
 	readonly #theme: Theme;
@@ -285,6 +338,7 @@ export class AnnotationOverlay implements Focusable {
 		});
 		this.#editor.setBorderVisible(false);
 		this.#editor.setPromptGutter("> ");
+		this.#editor.describePlaceholder = () => NOTE_PLACEHOLDER;
 		this.#editor.setScrollbarVisible(true);
 		this.#editor.onSubmit = value => this.#commitAnnotation(value);
 		this.#resetSourceCursor();
@@ -1331,6 +1385,30 @@ export class AnnotationOverlay implements Focusable {
 		}
 	}
 
+	/**
+	 * The terminal draws the frame: a full-pane glass sheet titled `Code review`
+	 * (or `Annotate text`), then what is under review as a quieter subtitle.
+	 */
+	get nativeOverlay(): NativeSheet {
+		if (!this.#nativeSheet) {
+			const subtitle = this.#textSource
+				? [span(sanitizeStatusText(this.#textSource.label), "muted")]
+				: modeSpans(sanitizeStatusText(this.#mode));
+			this.#nativeSheet = {
+				role: this.#textSource ? "zeta.overlay.annotateText" : "zeta.overlay.codeReview",
+				size: "full",
+				head: [span(this.#textSource ? TEXT_SHEET_TITLE : DIFF_SHEET_TITLE), ...subtitle],
+			};
+		}
+		return this.#nativeSheet;
+	}
+
+	/**
+	 * The sheet's body: the file rail (totals over the changed files) beside
+	 * the current file's diff (text: its numbered lines), the note composer
+	 * docked under the lines while a note is open, and a footer of key hints
+	 * and the actions.
+	 */
 	describe(): NativeNode {
 		// The terminal lays out the file sidebar; diffs always have one, text never does.
 		this.#sidebarShown = !this.#textSource;
@@ -1338,6 +1416,7 @@ export class AnnotationOverlay implements Focusable {
 		// Page size for PgUp/PgDn, matching the rendered body height.
 		const terminalHeight = this.#tui.terminal.rows;
 		this.#bodyHeight = Math.max(MIN_BODY_ROWS, terminalHeight - (this.#actions.length + 8));
+		this.#editor.setMaxHeight(Math.max(1, Math.min(MAX_ANNOTATION_EDITOR_ROWS, terminalHeight - 12)));
 		this.#editor.focused = this.focused && this.#annotating;
 		const body = this.#describeBodyItems();
 		const chooser = this.#annotationChooser;
@@ -1346,73 +1425,55 @@ export class AnnotationOverlay implements Focusable {
 			this.#fileIndex,
 			this.#sourceIndex,
 			this.#actionIndex,
+			this.#bodyHeight,
 			this.#annotating ? `annotating:${this.#annotationScope}:${this.#editingAnnotationIndex}` : "",
 			chooser ? `chooser:${chooser.selected}:${chooser.entries.join()}` : "",
 		].join("|");
 		if (this.#nativeRoot && sig === this.#nativeSig && body === this.#nativeRootBody) return this.#nativeRoot;
 
-		const children: NativeChild[] = [];
+		const editing = this.#annotating || chooser !== undefined;
+		const rowCount = this.#textSource ? this.#textLines.length : this.#currentSourceRows().length;
 		const lines = selectList("lines", body.items, {
-			selected: this.#focus === "diff" ? `l${this.#sourceIndex}` : null,
-			virtual: true,
-			empty: [span(this.#textSource ? "No text" : "No reviewable files", "dim")],
-			role: this.#textSource ? "zeta.overlay.annotateText.lines" : "zeta.overlay.codeReview.diff",
-			tone: this.#focus === "diff" ? "accent" : undefined,
+			selected: rowCount > 0 ? `l${this.#sourceIndex}` : null,
+			// Past 200 rows the terminal virtualizes the list itself (fixed one-line rows).
+			max: { lines: this.#bodyHeight },
+			empty: [span(this.#textSource ? "This text is empty" : "Nothing to review", "muted")],
+			role: this.#textSource ? "zeta.review.text" : "zeta.review.diff",
+			tone: this.#focus === "diff" && !editing ? "accent" : undefined,
 		});
-		// The header row ends in a clickable `esc` at the top right.
-		const title = node("col", { grow: 1, min: { w: 0 } }, [this.#describeHeader()], "title");
-		const head = keyed(rowNode([title, escCloseButton()], { gap: "md", align: "center" }), "head");
-		const main = node("col", { grow: 1 }, [head, lines], "main");
+		const pane: NativeChild[] = [this.#describePaneHead()];
+		pane.push(lines);
+		const composer = this.#describeComposer();
+		if (composer) pane.push(composer);
+		const main = node("col", { role: "zeta.review.pane", grow: 1, min: { w: 0 } }, pane, "pane");
+		const children: NativeChild[] = [];
 		if (this.#sidebarShown) {
-			const files = selectList(
-				"files",
-				this.#files.map((file, index) => {
-					const count = this.#annotationCount(index);
-					const value = [
-						span(`+${file.linesAdded}`, "ins"),
-						span("/", "dim"),
-						span(`-${file.linesRemoved}`, "del"),
-					];
-					if (count) value.push(span(` ✎${count}`, "warning"));
-					return item(`f${index}`, { label: [span(displayFileLabel(file), "path")], value });
-				}),
-				{
-					selected: this.#files.length > 0 ? `f${this.#fileIndex}` : null,
-					role: "zeta.overlay.codeReview.files",
-					tone: this.#focus === "files" ? "accent" : undefined,
-				},
-			);
-			const sidebar = node("col", { max: { w: "34ch" }, shrink: 0 }, [files], "sidebar");
-			children.push(keyed(rowNode([sidebar, main], { gap: "md", align: "start" }), "split"));
+			children.push(keyed(rowNode([this.#describeRail(editing), main], { role: "zeta.review.split" }), "split"));
 		} else {
 			children.push(main);
 		}
-		children.push(keyed(text([span(sanitizeStatusText(this.#mode), "accent strong")]), "mode"));
-		children.push(
-			selectList(
-				"actions",
-				this.#actions.map((label, index) =>
-					item(`a${index}`, { label, disabled: this.#actionDisabled(index) || undefined }),
-				),
-				{ selected: `a${this.#actionIndex}`, tone: this.#focus === "actions" ? "accent" : undefined },
-			),
-		);
-		children.push(...this.#describeFooter());
+		children.push(this.#describeFooter(editing));
 
 		this.#nativeSig = sig;
 		this.#nativeRootBody = body;
-		this.#nativeRoot = overlayCard(
-			this.#textSource ? "zeta.overlay.annotateText" : "zeta.overlay.codeReview",
-			this.#textSource ? TEXT_OVERLAY_TITLE : OVERLAY_TITLE,
-			children,
-		);
+		this.#nativeRoot = col(children);
 		return this.#nativeRoot;
 	}
 
 	handleNativeEvent(event: NativeUiEvent): void {
 		if (this.#finished || this.#externalOperation) return;
-		if (event.type === "action" && event.act === "close") {
-			this.#escape();
+		if (event.type === "action") {
+			if (event.act === "close") {
+				this.#escape();
+				return;
+			}
+			// A draft or the note chooser is open: finish or leave it first.
+			if (this.#annotating || this.#annotationChooser) return;
+			const index =
+				event.act === "review" && !this.#textSource ? 0 : event.act === "paste" ? (this.#textSource ? 0 : 1) : -1;
+			if (index < 0 || this.#actionDisabled(index)) return;
+			this.#actionIndex = index;
+			this.#confirmAction();
 			return;
 		}
 		if (event.type !== "select" && event.type !== "activate") return;
@@ -1445,99 +1506,124 @@ export class AnnotationOverlay implements Focusable {
 				this.#focus = "diff";
 				this.#sourceIndex = index;
 				this.#viewportDriven = false;
-				if (activate) this.#focus = "actions";
-				return;
-			}
-			case "actions": {
-				const index = itemIndex(event.item, "a");
-				if (index < 0 || index >= this.#actions.length || this.#actionDisabled(index)) return;
-				this.#focus = "actions";
-				this.#actionIndex = index;
-				if (activate) this.#confirmAction();
+				// Double-clicking a line opens its note, like `a`.
+				if (activate) this.#startAnnotation("line");
 				return;
 			}
 		}
 	}
 
-	/** One item per diff/text row; annotation callouts are disabled items before their row. */
+	/**
+	 * One item per diff/text row; notes are disabled `warning` items under
+	 * the row they belong to (file and whole-text notes lead). Diff rows carry
+	 * their kind as the tone (`success` added, `error` removed, `info` hunk).
+	 */
 	#describeBodyItems(): NativeBody {
 		const cached = this.#nativeBody;
 		if (cached && cached.fileIndex === this.#fileIndex && cached.rev === this.#annotationRev) return cached;
 		const items: NativeNode[] = [];
-		const note = (key: string, label: string, body: string) =>
+		const note = (key: string, body: string, scope?: string) =>
 			items.push(
 				item(key, {
-					label: noteSpans(label, sanitizeText(body)),
+					label: [span(sanitizeStatusText(body))],
+					value: scope ? [span(scope, "muted")] : undefined,
+					icon: "pen",
 					disabled: true,
 					tone: "warning",
-					role: "zeta.overlay.codeReview.note",
+					role: "zeta.review.note",
 				}),
 			);
+		const notice = (key: string, label: string, icon: string) =>
+			items.push(item(key, { label: [span(label, "muted")], icon, disabled: true, tone: "muted" }));
 		if (this.#textSource) {
 			for (const [index, entry] of this.#textAnnotations.entries()) {
-				if (entry.annotation.scope === "text") note(`n${index}`, "text note", entry.annotation.note);
+				if (entry.annotation.scope === "text") note(`n${index}`, entry.annotation.note, "Whole text");
 			}
+			const mono = this.#textSource.kind !== "message" && this.#textSource.kind !== "prompt";
+			const width = String(this.#textLines.length).length;
 			for (const [sourceIndex, sourceLine] of this.#textLines.entries()) {
+				items.push(
+					item(`l${sourceIndex}`, {
+						label: [span(replaceTabs(sanitizeText(sourceLine)), mono ? "mono" : undefined)],
+						value: [span(String(sourceIndex + 1).padStart(width), "mono")],
+					}),
+				);
 				for (const [index, entry] of this.#textAnnotations.entries()) {
 					if (entry.annotation.scope === "line" && entry.sourceIndex === sourceIndex) {
-						note(`n${index}`, "note", entry.annotation.note);
+						note(`n${index}`, entry.annotation.note);
 					}
 				}
-				items.push(item(`l${sourceIndex}`, { label: sanitizeText(sourceLine) }));
 			}
 		} else {
 			const file = this.#currentFile();
 			if (file) {
 				for (const [index, entry] of this.#annotations.entries()) {
 					if (entry.fileIndex === this.#fileIndex && entry.annotation.scope === "file") {
-						note(`n${index}`, "file note", entry.annotation.note);
+						note(`n${index}`, entry.annotation.note, "File note");
 					}
 				}
 				if (file.isBinary) {
-					items.push(
-						item("binary", { label: [span("Binary diff; no annotatable source rows", "dim")], disabled: true }),
-					);
+					notice("binary", "Binary file: no lines to annotate, but a file note works", "binary");
 				} else if (file.rows.length === 0) {
-					items.push(
-						item("empty", {
-							label: [span("No diff hunks; this may be a rename-only change", "dim")],
-							disabled: true,
-						}),
+					notice("empty", "No hunks: this looks like a rename-only change", "forward");
+				}
+				let lineWidth = 1;
+				for (const diffRow of file.isBinary ? [] : file.rows) {
+					if (!isSourceRow(diffRow)) continue;
+					lineWidth = Math.max(
+						lineWidth,
+						String(diffRow.oldLine ?? "").length,
+						String(diffRow.newLine ?? "").length,
 					);
 				}
+				// The old/new line gutter is the item's value (drawn first); rows without numbers keep its width.
+				const blankGutter = [span(" ".repeat(lineWidth * 2 + 1), "mono")];
 				let sourceIndex = 0;
 				for (const [rowIndex, diffRow] of file.isBinary ? [] : file.rows.entries()) {
 					if (!isSourceRow(diffRow)) {
-						const s = diffRow.kind === "hunk" ? "accent" : "dim";
-						items.push(item(`r${rowIndex}`, { label: [span(sanitizeText(diffRow.raw), s)], disabled: true }));
+						if (diffRow.kind === "hunk") {
+							const match = /^(@@[^@]*@@)\s?(.*)$/.exec(sanitizeText(diffRow.raw));
+							const label = match
+								? [span(match[1]!, "mono"), span(match[2] ? `  ${replaceTabs(match[2])}` : "", "muted mono")]
+								: [span(sanitizeText(diffRow.raw), "mono")];
+							items.push(item(`r${rowIndex}`, { label, value: blankGutter, disabled: true, tone: "info" }));
+						} else {
+							items.push(
+								item(`r${rowIndex}`, {
+									label: [span("No newline at end of file", "muted")],
+									value: blankGutter,
+									disabled: true,
+									tone: "muted",
+								}),
+							);
+						}
 						continue;
 					}
+					const added = diffRow.kind === "added";
+					const removed = diffRow.kind === "removed";
+					const oldCell = String((added ? undefined : diffRow.oldLine) ?? "").padStart(lineWidth);
+					const newCell = String((removed ? undefined : diffRow.newLine) ?? "").padStart(lineWidth);
+					const color: DiffColor = added ? "toolDiffAdded" : removed ? "toolDiffRemoved" : "toolDiffContext";
+					items.push(
+						item(`l${sourceIndex}`, {
+							label: [
+								span(added ? "+ " : removed ? "- " : "  ", `${color} mono`),
+								span(replaceTabs(sanitizeText(diffRow.content)), "mono"),
+							],
+							value: [span(`${oldCell} ${newCell}`, "mono")],
+							tone: added ? "success" : removed ? "error" : undefined,
+						}),
+					);
+					// A line's notes sit under it, like review comments.
 					for (const [index, entry] of this.#annotations.entries()) {
 						if (
 							entry.fileIndex === this.#fileIndex &&
 							entry.sourceIndex === sourceIndex &&
 							entry.annotation.scope === "line"
 						) {
-							note(`n${index}`, "note", entry.annotation.note);
+							note(`n${index}`, entry.annotation.note);
 						}
 					}
-					const marker = diffRow.kind === "added" ? "+" : diffRow.kind === "removed" ? "-" : " ";
-					const lineNumber = diffRow.kind === "removed" ? diffRow.oldLine : (diffRow.newLine ?? diffRow.oldLine);
-					const color: DiffColor =
-						diffRow.kind === "added"
-							? "toolDiffAdded"
-							: diffRow.kind === "removed"
-								? "toolDiffRemoved"
-								: "toolDiffContext";
-					items.push(
-						item(`l${sourceIndex}`, {
-							label: [
-								span(marker, `${color} mono`),
-								span(`${lineNumber ?? ""} `, "num dim mono"),
-								span(sanitizeText(diffRow.content), `${color} mono`),
-							],
-						}),
-					);
 					sourceIndex++;
 				}
 			}
@@ -1546,93 +1632,261 @@ export class AnnotationOverlay implements Focusable {
 		return this.#nativeBody;
 	}
 
-	#describeHeader(): NativeNode {
+	/** The file rail: the totals (file count, notes, `+a −r`) over the changed files. */
+	#describeRail(editing: boolean): NativeNode {
+		let added = 0;
+		let removed = 0;
+		for (const file of this.#files) {
+			added += file.linesAdded;
+			removed += file.linesRemoved;
+		}
+		const total: NativeChild[] = [text([span(plural(this.#files.length, "file"))], { grow: 1, wrap: "none" })];
+		if (this.#annotations.length > 0) {
+			total.push(
+				text([span(plural(this.#annotations.length, "note"))], { role: "zeta.review.count", wrap: "none" }),
+			);
+		}
+		total.push(
+			text([span(`+${added}`, "toolDiffAdded mono"), span(" "), span(`−${removed}`, "toolDiffRemoved mono")], {
+				wrap: "none",
+			}),
+		);
+		const files = selectList(
+			"files",
+			this.#files.map((file, index) => {
+				const { dir, leaf } = splitPath(displayFileLabel(file));
+				const status = fileStatus(file);
+				const count = this.#annotationCount(index);
+				const value: TspSpan[] = [];
+				if (count) value.push(span(`✎ ${count}`, "warning"), span(" "));
+				if (file.isBinary) value.push(span("bin", "muted"));
+				else
+					value.push(
+						span(`+${file.linesAdded}`, "toolDiffAdded mono"),
+						span(" "),
+						span(`−${file.linesRemoved}`, "toolDiffRemoved mono"),
+					);
+				return item(`f${index}`, {
+					label: [span(sanitizeStatusText(leaf))],
+					detail: dir ? [span(sanitizeStatusText(dir))] : undefined,
+					value,
+					icon: file.isBinary ? "binary" : FILE_STATUS_ICON[status],
+					tone: FILE_STATUS_TONE[status],
+				});
+			}),
+			{
+				selected: this.#files.length > 0 ? `f${this.#fileIndex}` : null,
+				max: { lines: this.#bodyHeight },
+				empty: [span("No files", "muted")],
+				role: "zeta.review.files",
+				tone: this.#focus === "files" && !editing ? "accent" : undefined,
+			},
+		);
+		return node(
+			"col",
+			{ role: "zeta.review.rail" },
+			[node("row", { role: "zeta.review.total", gap: "sm", align: "center" }, total, "total"), files],
+			"rail",
+		);
+	}
+
+	/**
+	 * Over the lines: the current file's full path, how it changed, its note
+	 * count and `+a −r` (text: its line and note counts).
+	 */
+	#describePaneHead(): NativeNode {
+		const children: NativeChild[] = [];
+		const props = { role: "zeta.review.head", gap: "sm", align: "center" } as const;
 		if (this.#textSource) {
-			const count = this.#textAnnotations.length;
-			const spans = [span(sanitizeStatusText(this.#textSource.label), "strong")];
-			if (count) spans.push(span(` ✎${count}`, "dim"));
-			return keyed(text(spans, { truncate: "end" }), "header");
+			children.push(text([span(plural(this.#textLines.length, "line"))], { grow: 1, wrap: "none" }));
+			const notes = this.#textAnnotations.length;
+			if (notes) children.push(text([span(plural(notes, "note"))], { role: "zeta.review.count", wrap: "none" }));
+			return node("row", props, children, "head");
 		}
 		const file = this.#currentFile();
-		if (!file) return keyed(text([span("No reviewable files", "dim")]), "header");
+		if (!file) return node("row", props, [text([span("No reviewable files", "muted")])], "head");
+		const status = fileStatus(file);
+		children.push(
+			text([span(sanitizeStatusText(displayFileLabel(file)), "path")], { truncate: "middle", min: { w: 0 } }),
+		);
+		const what =
+			status === "renamed" && file.oldPath
+				? `Renamed from ${sanitizeStatusText(file.oldPath)}`
+				: status === "added"
+					? "New file"
+					: status === "deleted"
+						? "Deleted"
+						: file.isBinary
+							? "Binary"
+							: undefined;
+		if (what) {
+			children.push(
+				text([span(what)], {
+					role: "zeta.review.status",
+					tone: FILE_STATUS_TONE[status],
+					truncate: "end",
+					min: { w: 0 },
+				}),
+			);
+		}
+		children.push(node("spacer", { grow: 1 }));
 		const count = this.#annotationCount(this.#fileIndex);
-		const spans = [
-			span(sanitizeStatusText(displayFileLabel(file)), "strong path"),
-			span(` +${file.linesAdded}`, "ins"),
-			span("/", "dim"),
-			span(`-${file.linesRemoved}`, "del"),
-		];
-		if (count) spans.push(span(` ✎${count}`, "dim"));
-		return keyed(text(spans, { truncate: "middle" }), "header");
+		if (count) children.push(text([span(plural(count, "note"))], { role: "zeta.review.count", wrap: "none" }));
+		if (!file.isBinary) {
+			children.push(
+				text(
+					[
+						span(`+${file.linesAdded}`, "toolDiffAdded mono"),
+						span(" "),
+						span(`−${file.linesRemoved}`, "toolDiffRemoved mono"),
+					],
+					{ wrap: "none" },
+				),
+			);
+		}
+		return node("row", props, children, "head");
 	}
 
-	#describeFooter(): NativeChild[] {
+	/** Docked under the lines: the note being written (what it is on, then the field) or the note chooser. */
+	#describeComposer(): NativeNode | undefined {
 		const chooser = this.#annotationChooser;
 		if (chooser) {
 			const entries = chooser.entries.map((index, i) => {
 				const entry = chooser.kind === "text" ? this.#textAnnotations[index] : this.#annotations[index];
-				const location = !entry
+				// Every candidate is on the current file (or text), so the place is just the line.
+				const annotation = entry?.annotation;
+				const location = !annotation
 					? ""
-					: "fileIndex" in entry
-						? this.#annotationLocation(entry)
-						: this.#textAnnotationLocation(entry);
+					: annotation.scope === "file"
+						? "File note"
+						: annotation.scope === "text"
+							? "Whole text"
+							: "line" in annotation
+								? `Line ${annotation.line}`
+								: annotation.newLine !== undefined
+									? `Line ${annotation.newLine}`
+									: `Removed line ${annotation.oldLine ?? ""}`.trim();
 				return item(`c${i}`, {
-					label: sanitizeStatusText(entry?.annotation.note.split(/\r?\n/, 1)[0] ?? ""),
-					detail: location,
+					label: sanitizeStatusText(annotation?.note.split(/\r?\n/, 1)[0] ?? ""),
+					value: location,
+					icon: "pen",
 				});
 			});
-			return [
-				keyed(text([span("Edit annotation", "accent strong")]), "chooserHead"),
-				selectList("chooser", entries, { selected: `c${chooser.selected}` }),
-				hintsRow(
-					[
-						this.#hint(["tui.select.up", "tui.select.down"], "choose"),
-						this.#hint("tui.select.confirm", "edit"),
-						this.#hint("tui.select.cancel", "cancel"),
-					],
-					"chooserHints",
-				),
-			];
+			return node(
+				"col",
+				{ role: "zeta.review.composer" },
+				[
+					keyed(text([span("Edit which note?", "strong")]), "caption"),
+					selectList("chooser", entries, { selected: `c${chooser.selected}`, tone: "accent" }),
+				],
+				"chooser",
+			);
 		}
-		if (this.#annotating) {
-			const { action, location } = this.#annotationCaption();
-			return [
-				keyed(text([span(`${action} `, "dim"), span(location, "accent")], { truncate: "end" }), "annotateHead"),
-				this.#editor,
-				hintsRow(
-					[
-						this.#hint("tui.input.submit", "save"),
-						this.#hint("tui.input.newLine", "newline"),
-						this.#hint("tui.select.cancel", "cancel"),
-						{ keys: [appExternalEditorKey()], label: "editor" },
-					],
-					"annotateHints",
+		if (!this.#annotating) return undefined;
+		return node(
+			"col",
+			{ role: "zeta.review.composer" },
+			[keyed(text(this.#noteCaption(), { truncate: "end" }), "caption"), this.#editor],
+			"composer",
+		);
+	}
+
+	/** Where the open note lands: `Note on line 42 in src/app.ts`, `Edit note on src/app.ts`, `Note on the whole text`. */
+	#noteCaption(): TspSpan[] {
+		const verb = span(this.#editingAnnotationIndex === undefined ? "Note on " : "Edit note on ", "muted");
+		if (this.#textSource) {
+			return this.#annotationScope === "text"
+				? [verb, span("the whole text", "strong")]
+				: [verb, span(`line ${this.#sourceIndex + 1}`, "strong")];
+		}
+		const file = this.#currentFile();
+		const path = file ? sanitizeStatusText(displayFileLabel(file)) : "file";
+		if (this.#annotationScope === "file") return [verb, span(path, "path")];
+		const source = this.#currentSourceRows()[this.#sourceIndex];
+		const where =
+			source?.kind === "removed"
+				? `removed line ${source.oldLine ?? ""}`
+				: `line ${source?.newLine ?? source?.oldLine ?? ""}`;
+		return [verb, span(where.trim(), "strong"), span(" in ", "muted"), span(path, "path")];
+	}
+
+	/**
+	 * The footer: key hints for what has focus, then Cancel and the actions
+	 * (the primary last). Each button's key lives in its tooltip; the action
+	 * picked from the keyboard is marked `pick`, an unavailable one `drop`.
+	 */
+	#describeFooter(editing: boolean): NativeNode {
+		const pick = (index: number): "pick" | "drop" | undefined =>
+			editing || this.#actionDisabled(index)
+				? "drop"
+				: this.#focus === "actions" && this.#actionIndex === index
+					? "pick"
+					: undefined;
+		const marked = (button: NativeNode, mark: "pick" | "drop" | undefined): NativeNode =>
+			mark ? ({ ...button, p: { ...button.p, mark } } as NativeNode) : button;
+		const hasNotes = this.#textSource ? this.#textAnnotations.length > 0 : this.#annotations.length > 0;
+		const pasteTitle = hasNotes ? PASTE_CODE_REVIEW_ACTION : "Add a note to paste it into the prompt";
+		const buttons: NativeNode[] = [actionButton("Cancel", "close", { keys: "escape" })];
+		if (this.#textSource) {
+			buttons.push(
+				marked(actionButton("Paste into prompt", "paste", { tone: "accent", title: pasteTitle }), pick(0)),
+			);
+		} else {
+			buttons.push(
+				marked(actionButton("Paste into prompt", "paste", { title: pasteTitle }), pick(1)),
+				marked(
+					actionButton("Review with LLM", "review", { tone: "accent", title: CONTINUE_CODE_REVIEW_ACTION }),
+					pick(0),
 				),
-			];
+			);
 		}
+		return node(
+			"row",
+			{ role: "zeta.actions", gap: "sm", align: "center" },
+			[hintsRow(this.#footerHints()), ...buttons],
+			"actions",
+		);
+	}
+
+	/** At most a handful of hints, for the region (or draft) that has the keys. */
+	#footerHints(): (NativeHint | undefined)[] {
 		const key = (keys: KeyName | readonly KeyName[], label: string): NativeHint => ({
 			keys: typeof keys === "string" ? [keys] : keys,
 			label,
 		});
 		const upDown = (label: string) => this.#hint(["tui.select.up", "tui.select.down"], label);
-		const editNote = key("e", "edit note");
-		const hints: (NativeHint | undefined)[] =
-			this.#focus === "files"
-				? [upDown("file"), this.#hint("tui.select.confirm", "diff"), key(["a", "shift+a"], "file note"), editNote]
-				: this.#focus === "diff"
-					? [
-							upDown("line"),
-							key("shift", "faster"),
-							this.#hint(["tui.select.pageUp", "tui.select.pageDown"], "page"),
-							key(["g", "shift+g"], "ends"),
-							key("a", "line note"),
-							key("shift+a", this.#textSource ? "text note" : "file note"),
-							editNote,
-						]
-					: [upDown("select"), this.#hint("tui.select.confirm", "confirm")];
-		if (this.#callbacks.onExternalEditor) hints.push({ keys: [appExternalEditorKey()], label: "editor" });
-		hints.push(key("u", "undo"), key("tab", "regions"), this.#hint("tui.select.cancel", "cancel"));
-		return [hintsRow(hints)];
+		if (this.#annotationChooser) {
+			return [upDown("choose"), this.#hint("tui.select.confirm", "edit"), this.#hint("tui.select.cancel", "back")];
+		}
+		if (this.#annotating) {
+			return [
+				this.#hint("tui.input.submit", "save"),
+				this.#hint("tui.input.newLine", "new line"),
+				this.#hint("tui.select.cancel", "discard"),
+				this.#callbacks.onAnnotationExternalEditor ? key(appExternalEditorKey(), "editor") : undefined,
+			];
+		}
+		const undo = this.#undoStack.length > 0 ? key("u", "undo") : undefined;
+		if (this.#focus === "files") {
+			return [
+				upDown("file"),
+				this.#hint("tui.select.confirm", "open"),
+				key("a", "file note"),
+				undo,
+				key("tab", "pane"),
+			];
+		}
+		if (this.#focus === "diff") {
+			return [
+				upDown("line"),
+				key("a", "note"),
+				key("shift+a", this.#textSource ? "note on all" : "file note"),
+				this.#annotationCandidates().length > 0 ? key("e", "edit note") : undefined,
+				undo,
+				key("tab", this.#textSource ? "actions" : "pane"),
+			];
+		}
+		return [upDown("choose"), this.#hint("tui.select.confirm", "run"), key("tab", "pane")];
 	}
 
 	/** Keycap hint for the primary keys this overlay's keybindings bind to `actions`. */