@oh-my-pi/pi-tui 18.6.3 → 18.7.0

package/src/fuzzy.ts

@@ -307,11 +307,11 @@ function scoreTokenDirect(token: string, index: SearchIndex): FuzzyMatch {
 	return best ?? { matches: false, score: 0 };
 }
 
-function scoreToken(token: string, index: SearchIndex): FuzzyMatch {
+function scoreToken(token: string, swapVariants: readonly string[], index: SearchIndex): FuzzyMatch {
 	let best = scoreTokenDirect(token, index);
 	if (best.matches) return best;
 
-	for (const variant of buildAlphanumericSwapQueries(token)) {
+	for (const variant of swapVariants) {
 		const match = scoreTokenDirect(variant, index);
 		if (!match.matches) continue;
 		const score = match.score + ALPHANUMERIC_SWAP_PENALTY;
@@ -323,18 +323,26 @@ function scoreToken(token: string, index: SearchIndex): FuzzyMatch {
 	return best;
 }
 
-/** A query normalized and split once, so `fuzzyRank` doesn't re-normalize the
- * same query for every candidate in the list. */
+/** A query normalized and split once, so ranking doesn't re-normalize the
+ * same query (or rebuild its alphanumeric-swap variants) for every candidate. */
 interface PreparedQuery {
 	normalized: string;
 	tokens: string[];
+	/** `buildAlphanumericSwapQueries` of each token, index-aligned with `tokens`. */
+	tokenSwaps: string[][];
 	compact: string;
 }
 
 function prepareQuery(query: string): PreparedQuery | null {
 	const normalized = normalizeForSearch(query);
 	if (normalized.length === 0) return null;
-	return { normalized, tokens: normalized.split(" "), compact: normalized.replaceAll(" ", "") };
+	const tokens = normalized.split(" ");
+	return {
+		normalized,
+		tokens,
+		tokenSwaps: tokens.map(buildAlphanumericSwapQueries),
+		compact: normalized.replaceAll(" ", ""),
+	};
 }
 
 function fuzzyMatchCore(pq: PreparedQuery | null, index: SearchIndex): FuzzyMatch {
@@ -359,8 +367,8 @@ function fuzzyMatchCore(pq: PreparedQuery | null, index: SearchIndex): FuzzyMatc
 		totalScore += compactPhraseIndex * 0.01;
 	}
 
-	for (const token of pq.tokens) {
-		const match = scoreToken(token, index);
+	for (let i = 0; i < pq.tokens.length; i++) {
+		const match = scoreToken(pq.tokens[i]!, pq.tokenSwaps[i]!, index);
 		if (!match.matches) {
 			return { matches: false, score: 0 };
 		}
@@ -399,6 +407,49 @@ export class FuzzyText {
 	}
 }
 
+/**
+ * Items prepared once for repeated {@link fuzzyRank}-equivalent ranking.
+ *
+ * `fuzzyRank` resolves each candidate's search index through the module cache,
+ * which stops admitting entries at {@link INDEX_CACHE_MAX}; larger candidate
+ * lists (the full model catalog) rebuild the overflow on every query. Hold one
+ * corpus per stable candidate list and call {@link rank} per keystroke instead.
+ */
+export class FuzzyCorpus<T> {
+	readonly #items: readonly T[];
+	readonly #indexes: SearchIndex[];
+
+	constructor(items: readonly T[], getText: (item: T) => string) {
+		this.#items = items;
+		this.#indexes = items.map(item => buildUncachedSearchIndex(getText(item)));
+	}
+
+	/** Same results as `fuzzyRank(items, query, getText)` for the prepared items. */
+	rank(query: string): FuzzyFilterResult<T>[] {
+		if (!query.trim()) return this.#items.map(item => ({ item, score: 0 }));
+		const indexes = this.#indexes;
+		return rankIndexed(this.#items, prepareQuery(query), i => indexes[i]!);
+	}
+}
+
+function rankIndexed<T>(
+	items: readonly T[],
+	pq: PreparedQuery | null,
+	indexAt: (i: number) => SearchIndex,
+): FuzzyFilterResult<T>[] {
+	const results: FuzzyFilterResult<T>[] = [];
+	for (let i = 0; i < items.length; i++) {
+		const index = indexAt(i);
+		const match = pq === null ? { matches: true, score: 0 } : fuzzyMatchCore(pq, index);
+		if (match.matches) {
+			results.push({ item: items[i]!, score: match.score });
+		}
+	}
+
+	results.sort((a, b) => a.score - b.score);
+	return results;
+}
+
 /**
  * Filter and sort items by fuzzy match quality (best matches first).
  * Supports space-separated tokens: all tokens must match.
@@ -411,18 +462,7 @@ export function fuzzyRank<T>(items: readonly T[], query: string, getText: (item:
 	// A non-blank query that normalizes to empty (pure punctuation) matches
 	// everything with score 0, but still calls getText per item — consumers rely
 	// on its side effects (see fuzzy-cache.test.ts).
-	const pq = prepareQuery(query);
-	const results: FuzzyFilterResult<T>[] = [];
-	for (const item of items) {
-		const text = getText(item);
-		const match = pq === null ? { matches: true, score: 0 } : fuzzyMatchCore(pq, buildSearchIndex(text));
-		if (match.matches) {
-			results.push({ item, score: match.score });
-		}
-	}
-
-	results.sort((a, b) => a.score - b.score);
-	return results;
+	return rankIndexed(items, prepareQuery(query), i => buildSearchIndex(getText(items[i]!)));
 }
 
 export function fuzzyFilter<T>(items: T[], query: string, getText: (item: T) => string): T[] {

package/src/keybindings.ts

@@ -105,7 +105,7 @@ export const TUI_KEYBINDINGS = {
 		description: "Delete word backward",
 	},
 	"tui.editor.deleteWordForward": {
-		defaultKeys: ["alt+delete", "alt+d", "super+alt+delete", "super+alt+d"],
+		defaultKeys: ["alt+delete", "alt+d", "ctrl+delete", "super+alt+delete", "super+alt+d"],
 		description: "Delete word forward",
 	},
 	"tui.editor.deleteToLineStart": {

package/src/overlays/agent-transcript-viewer.ts

@@ -201,6 +201,8 @@ export class AgentTranscriptViewer implements Component {
 			hideThinkingBlock: deps.hideThinkingBlock,
 			proseOnlyThinking: deps.proseOnlyThinking,
 			expandThinkingBlocks: deps.expandThinkingBlocks,
+			// Charts are for the main session's answers, not parked subagent, advisor, or guest transcripts.
+			tableCharts: false,
 			requestRender: deps.requestRender,
 		});
 		this.#browser = new TranscriptBrowser({

package/src/overlays/agents-hub.ts

@@ -141,6 +141,11 @@ export interface AgentsHubCallbacks {
 const IDENTIFIER_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+){1,5}$/;
 
 function extractJsonObject(raw: string): string {
+	// A bare JSON object may legitimately contain code fences inside string values; keep it intact.
+	try {
+		JSON.parse(raw);
+		return raw;
+	} catch {}
 	const fenceMatch = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
 	if (fenceMatch?.[1]) return fenceMatch[1].trim();
 	const start = raw.indexOf("{");
@@ -149,7 +154,15 @@ function extractJsonObject(raw: string): string {
 	return raw.trim();
 }
 
-function parseGeneratedAgentSpec(raw: string): GeneratedAgentSpec {
+/**
+ * Parse model output into a {@link GeneratedAgentSpec}. Accepts a bare JSON object
+ * (tried first) or one wrapped in a code fence. Returns the spec with trimmed fields.
+ * Throws if the output is not valid JSON or not an object, if `identifier`, `whenToUse`
+ * or `systemPrompt` is missing or not a string, if the identifier is not lowercase
+ * kebab-case with 2+ words, if `whenToUse` does not start with "Use this agent when",
+ * or if `systemPrompt` is empty.
+ */
+export function parseGeneratedAgentSpec(raw: string): GeneratedAgentSpec {
 	const parsed = JSON.parse(extractJsonObject(raw)) as Partial<GeneratedAgentSpec>;
 	if (!parsed || typeof parsed !== "object") {
 		throw new Error("Model output is not a JSON object");

package/src/overlays/annotation-overlay.ts

@@ -1,5 +1,5 @@
 import {
-	type Component,
+	type Focusable,
 	Editor,
 	Ellipsis,
 	matchesKey,
@@ -11,6 +11,8 @@ import {
 	visibleWidth,
 	wrapTextWithAnsi,
 } from "../index";
+import { compositeLineAt } from "../render/composite";
+import { wrapLiteralLine } from "../utils";
 import { appKey, editorKey } from "../chrome/keybinding-hints";
 import { formatKeyHint, formatKeyHints, type KeybindingsManager } from "../app-keybindings";
 import type { Keybinding } from "../keybindings";
@@ -94,7 +96,8 @@ interface CommittedTextAnnotation {
 interface RenderedDiffBody {
 	lines: string[];
 	renderedRowBySource: number[];
-	selectedSourceLines: string[];
+	sourceIndexByRenderedRow: Array<number | undefined>;
+	selectedSourceLines: Array<string | undefined>;
 }
 
 interface RenderedBody {
@@ -145,7 +148,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";
@@ -167,9 +171,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 +272,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();
 	}
@@ -417,34 +424,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;
+			}
 		}
 	}
 
@@ -501,6 +522,7 @@ export class AnnotationOverlay implements Component {
 
 	#resetSourceCursor(): void {
 		this.#sourceIndex = 0;
+		this.#viewportDriven = false;
 	}
 
 	#currentFile(): ReviewDiffFile | undefined {
@@ -511,20 +533,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 +554,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 {
@@ -809,7 +831,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 +843,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 +859,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 +888,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 +902,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 +1060,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);
 		}
@@ -1044,7 +1078,6 @@ export class AnnotationOverlay implements Component {
 			];
 			const externalEditorKey = appKey(this.#keybindings, "app.editor.external");
 			if (externalEditorKey) hints.push(`${externalEditorKey} editor`);
-			this.#editor.focused = true;
 			return [caption, ...this.#editor.render(width), this.#theme.fg("dim", hints.join(" · "))];
 		}
 		return [this.#theme.fg("dim", this.#helpText())];
@@ -1098,13 +1131,19 @@ export class AnnotationOverlay implements Component {
 		return `${focusHelp} · ${formatKeyHint("u")} undo · ${formatKeyHint("tab")} regions · ${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 +1156,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 +1190,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 = [
@@ -1244,7 +1341,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;
 			}
@@ -1445,14 +1542,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 +1560,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 +1590,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;
 	}
 }