@danypops/pi-lector 0.13.7 → 0.13.11

package/extension/src/code-intelligence/operations.ts

@@ -1,5 +1,9 @@
 import type { JobSnapshot, OperationInputs, OperationOutputs, PopulateSymbolGraphResult, SymbolEdgeKind, SymbolNode } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForCodeIntelligencePath, workspaceForPathOrDirectory } from "../lector-client.ts";
+import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
+
+const CODE_ACTION_PREVIEW_PERMISSIONS = ["workspace:read"];
+const CODE_ACTION_APPLY_PERMISSIONS = ["workspace:write"];
 
 /**
  * Thin wrappers over Lector's code-intelligence operations: goToDefinition,
@@ -34,9 +38,50 @@ export interface CodeIntelligenceOperations {
 	hover(path: string, line: number, character: number): Promise<OperationOutputs["workspace.hover"]>;
 	documentSymbols(path: string): Promise<OperationOutputs["workspace.documentSymbols"]>;
 	diagnostics(path: string): Promise<OperationOutputs["workspace.diagnostics"]>;
+	previewCodeActions(
+		path: string,
+		input: Omit<OperationInputs["workspace.previewCodeActions"], "workspaceId" | "path">,
+		call: LectorVehicleCall,
+	): Promise<OperationOutputs["workspace.previewCodeActions"]>;
+	applyCodeAction(
+		path: string,
+		previewId: OperationInputs["workspace.applyCodeAction"]["previewId"],
+		call: LectorVehicleCall,
+	): Promise<OperationOutputs["workspace.applyCodeAction"]>;
+	diagnosticDelta(
+		path: string,
+		source: OperationInputs["workspace.diagnosticDelta"]["source"],
+		bounds?: Omit<OperationInputs["workspace.diagnosticDelta"], "workspaceId" | "source">,
+	): Promise<OperationOutputs["workspace.diagnosticDelta"]>;
 	prepareCallHierarchy(path: string, line: number, character: number): Promise<OperationOutputs["workspace.prepareCallHierarchy"]>;
 	incomingCalls(path: string, line: number, character: number): Promise<OperationOutputs["workspace.incomingCalls"]>;
 	outgoingCalls(path: string, line: number, character: number): Promise<OperationOutputs["workspace.outgoingCalls"]>;
+	prepareTypeHierarchy(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.prepareTypeHierarchy"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.prepareTypeHierarchy"]>;
+	supertypes(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.supertypes"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.supertypes"]>;
+	subtypes(
+		path: string,
+		line: number,
+		character: number,
+		bounds?: Pick<OperationInputs["workspace.subtypes"], "maxResults" | "maxBytes" | "deadlineMs">,
+	): Promise<OperationOutputs["workspace.subtypes"]>;
+	impactAnalysis(
+		path: string,
+		source: OperationInputs["workspace.impactAnalysis"]["source"],
+		bounds: Pick<
+			OperationInputs["workspace.impactAnalysis"],
+			"maxDepth" | "maxNodes" | "maxEdges" | "maxBytes" | "deadlineMs" | "coverage" | "autoPopulate" | "maxFiles" | "maxSymbolsPerFile"
+		>,
+	): Promise<OperationOutputs["workspace.impactAnalysis"]>;
 	/**
 	 * Not exposed as a standalone Pi tool -- every workspace auto-populates on first touch via
 	 * monitorWorkspaceCache (workspace-cache/operations.ts). Kept here as an internal capability
@@ -46,7 +91,14 @@ export interface CodeIntelligenceOperations {
 	populateSymbolGraph(path: string, maxFiles: number, maxSymbolsPerFile: number, waitMs?: number): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
 	/** Not exposed as a standalone Pi tool -- see populateSymbolGraph. */
 	jobStatus(jobId: string): Promise<JobSnapshot<PopulateSymbolGraphResult>>;
-	reachableFrom(path: string, line: number, character: number, maxDepth: number, kind?: SymbolEdgeKind): Promise<readonly SymbolNode[]>;
+	reachableFrom(
+		path: string,
+		line: number,
+		character: number,
+		maxDepth: number,
+		kind?: SymbolEdgeKind,
+		autoPopulation?: Pick<OperationInputs["workspace.reachableFrom"], "autoPopulate" | "maxFiles" | "maxSymbolsPerFile">,
+	): Promise<readonly SymbolNode[]>;
 	/** Never spawns a symbol index -- safe to call opportunistically (e.g. before deciding whether to enrich a result). */
 	hasWarmIndex(path: string): Promise<boolean>;
 	workspaceMap(path: string, maxNodes: number, maxEdges: number, maxEntries: number, maxBytes: number): Promise<OperationOutputs["workspace.map"]>;
@@ -120,6 +172,36 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		async previewCodeActions(path, input, call) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<OperationOutputs["workspace.previewCodeActions"]>(
+						"workspace.previewCodeActions",
+						{ workspaceId, path, ...input },
+						CODE_ACTION_PREVIEW_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async applyCodeAction(path, previewId, call) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<OperationOutputs["workspace.applyCodeAction"]>(
+						"workspace.applyCodeAction",
+						{ workspaceId, previewId },
+						CODE_ACTION_APPLY_PERMISSIONS,
+						call,
+					),
+			);
+		},
+		async diagnosticDelta(path, source, bounds) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.diagnosticDelta", { workspaceId, source, ...bounds }),
+			);
+		},
 		async prepareCallHierarchy(path, line, character) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
@@ -147,6 +229,30 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 				},
 			);
 		},
+		async prepareTypeHierarchy(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.prepareTypeHierarchy", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async supertypes(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.supertypes", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async subtypes(path, line, character, bounds) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.subtypes", { workspaceId, path, line, character, ...bounds }),
+			);
+		},
+		async impactAnalysis(path, source, bounds) {
+			return withWorkspace(
+				() => workspaceForPathOrDirectory(path),
+				async ({ workspaceId }) => (await lectorClient()).call("workspace.impactAnalysis", { workspaceId, source, ...bounds }),
+			);
+		},
 		async populateSymbolGraph(path, maxFiles, maxSymbolsPerFile, waitMs = 500) {
 			return withWorkspace(
 				() => workspaceForPathOrDirectory(path),
@@ -167,12 +273,12 @@ export function createLectorCodeIntelligenceOperations(ownerId?: string): CodeIn
 			const { job } = await client.call("job.status", { jobId });
 			return job;
 		},
-		async reachableFrom(path, line, character, maxDepth, kind) {
+		async reachableFrom(path, line, character, maxDepth, kind, autoPopulation) {
 			return withWorkspace(
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind });
+					const { symbols } = await client.call("workspace.reachableFrom", { workspaceId, path, line, character, maxDepth, kind, ...autoPopulation });
 					return symbols;
 				},
 			);

package/extension/src/code-intelligence/rendering.ts

@@ -5,6 +5,7 @@ import type {
 	Hover,
 	IncomingCall,
 	IntelligenceProvenance,
+	OperationOutputs,
 	OutgoingCall,
 	SymbolNode,
 	WorkspaceLocation,
@@ -27,6 +28,7 @@ const DEFAULT_VISIBLE_LOCATIONS = 8;
 const DEFAULT_VISIBLE_SYMBOLS = 12;
 const DEFAULT_VISIBLE_DIAGNOSTICS = 12;
 const DEFAULT_VISIBLE_CALLS = 12;
+const DEFAULT_VISIBLE_CHANGES = 12;
 
 const DIAGNOSTIC_SEVERITY_COLOR: Record<Diagnostic["severity"], ThemeColor> = {
 	error: "error",
@@ -171,6 +173,123 @@ export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | und
 	return lines.join("\n");
 }
 
+function formatPathCall(toolName: string, args: { path?: unknown }, theme: LectorTheme, qualifier = ""): string {
+	const path = typeof args.path === "string" ? args.path : "";
+	return `${theme.fg("toolTitle", theme.bold(toolName))}${qualifier ? ` ${theme.fg("muted", qualifier)}` : ""} ${theme.fg("accent", path)}`;
+}
+
+export function formatCodeActionPreviewCall(
+	args: { path?: unknown; startLine?: unknown; startCharacter?: unknown; endLine?: unknown; endCharacter?: unknown },
+	theme: LectorTheme,
+): string {
+	const range = `${typeof args.startLine === "number" ? args.startLine : "?"}:${typeof args.startCharacter === "number" ? args.startCharacter : "?"}-${typeof args.endLine === "number" ? args.endLine : "?"}:${typeof args.endCharacter === "number" ? args.endCharacter : "?"}`;
+	return formatPathCall("code_action_preview", args, theme, range);
+}
+
+export function formatCodeActionPreviewResult(
+	result: OperationOutputs["workspace.previewCodeActions"] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.actions.length === 0) return theme.fg("dim", "No code actions.");
+	return [
+		theme.fg("muted", `${result.actions.length} code action${result.actions.length === 1 ? "" : "s"}:`),
+		...renderTruncatedList({
+			items: result.actions,
+			expanded,
+			visibleCount: DEFAULT_VISIBLE_CHANGES,
+			formatItem: (action) => {
+				const state = action.disabledReason
+					? theme.fg("warning", `disabled: ${action.disabledReason}`)
+					: action.preferred
+						? theme.fg("success", "preferred")
+						: "";
+				const paths = action.affectedPaths.length > 0 ? action.affectedPaths.join(", ") : "command only";
+				return `  ${theme.bold(action.title)}${action.kind ? ` (${action.kind})` : ""} -- ${paths}${state ? ` -- ${state}` : ""}`;
+			},
+			moreLine: moreLine(theme),
+			truncationWarning: result.truncated || result.deadlineReached ? theme.fg("warning", "results truncated by the requested bounds") : undefined,
+		}),
+	].join("\n");
+}
+
+export function formatCodeActionApplyCall(args: { path?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("code_action_apply", args, theme);
+}
+
+export function formatCodeActionApplyResult(result: OperationOutputs["workspace.applyCodeAction"] | undefined, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No code-action result.");
+	const lines = result.touchedPaths.map((path) => `  ${path}`);
+	if (result.transactionId) lines.push(theme.fg("muted", `transaction ${result.transactionId}`));
+	if (result.pendingCommand) lines.push(theme.fg("warning", `pending command ${result.pendingCommand.command}`));
+	return lines.length > 0 ? lines.join("\n") : theme.fg("dim", "Code action made no file changes.");
+}
+
+export function formatDiagnosticDeltaCall(args: { path?: unknown; source?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("diagnostic_delta", args, theme, typeof args.source === "string" ? args.source : "");
+}
+
+export function formatDiagnosticDeltaResult(result: OperationOutputs["workspace.diagnosticDelta"] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No diagnostic delta.");
+	const changes = [
+		...result.introduced.map((diagnostic) => ({ label: "introduced", diagnostic })),
+		...result.resolved.map((diagnostic) => ({ label: "resolved", diagnostic })),
+		...result.changed.map(({ after }) => ({ label: "changed", diagnostic: after })),
+	];
+	if (changes.length === 0) return theme.fg("success", "No diagnostic changes.");
+	return renderTruncatedList({
+		items: changes,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CHANGES,
+		formatItem: ({ label, diagnostic }) =>
+			`${theme.fg(label === "introduced" ? "error" : label === "resolved" ? "success" : "warning", label)} ${formatLocation(theme, diagnostic.range.path, diagnostic.range.start.line, diagnostic.range.start.character)} -- ${diagnostic.message}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "results truncated by maxResults/maxBytes") : undefined,
+	}).join("\n");
+}
+
+export function formatTypeHierarchyCall(args: { direction?: unknown; path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	return `${formatPositionalCall("type_hierarchy", args, theme)} ${theme.fg("muted", typeof args.direction === "string" ? args.direction : "")}`;
+}
+
+export function formatTypeHierarchyResult(
+	result: OperationOutputs["workspace.prepareTypeHierarchy"] | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.items.length === 0) return theme.fg("dim", "No type-hierarchy items found.");
+	return renderTruncatedList({
+		items: result.items,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CALLS,
+		formatItem: (item) => `  ${formatCallHierarchyEntry(item, theme)}${item.detail ? theme.fg("dim", ` -- ${item.detail}`) : ""}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated ? theme.fg("warning", "results truncated by the requested bounds") : undefined,
+	}).join("\n");
+}
+
+export function formatImpactAnalysisCall(args: { path?: unknown; source?: unknown }, theme: LectorTheme): string {
+	return formatPathCall("impact_analysis", args, theme, typeof args.source === "string" ? args.source : "");
+}
+
+export function formatImpactAnalysisResult(result: OperationOutputs["workspace.impactAnalysis"] | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!result) return theme.fg("dim", "No impact-analysis result.");
+	const impacts = [
+		...result.changedSymbols.map(({ symbol, side }) => ({ label: `changed ${side}`, symbol })),
+		...result.impactedSymbols.map(({ symbol, depth }) => ({ label: `impact depth=${depth}`, symbol })),
+		...result.relatedTests.map(({ symbol, evidence }) => ({ label: `test ${evidence.kind}`, symbol })),
+	];
+	if (impacts.length === 0) return theme.fg("dim", "No changed symbols resolved.");
+	return renderTruncatedList({
+		items: impacts,
+		expanded,
+		visibleCount: DEFAULT_VISIBLE_CHANGES,
+		formatItem: ({ label, symbol }) => `${theme.fg("muted", label)} ${formatCallHierarchyEntry(symbol, theme)}`,
+		moreLine: moreLine(theme),
+		truncationWarning: result.truncated || result.deadlineReached ? theme.fg("warning", "analysis truncated by the requested bounds") : undefined,
+	}).join("\n");
+}
+
 function formatCallHierarchyEntry(entry: { kind: string; name: string; location: WorkspaceLocation }, theme: LectorTheme): string {
 	const kind = theme.fg(colorForKind(entry.kind), entry.kind);
 	const name = theme.fg("text", theme.bold(entry.name));

package/extension/src/cross-workspace-search/rendering.ts

@@ -83,6 +83,9 @@ export function formatSearchTextAcrossProjectsResult(
 		lines.push(formatOutcomeHeader(entry, theme));
 		const { outcome } = entry;
 		if (outcome.status !== "ready") continue;
+		if (outcome.result.provenance) {
+			lines.push(theme.fg("dim", `  lexical via ${outcome.result.provenance.backend} (${outcome.result.provenance.indexState})`));
+		}
 		if (outcome.result.matches.length === 0) {
 			lines.push(theme.fg("dim", "  no matches"));
 			continue;

package/extension/src/editor/editor-state.ts

@@ -4,6 +4,26 @@ export type EditorMode = "normal" | "insert" | "command";
 
 export type EditorAction = { kind: "save" } | { kind: "save-and-quit" } | { kind: "quit" } | { kind: "hover" };
 
+export interface EditorSourcePosition {
+	/** One-based line number. */
+	readonly line: number;
+	/** One-based UTF-16 code-unit position within the line. */
+	readonly character: number;
+}
+
+export type EditorPositionErrorCode = "line-out-of-range" | "character-out-of-range";
+
+/** Reports why a requested source position cannot identify a cursor location in the current buffer. */
+export class EditorPositionError extends Error {
+	constructor(
+		readonly code: EditorPositionErrorCode,
+		message: string,
+	) {
+		super(`${code}: ${message}`);
+		this.name = "EditorPositionError";
+	}
+}
+
 const BACKSPACE_KEYS = new Set(["\x7f", "\b"]);
 
 /**
@@ -27,8 +47,25 @@ export class EditorState {
 	private insertPendingJ = false;
 	private yankedLine: string | undefined;
 
-	constructor(content: string) {
+	constructor(content: string, initialPosition?: EditorSourcePosition) {
 		this.buffer = new LiveBuffer(content);
+		if (initialPosition) this.moveToInitialPosition(initialPosition);
+	}
+
+	private moveToInitialPosition(position: EditorSourcePosition): void {
+		if (!Number.isSafeInteger(position.line) || position.line < 1 || position.line > this.buffer.lineCount) {
+			throw new EditorPositionError("line-out-of-range", `Line ${position.line} is outside this ${this.buffer.lineCount}-line buffer`);
+		}
+		const lineLength = this.buffer.lineText(position.line).length;
+		const maxCharacter = Math.max(lineLength, 1);
+		if (!Number.isSafeInteger(position.character) || position.character < 1 || position.character > maxCharacter) {
+			throw new EditorPositionError(
+				"character-out-of-range",
+				`Character ${position.character} is outside line ${position.line}'s ${lineLength} UTF-16 code units`,
+			);
+		}
+		this.cursorLine = position.line;
+		this.cursorCharacter = position.character;
 	}
 
 	get currentLineText(): string {

package/extension/src/editor/explorer-component.ts

@@ -9,7 +9,14 @@ import type { EditorTheme } from "./editor-theme.ts";
 import type { ExplorerDiff, ExplorerEntry } from "./explorer-diff.ts";
 import { diffExplorerLines, formatExplorerLine, parseExplorerLine } from "./explorer-diff.ts";
 
-export type ExplorerResult = { kind: "quit" } | { kind: "open-file"; absolutePath: string };
+/** Restores one Workspace's directory and active entry when its Explorer becomes visible again. */
+export interface ExplorerViewState {
+	readonly relativePath: string;
+	readonly selectedEntryName?: string;
+}
+
+/** Reports why the Explorer closed plus its latest restorable location when the host supports view-state persistence. */
+export type ExplorerResult = { kind: "quit"; viewState?: ExplorerViewState } | { kind: "open-file"; absolutePath: string; viewState?: ExplorerViewState };
 
 /** Joins a directory-relative name onto `directory` ("" means the resolved root itself). */
 export function joinExplorerPath(directory: string, name: string): string {
@@ -51,12 +58,19 @@ export class ExplorerComponent implements Component {
 	private statusMessage = "";
 	private confirming: PendingConfirmation | undefined;
 
-	constructor(tui: TUI, theme: EditorTheme, session: DirectoryExplorerSession, initialRelativePath: string, done: (result: ExplorerResult) => void) {
+	constructor(
+		tui: TUI,
+		theme: EditorTheme,
+		session: DirectoryExplorerSession,
+		initialRelativePath: string,
+		done: (result: ExplorerResult) => void,
+		initialSelectedEntryName?: string,
+	) {
 		this.tui = tui;
 		this.theme = theme;
 		this.session = session;
 		this.done = done;
-		this.pending = this.loadDirectory(initialRelativePath).catch((error: unknown) => this.reportError(error));
+		this.pending = this.loadDirectory(initialRelativePath, initialSelectedEntryName).catch((error: unknown) => this.reportError(error));
 	}
 
 	private pending: Promise<void> = Promise.resolve();
@@ -111,13 +125,20 @@ export class ExplorerComponent implements Component {
 		this.tui.requestRender();
 	}
 
-	private async loadDirectory(relativePath: string): Promise<void> {
+	private async loadDirectory(relativePath: string, selectedEntryName?: string): Promise<void> {
 		const listing = await this.session.listDirectory(relativePath);
 		this.currentPath = relativePath;
 		this.nextId = 1;
 		this.entries = listing.entries.map((entry) => ({ id: this.nextId++, name: entry.name, kind: entry.kind }));
 		const text = this.entries.length > 0 ? this.entries.map((entry) => formatExplorerLine(entry)).join("\n") : "";
 		this.state = new EditorState(text);
+		const selectedIndex = selectedEntryName === undefined ? -1 : this.entries.findIndex((entry) => entry.name === selectedEntryName);
+		const selectedEntry = selectedIndex >= 0 ? this.entries[selectedIndex] : undefined;
+		if (selectedEntry) {
+			this.state.cursorLine = selectedIndex + 1;
+			this.state.cursorCharacter = `${selectedEntry.id} `.length + 1;
+			this.scrollToKeepCursorVisible();
+		}
 		this.confirming = undefined;
 		this.statusMessage = "";
 		this.tui.requestRender();
@@ -133,12 +154,17 @@ export class ExplorerComponent implements Component {
 			await this.loadDirectory(joinExplorerPath(this.currentPath, entry.name));
 			return;
 		}
-		this.done({ kind: "open-file", absolutePath: join(this.session.root, joinExplorerPath(this.currentPath, entry.name)) });
+		this.done({
+			kind: "open-file",
+			absolutePath: join(this.session.root, joinExplorerPath(this.currentPath, entry.name)),
+			viewState: { relativePath: this.currentPath, selectedEntryName: entry.name },
+		});
 	}
 
 	private async navigateToParent(): Promise<void> {
 		if (this.currentPath === "") return; // already at the resolved root -- v1 never widens scope above it
-		await this.loadDirectory(parentExplorerPath(this.currentPath));
+		const childName = posix.basename(this.currentPath);
+		await this.loadDirectory(parentExplorerPath(this.currentPath), childName);
 	}
 
 	private async performAction(action: EditorAction): Promise<void> {
@@ -149,14 +175,14 @@ export class ExplorerComponent implements Component {
 				this.state.dirty = false;
 				if (diffs.length === 0) {
 					this.statusMessage = "no changes";
-					if (action.kind === "save-and-quit") this.done({ kind: "quit" });
+					if (action.kind === "save-and-quit") this.done({ kind: "quit", viewState: this.viewState() });
 					return;
 				}
 				this.confirming = { diffs, andQuit: action.kind === "save-and-quit" };
 				return;
 			}
 			case "quit":
-				this.done({ kind: "quit" });
+				this.done({ kind: "quit", viewState: this.viewState() });
 				return;
 			case "hover":
 				this.statusMessage = "hover is not applicable in the file explorer";
@@ -186,13 +212,19 @@ export class ExplorerComponent implements Component {
 			return;
 		}
 		if (andQuit) {
-			this.done({ kind: "quit" });
+			this.done({ kind: "quit", viewState: this.viewState() });
 			return;
 		}
 		await this.loadDirectory(this.currentPath);
 		this.statusMessage = "applied";
 	}
 
+	private viewState(): ExplorerViewState {
+		const parsed = parseExplorerLine(this.state.currentLineText);
+		const entry = !parsed || parsed.id === null ? undefined : this.entries.find((candidate) => candidate.id === parsed.id);
+		return entry ? { relativePath: this.currentPath, selectedEntryName: entry.name } : { relativePath: this.currentPath };
+	}
+
 	private scrollToKeepCursorVisible(): void {
 		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
 		if (this.state.cursorLine < this.scrollTop) this.scrollTop = this.state.cursorLine;

package/extension/src/editor/explorer-flow.ts

@@ -1,10 +1,10 @@
-import { dirname, relative } from "node:path";
+import { basename, dirname, relative } from "node:path";
 import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
-import type { ExplorerResult } from "./explorer-component.ts";
+import type { ExplorerResult, ExplorerViewState } from "./explorer-component.ts";
 
 export interface ExplorerFlowHost {
-	/** Shows the explorer at `relativePath` (root-relative, "" for the resolved root) and resolves once the user quits or opens a file. */
-	showExplorer(session: DirectoryExplorerSession, relativePath: string): Promise<ExplorerResult>;
+	/** Shows the explorer at `relativePath` (root-relative, "" for the resolved root), optionally revealing one active entry, and resolves once the user quits or opens a file. */
+	showExplorer(session: DirectoryExplorerSession, relativePath: string, selectedEntryName?: string): Promise<ExplorerResult>;
 	/** Shows the real file editor for `absolutePath` and resolves once the user quits it. */
 	showEditor(absolutePath: string): Promise<void>;
 }
@@ -14,14 +14,21 @@ export interface ExplorerFlowHost {
  * the explorer -- at the directory the opened file lives in, not the resolved root -- once that
  * editor quits, rather than closing the whole session after the first file opened.
  */
-export async function runExplorerFlow(session: DirectoryExplorerSession, host: ExplorerFlowHost): Promise<void> {
-	let relativePath = "";
+export async function runExplorerFlow(
+	session: DirectoryExplorerSession,
+	host: ExplorerFlowHost,
+	initialViewState: ExplorerViewState = { relativePath: "" },
+): Promise<ExplorerViewState> {
+	let viewState = initialViewState;
 	for (;;) {
-		const result = await host.showExplorer(session, relativePath);
-		if (result.kind === "quit") return;
+		const result = await host.showExplorer(session, viewState.relativePath, viewState.selectedEntryName);
+		if (result.kind === "quit") return result.viewState ?? viewState;
 
 		await host.showEditor(result.absolutePath);
 		// path.relative(root, root) is "" directly, matching ExplorerComponent's own root-relative convention -- no "." case to normalize.
-		relativePath = relative(session.root, dirname(result.absolutePath));
+		viewState = result.viewState ?? {
+			relativePath: relative(session.root, dirname(result.absolutePath)),
+			selectedEntryName: basename(result.absolutePath),
+		};
 	}
 }

package/extension/src/editor/index.ts

@@ -29,9 +29,16 @@
  */
 
 export type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
-export { type EditorAction, type EditorMode, EditorState } from "./editor-state.ts";
+export {
+	type EditorAction,
+	type EditorMode,
+	EditorPositionError,
+	type EditorPositionErrorCode,
+	type EditorSourcePosition,
+	EditorState,
+} from "./editor-state.ts";
 export type { EditorTheme } from "./editor-theme.ts";
-export { ExplorerComponent, type ExplorerResult, joinExplorerPath } from "./explorer-component.ts";
+export { ExplorerComponent, type ExplorerResult, type ExplorerViewState, joinExplorerPath } from "./explorer-component.ts";
 // runExplorerFlow is pure orchestration over the two interfaces above (browse, open a file into
 // the real editor, return to the explorer at that file's own directory once it quits) -- exported
 // for the same reason ExplorerComponent/DirectoryExplorerSession are: any real host can drive this
@@ -44,4 +51,5 @@ export {
 	type EditorHoverRequest,
 	ModalEditorComponent,
 	type ModalEditorHost,
+	type ModalEditorOptions,
 } from "./modal-editor-component.ts";

package/extension/src/editor/modal-editor-component.ts

@@ -4,7 +4,7 @@ import { contentHashOf, highlightSpans } from "@danypops/lector";
 import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import type { EditorAction } from "./editor-state.ts";
+import type { EditorAction, EditorSourcePosition } from "./editor-state.ts";
 import { EditorState } from "./editor-state.ts";
 import type { EditorTheme } from "./editor-theme.ts";
 
@@ -26,6 +26,11 @@ export type EditorHoverOutcome =
 	| { readonly kind: "ready"; readonly hover?: { readonly contents: string } }
 	| { readonly kind: "stale-active-buffer"; readonly bufferHash: ContentHash };
 
+export interface ModalEditorOptions {
+	/** Positions the cursor using one-based UTF-16 coordinates and scrolls it into the first viewport. */
+	readonly initialPosition?: EditorSourcePosition;
+}
+
 export interface ModalEditorHost {
 	filePath: string;
 	/** Saves the buffer's current text through Lector's hash-guarded write. Throws (surfaced as a status message, not a crash) on a genuinely concurrent external change. */
@@ -65,13 +70,14 @@ export class ModalEditorComponent implements Component {
 	private statusMessage = "";
 	private highlightCache: { text: string; spans: readonly HighlightSpan[] } | undefined;
 
-	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void) {
+	constructor(tui: TUI, theme: EditorTheme, host: ModalEditorHost, content: string, done: () => void, options: ModalEditorOptions = {}) {
 		this.tui = tui;
 		this.theme = theme;
 		this.host = host;
 		this.done = done;
 		this.extension = extname(host.filePath);
-		this.state = new EditorState(content);
+		this.state = new EditorState(content, options.initialPosition);
+		this.scrollToKeepCursorVisible();
 		this.refreshHighlightsSafely();
 	}
 

package/extension/src/git/operations.ts

@@ -1,4 +1,4 @@
-import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationOutputs } from "@danypops/lector";
+import type { GitDiffResult, GitLogEntry, GitStatusSummary, OperationInputs, OperationOutputs } from "@danypops/lector";
 import { lectorClient, withWorkspace, workspaceForDirectory } from "../lector-client.ts";
 import { invokeLectorVehicleOperation, type LectorVehicleCall } from "../vehicle-client.ts";
 
@@ -6,6 +6,8 @@ type SymbolComparison = OperationOutputs["workspace.compareSymbolAcrossVersions"
 type GitWorktreeAddResult = OperationOutputs["workspace.gitWorktreeAdd"];
 type GitWorktreeRemoveResult = OperationOutputs["workspace.gitWorktreeRemove"];
 type GitGrepResult = OperationOutputs["workspace.gitGrep"];
+type GitHistoryGrepResult = OperationOutputs["workspace.gitGrepHistory"];
+type GitHistoryGrepBounds = Omit<OperationInputs["workspace.gitGrepHistory"], "workspaceId" | "pattern" | "pathspecs">;
 type GitListFilesResult = OperationOutputs["workspace.gitListFiles"];
 
 /** Matches GIT_READ_PERMISSIONS' own declared value server-side (git/operation-registration.ts). */
@@ -42,6 +44,14 @@ export interface GitOperations {
 		maxBytes: number,
 		call: LectorVehicleCall,
 	): Promise<GitGrepResult>;
+	/** Bounded extended-regex search across commit trees reachable from every ref, with deterministic topological paging and exact-match deduplication. */
+	grepHistory(
+		directory: string,
+		pattern: string,
+		pathspecs: readonly string[] | undefined,
+		bounds: GitHistoryGrepBounds,
+		call: LectorVehicleCall,
+	): Promise<GitHistoryGrepResult>;
 	/** Every file path in `ref`'s own tree, no checkout -- pathspecs narrows the listing (prefix-based, not glob-based like grep's). */
 	listFiles(directory: string, ref: string, pathspecs: readonly string[] | undefined, maxResults: number, call: LectorVehicleCall): Promise<GitListFilesResult>;
 	/** True iff ancestorRef is a real ancestor of (or the exact same commit as) ref -- the backport/reachability check "was this fix ported to this branch" actually needs. */
@@ -139,6 +149,18 @@ export function createLectorGitOperations(): GitOperations {
 					),
 			);
 		},
+		async grepHistory(directory, pattern, pathspecs, bounds, call) {
+			return withWorkspace(
+				() => workspaceForDirectory(directory),
+				({ workspaceId }) =>
+					invokeLectorVehicleOperation<GitHistoryGrepResult>(
+						"workspace.gitGrepHistory",
+						{ workspaceId, pattern, pathspecs, ...bounds },
+						GIT_READ_PERMISSIONS,
+						call,
+					),
+			);
+		},
 		async listFiles(directory, ref, pathspecs, maxResults, call) {
 			return withWorkspace(
 				() => workspaceForDirectory(directory),