@gavin-hu/my-pi-agent 0.15.0 → 0.15.1

package/README.md

@@ -73,10 +73,9 @@ Then, from inside Pi:
 - `/bytefly [extension] [refresh]` opens the control center on Extensions, lists
   every loaded extension with its runtime health, enables or disables one, and
   clears a project override with `x`.
-- `/bytefly settings` opens the control center's Settings section: ten groups
-  covering startup, notifications, diagnostics, pricing, transcript, terminal,
-  worktree, snapshots, jobs, and memory, plus a **Theme** row, with
-  `Space`/`Enter` to change a value and `Tab` for Global/Project scope.
+- `/bytefly settings` opens the control center's Settings section: the curated
+  settings, grouped by area, plus a **Theme** row, with `Space`/`Enter` to change
+  a value and `Tab` for Global/Project scope.
 - `/bytefly doctor [extension] [refresh]` prints the doctor report —
   `run_doctor`'s text — and checks that each enabled extension has what it needs
   at runtime.
@@ -94,9 +93,8 @@ Nothing about the session is sent, and `PI_OFFLINE` skips the check;
 
 ## What you get
 
-Seventeen extensions and two packaged skills, grouped by what you are trying to
-do, plus two themes. Each extension's own `README.md` has the full tool and
-command surface.
+17 extensions, 2 packaged skills, and 2 themes, grouped by what you are trying
+to do. Each extension's own `README.md` has the full tool and command surface.
 
 ### Plan and delegate
 
@@ -124,7 +122,7 @@ command surface.
 | Extension | Tools and commands | What it does |
 |---|---|---|
 | [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | Search the web (keyless DuckDuckGo by default, optional SearXNG or Brave) and fetch a page as readable text, with paging, `find`, per-hop SSRF checks, and optional PDF support. |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview and a fuzzy quick-open palette. |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | Start a loopback, read-only file browser rooted at the working directory, with Markdown preview, a fuzzy quick-open palette, and live status for a page left open. |
 | [`document`](./extensions/document/) | `read_doc` | Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged. |
 | [`file-open`](./extensions/file-open/) | `/open`, `open_path` | Open or reveal a file or directory in the OS-native application. |
 | [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | Bridge a WeChat chat to the live session over the Weixin iLink bot API; inbound text, images, and files become turns. |

package/README.zh-CN.md

@@ -64,9 +64,8 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 - `/bytefly [extension] [refresh]` 打开控制中心的 Extensions 区，列出每个已加载扩展
   及其运行时健康状况，启用或禁用一个扩展，并用 `x` 清除项目级覆盖。
-- `/bytefly settings` 打开控制中心的 Settings 区：十个分组覆盖启动、通知、
-  诊断、计价、转录、终端、worktree、快照、任务与监听器、记忆，并提供 **Theme**
-  行；用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project 作用域。
+- `/bytefly settings` 打开控制中心的 Settings 区：精选设置按类别分组，并提供
+  **Theme** 行；用 `Space`/`Enter` 修改，用 `Tab` 切换 Global/Project 作用域。
 - `/bytefly doctor [extension] [refresh]` 打印 doctor 报告（`run_doctor` 的文本），
   检查每个已启用扩展在运行时是否具备所需条件。
 - `/bytefly update` 立即重跑包更新检查，报告可更新的包、本包版本与 release URL，
@@ -81,7 +80,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 
 ## 包含内容
 
-十七个扩展和两个随包技能，按你想达成的目标分组，外加两个主题。每个扩展自己的 `README.md`
+17 个扩展、2 个随包技能，以及 2 个主题，按你想达成的目标分组。每个扩展自己的 `README.md`
 提供完整的工具与命令说明。
 
 ### 规划与委派
@@ -110,7 +109,7 @@ Windows、macOS 和 Linux 均可运行，完整检查套件在每个平台上都
 | 扩展 | 工具与命令 | 说明 |
 |---|---|---|
 | [`web-access`](./extensions/web-access/) | `web_search`, `web_fetch` | 搜索网络（默认无密钥的 DuckDuckGo，可选 SearXNG 或 Brave），并把页面抓取为可读文本，支持分页、`find`、逐跳 SSRF 检查以及可选的 PDF 支持。 |
-| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览和模糊快速打开面板。 |
+| [`file-browse`](./extensions/file-browse/) | `/browse` | 启动一个以工作目录为根的本地回环、只读文件浏览器，带 Markdown 预览、模糊快速打开面板，以及为常开页面提供的实时状态。 |
 | [`document`](./extensions/document/) | `read_doc` | 在进程内从本地 PDF、DOCX、DOC、ODT、RTF 或 XLSX 提取文本，支持分页。 |
 | [`file-open`](./extensions/file-open/) | `/open`, `open_path` | 用操作系统原生应用打开或定位文件/目录。 |
 | [`wechat`](./extensions/wechat/) | `/wechat`, `send_wechat` | 通过微信 iLink 机器人 API 把微信聊天桥接到实时会话；入站文本、图片和文件会变成回合。 |

package/extensions/file-browse/README.md

@@ -83,6 +83,13 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   `worktree`; untracked files show as all-add, an unborn `HEAD` falls back to the
   index, and a non-repository is a plain empty state. Read-only, capped, and
   rendered with the shared diff colors.
+- **Live status.** A page left open keeps up with the session: a `◉ live · 2s`
+  chip beside `read-only` says whether status is flowing (green, with the age of
+  the last frame), still connecting (accent), stalled (amber), or offline (red);
+  the branch chip, the `● N changes +A −D` chip, and the change markers in the
+  tree and the listing update in place; and the footer line reports `up 2m 14s ·
+  37 requests`. One Server-Sent Events stream per page carries it, on the same
+  loopback server, so nothing extra is opened and nothing is written.
 - **No dependencies.** `node:http` plus the inline sprite, CSS, and client
   script.
 
@@ -114,6 +121,19 @@ beside `⎇ branch` and `⑂ worktree`; it
 is cleared on stop and on `session_shutdown`. The chip is session-local: it
 reflects only this session's server, with no cross-session sharing.
 
+The page has its own live status, which is what a left-open tab reads. The
+header chip starts hidden and is painted by the client from `/events`: `◉ live ·
+2s` in the success colour while frames arrive, `◉ connecting` before the first
+one, `◉ stale · 9s` in the warning colour when three intervals pass without a
+frame on an open connection, and `◉ offline` in the danger colour once the
+stream errors. The same frame carries the branch (or detached head), the
+uncommitted-change totals and paths, the server's uptime, and the requests it
+has answered, so the branch chip, the changes chip, the markers, and the footer
+line are painted from one snapshot rather than four requests. Losing the stream
+leaves everything the page last showed in place: it is read-only, so a stale
+label is never a stale action. `"live": false` turns the whole surface off — no
+chip, no stream, no `/events` route — and so does JavaScript off.
+
 ## Routes
 
 | Route | Result |
@@ -126,6 +146,7 @@ reflects only this session's server, with no cross-session sharing.
 | `/diff/<rel>[?mode=…]` | one file's unified diff |
 | `/api/tree?path=<rel>` | JSON children for lazy tree expansion |
 | `/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
+| `/events` | Server-Sent Events stream of `status` frames for the open page |
 | `/app.js` | the first-party client script |
 | `/theme.js` | the pre-paint theme bootstrap |
 | `/favicon.ico` | `204` (the icon is a data URI) |
@@ -150,7 +171,9 @@ document and the project document (project wins):
   "maxIndexEntries": 20000,  // files collected for quick open before truncation
   "gitDiff": true,           // offer the read-only diff view
   "diffContext": 3,          // unified diff context lines
-  "maxDiffLines": 4000       // diff lines rendered before truncation
+  "maxDiffLines": 4000,      // diff lines rendered before truncation
+  "live": true,              // stream live status to open pages
+  "liveIntervalMs": 3000     // ms between status frames while a page is connected
 }
 ```
 
@@ -185,6 +208,13 @@ document and the project document (project wins):
 - **Highlighting safety.** The highlighter escapes every literal before it
   wraps it in a token span, so a code file's content cannot inject markup or
   attributes; only the fixed `tok-*` class names reach the page.
+- **Event stream.** `/events` is a `GET` on the same loopback server, behind
+  the same method and `Host` checks, and it only reads: the frame is the branch,
+  the change paths, an uptime, and a request count, all of which the page it
+  feeds already renders. It carries no page policy (`text/event-stream` is not a
+  document), sends `Cache-Control: no-store`, and cannot be cached or replayed.
+  A tick runs only while a page is attached, and the timer is `unref`ed, so an
+  idle server does no work and a forgotten tab cannot hold the process open.
 - **Caps.** `maxFileBytes` (inline rendering), `maxTextLines` (rendered lines),
   `maxThumbBytes` (thumbnails), and `maxDirEntries` (listings) bound every read.
 - **Git reads.** The header chip and the diff view run read-only git
@@ -200,6 +230,11 @@ document and the project document (project wins):
   type renders exactly as before. State that the tokenizer does not carry
   across lines (shell heredocs, interpolation inside a template literal) is
   approximated rather than parsed.
+- Live status updates what the page already contains: the header chips, the
+  markers on the rows it rendered, and the footer line. A file that appears on
+  disk joins the listing on the next reload, the `/diff` table and a file page's
+  `changes` action stay page-load snapshots, and the branch chip is only patched
+  when the page was served inside a repository.
 - `/browse` has no auth; a malicious local page could probe the port. The `Host`
   allowlist and the absence of CORS headers mitigate reads, and the server is
   read-only.
@@ -221,7 +256,7 @@ document and the project document (project wins):
 |---|---|
 | Command | `/browse` registers a single command from the factory; no tools are exposed. |
 | State | The running server, its root, and the session port live in a module-local closure; nothing is persisted and no session entries are written. |
-| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop` and `session_shutdown`. |
+| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop` and `session_shutdown`, which also ends every attached status stream. |
 
 ## Design notes
 
@@ -309,6 +344,19 @@ document and the project document (project wins):
   with the file view. `git diff --stat` supplies the chip totals and
   `changeDirs` derives the directory markers; the changed lines are highlighted
   per hunk by rebuilding the old and new sides for `lib/highlight`.
+- **Live status.** `live.ts` builds one snapshot per tick — the git status,
+  the `head` change index, the server's uptime, and its request count — and
+  `frameOf` serializes it as one `status` event. `createLiveChannel` holds the
+  attached pages and starts the ticker on the first attach, so an idle server
+  does no work; it shares a single in-flight snapshot between pages, drops a
+  page whose write fails, and stops on the last detach and on `close()`, which
+  `server.ts` calls before closing the socket. Both providers are already
+  TTL-cached, so a tick re-reads at most one `git status`, and every read
+  failure degrades to `null` rather than a failed frame. The event-stream
+  headers and the `retry:` preamble live in `lib/http` with the rest of the
+  loopback policy, shared with plan's review page. The client half is
+  `live-client.ts`: one `EventSource`, one snapshot paint (`textContent` only,
+  never markup), a one-second age ticker, and a `pagehide` cleanup.
 - **Streaming responses.** The server streams `filePath` responses and
   suppresses bodies for `HEAD`, so large `/raw` files are not buffered.
 - **Root confinement over feature breadth.** The root is deliberately confined
@@ -325,7 +373,7 @@ document and the project document (project wins):
 | [`../../lib/escape.ts`](../../lib/escape.ts) | `escapeHtml`, the shared HTML escaping used by every renderer |
 | [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer for the code view (shared with `plan`) |
 | [`../../lib/web/index.ts`](../../lib/web/index.ts) | The shared Bytefly web brand system: tokens, base, components, layout, runtime, and markup |
-| `files.ts` | Classification (incl. Markdown), listings, text reads, sidebar tree |
+| `files.ts` | Classification (incl. Markdown), text reads, and one page-level walk (`directoryView`) that returns a directory's listing and its sidebar tree |
 | `diff.ts` | Pure unified-diff and porcelain-status parsing for the diff view |
 | `fuzzy.ts` | Fuzzy path matching and ranking for the quick-open palette |
 | `markdown.ts` | First-party escape-first Markdown-to-HTML renderer (fenced code highlighted; raw HTML through `raw-html.ts`) |
@@ -334,10 +382,13 @@ document and the project document (project wins):
 | `git.ts` | Read-only branch/dirty provider for the header chip |
 | `icons.ts` | Inline SVG sprite and the per-language mapping |
 | `client.ts` | The `/app.js` source (tree toggle, filter, sort, wrap, copy, quick open) |
-| `html.ts` | Page renderers, sortable headers, and the page-only `browse-*` CSS (the `bf-*` kit comes from `lib/web`) |
+| `live-client.ts` | The client's live status block: the event stream, the chips, the markers, and the footer line (interpolated into `client.ts`) |
+| `live.ts` | The live status snapshot, its frame, and the fan-out channel that ticks it |
+| `styles.ts` | The page-only `browse-*` stylesheet (the `bf-*` kit comes from `lib/web`) |
+| `html.ts` | Page renderers: the shared shell, the two-pane layout, the listing, the cards, and the diff body |
 | `router.ts` | Pure request handler: routes, the `/raw` sandbox policy, and the error page |
 | `server.ts` | `node:http` server: this extension's handler over the shared bind, writer, and close |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: page/script/JSON headers, `ServeResponse`, the request-envelope helpers, bind/respond/close |
+| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, bind/respond/close, and `openEventStream` |
 | [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform browser opener (shared with `plan`) |
 
 ## Testing
@@ -360,5 +411,9 @@ on first start, reused, and re-rolled after a conflict), the git status provider
 and provider (line kinds, line numbers, status and rename parsing, mode
 filtering, untracked all-add, unborn-HEAD fallback, literal pathspec, and TTL
 cache), the diff renderers (highlighted changed lines, marker sets, and chip
-totals), and the command
+totals), the live status feed (snapshot fields, degraded providers, the frame,
+and the channel's ticker driven by an injected timer), the `/events` route and
+its 404 when the channel is off, a real socket that reads a page's first frame
+and the ticker's next one and sees the stream end when the server closes, the
+live chrome a page renders when on and not when off, and the command
 lifecycle with injected seams.

package/extensions/file-browse/client.ts

@@ -12,6 +12,7 @@
  */
 
 import { keysDialogScript, SIDEBAR_COLLAPSE_MAX, THEME_TOGGLE_JS } from "../../lib/web/index.ts";
+import { LIVE_CLIENT_JS } from "./live-client.ts";
 
 export const CLIENT_JS = `(function () {
 	"use strict";
@@ -716,5 +717,6 @@ export const CLIENT_JS = `(function () {
 
 	// The control starts in the state the rendered tree implies.
 	syncFoldButton();
-})();
+
+${LIVE_CLIENT_JS}})();
 `;

package/extensions/file-browse/config.ts

@@ -36,6 +36,10 @@ export interface ServeConfig {
 	diffContext: number;
 	/** Diff lines rendered before the view is truncated. */
 	maxDiffLines: number;
+	/** Push live status to open pages over `/events`. */
+	live: boolean;
+	/** How often a connected page is sent a status frame, in ms. */
+	liveIntervalMs: number;
 }
 
 export const DEFAULT_CONFIG: ServeConfig = {
@@ -52,6 +56,8 @@ export const DEFAULT_CONFIG: ServeConfig = {
 	gitDiff: true,
 	diffContext: 3,
 	maxDiffLines: 4000,
+	live: true,
+	liveIntervalMs: 3000,
 };
 
 /** Base of the per-session port range. */
@@ -60,6 +66,13 @@ export const PORT_BASE = 4780;
 /** Number of ports in the per-session range. */
 export const PORT_RANGE = 1000;
 
+/** Fastest live-status cadence a page may be given, short enough to watch and
+ * long enough that the 2 s provider caches absorb most ticks. */
+export const LIVE_INTERVAL_MIN = 250;
+
+/** Slowest live-status cadence, so a page cannot look abandoned. */
+export const LIVE_INTERVAL_MAX = 60_000;
+
 /** A random port in the per-session range `PORT_BASE`–`PORT_BASE + PORT_RANGE - 1`. */
 export function randomPort(): number {
 	return PORT_BASE + randomInt(PORT_RANGE);
@@ -85,6 +98,8 @@ export function normalizeConfig(
 		gitDiff: asBoolean(raw.gitDiff, base.gitDiff),
 		diffContext: clampInteger(raw.diffContext, base.diffContext, 0, 100),
 		maxDiffLines: clampInteger(raw.maxDiffLines, base.maxDiffLines, 1, 1_000_000),
+		live: asBoolean(raw.live, base.live),
+		liveIntervalMs: clampInteger(raw.liveIntervalMs, base.liveIntervalMs, LIVE_INTERVAL_MIN, LIVE_INTERVAL_MAX),
 	};
 }
 

package/extensions/file-browse/files.ts

@@ -8,6 +8,7 @@
 import type { Dirent, Stats } from "node:fs";
 import { readFile, readdir, stat, lstat } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
+import { mapConcurrent } from "../../lib/pool.ts";
 import { HttpError } from "./paths.ts";
 
 export type EntryKind = "directory" | "text" | "image" | "binary";
@@ -188,63 +189,168 @@ function toAbs(root: string, rel: string): string {
 	return rel ? join(root, ...rel.split("/")) : root;
 }
 
-/** List a directory, sorted (directories first, then case-insensitive name). */
-export async function listDirectory(root: string, relDir: string, limit: number): Promise<Listing> {
+/** The `Dirent` fields a listing reads; a test's fake need not be a real `Dirent`. */
+export interface DirectoryEntryInfo {
+	name: string;
+	isDirectory(): boolean;
+	isSymbolicLink(): boolean;
+}
+
+/** The `Stats` fields a listing reads. */
+export interface DirectoryStats {
+	size: number;
+	mtimeMs: number;
+	isDirectory(): boolean;
+}
+
+/**
+ * The three filesystem reads a listing makes.
+ *
+ * Injected so a test can observe them: the interesting property — a directory is
+ * read once per entry, not once per entry *and* once per row drawn — is a count,
+ * not a value, and a wall-clock assertion would be flaky on a loaded machine.
+ */
+export interface DirectoryFs {
+	readdir(path: string): Promise<DirectoryEntryInfo[]>;
+	lstat(path: string): Promise<DirectoryStats>;
+	stat(path: string): Promise<DirectoryStats>;
+}
+
+/** Production reads; a symlink's size and kind come from the target. */
+const NODE_DIRECTORY_FS: DirectoryFs = {
+	readdir: (path) => readdir(path, { withFileTypes: true }),
+	lstat: (path) => lstat(path),
+	stat: (path) => stat(path),
+};
+
+/** Reads in flight per listing: enough to hide latency, bounded against a burst. */
+const LISTING_CONCURRENCY = 32;
+
+/** A row while it is still missing its metadata. */
+interface Row {
+	name: string;
+	rel: string;
+	isDir: boolean;
+	isSymlink: boolean;
+	broken: boolean;
+	size: number;
+	mtimeMs: number;
+}
+
+/**
+ * Resolve one symlink: the link's own stat, then the target's.
+ *
+ * A symlink's directory-ness is the target's, so this cannot wait until after
+ * the sort; it is also the only entry whose classification needs a read.
+ */
+async function resolveSymlink(fs: DirectoryFs, absDir: string, row: Row): Promise<void> {
+	const abs = join(absDir, row.name);
+	try {
+		const info = await fs.lstat(abs);
+		row.size = info.size;
+		row.mtimeMs = info.mtimeMs;
+	} catch {
+		// Vanished between readdir and lstat: the target read decides below.
+	}
+	try {
+		const target = await fs.stat(abs);
+		row.isDir = target.isDirectory();
+		row.size = target.size;
+		row.mtimeMs = target.mtimeMs;
+	} catch {
+		row.broken = true;
+	}
+}
+
+/**
+ * List a directory, sorted (directories first, then case-insensitive name).
+ *
+ * A listing is latency per entry, not work per entry, so it is read in three
+ * passes instead of one entry at a time:
+ *
+ * 1. `readdir`, whose dirents already say whether each name is a directory;
+ * 2. the symlinks only, resolved through the pool, because their kind is the
+ *    target's and the sort needs it;
+ * 3. the kept rows only, `stat`ed through the pool — so a directory of three
+ *    thousand names pays for the two thousand it draws, not for every name, and
+ *    pays them concurrently instead of in turn.
+ *
+ * `total` is still the directory's full entry count and `truncated` its `> limit`
+ * flip, so the page can say how many were dropped. Ties keep `readdir` order:
+ * `sort` is stable and the rows arrive unsorted.
+ */
+export async function listDirectory(
+	root: string,
+	relDir: string,
+	limit: number,
+	fs: DirectoryFs = NODE_DIRECTORY_FS,
+): Promise<Listing> {
 	const absDir = toAbs(root, relDir);
-	let dirents: Dirent[];
+	let dirents: DirectoryEntryInfo[];
 	try {
-		dirents = await readdir(absDir, { withFileTypes: true });
+		dirents = await fs.readdir(absDir);
 	} catch {
 		throw new HttpError(404, "That folder could not be read.");
 	}
 
-	const entries: DirEntry[] = [];
-	for (const dirent of dirents) {
-		const abs = join(absDir, dirent.name);
-		const isSymlink = dirent.isSymbolicLink();
-		let isDir = dirent.isDirectory();
-		let broken = false;
-		let size = 0;
-		let mtimeMs = 0;
-		try {
-			const info = isSymlink ? await lstat(abs) : await stat(abs);
-			size = info.size;
-			mtimeMs = info.mtimeMs;
-		} catch {
-			// Directory entry vanished between readdir and stat.
-		}
-		if (isSymlink) {
-			try {
-				const target = await stat(abs);
-				isDir = target.isDirectory();
-				size = target.size;
-				mtimeMs = target.mtimeMs;
-			} catch {
-				broken = true;
-			}
-		}
-		const kind: EntryKind = isDir ? "directory" : classifyByName(dirent.name);
-		entries.push({
+	const links: Row[] = [];
+	const rows: Row[] = dirents.map((dirent) => {
+		const row: Row = {
 			name: dirent.name,
 			rel: relDir ? `${relDir}/${dirent.name}` : dirent.name,
-			isDir,
-			isSymlink,
-			broken,
-			size,
-			mtimeMs,
-			kind,
-			isImage: !isDir && kind === "image",
-		});
-	}
+			isDir: dirent.isDirectory(),
+			isSymlink: dirent.isSymbolicLink(),
+			broken: false,
+			size: 0,
+			mtimeMs: 0,
+		};
+		if (row.isSymlink) links.push(row);
+		return row;
+	});
+
+	await mapConcurrent(links, LISTING_CONCURRENCY, (row) => resolveSymlink(fs, absDir, row));
 
-	entries.sort((a, b) => {
+	// Directories first, then case-insensitive name. The sort runs before the cap,
+	// so the rows that survive it are the rows that would have been drawn.
+	rows.sort((a, b) => {
 		if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
 		return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
 	});
 
-	const total = entries.length;
+	const total = rows.length;
 	const truncated = total > limit;
-	return { entries: truncated ? entries.slice(0, limit) : entries, total, truncated };
+	const kept = truncated ? rows.slice(0, limit) : rows;
+
+	await mapConcurrent(
+		kept.filter((row) => !row.isSymlink),
+		LISTING_CONCURRENCY,
+		async (row) => {
+			try {
+				const info = await fs.stat(join(absDir, row.name));
+				row.size = info.size;
+				row.mtimeMs = info.mtimeMs;
+			} catch {
+				// Directory entry vanished between readdir and stat.
+			}
+		},
+	);
+
+	const entries: DirEntry[] = kept.map((row) => {
+		const kind: EntryKind = row.isDir ? "directory" : classifyByName(row.name);
+		return {
+			name: row.name,
+			rel: row.rel,
+			isDir: row.isDir,
+			isSymlink: row.isSymlink,
+			broken: row.broken,
+			size: row.size,
+			mtimeMs: row.mtimeMs,
+			kind,
+			isImage: !row.isDir && kind === "image",
+		};
+	});
+
+	return { entries, total, truncated };
 }
 
 /** Read a file into a renderable view, honouring the size and line caps. */
@@ -305,12 +411,37 @@ export async function buildTree(root: string, currentRel: string, limit: number)
 	return buildNode(root, "", currentRel, basename(root) || root, limit);
 }
 
+/** A directory page's two views of one directory. */
+export interface DirectoryView {
+	/** The current directory's own rows, for the page's listing. */
+	listing: Listing;
+	/** The sidebar tree, with the current path expanded. */
+	tree: TreeNode;
+}
+
+/**
+ * One walk for a directory page: the listing it draws, and the tree that shows
+ * where it sits.
+ *
+ * `listDirectory` is what decides whether the directory can be read at all, so it
+ * runs first and its 404 is the page's error. The walk then reuses that listing
+ * for the same directory instead of reading it a second time; the ancestors are
+ * still read once each, which is what the tree needs.
+ */
+export async function directoryView(root: string, currentRel: string, limit: number): Promise<DirectoryView> {
+	const listing = await listDirectory(root, currentRel, limit);
+	const tree = await buildNode(root, "", currentRel, basename(root) || root, limit, { rel: currentRel, listing });
+	return { listing, tree };
+}
+
 async function buildNode(
 	root: string,
 	relDir: string,
 	currentRel: string,
 	label: string,
 	limit: number,
+	/** A listing the caller already read for this directory, so it is not re-read. */
+	known?: { rel: string; listing: Listing },
 ): Promise<TreeNode> {
 	const node: TreeNode = {
 		name: label,
@@ -322,10 +453,14 @@ async function buildNode(
 		children: [],
 	};
 	let listing: Listing;
-	try {
-		listing = await listDirectory(root, relDir, limit);
-	} catch {
-		return node;
+	if (known && known.rel === relDir) {
+		listing = known.listing;
+	} else {
+		try {
+			listing = await listDirectory(root, relDir, limit);
+		} catch {
+			return node;
+		}
 	}
 	for (const entry of listing.entries) {
 		const child: TreeNode = {
@@ -340,7 +475,7 @@ async function buildNode(
 		if (entry.isDir) {
 			const onPath = currentRel === entry.rel || currentRel.startsWith(`${entry.rel}/`);
 			if (onPath) {
-				child.children = (await buildNode(root, entry.rel, currentRel, entry.name, limit)).children;
+				child.children = (await buildNode(root, entry.rel, currentRel, entry.name, limit, known)).children;
 			}
 		}
 		node.children.push(child);

package/extensions/file-browse/fuzzy.ts

@@ -8,6 +8,10 @@
  * parent directory. The matched character positions are returned so the client
  * can highlight them; the palette never sees HTML.
  *
+ * The palette runs this on every keystroke over an index of thousands of paths,
+ * so ranking keeps only the best `limit` candidates instead of sorting them all:
+ * the highlighted columns are computed for those winners and no others.
+ *
  * Pure and dependency-free so it can be unit-tested without a DOM.
  */
 
@@ -24,15 +28,30 @@ export interface FuzzyResult {
 /** Queries longer than this are treated as no match. */
 const MAX_QUERY_LENGTH = 256;
 
-/** Score one path against a query; `undefined` when it is not a subsequence. */
-export function fuzzyMatch(query: string, text: string): FuzzyMatch | undefined {
-	if (query === "") return { score: 0, positions: [] };
+/** A candidate while it is still unranked: a path and its score. */
+interface Candidate {
+	path: string;
+	score: number;
+}
+
+/** A scan's result; `positions` is collected only when the caller asked for it. */
+interface Scan {
+	score: number;
+	positions?: number[];
+}
+
+/**
+ * The one subsequence scan. `collect` fills the matched columns, which the
+ * ranking pass does not need and allocates an array for on every candidate.
+ */
+function scan(query: string, text: string, collect: boolean): Scan | undefined {
+	if (query === "") return collect ? { score: 0, positions: [] } : { score: 0 };
 	if (query.length > MAX_QUERY_LENGTH) return undefined;
 
 	const lowerQuery = query.toLowerCase();
 	const lowerText = text.toLowerCase();
 	const baseStart = text.lastIndexOf("/") + 1;
-	const positions: number[] = [];
+	const positions: number[] | undefined = collect ? [] : undefined;
 	let score = 0;
 	let cursor = 0;
 	let previous = -2;
@@ -40,7 +59,7 @@ export function fuzzyMatch(query: string, text: string): FuzzyMatch | undefined
 	for (let index = 0; index < lowerQuery.length; index++) {
 		const found = lowerText.indexOf(lowerQuery[index], cursor);
 		if (found === -1) return undefined;
-		positions.push(found);
+		positions?.push(found);
 
 		let bonus = 1;
 		if (text[found] === query[index]) bonus += 1;
@@ -55,21 +74,56 @@ export function fuzzyMatch(query: string, text: string): FuzzyMatch | undefined
 		previous = found;
 		cursor = found + 1;
 	}
-	return { score, positions };
+	return positions ? { score, positions } : { score };
+}
+
+/** Score one path against a query; `undefined` when it is not a subsequence. */
+export function fuzzyMatch(query: string, text: string): FuzzyMatch | undefined {
+	const scanned = scan(query, text, true);
+	return scanned ? { score: scanned.score, positions: scanned.positions ?? [] } : undefined;
+}
+
+/**
+ * The palette's one total order: the higher score first, then the shorter path
+ * (a basename match beats a name buried in a directory), then the path itself so
+ * two candidates never compare equal.
+ */
+function compare(a: Candidate, b: Candidate): number {
+	if (a.score !== b.score) return b.score - a.score;
+	if (a.path.length !== b.path.length) return a.path.length - b.path.length;
+	return a.path.localeCompare(b.path);
+}
+
+/** Keep `candidate` in `window` — sorted by {@link compare}, never longer than `limit`. */
+function keepBest(window: Candidate[], candidate: Candidate, limit: number): void {
+	let low = 0;
+	let high = window.length;
+	while (low < high) {
+		const middle = (low + high) >> 1;
+		if (compare(window[middle], candidate) <= 0) low = middle + 1;
+		else high = middle;
+	}
+	if (low >= limit) return;
+	window.splice(low, 0, candidate);
+	if (window.length > limit) window.pop();
 }
 
 /**
  * Rank `paths` against `query` and return the best `limit` matches. An empty
  * query returns nothing: the palette shows the index size instead.
+ *
+ * The result is the same list a full sort would produce — `keepBest` inserts on
+ * the same order — but the work is bounded by `limit` rather than by the index,
+ * and the matched columns are computed for the winners only.
  */
 export function fuzzySearch(query: string, paths: readonly string[], limit: number): FuzzyResult[] {
 	const trimmed = query.trim();
 	if (trimmed === "" || limit <= 0) return [];
-	const scored: Array<FuzzyResult & { score: number }> = [];
+	const window: Candidate[] = [];
 	for (const path of paths) {
-		const match = fuzzyMatch(trimmed, path);
-		if (match) scored.push({ path, positions: match.positions, score: match.score });
+		const scored = scan(trimmed, path, false);
+		if (scored === undefined) continue;
+		keepBest(window, { path, score: scored.score }, limit);
 	}
-	scored.sort((a, b) => b.score - a.score || a.path.length - b.path.length || a.path.localeCompare(b.path));
-	return scored.slice(0, limit).map(({ path, positions }) => ({ path, positions }));
+	return window.map(({ path }) => ({ path, positions: fuzzyMatch(trimmed, path)?.positions ?? [] }));
 }