@danypops/pi-lector 0.10.0 → 0.11.1

package/extension/src/editor/apply-explorer-diffs.ts

@@ -0,0 +1,45 @@
+import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
+import type { ExplorerDiff } from "./explorer-diff.ts";
+
+function joinRelative(directory: string, name: string): string {
+	return directory === "" ? name : `${directory}/${name}`;
+}
+
+/** Applies a diff batch to `directory`, in order. Never partial-rolls-back a failure partway through -- the caller (the explorer's own :w confirmation flow) is responsible for surfacing which operations landed before an error, via each real thrown error's own message. */
+export async function applyExplorerDiffs(session: DirectoryExplorerSession, directory: string, diffs: readonly ExplorerDiff[]): Promise<void> {
+	for (const diff of diffs) {
+		switch (diff.kind) {
+			case "create":
+				if (diff.isDirectory) await session.createDirectory(joinRelative(directory, diff.name));
+				else await session.createFile(joinRelative(directory, diff.name));
+				break;
+			case "rename":
+				await session.renamePath(joinRelative(directory, diff.fromName), joinRelative(directory, diff.toName));
+				break;
+			case "delete":
+				if (diff.isDirectory) await session.deleteDirectory(joinRelative(directory, diff.name));
+				else await session.deleteFile(joinRelative(directory, diff.name));
+				break;
+			default: {
+				const exhaustive: never = diff;
+				throw new Error(`unreachable explorer diff kind: ${JSON.stringify(exhaustive)}`);
+			}
+		}
+	}
+}
+
+/** One human-readable confirmation line for a pending diff, shown before :w actually applies anything. */
+export function summarizeExplorerDiff(diff: ExplorerDiff): string {
+	switch (diff.kind) {
+		case "create":
+			return `+ ${diff.name}${diff.isDirectory ? "/" : ""}`;
+		case "rename":
+			return `${diff.fromName} -> ${diff.toName}`;
+		case "delete":
+			return `- ${diff.name}${diff.isDirectory ? "/" : ""}`;
+		default: {
+			const exhaustive: never = diff;
+			throw new Error(`unreachable explorer diff kind: ${JSON.stringify(exhaustive)}`);
+		}
+	}
+}

package/extension/src/editor/directory-explorer-operations.ts

@@ -0,0 +1,61 @@
+import type { DirectoryListing, WorkspaceId } from "@danypops/lector";
+import { lectorClient, withWorkspace, workspaceForPathOrDirectory } from "../lector-client.ts";
+
+/** Oil's own default (view_options.show_hidden = false): dotfiles/dotdirs excluded unless explicitly toggled. Toggling is deferred (v2) -- this always applies for now, matching the tool's own out-of-the-box behavior. */
+function isHidden(name: string): boolean {
+	return name.startsWith(".");
+}
+
+/**
+ * Backs the /editor no-path Oil-style explorer: one resolved workspace for the whole browsing
+ * session (navigating between directories never re-resolves a workspace, just changes which
+ * relative path is listed), plus the four mutation primitives its :w diff-and-apply step needs.
+ *
+ * deleteFile is not a thin pass-through: workspace.deleteEntry is hash-guarded and the explorer
+ * only ever has a directory *listing* (no content hash) for the line being deleted, so it reads
+ * the file's current hash immediately before deleting it -- an extra round trip, acceptable for
+ * an infrequent interactive action, not a hot path.
+ */
+export interface DirectoryExplorerSession {
+	readonly root: string;
+	readonly workspaceId: WorkspaceId;
+	listDirectory(relativePath: string): Promise<DirectoryListing>;
+	createFile(relativePath: string): Promise<void>;
+	createDirectory(relativePath: string): Promise<void>;
+	renamePath(oldRelativePath: string, newRelativePath: string): Promise<void>;
+	deleteFile(relativePath: string): Promise<void>;
+	deleteDirectory(relativePath: string): Promise<void>;
+}
+
+export function openDirectoryExplorer(absoluteDirectory: string): Promise<DirectoryExplorerSession> {
+	return withWorkspace(
+		() => workspaceForPathOrDirectory(absoluteDirectory),
+		async ({ workspaceId, root }) => {
+			const client = await lectorClient();
+			return {
+				root,
+				workspaceId,
+				listDirectory: async (relativePath: string): Promise<DirectoryListing> => {
+					const listing = await client.call("workspace.listDirectory", { workspaceId, path: relativePath });
+					return { ...listing, entries: listing.entries.filter((entry) => !isHidden(entry.name)) };
+				},
+				createFile: async (relativePath: string) => {
+					await client.callOnce("workspace.exactEdit", { workspaceId, path: relativePath, expectedHash: null, content: "" });
+				},
+				createDirectory: async (relativePath: string) => {
+					await client.callOnce("workspace.createDirectory", { workspaceId, path: relativePath });
+				},
+				renamePath: async (oldRelativePath: string, newRelativePath: string) => {
+					await client.callOnce("workspace.renamePath", { workspaceId, oldPath: oldRelativePath, newPath: newRelativePath });
+				},
+				deleteFile: async (relativePath: string) => {
+					const { hash } = await client.call("workspace.rawRead", { workspaceId, path: relativePath });
+					await client.callOnce("workspace.deleteEntry", { workspaceId, path: relativePath, expectedHash: hash });
+				},
+				deleteDirectory: async (relativePath: string) => {
+					await client.callOnce("workspace.deleteDirectory", { workspaceId, path: relativePath });
+				},
+			};
+		},
+	);
+}

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

@@ -0,0 +1,7 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** Real theme, narrowed to exactly what the editor/explorer components need -- avoids depending on pi-coding-agent's full internal Theme shape. */
+export interface EditorTheme {
+	fg(color: ThemeColor, text: string): string;
+	bg(color: "selectedBg", text: string): string;
+}

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

@@ -0,0 +1,252 @@
+import { join, posix } from "node:path";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { applyExplorerDiffs, summarizeExplorerDiff } from "./apply-explorer-diffs.ts";
+import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
+import type { EditorAction } from "./editor-state.ts";
+import { EditorState } from "./editor-state.ts";
+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 };
+
+/** Joins a directory-relative name onto `directory` ("" means the resolved root itself). */
+export function joinExplorerPath(directory: string, name: string): string {
+	return directory === "" ? name : `${directory}/${name}`;
+}
+
+/** The relative parent of a directory-relative path; "" once already at the root. */
+function parentExplorerPath(directory: string): string {
+	const parent = posix.dirname(directory);
+	return parent === "." ? "" : parent;
+}
+
+interface PendingConfirmation {
+	readonly diffs: readonly ExplorerDiff[];
+	readonly andQuit: boolean;
+}
+
+/**
+ * An oil.nvim-style directory explorer: the listing IS the buffer (EditorState/LiveBuffer,
+ * reused as-is from the file editor -- normal/insert/dd/yy/p/undo/:w all already do exactly what
+ * renaming, deleting, and creating entries as text edits needs). Enter/`-` are intercepted before
+ * EditorState ever sees them (it has no existing mapping for either, confirmed against its own
+ * normal-mode key handling) since they're navigation, not buffer edits.
+ *
+ * :w never applies silently -- it always shows a confirmation summary first (oil.nvim's own
+ * default, skip_confirm_for_simple_edits = false), even for a single change.
+ */
+export class ExplorerComponent implements Component {
+	private readonly session: DirectoryExplorerSession;
+	private readonly tui: TUI;
+	private readonly theme: EditorTheme;
+	private readonly done: (result: ExplorerResult) => void;
+
+	private currentPath = "";
+	private entries: ExplorerEntry[] = [];
+	private nextId = 1;
+	private state = new EditorState("");
+	private scrollTop = 1;
+	private statusMessage = "";
+	private confirming: PendingConfirmation | undefined;
+
+	constructor(tui: TUI, theme: EditorTheme, session: DirectoryExplorerSession, initialRelativePath: string, done: (result: ExplorerResult) => void) {
+		this.tui = tui;
+		this.theme = theme;
+		this.session = session;
+		this.done = done;
+		this.pending = this.loadDirectory(initialRelativePath).catch((error: unknown) => this.reportError(error));
+	}
+
+	private pending: Promise<void> = Promise.resolve();
+
+	invalidate(): void {}
+
+	/**
+	 * Fire-and-forget from the real TUI's own perspective (matching Component's void-returning
+	 * contract) -- tests await settled() for deterministic assertions after triggering async work.
+	 * Any rejection (a daemon call failing, a stale/incompatible daemon, a genuine bug) is caught
+	 * here rather than left to become an unhandled rejection: that crashed the whole Pi process in
+	 * production once already, when a stale running daemon didn't yet support workspace.listDirectory.
+	 */
+	handleInput(data: string): void {
+		this.pending = this.handleInputAsync(data).catch((error: unknown) => this.reportError(error));
+	}
+
+	private reportError(error: unknown): void {
+		this.statusMessage = `error: ${error instanceof Error ? error.message : String(error)}`;
+		this.tui.requestRender();
+	}
+
+	/** Resolves once every async operation triggered by the most recent handleInput() call has finished -- a test-determinism hook, not part of the Component contract. */
+	settled(): Promise<void> {
+		return this.pending;
+	}
+
+	private async handleInputAsync(data: string): Promise<void> {
+		if (this.confirming) {
+			await this.handleConfirmationInput(data);
+			this.tui.requestRender();
+			return;
+		}
+
+		if (this.state.mode === "normal") {
+			if (data === "\r" || data === "\n") {
+				await this.openCurrentLine();
+				this.tui.requestRender();
+				return;
+			}
+			if (data === "-") {
+				await this.navigateToParent();
+				this.tui.requestRender();
+				return;
+			}
+		}
+
+		this.state.handleKey(data);
+		this.scrollToKeepCursorVisible();
+		const action = this.state.pendingAction;
+		if (action) await this.performAction(action);
+		this.tui.requestRender();
+	}
+
+	private async loadDirectory(relativePath: 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);
+		this.confirming = undefined;
+		this.statusMessage = "";
+		this.tui.requestRender();
+	}
+
+	private async openCurrentLine(): Promise<void> {
+		const parsed = parseExplorerLine(this.state.currentLineText);
+		if (!parsed || parsed.id === null) return; // a blank line or an unsaved new entry -- nothing real to open yet
+		const entry = this.entries.find((candidate) => candidate.id === parsed.id);
+		if (!entry) return;
+
+		if (entry.kind === "directory") {
+			await this.loadDirectory(joinExplorerPath(this.currentPath, entry.name));
+			return;
+		}
+		this.done({ kind: "open-file", absolutePath: join(this.session.root, joinExplorerPath(this.currentPath, 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));
+	}
+
+	private async performAction(action: EditorAction): Promise<void> {
+		switch (action.kind) {
+			case "save":
+			case "save-and-quit": {
+				const diffs = diffExplorerLines(this.entries, this.state.buffer.text.split("\n"));
+				this.state.dirty = false;
+				if (diffs.length === 0) {
+					this.statusMessage = "no changes";
+					if (action.kind === "save-and-quit") this.done({ kind: "quit" });
+					return;
+				}
+				this.confirming = { diffs, andQuit: action.kind === "save-and-quit" };
+				return;
+			}
+			case "quit":
+				this.done({ kind: "quit" });
+				return;
+			case "hover":
+				this.statusMessage = "hover is not applicable in the file explorer";
+				return;
+			default: {
+				const exhaustive: never = action;
+				throw new Error(`Unhandled editor action: ${JSON.stringify(exhaustive)}`);
+			}
+		}
+	}
+
+	private async handleConfirmationInput(data: string): Promise<void> {
+		if (!this.confirming) return;
+		if (data === "n" || data === "\x1b") {
+			this.confirming = undefined;
+			this.statusMessage = "cancelled";
+			return;
+		}
+		if (data !== "y" && data !== "\r" && data !== "\n") return;
+
+		const { diffs, andQuit } = this.confirming;
+		try {
+			await applyExplorerDiffs(this.session, this.currentPath, diffs);
+		} catch (error) {
+			this.confirming = undefined;
+			this.statusMessage = `apply failed: ${error instanceof Error ? error.message : String(error)}`;
+			return;
+		}
+		if (andQuit) {
+			this.done({ kind: "quit" });
+			return;
+		}
+		await this.loadDirectory(this.currentPath);
+		this.statusMessage = "applied";
+	}
+
+	private scrollToKeepCursorVisible(): void {
+		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
+		if (this.state.cursorLine < this.scrollTop) this.scrollTop = this.state.cursorLine;
+		else if (this.state.cursorLine >= this.scrollTop + viewportHeight) this.scrollTop = this.state.cursorLine - viewportHeight + 1;
+	}
+
+	render(width: number): string[] {
+		if (this.confirming) return this.renderConfirmation(this.confirming, width);
+
+		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
+		const lastLine = Math.min(this.state.buffer.lineCount, this.scrollTop + viewportHeight - 1);
+
+		const lines: string[] = [];
+		for (let line = this.scrollTop; line <= lastLine; line++) lines.push(this.renderLine(line, width));
+		while (lines.length < viewportHeight) lines.push("");
+
+		lines.push(this.renderStatusLine(width));
+		return lines;
+	}
+
+	private renderConfirmation(confirming: PendingConfirmation, width: number): string[] {
+		const lines = ["Pending changes:", "", ...confirming.diffs.map((diff) => `  ${summarizeExplorerDiff(diff)}`), "", "Apply? (y/n)"];
+		return lines.map((line) => truncateToWidth(line, width, ""));
+	}
+
+	private renderLine(line: number, width: number): string {
+		const lineText = this.state.buffer.lineText(line);
+		const isCursorLine = line === this.state.cursorLine;
+		const styled = isCursorLine ? this.renderLineWithCursor(lineText) : this.renderStyledLine(lineText);
+		return truncateToWidth(styled, width, "");
+	}
+
+	/** Dims the id prefix (a real character sequence in this terminal, not truly hidden -- see explorer-diff.ts) so it reads as secondary to the entry's own name. */
+	private renderStyledLine(lineText: string): string {
+		const match = lineText.match(/^(\d+ )(.*)$/);
+		if (!match) return lineText;
+		const [, idPart, rest] = match;
+		return `${this.theme.fg("muted", idPart ?? "")}${rest ?? ""}`;
+	}
+
+	private renderLineWithCursor(lineText: string): string {
+		const col = this.state.cursorCharacter - 1;
+		const before = this.renderStyledLine(lineText.slice(0, col));
+		const atCursor = col < lineText.length ? lineText[col] : " ";
+		const after = lineText.slice(col + 1);
+		return `${before}\x1b[7m${atCursor}\x1b[0m${after}`;
+	}
+
+	private renderStatusLine(width: number): string {
+		const modeLabel = { normal: " NORMAL ", insert: " INSERT ", command: " COMMAND " }[this.state.mode];
+		const location = this.currentPath === "" ? "/" : `/${this.currentPath}/`;
+		const left = this.state.mode === "command" ? `:${this.state.commandText}` : `${this.theme.fg("accent", modeLabel)} ${location}`;
+		const right = this.statusMessage || `${this.state.cursorLine}:${this.state.cursorCharacter}`;
+		const gap = Math.max(1, width - visibleWidth(left) - visibleWidth(right));
+		return truncateToWidth(`${left}${" ".repeat(gap)}${right}`, width, "");
+	}
+}

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

@@ -0,0 +1,85 @@
+import type { FileTreeEntryKind } from "@danypops/lector";
+
+/** One entry as last known from a real directory listing -- id is this explorer's own per-session identity, not anything Lector's daemon tracks. */
+export interface ExplorerEntry {
+	readonly id: number;
+	readonly name: string;
+	readonly kind: FileTreeEntryKind;
+}
+
+/** One buffer line, parsed back into its id (if any) and name. */
+export interface ParsedExplorerLine {
+	readonly id: number | null;
+	readonly name: string;
+	readonly isDirectory: boolean;
+}
+
+export type ExplorerDiff =
+	| { readonly kind: "create"; readonly name: string; readonly isDirectory: boolean }
+	| { readonly kind: "rename"; readonly id: number; readonly fromName: string; readonly toName: string }
+	| { readonly kind: "delete"; readonly id: number; readonly name: string; readonly isDirectory: boolean };
+
+/** Renders one entry as this explorer's own line format: "<id> name", a trailing "/" for directories. Ported from oil.nvim's own id-prefix convention (lua/oil/mutator/parser.lua) -- this terminal has no Neovim conceallevel equivalent, so the id is real, visible (if dimly styled) text, not truly hidden. */
+export function formatExplorerLine(entry: ExplorerEntry): string {
+	return `${entry.id} ${entry.name}${entry.kind === "directory" ? "/" : ""}`;
+}
+
+const EXISTING_LINE_PATTERN = /^(\d+) (.+)$/;
+
+function stripTrailingSlash(name: string): { name: string; isDirectory: boolean } {
+	return name.endsWith("/") ? { name: name.slice(0, -1), isDirectory: true } : { name, isDirectory: false };
+}
+
+/** Parses one buffer line back into id/name/isDirectory. Returns null for a blank line -- ignored entirely, never a new entry named "". */
+export function parseExplorerLine(rawLine: string): ParsedExplorerLine | null {
+	const trimmed = rawLine.trim();
+	if (trimmed === "") return null;
+
+	const existingMatch = trimmed.match(EXISTING_LINE_PATTERN);
+	if (existingMatch) {
+		const idText = existingMatch[1];
+		const rest = existingMatch[2];
+		if (idText === undefined || rest === undefined) return null;
+		const { name, isDirectory } = stripTrailingSlash(rest.trim());
+		return { id: Number(idText), name, isDirectory };
+	}
+
+	const { name, isDirectory } = stripTrailingSlash(trimmed);
+	return { id: null, name, isDirectory };
+}
+
+/**
+ * Diffs the explorer's current buffer lines against the original listing, matched by id -- never
+ * by line position, so reordering existing lines produces no diff at all. Every original entry
+ * not re-seen by its own id becomes a delete; every id-tagged line whose name changed becomes a
+ * rename; every line with no id tag becomes a create.
+ */
+export function diffExplorerLines(original: readonly ExplorerEntry[], currentLines: readonly string[]): ExplorerDiff[] {
+	const byId = new Map(original.map((entry) => [entry.id, entry]));
+	const unseenIds = new Set(byId.keys());
+	const diffs: ExplorerDiff[] = [];
+
+	for (const rawLine of currentLines) {
+		const parsed = parseExplorerLine(rawLine);
+		if (!parsed) continue;
+
+		if (parsed.id === null) {
+			diffs.push({ kind: "create", name: parsed.name, isDirectory: parsed.isDirectory });
+			continue;
+		}
+
+		const originalEntry = byId.get(parsed.id);
+		unseenIds.delete(parsed.id);
+		if (!originalEntry) continue; // an id that doesn't match anything real -- silently ignored, same as a stray line would be
+		if (originalEntry.name !== parsed.name) {
+			diffs.push({ kind: "rename", id: parsed.id, fromName: originalEntry.name, toName: parsed.name });
+		}
+	}
+
+	for (const id of unseenIds) {
+		const entry = byId.get(id);
+		if (entry) diffs.push({ kind: "delete", id: entry.id, name: entry.name, isDirectory: entry.kind === "directory" });
+	}
+
+	return diffs;
+}

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

@@ -0,0 +1,27 @@
+import { dirname, relative } from "node:path";
+import type { DirectoryExplorerSession } from "./directory-explorer-operations.ts";
+import type { ExplorerResult } 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 real file editor for `absolutePath` and resolves once the user quits it. */
+	showEditor(absolutePath: string): Promise<void>;
+}
+
+/**
+ * Oil-style /editor-with-no-path loop: browse, open a file into the real editor, then return to
+ * 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 = "";
+	for (;;) {
+		const result = await host.showExplorer(session, relativePath);
+		if (result.kind === "quit") return;
+
+		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));
+	}
+}

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

@@ -6,12 +6,9 @@ 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 { EditorState } from "./editor-state.ts";
+import type { EditorTheme } from "./editor-theme.ts";
 
-/** Real theme, narrowed to exactly what this component needs -- avoids depending on pi-coding-agent's full internal Theme shape. */
-export interface EditorTheme {
-	fg(color: ThemeColor, text: string): string;
-	bg(color: "selectedBg", text: string): string;
-}
+export type { EditorTheme } from "./editor-theme.ts";
 
 export interface NeovimEditorHost {
 	filePath: string;
@@ -57,21 +54,40 @@ export class NeovimEditorComponent implements Component {
 		this.done = done;
 		this.extension = extname(host.filePath);
 		this.state = new EditorState(content);
-		void this.refreshHighlights();
+		this.refreshHighlightsSafely();
 	}
 
 	invalidate(): void {
 		this.highlightCache = undefined;
 	}
 
+	/**
+	 * Fire-and-forget from the real TUI's own perspective (matching Component's void-returning
+	 * contract). Any rejection from performAction (host.save/host.hover talking to a daemon that
+	 * fails or restarts mid-session) is caught here rather than left to become an unhandled
+	 * rejection that crashes the whole Pi process -- the same defect class found and fixed in
+	 * ExplorerComponent's own constructor.
+	 */
 	handleInput(data: string): void {
 		this.state.handleKey(data);
 		this.scrollToKeepCursorVisible();
 		const action = this.state.pendingAction;
-		if (action) void this.performAction(action);
+		if (action) this.performActionSafely(action);
 		this.tui.requestRender();
 	}
 
+	private performActionSafely(action: EditorAction): void {
+		void this.performAction(action).catch((error: unknown) => {
+			this.statusMessage = `error: ${error instanceof Error ? error.message : String(error)}`;
+			this.tui.requestRender();
+		});
+	}
+
+	/** Highlighting is cosmetic: a failure here must never surface as a status message that stomps a real save/hover result, and must never crash the editor. */
+	private refreshHighlightsSafely(): void {
+		void this.refreshHighlights().catch(() => undefined);
+	}
+
 	private async performAction(action: EditorAction): Promise<void> {
 		switch (action.kind) {
 			case "save":
@@ -115,6 +131,10 @@ export class NeovimEditorComponent implements Component {
 		this.tui.requestRender();
 	}
 
+	private refreshHighlightsIfStale(): void {
+		if (this.highlightCache?.text !== this.state.buffer.text) this.refreshHighlightsSafely();
+	}
+
 	private scrollToKeepCursorVisible(): void {
 		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
 		if (this.state.cursorLine < this.scrollTop) this.scrollTop = this.state.cursorLine;
@@ -122,7 +142,7 @@ export class NeovimEditorComponent implements Component {
 	}
 
 	render(width: number): string[] {
-		if (this.highlightCache?.text !== this.state.buffer.text) void this.refreshHighlights();
+		this.refreshHighlightsIfStale();
 
 		const viewportHeight = Math.max(1, this.tui.terminal.rows - 2);
 		const gutterWidth = Math.max(3, String(this.state.buffer.lineCount).length) + 1;

package/extension/src/index.ts

@@ -35,6 +35,7 @@ import {
 	createReadToolDefinition,
 	createWriteToolDefinition,
 	type ExtensionAPI,
+	type ExtensionCommandContext,
 } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { renderBoundedTable, type TextMeasure } from "malevich-tui-components";
@@ -70,6 +71,9 @@ import {
 import { type CrossWorkspaceOutcome, createLectorCrossWorkspaceSearchOperations } from "./cross-workspace-search/operations.ts";
 import { formatCrossWorkspaceCall, formatFindSymbolsAcrossProjectsResult, formatSearchTextAcrossProjectsResult } from "./cross-workspace-search/rendering.ts";
 import { createLectorEditOperations } from "./edit/operations.ts";
+import { openDirectoryExplorer } from "./editor/directory-explorer-operations.ts";
+import { ExplorerComponent, type ExplorerResult } from "./editor/explorer-component.ts";
+import { runExplorerFlow } from "./editor/explorer-flow.ts";
 import { NeovimEditorComponent, type NeovimEditorHost } from "./editor/neovim-editor-component.ts";
 import { openEditorFile } from "./editor/operations.ts";
 import { createExternalSearchOperations } from "./external-search/operations.ts";
@@ -347,38 +351,59 @@ export default function (pi: ExtensionAPI) {
 
 		const codeIntelligenceOperations = createLectorCodeIntelligenceOperations();
 
+		const editorOverlayOptions = { overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "center" } } as const;
+
+		async function openFileInEditor(commandCtx: ExtensionCommandContext, absolutePath: string): Promise<void> {
+			let session: Awaited<ReturnType<typeof openEditorFile>>;
+			try {
+				session = await openEditorFile(absolutePath);
+			} catch (error) {
+				commandCtx.ui.notify(`Could not open ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`, "error");
+				return;
+			}
+
+			await commandCtx.ui.custom<void>((tui, theme, _keybindings, done) => {
+				const host: NeovimEditorHost = {
+					filePath: absolutePath,
+					save: (text) => session.save(text),
+					hover: async (line, character) => {
+						const result = await codeIntelligenceOperations.hover(absolutePath, line, character);
+						return result.hover;
+					},
+				};
+				return new NeovimEditorComponent(tui, theme, host, session.content, () => done(undefined));
+			}, editorOverlayOptions);
+		}
+
+		/** Oil-style: /editor with no path browses the caller's cwd (nearest git root, matching workspaceForDirectory's own convention). runExplorerFlow owns the browse/open/return-to-explorer loop; this just wires it to the real UI and Lector session. */
+		async function openExplorerFlow(commandCtx: ExtensionCommandContext): Promise<void> {
+			let session: Awaited<ReturnType<typeof openDirectoryExplorer>>;
+			try {
+				session = await openDirectoryExplorer(commandCtx.cwd);
+			} catch (error) {
+				commandCtx.ui.notify(`Could not open explorer at ${commandCtx.cwd}: ${error instanceof Error ? error.message : String(error)}`, "error");
+				return;
+			}
+
+			await runExplorerFlow(session, {
+				showExplorer: (explorerSession, relativePath) =>
+					commandCtx.ui.custom<ExplorerResult>(
+						(tui, theme, _keybindings, done) => new ExplorerComponent(tui, theme, explorerSession, relativePath, done),
+						editorOverlayOptions,
+					),
+				showEditor: (absolutePath) => openFileInEditor(commandCtx, absolutePath),
+			});
+		}
+
 		pi.registerCommand("editor", {
-			description: "Open a file in a neovim-style modal code editor",
+			description: "Open a file in a neovim-style modal code editor, or a filesystem explorer with no path",
 			handler: async (args, commandCtx) => {
 				const target = args.trim();
 				if (!target) {
-					commandCtx.ui.notify("Usage: /editor <path>", "error");
+					await openExplorerFlow(commandCtx);
 					return;
 				}
-				const absolutePath = resolve(commandCtx.cwd, target);
-
-				let session: Awaited<ReturnType<typeof openEditorFile>>;
-				try {
-					session = await openEditorFile(absolutePath);
-				} catch (error) {
-					commandCtx.ui.notify(`Could not open ${absolutePath}: ${error instanceof Error ? error.message : String(error)}`, "error");
-					return;
-				}
-
-				await commandCtx.ui.custom<void>(
-					(tui, theme, _keybindings, done) => {
-						const host: NeovimEditorHost = {
-							filePath: absolutePath,
-							save: (text) => session.save(text),
-							hover: async (line, character) => {
-								const result = await codeIntelligenceOperations.hover(absolutePath, line, character);
-								return result.hover;
-							},
-						};
-						return new NeovimEditorComponent(tui, theme, host, session.content, () => done(undefined));
-					},
-					{ overlay: true, overlayOptions: { width: "100%", maxHeight: "100%", anchor: "center" } },
-				);
+				await openFileInEditor(commandCtx, resolve(commandCtx.cwd, target));
 			},
 		});
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.10.0",
+	"version": "0.11.1",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -19,10 +19,12 @@
 	},
 	"dependencies": {
 		"@danypops/vehicle-client": "^0.2.0",
-		"@danypops/lector": "^0.14.0",
+		"@danypops/lector": "^0.15.0",
 		"malevich-tui-components": "^0.19.0"
 	},
 	"devDependencies": {
+		"@danypops/pi-extension-harness": "^0.2.0",
+		"@danypops/pi-tui-harness": "^0.0.1",
 		"@earendil-works/pi-ai": "^0.81.1",
 		"@earendil-works/pi-coding-agent": "^0.81.1",
 		"@earendil-works/pi-tui": "^0.81.1",