@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/overlays/annotation-overlay.ts

@@ -1,5 +1,5 @@
 import {
-	type Component,
+	type Focusable,
 	Editor,
 	Ellipsis,
 	matchesKey,
@@ -11,7 +11,9 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "../index";
-import { appKey, editorKey } from "../chrome/keybinding-hints";
+import { compositeLineAt } from "../render/composite";
+import { wrapLiteralLine } from "../utils";
+import { editorKey } from "../chrome/keybinding-hints";
 import { formatKeyHint, formatKeyHints, type KeybindingsManager } from "../app-keybindings";
 import type { Keybinding } from "../keybindings";
 import { sanitizeText } from "@linxiraos/pi-utils";
@@ -36,11 +38,19 @@ import {
 	topBorder,
 	topBorderSplit,
 } from "../chrome/overlay-box";
-import { matchesAppExternalEditor } from "../keybinding-matchers";
+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 { leafKey, type NativeChild, type NativeNode, type NativeUiEvent } from "../native/node";
-import { hintsRow, itemIndex, type NativeHint, noteSpans, overlayCard, selectList } from "../native/overlay";
+import {
+	escCloseButton,
+	hintsRow,
+	itemIndex,
+	type NativeHint,
+	noteSpans,
+	overlayCard,
+	selectList,
+} from "../native/overlay";
 
 function fit(text: string, width: number): string {
 	if (width <= 0) return "";
@@ -60,6 +70,8 @@ export interface AnnotationOverlayCallbacks {
 	onWarning?(message: string): void;
 	/** Open the draft in the host's editor and invoke `commit` with its result. */
 	onAnnotationExternalEditor?(draft: string, commit: (text: string | null) => void): void | Promise<void>;
+	/** Open the current source in the host's editor. The overlay stays open. */
+	onExternalEditor?(): void | Promise<void>;
 }
 
 export interface CodeReviewOverlayCallbacks extends AnnotationOverlayCallbacks {
@@ -94,7 +106,8 @@ interface CommittedTextAnnotation {
 interface RenderedDiffBody {
 	lines: string[];
 	renderedRowBySource: number[];
-	selectedSourceLines: string[];
+	sourceIndexByRenderedRow: Array<number | undefined>;
+	selectedSourceLines: Array<string | undefined>;
 }
 
 interface RenderedBody {
@@ -136,7 +149,8 @@ function sanitizeStatusText(text: string): string {
 		.trim();
 }
 
-function splitTextLines(text: string): string[] {
+/** Splits a text source into the overlay's 1-based annotatable lines. */
+export function splitTextLines(text: string): string[] {
 	return text.split(/\r\n|\n|\r/);
 }
 
@@ -145,7 +159,8 @@ function isTextSource(value: readonly ReviewDiffFile[] | TextReviewSource): valu
 }
 
 /** A fullscreen, annotated diff picker that only relies on public OMP APIs. */
-export class AnnotationOverlay implements Component {
+export class AnnotationOverlay implements Focusable {
+	focused = false;
 	#scrollView: ScrollView;
 	#editor: Editor;
 	#focus: FocusRegion = "files";
@@ -159,6 +174,8 @@ export class AnnotationOverlay implements Component {
 	#editingAnnotationIndex: number | undefined;
 	#annotationChooser: AnnotationChooser | undefined;
 	#externalOperation = false;
+	/** Set once {@link replaceTextSource} runs; the paste result then carries the edited text. */
+	#textSourceEdited = false;
 	#finished = false;
 	#annotations: CommittedAnnotation[] = [];
 	#textAnnotations: CommittedTextAnnotation[] = [];
@@ -167,9 +184,11 @@ export class AnnotationOverlay implements Component {
 	#actions: readonly string[] = CODE_REVIEW_ACTIONS;
 	#textSource: TextReviewSource | undefined;
 	#textLines: readonly string[] = [];
-	#textViewportDriven = false;
-	#textRenderedRowBySource: readonly number[] = [];
-	#staticRenderedDiffBodies = new WeakMap<ReviewDiffFile, RenderedDiffBody>();
+	#viewportDriven = false;
+	/** Last viewport move went toward the end, so a viewport resting at its maximum offset selects the last visible row. */
+	#viewportTowardEnd = false;
+	#renderedRowBySource: readonly number[] = [];
+	#staticRenderedDiffBodies = new WeakMap<ReviewDiffFile, { width: number; body: RenderedDiffBody }>();
 	/** Bumped on every annotation change (each one pushes an undo snapshot) and on undo. */
 	#annotationRev = 0;
 	#nativeBody: NativeBody | undefined;
@@ -266,15 +285,16 @@ export class AnnotationOverlay implements Component {
 		});
 		this.#editor.setBorderVisible(false);
 		this.#editor.setPromptGutter("> ");
-		this.#editor.setUseTerminalCursor(false);
-		// Keep the editor's CURSOR_MARKER for terminal cursor placement, but
-		// replace its visible end-of-input caret with a stable blank cell.
-		this.#editor.cursorOverride = " ";
 		this.#editor.setScrollbarVisible(true);
 		this.#editor.onSubmit = value => this.#commitAnnotation(value);
 		this.#resetSourceCursor();
 	}
 
+	/** Keep the nested editor's cursor mode aligned with the overlay focus target. */
+	setUseTerminalCursor(useTerminalCursor: boolean): void {
+		this.#editor.setUseTerminalCursor(useTerminalCursor);
+	}
+
 	invalidate(): void {
 		this.#staticRenderedDiffBodies = new WeakMap();
 	}
@@ -291,6 +311,61 @@ export class AnnotationOverlay implements Component {
 		return this.#textAnnotations.map(entry => ({ ...entry.annotation }));
 	}
 
+	/** Repo-relative path of the diff file under the cursor, if this is a code review. */
+	reviewFilePath(): string | undefined {
+		const file = this.#files[this.#fileIndex];
+		if (!file) return undefined;
+		return file.newPath ?? file.oldPath ?? file.path;
+	}
+
+	/** Current text-source bytes, including edits applied by {@link replaceTextSource}. */
+	textSourceText(): string | undefined {
+		return this.#textSource?.text;
+	}
+
+	/**
+	 * Replace the text under review. Line notes whose quote still sits on the
+	 * same row stay; a quote that moved to exactly one row is retargeted;
+	 * every other line note is dropped. Returns how many were dropped.
+	 */
+	replaceTextSource(text: string): number {
+		if (!this.#textSource) return 0;
+		this.#textSource = { ...this.#textSource, text };
+		this.#textSourceEdited = true;
+		this.#textLines = splitTextLines(text);
+		this.#viewportDriven = false;
+		this.#sourceIndex = Math.min(this.#sourceIndex, Math.max(0, this.#textLines.length - 1));
+		let dropped = 0;
+		const kept: CommittedTextAnnotation[] = [];
+		for (const entry of this.#textAnnotations) {
+			if (entry.annotation.scope !== "line") {
+				kept.push(entry);
+				continue;
+			}
+			const quote = entry.annotation.quote;
+			if (this.#textLines[entry.sourceIndex] === quote) {
+				kept.push(entry);
+				continue;
+			}
+			const matches = this.#textLines.flatMap((line, index) => (line === quote ? [index] : []));
+			const only = matches.length === 1 ? matches[0] : undefined;
+			if (only !== undefined) {
+				kept.push({
+					sourceIndex: only,
+					annotation: { ...entry.annotation, line: only + 1 },
+				});
+				continue;
+			}
+			dropped++;
+		}
+		this.#textAnnotations = kept;
+		// Earlier snapshots hold notes anchored to the old text; undo must not resurrect them.
+		this.#undoStack = [];
+		this.#annotationRev++;
+		this.#nativeBody = undefined;
+		return dropped;
+	}
+
 	handleInput(data: string): void {
 		if (this.#finished || this.#externalOperation) return;
 		if (this.#annotationChooser) {
@@ -310,7 +385,11 @@ export class AnnotationOverlay implements Component {
 			return;
 		}
 		if (this.#keybindings.matches(data, "tui.select.cancel")) {
-			this.#finish(undefined);
+			this.#escape();
+			return;
+		}
+		if (this.#callbacks.onExternalEditor && matchesAppExternalEditor(data)) {
+			void this.#openSourceEditor();
 			return;
 		}
 		if (data === "A" && (this.#focus === "files" || this.#focus === "diff")) {
@@ -362,6 +441,13 @@ export class AnnotationOverlay implements Component {
 		}
 	}
 
+	/** Esc, by state: leave the note chooser, drop the note draft, else close the review. */
+	#escape(): void {
+		if (this.#annotationChooser) this.#annotationChooser = undefined;
+		else if (this.#annotating) this.#cancelAnnotation();
+		else this.#finish(undefined);
+	}
+
 	#cycleFocus(direction: number): void {
 		const regions: FocusRegion[] = this.#sidebarShown ? ["files", "diff", "actions"] : ["diff", "actions"];
 		const current = regions.indexOf(this.#focus);
@@ -417,34 +503,48 @@ export class AnnotationOverlay implements Component {
 			return;
 		}
 		if (this.#keybindings.matches(data, "tui.select.pageUp")) {
-			if (this.#textSource) {
-				this.#scrollView.page(-1);
-				this.#textViewportDriven = true;
-				this.#syncTextCursorToViewport();
-			} else {
+			if (this.#tui.nativeRendering && !this.#textSource) {
 				this.#moveSourceCursor(-Math.max(1, this.#bodyHeight - 1));
+			} else {
+				this.#scrollView.page(-1);
+				this.#viewportDriven = true;
+				this.#viewportTowardEnd = false;
+				this.#syncCursorToViewport();
 			}
 			return;
 		}
 		if (this.#keybindings.matches(data, "tui.select.pageDown")) {
-			if (this.#textSource) {
-				this.#scrollView.page(1);
-				this.#textViewportDriven = true;
-				this.#syncTextCursorToViewport();
-			} else {
+			if (this.#tui.nativeRendering && !this.#textSource) {
 				this.#moveSourceCursor(Math.max(1, this.#bodyHeight - 1));
+			} else {
+				this.#scrollView.page(1);
+				this.#viewportDriven = true;
+				this.#viewportTowardEnd = true;
+				this.#syncCursorToViewport();
 			}
 			return;
 		}
 		if (data === "g" || matchesKey(data, "home")) {
 			this.#sourceIndex = 0;
-			this.#textViewportDriven = false;
+			if (this.#textSource || this.#tui.nativeRendering) {
+				this.#viewportDriven = false;
+			} else {
+				this.#scrollView.scrollToTop();
+				this.#viewportDriven = true;
+				this.#viewportTowardEnd = false;
+			}
 		} else if (data === "G" || matchesKey(data, "end")) {
 			this.#sourceIndex = Math.max(
 				0,
 				(this.#textSource ? this.#textLines.length : this.#currentSourceRows().length) - 1,
 			);
-			this.#textViewportDriven = false;
+			if (this.#textSource || this.#tui.nativeRendering) {
+				this.#viewportDriven = false;
+			} else {
+				this.#scrollView.scrollToBottom();
+				this.#viewportDriven = true;
+				this.#viewportTowardEnd = true;
+			}
 		}
 	}
 
@@ -478,6 +578,7 @@ export class AnnotationOverlay implements Component {
 			this.#finish({
 				action: "paste",
 				annotations: this.getTextAnnotations(),
+				...(this.#textSourceEdited ? { editedText: this.#textSource.text } : {}),
 			});
 		} else {
 			this.#finish({
@@ -501,6 +602,7 @@ export class AnnotationOverlay implements Component {
 
 	#resetSourceCursor(): void {
 		this.#sourceIndex = 0;
+		this.#viewportDriven = false;
 	}
 
 	#currentFile(): ReviewDiffFile | undefined {
@@ -511,20 +613,20 @@ export class AnnotationOverlay implements Component {
 		const file = this.#currentFile();
 		return file ? file.rows.filter(isSourceRow) : [];
 	}
-	#syncTextCursorToViewport(): void {
-		if (!this.#textSource || this.#textRenderedRowBySource.length === 0) return;
+	#syncCursorToViewport(): void {
+		if (this.#renderedRowBySource.length === 0) return;
 		const viewportTop = this.#scrollView.getScrollOffset();
 		const viewportBottom = viewportTop + Math.max(0, this.#bodyHeight - 1);
 		let topSourceIndex = 0;
 		let lastVisibleSourceIndex = 0;
-		for (let index = 1; index < this.#textRenderedRowBySource.length; index++) {
-			const renderedRow = this.#textRenderedRowBySource[index];
+		for (let index = 1; index < this.#renderedRowBySource.length; index++) {
+			const renderedRow = this.#renderedRowBySource[index];
 			if (renderedRow === undefined || renderedRow > viewportBottom) break;
 			lastVisibleSourceIndex = index;
 			if (renderedRow <= viewportTop) topSourceIndex = index;
 		}
-		const atBottom =
-			this.#scrollView.getMaxScrollOffset() > 0 && viewportTop === this.#scrollView.getMaxScrollOffset();
+		// A short pane has no scroll range, so paging toward the end must still reach the last row.
+		const atBottom = this.#viewportTowardEnd && viewportTop >= this.#scrollView.getMaxScrollOffset();
 		this.#sourceIndex = atBottom ? lastVisibleSourceIndex : topSourceIndex;
 	}
 
@@ -532,7 +634,7 @@ export class AnnotationOverlay implements Component {
 		const rowCount = this.#textSource ? this.#textLines.length : this.#currentSourceRows().length;
 		if (rowCount === 0) return;
 		this.#sourceIndex = Math.max(0, Math.min(rowCount - 1, this.#sourceIndex + delta));
-		if (this.#textSource) this.#textViewportDriven = false;
+		this.#viewportDriven = false;
 	}
 
 	#startAnnotation(scope: AnnotationScope, existingIndex?: number): void {
@@ -795,6 +897,22 @@ export class AnnotationOverlay implements Component {
 		}
 	}
 
+	async #openSourceEditor(): Promise<void> {
+		const openEditor = this.#callbacks.onExternalEditor;
+		if (this.#externalOperation || !openEditor) return;
+		this.#externalOperation = true;
+		try {
+			await openEditor();
+		} catch (error) {
+			this.#callbacks.onWarning?.(
+				`Failed to open external editor: ${error instanceof Error ? error.message : String(error)}`,
+			);
+		} finally {
+			this.#externalOperation = false;
+			this.#tui.requestRender(true);
+		}
+	}
+
 	#annotationCount(fileIndex: number): number {
 		let count = 0;
 		for (const entry of this.#annotations) if (entry.fileIndex === fileIndex) count++;
@@ -809,7 +927,7 @@ export class AnnotationOverlay implements Component {
 				lines: [this.#theme.fg("dim", "No reviewable files")],
 				renderedRowBySource: [],
 			};
-		const staticBody = this.#getStaticRenderedBody(file);
+		const staticBody = this.#getStaticRenderedBody(file, contentWidth);
 		const lines: string[] = [];
 		const renderedRowBySource: number[] = [];
 
@@ -821,12 +939,10 @@ export class AnnotationOverlay implements Component {
 			}
 		}
 
-		let sourceIndex = 0;
 		for (let staticRow = 0; staticRow < staticBody.lines.length; staticRow++) {
-			const currentSourceIndex =
-				staticBody.renderedRowBySource[sourceIndex] === staticRow ? sourceIndex++ : undefined;
+			const currentSourceIndex = staticBody.sourceIndexByRenderedRow[staticRow];
 			let renderedLine = staticBody.lines[staticRow] ?? "";
-			if (currentSourceIndex !== undefined) {
+			if (currentSourceIndex !== undefined && staticBody.renderedRowBySource[currentSourceIndex] === staticRow) {
 				// Line notes belong immediately before their source row. This keeps
 				// the selected row and all notes in a stable, readable order.
 				for (const entry of this.#annotations) {
@@ -839,12 +955,10 @@ export class AnnotationOverlay implements Component {
 					}
 				}
 				renderedRowBySource[currentSourceIndex] = lines.length;
-				if (this.#focus === "diff" && currentSourceIndex === this.#sourceIndex) {
-					renderedLine = this.#theme.bg(
-						"selectedBg",
-						fit(staticBody.selectedSourceLines[currentSourceIndex] ?? "", contentWidth),
-					);
-				}
+			}
+			if (this.#focus === "diff" && currentSourceIndex === this.#sourceIndex) {
+				renderedLine = staticBody.selectedSourceLines[staticRow] ?? renderedLine;
+				renderedLine = this.#theme.bg("selectedBg", fit(renderedLine, contentWidth));
 			}
 			lines.push(truncateToWidth(renderedLine, contentWidth));
 		}
@@ -870,8 +984,7 @@ export class AnnotationOverlay implements Component {
 			}
 			renderedRowBySource[sourceIndex] = lines.length;
 			const displayLine = replaceTabs(sanitizeText(sourceLine));
-			const wrapped = wrapTextWithAnsi(displayLine, textWidth);
-			const visualRows = wrapped.length > 0 ? wrapped : [""];
+			const visualRows = wrapLiteralLine(displayLine, textWidth);
 			for (const [rowIndex, visualRow] of visualRows.entries()) {
 				const selected = this.#focus === "diff" && sourceIndex === this.#sourceIndex;
 				const gutter =
@@ -885,47 +998,63 @@ export class AnnotationOverlay implements Component {
 		return { lines, renderedRowBySource };
 	}
 
-	#getStaticRenderedBody(file: ReviewDiffFile): RenderedDiffBody {
+	#getStaticRenderedBody(file: ReviewDiffFile, contentWidth: number): RenderedDiffBody {
+		const normalizedWidth = Math.max(1, Math.floor(contentWidth));
 		const cached = this.#staticRenderedDiffBodies.get(file);
-		if (cached) return cached;
+		if (cached?.width === normalizedWidth) return cached.body;
 		const lines: string[] = [];
 		const renderedRowBySource: number[] = [];
-		const selectedSourceLines: string[] = [];
+		const sourceIndexByRenderedRow: Array<number | undefined> = [];
+		const selectedSourceLines: Array<string | undefined> = [];
+		const pushStaticLine = (line: string) => {
+			lines.push(line);
+			sourceIndexByRenderedRow.push(undefined);
+			selectedSourceLines.push(undefined);
+		};
 		if (file.isBinary) {
-			lines.push(this.#theme.fg("dim", "Binary diff; no annotatable source rows"));
+			pushStaticLine(this.#theme.fg("dim", "Binary diff; no annotatable source rows"));
 		} else if (file.rows.length === 0) {
-			lines.push(this.#theme.fg("dim", "No diff hunks; this may be a rename-only change"));
+			pushStaticLine(this.#theme.fg("dim", "No diff hunks; this may be a rename-only change"));
 		} else {
 			let sourceIndex = 0;
 			for (const diffRow of file.rows) {
 				if (!isSourceRow(diffRow)) {
-					lines.push(
+					pushStaticLine(
 						this.#theme.fg(diffRow.kind === "hunk" ? "accent" : "dim", replaceTabs(sanitizeText(diffRow.raw))),
 					);
 					continue;
 				}
-				renderedRowBySource[sourceIndex] = lines.length;
 				const marker = diffRow.kind === "added" ? "+" : diffRow.kind === "removed" ? "-" : " ";
 				const lineNumber = diffRow.kind === "removed" ? diffRow.oldLine : (diffRow.newLine ?? diffRow.oldLine);
-				const suffix = `${marker}${String(lineNumber ?? "").padStart(4)} ${replaceTabs(sanitizeText(diffRow.content))}`;
-				const color: DiffColor =
+				const prefix = `${marker}${String(lineNumber ?? "").padStart(4)} `;
+				const prefixWidth = visibleWidth(prefix);
+				const contentColor: DiffColor =
 					diffRow.kind === "added"
 						? "toolDiffAdded"
 						: diffRow.kind === "removed"
 							? "toolDiffRemoved"
 							: "toolDiffContext";
-				const coloredSuffix = this.#theme.fg(color, suffix);
-				const gutter = " ".repeat(SOURCE_SELECTION_GUTTER_WIDTH);
-				selectedSourceLines[sourceIndex] = `${fit(
-					`${this.#theme.nav.cursor} `,
-					SOURCE_SELECTION_GUTTER_WIDTH,
-				)}${coloredSuffix}`;
-				lines.push(`${gutter}${coloredSuffix}`);
+				const sourceContent = replaceTabs(sanitizeText(diffRow.content));
+				const contentWidthForRow = Math.max(1, normalizedWidth - SOURCE_SELECTION_GUTTER_WIDTH - prefixWidth);
+				const visualRows = wrapLiteralLine(sourceContent, contentWidthForRow);
+				const firstRenderedRow = lines.length;
+				renderedRowBySource[sourceIndex] = firstRenderedRow;
+				for (const [rowIndex, visualRow] of visualRows.entries()) {
+					const first = rowIndex === 0;
+					const gutter = " ".repeat(SOURCE_SELECTION_GUTTER_WIDTH);
+					const continuationPrefix = " ".repeat(prefixWidth);
+					const prefixForRow = first ? this.#theme.fg(contentColor, prefix) : continuationPrefix;
+					const selectedGutter = first ? fit(`${this.#theme.nav.cursor} `, SOURCE_SELECTION_GUTTER_WIDTH) : gutter;
+					const styledRow = this.#theme.fg(contentColor, visualRow);
+					lines.push(`${gutter}${prefixForRow}${styledRow}`);
+					sourceIndexByRenderedRow.push(sourceIndex);
+					selectedSourceLines.push(`${selectedGutter}${prefixForRow}${styledRow}`);
+				}
 				sourceIndex++;
 			}
 		}
-		const body = { lines, renderedRowBySource, selectedSourceLines };
-		this.#staticRenderedDiffBodies.set(file, body);
+		const body = { lines, renderedRowBySource, sourceIndexByRenderedRow, selectedSourceLines };
+		this.#staticRenderedDiffBodies.set(file, { width: normalizedWidth, body });
 		return body;
 	}
 
@@ -1027,6 +1156,7 @@ export class AnnotationOverlay implements Component {
 	}
 
 	#renderFooter(width: number, maxChooserRows = Number.POSITIVE_INFINITY): string[] {
+		this.#editor.focused = this.focused && this.#annotating;
 		if (this.#annotationChooser) {
 			return this.#renderAnnotationChooser(width, maxChooserRows);
 		}
@@ -1042,9 +1172,7 @@ export class AnnotationOverlay implements Component {
 				`${editorKey("tui.input.newLine")} newline`,
 				`${this.#key("tui.select.cancel")} cancel`,
 			];
-			const externalEditorKey = appKey(this.#keybindings, "app.editor.external");
-			if (externalEditorKey) hints.push(`${externalEditorKey} editor`);
-			this.#editor.focused = true;
+			hints.push(`${formatKeyHint(appExternalEditorKey())} editor`);
 			return [caption, ...this.#editor.render(width), this.#theme.fg("dim", hints.join(" · "))];
 		}
 		return [this.#theme.fg("dim", this.#helpText())];
@@ -1095,16 +1223,23 @@ export class AnnotationOverlay implements Component {
 				: this.#focus === "diff"
 					? `${upDown} line · ${formatKeyHint("shift")} faster · ${this.#key("tui.select.pageUp")}/${this.#key("tui.select.pageDown")} · ${formatKeyHints(["g", "shift+g"])} ends · ${formatKeyHint("a")} line note · ${formatKeyHint("shift+a")} ${this.#textSource ? "text" : "file"} note · ${editNote}`
 					: `${upDown} select · ${confirm} confirm`;
-		return `${focusHelp} · ${formatKeyHint("u")} undo · ${formatKeyHint("tab")} regions · ${this.#key("tui.select.cancel")} cancel`;
+		const editorHint = this.#callbacks.onExternalEditor ? ` · ${formatKeyHint(appExternalEditorKey())} editor` : "";
+		return `${focusHelp} · ${formatKeyHint("u")} undo · ${formatKeyHint("tab")} regions${editorHint} · ${this.#key("tui.select.cancel")} cancel`;
 	}
 
-	#ensureCursorVisible(renderedRowBySource: readonly number[]): void {
-		if (this.#textSource && this.#textViewportDriven) return;
+	#ensureCursorVisible(renderedRowBySource: readonly number[]): boolean {
+		this.#renderedRowBySource = renderedRowBySource;
+		if (this.#viewportDriven) {
+			const sourceIndex = this.#sourceIndex;
+			if (!this.#annotating && !this.#annotationChooser) this.#syncCursorToViewport();
+			return this.#sourceIndex !== sourceIndex;
+		}
 		const rowIndex = renderedRowBySource[this.#sourceIndex];
-		if (rowIndex === undefined) return;
+		if (rowIndex === undefined) return false;
 		const offset = this.#scrollView.getScrollOffset();
 		if (rowIndex < offset) this.#scrollView.setScrollOffset(rowIndex);
 		else if (rowIndex >= offset + this.#bodyHeight) this.#scrollView.setScrollOffset(rowIndex - this.#bodyHeight + 1);
+		return false;
 	}
 
 	#sidebarWidth(width: number): number {
@@ -1117,19 +1252,31 @@ export class AnnotationOverlay implements Component {
 		);
 	}
 
+	#sidebarStart(rows: number): number {
+		return Math.max(0, Math.min(this.#fileIndex - Math.floor(rows / 2), Math.max(0, this.#files.length - rows)));
+	}
+
+	#renderSidebarBadge(file: ReviewDiffFile, count: number): string {
+		const changes = ` +${file.linesAdded}/-${file.linesRemoved}`;
+		const annotations = count ? ` ✎${count}` : "";
+		return this.#theme.fg("dim", changes) + (annotations ? this.#theme.fg("warning", annotations) : "");
+	}
+
+	#sidebarLabelWidth(file: ReviewDiffFile, count: number, width: number): number {
+		const badge = this.#renderSidebarBadge(file, count);
+		return Math.max(0, width - visibleWidth(badge) - 2);
+	}
+
 	#renderSidebar(rows: number, width: number): string[] {
-		const start = Math.max(
-			0,
-			Math.min(this.#fileIndex - Math.floor(rows / 2), Math.max(0, this.#files.length - rows)),
-		);
+		const start = this.#sidebarStart(rows);
 		return Array.from({ length: rows }, (_, rowIndex) => {
 			const index = start + rowIndex;
 			const file = this.#files[index];
 			if (!file) return "";
 			const selected = index === this.#fileIndex;
 			const count = this.#annotationCount(index);
-			const badge = `${this.#theme.fg("dim", ` +${file.linesAdded}/-${file.linesRemoved}`)}${count ? this.#theme.fg("warning", ` ✎${count}`) : ""}`;
-			const available = Math.max(0, width - visibleWidth(badge) - 2);
+			const badge = this.#renderSidebarBadge(file, count);
+			const available = this.#sidebarLabelWidth(file, count, width);
 			const label = truncateToWidth(sanitizeStatusText(displayFileLabel(file)), available, Ellipsis.Unicode);
 			const cursor = selected ? (this.#focus === "files" ? "› " : "▎ ") : "  ";
 			const line = fit(`${cursor}${label}${badge}`, width);
@@ -1139,13 +1286,59 @@ export class AnnotationOverlay implements Component {
 		});
 	}
 
+	#revealSelectedFile(output: string[], width: number): void {
+		const file = this.#currentFile();
+		if (
+			!file ||
+			!this.#sidebarShown ||
+			this.#textSource ||
+			this.#focus !== "files" ||
+			this.#annotating ||
+			this.#annotationChooser
+		) {
+			return;
+		}
+
+		const pathColumn = 4;
+		const lineWidth = Math.max(0, width - pathColumn - 1);
+		if (lineWidth === 0) return;
+
+		const selectedRow = 1 + this.#fileIndex - this.#sidebarStart(this.#bodyHeight + 1);
+		const interiorTop = 1;
+		const lastBodyRow = this.#bodyHeight + 1;
+		const interiorRows = lastBodyRow - interiorTop + 1;
+		if (selectedRow < interiorTop || selectedRow > lastBodyRow || interiorRows <= 0) return;
+
+		const label = replaceTabs(sanitizeStatusText(displayFileLabel(file)));
+		if (!label) return;
+		const count = this.#annotationCount(this.#fileIndex);
+		if (visibleWidth(label) <= this.#sidebarLabelWidth(file, count, this.#sidebarWidth(width))) return;
+
+		let wrapped = wrapTextWithAnsi(label, lineWidth);
+		if (wrapped.length > interiorRows) {
+			wrapped = wrapped.slice(-interiorRows);
+			wrapped[0] = truncateToWidth(`…${wrapped[0] ?? ""}`, lineWidth, Ellipsis.Omit);
+		}
+		const overlayTop = Math.max(interiorTop, Math.min(selectedRow, lastBodyRow - wrapped.length + 1));
+		const overlayWidth = Math.min(lineWidth, Math.max(0, ...wrapped.map(visibleWidth)) + 1);
+		for (const [index, line] of wrapped.entries()) {
+			const highlighted = this.#theme.bg("selectedBg", this.#theme.bold(fit(line, overlayWidth)));
+			const targetRow = overlayTop + index;
+			const baseLine = output[targetRow];
+			if (overlayWidth > 0 && baseLine !== undefined) {
+				output[targetRow] = compositeLineAt(baseLine, highlighted, pathColumn, overlayWidth, width);
+			}
+		}
+	}
+
 	describe(): NativeNode {
 		// The terminal lays out the file sidebar; diffs always have one, text never does.
 		this.#sidebarShown = !this.#textSource;
 		if (!this.#sidebarShown && this.#focus === "files") this.#focus = "diff";
 		// Page size for PgUp/PgDn, matching the rendered body height.
-		this.#bodyHeight = Math.max(MIN_BODY_ROWS, (process.stdout.rows || 40) - (this.#actions.length + 8));
-		this.#editor.focused = this.#annotating;
+		const terminalHeight = this.#tui.terminal.rows;
+		this.#bodyHeight = Math.max(MIN_BODY_ROWS, terminalHeight - (this.#actions.length + 8));
+		this.#editor.focused = this.focused && this.#annotating;
 		const body = this.#describeBodyItems();
 		const chooser = this.#annotationChooser;
 		const sig = [
@@ -1166,7 +1359,10 @@ export class AnnotationOverlay implements Component {
 			role: this.#textSource ? "zeta.overlay.annotateText.lines" : "zeta.overlay.codeReview.diff",
 			tone: this.#focus === "diff" ? "accent" : undefined,
 		});
-		const main = node("col", { grow: 1 }, [this.#describeHeader(), lines], "main");
+		// 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");
 		if (this.#sidebarShown) {
 			const files = selectList(
 				"files",
@@ -1215,6 +1411,10 @@ export class AnnotationOverlay implements Component {
 
 	handleNativeEvent(event: NativeUiEvent): void {
 		if (this.#finished || this.#externalOperation) return;
+		if (event.type === "action" && event.act === "close") {
+			this.#escape();
+			return;
+		}
 		if (event.type !== "select" && event.type !== "activate") return;
 		const activate = event.type === "activate";
 		const leaf = leafKey(event.key);
@@ -1244,7 +1444,7 @@ export class AnnotationOverlay implements Component {
 				if (index < 0 || index >= rowCount) return;
 				this.#focus = "diff";
 				this.#sourceIndex = index;
-				this.#textViewportDriven = false;
+				this.#viewportDriven = false;
 				if (activate) this.#focus = "actions";
 				return;
 			}
@@ -1404,7 +1604,7 @@ export class AnnotationOverlay implements Component {
 						this.#hint("tui.input.submit", "save"),
 						this.#hint("tui.input.newLine", "newline"),
 						this.#hint("tui.select.cancel", "cancel"),
-						this.#hint("app.editor.external", "editor"),
+						{ keys: [appExternalEditorKey()], label: "editor" },
 					],
 					"annotateHints",
 				),
@@ -1430,6 +1630,7 @@ export class AnnotationOverlay implements Component {
 							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)];
 	}
@@ -1445,14 +1646,14 @@ export class AnnotationOverlay implements Component {
 	}
 
 	render(width: number): readonly string[] {
-		const terminalHeight = process.stdout.rows || 40;
+		const terminalHeight = this.#tui.terminal.rows;
 		this.#sidebarShown = this.#textSource ? false : this.#canShowSidebar(width);
 		if (!this.#sidebarShown && this.#focus === "files") this.#focus = "diff";
 		const sidebarWidth = this.#sidebarShown ? this.#sidebarWidth(width) : 0;
 		const innerWidth = Math.max(1, width - 4);
 		const bodyWidth = this.#sidebarShown ? splitBodyWidth(width, sidebarWidth) : innerWidth;
 		this.#editor.setMaxHeight(Math.max(1, Math.min(MAX_ANNOTATION_EDITOR_ROWS, terminalHeight - 12)));
-		this.#editor.focused = this.#annotating;
+		this.#editor.focused = this.focused && this.#annotating;
 		const chooserBaseRows = terminalHeight - (this.#actions.length + 7);
 		const chooserFooterRows = this.#annotationChooser
 			? Math.max(0, Math.min(chooserBaseRows, Math.max(3, chooserBaseRows - MIN_BODY_ROWS)))
@@ -1463,14 +1664,15 @@ export class AnnotationOverlay implements Component {
 		this.#bodyHeight = this.#annotationChooser
 			? Math.max(0, availableBodyRows)
 			: Math.max(MIN_BODY_ROWS, availableBodyRows);
-		const renderedBody = this.#renderBody(this.#textSource ? Math.max(1, bodyWidth - 1) : bodyWidth);
+		const bodyContentWidth = Math.max(1, bodyWidth - 1);
+		let renderedBody = this.#renderBody(bodyContentWidth);
 		this.#scrollView.setLines(renderedBody.lines);
 		this.#scrollView.setHeight(this.#bodyHeight);
-		if (this.#textSource) {
-			this.#textRenderedRowBySource = renderedBody.renderedRowBySource;
-			if (this.#textViewportDriven) this.#syncTextCursorToViewport();
+		if (this.#ensureCursorVisible(renderedBody.renderedRowBySource)) {
+			renderedBody = this.#renderBody(bodyContentWidth);
+			this.#scrollView.setLines(renderedBody.lines);
+			this.#renderedRowBySource = renderedBody.renderedRowBySource;
 		}
-		this.#ensureCursorVisible(renderedBody.renderedRowBySource);
 		const body = this.#scrollView.render(bodyWidth);
 		const output: string[] = [];
 		if (this.#sidebarShown) {
@@ -1492,6 +1694,7 @@ export class AnnotationOverlay implements Component {
 		output.push(divider(width));
 		for (const footerLine of footer) output.push(row(footerLine, width));
 		output.push(bottomBorder(width));
+		this.#revealSelectedFile(output, width);
 		return output;
 	}
 }