@gavin-hu/my-pi-agent 0.11.4 → 0.13.0

package/extensions/document/README.md

@@ -44,7 +44,7 @@ them along. Then ask the model to read a document, or call the tool directly:
 
 ## Tool
 
-`read_doc` — `exposure: "direct"`, active by default, read-only, closed-world
+`read_doc` — direct exposure, active by default, read-only, closed-world
 (no network).
 
 | Parameter | Type | Meaning |
@@ -124,11 +124,12 @@ merged over the defaults and clamped:
 |---|---|---|---|
 | `maxFileBytes` | `20971520` (20 MiB) | 1 KiB – 512 MiB | Reject larger files. |
 | `maxChars` | `40000` | 200 – 100000 | Default slice size. |
+| `extractTimeoutMs` | `30000` (30 s) | 1 s – 5 min | Per-call extraction deadline; a parser that outlasts it is abandoned. |
 | `formats` | `{ "pdf": true, "docx": true, "doc": true, "odt": true, "rtf": true, "xlsx": true }` | — | Per-format on/off, merged over each registry entry's default; unknown keys are ignored. |
 
 ```jsonc
 // bytefly.json → "document"
-{ "maxChars": 80000, "formats": { "docx": false } }
+{ "maxChars": 80000, "extractTimeoutMs": 60000, "formats": { "docx": false } }
 ```
 
 `doc.json` is not read, and neither is the old per-extension `document.json`;
@@ -142,8 +143,9 @@ run `bun run config:migrate` to move a `document.json` into the shared file.
   `resolveEffectiveCwd`; absolute paths are allowed only inside it. Containment
   is symlink-aware (`isInsideReal`), and the real, resolved path is what the
   parser receives.
-- **Size-capped.** Files larger than `maxFileBytes` are rejected before any
-  parser runs.
+- **Size-capped and time-bounded.** Files larger than `maxFileBytes` are rejected
+  before any parser runs, and a parser that outlasts `extractTimeoutMs` is
+  abandoned so the turn is not held open by one document.
 - **No subprocesses.** Extraction never spawns a process, so it grants no
   privileges beyond the current process.
 - **Untrusted text.** Extracted document text is treated as untrusted: it is
@@ -171,6 +173,10 @@ Each extractor builds a plain-text document from the format's bytes:
 The tool is pageable across the whole extracted text, so a word-processing
 document or workbook is read in the same `startIndex` / `maxChars` way as a PDF.
 
+Each call is bounded by `extractTimeoutMs` (30 s by default). A parser that
+outlasts the deadline is abandoned — the read fails with the limit named, and a
+late result is discarded — so a pathological document cannot park the turn.
+
 ## Supported formats
 
 | Format | Extensions | Extractor | Enabled by default |
@@ -203,13 +209,17 @@ config defaults, and error listing all derive from it.
 
 - Parsing is best-effort and format-specific: output fidelity varies by library,
   and a malformed file fails with that library's message.
-- Legacy `.doc` relies on `word-extractor`; there is no fixture for the OLE
-  format in the test suite, so that path is covered only for its error case.
+- Legacy `.doc` relies on `word-extractor`, which now has a committed OLE fixture
+  (`test/helpers/fixtures/files/legacy.doc`, two paragraphs generated once by a
+  real word processor). Real Word 6/95 documents vary far more than one fixture
+  can show, so the format stays best-effort.
 - No OCR: scanned or image-only PDFs return little or no text.
 - Formatting, tables, and images are not preserved (XLSX keeps the row/column
   shape but drops cell styling and formulas; DOCX/ODT keep table cells as tabs).
-- No extraction timeout. `maxFileBytes` bounds the input, but a complex PDF can
-  be CPU-heavy; `maxChars` limits the returned slice, not peak extraction memory.
+- The deadline stops waiting and discards the result; it cannot preempt a parser
+  that never yields to the event loop, because JavaScript cannot interrupt a
+  synchronous parse. A worker thread could; the package does not use one.
+- `maxChars` limits the returned slice, not peak extraction memory.
 - Only one file per call; legacy `.xls` gets a conversion hint.
 
 ## Non-goals
@@ -226,7 +236,7 @@ config defaults, and error listing all derive from it.
 | Aspect | Contract |
 |---|---|
 | Registration | `document(pi)` in `index.ts` calls `registerDocTool(pi)`, which registers `read_doc`. The factory only registers; no parser loads until a read needs it. |
-| Tool | `read_doc`, `exposure: "direct"`, `defaultActive: true`, default (`parallel`) execution, `annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, and `renderCall`/`renderResult` (reuse `context.lastComponent`; read `context.cwd` and `context.isError`). |
+| Tool | `read_doc`, direct exposure and active on registration (the defaults), default (`parallel`) execution, `annotations: { readOnlyHint: true, openWorldHint: false }`, TypeBox `parameters` and `outputSchema`, and `renderCall`/`renderResult` (reuse `context.lastComponent`; read `context.cwd` and `context.isError`). |
 | State | None persisted. Per-result state lives in the tool-result `details` / `structuredContent`; the renderer reads only that. |
 | Lifecycle | No `session_start` / `session_shutdown` hooks: each read imports a parser, runs it, and holds no long-lived resources. |
 | Host seams | `resolveEffectiveCwd` (`lib/env.ts`), `isInsideReal` / `realPathOfNearest` (`lib/path.ts`), `loadConfigSection` (`lib/config.ts`), `stripControlChars` / `sanitize` / `formatTokens` (`lib/format.ts`), `SEPARATORS` (`lib/tui/glyphs.ts`). |
@@ -285,8 +295,8 @@ bun test extensions/document
 ```
 
 Extractor tests run against real minimal files (`test/helpers/fixtures/documents.ts`
-builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`), so the
-libraries are exercised, not stubbed. `tool.test.ts` injects fake extractors for
-behavioural cases and reads one real PDF end to end;
-`test/helpers/fixtures/document.ts` provides the scratch root and an escape
-symlink.
+builds a genuine PDF, DOCX, and ODT; XLSX is written with `exceljs`; legacy `.doc`
+reads the committed `files/legacy.doc`), so the libraries are exercised, not
+stubbed. `tool.test.ts` injects fake extractors for behavioural cases and reads a
+real PDF and a real `.doc` end to end; `test/helpers/fixtures/document.ts`
+provides the scratch root and an escape symlink.

package/extensions/document/config.ts

@@ -15,6 +15,8 @@ export interface DocConfig {
 	maxFileBytes: number;
 	/** Default character budget for the returned slice. */
 	maxChars: number;
+	/** Per-call extraction deadline; a parser that outlasts it is abandoned. */
+	extractTimeoutMs: number;
 	/** Per-format on/off, merged over each registry entry's `defaultEnabled`. */
 	formats: Record<FormatId, boolean>;
 }
@@ -22,6 +24,7 @@ export interface DocConfig {
 export const DEFAULT_CONFIG: DocConfig = {
 	maxFileBytes: 20 * 1024 * 1024,
 	maxChars: 40_000,
+	extractTimeoutMs: 30_000,
 	formats: Object.fromEntries(FORMATS.map((format) => [format.id, format.defaultEnabled])) as Record<FormatId, boolean>,
 };
 
@@ -43,6 +46,7 @@ export function normalizeConfig(raw: Record<string, unknown> | undefined, base:
 	return {
 		maxFileBytes: clampInteger(raw.maxFileBytes, base.maxFileBytes, 1_024, 512 * 1024 * 1024),
 		maxChars: clampInteger(raw.maxChars, base.maxChars, 200, 100_000),
+		extractTimeoutMs: clampInteger(raw.extractTimeoutMs, base.extractTimeoutMs, 1_000, 300_000),
 		formats: normalizeFormats(raw.formats, base.formats),
 	};
 }

package/extensions/document/deadline.ts

@@ -0,0 +1,61 @@
+/**
+ * A per-call deadline for one in-process extraction.
+ *
+ * A parser is a library call, not a subprocess: JavaScript cannot preempt a
+ * synchronous parse, so the deadline stops *waiting* for the work and discards
+ * its result rather than killing it. What it guarantees is the turn: a
+ * pathological file fails with the limit named instead of parking the session,
+ * and a late settle from the abandoned promise never surfaces.
+ *
+ * The timer is a plain `setTimeout` cleared in `finally` (unlike
+ * `AbortSignal.timeout`, whose timer cannot be cancelled and would stay pending
+ * after every fast read). The deadline is deliberately not passed into `work`:
+ * the caller's abort signal is the only abort an extractor sees, so a timeout
+ * can never be reported as a turn abort or the reverse.
+ */
+
+/** How the deadline reports, and when to give up. */
+export interface DeadlineOptions {
+	/** Milliseconds to wait before abandoning the work. */
+	timeoutMs: number;
+	/** The error message a timeout throws; the caller names its own limit. */
+	timeoutMessage: string;
+	/** The turn's abort signal; an abort wins over the deadline. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Run `work` with a deadline. Resolves with its value, rethrows its error
+ * unchanged, or rejects with `timeoutMessage` (or the caller's abort reason).
+ */
+export async function withDeadline<T>(work: () => Promise<T>, options: DeadlineOptions): Promise<T> {
+	const { timeoutMs, timeoutMessage, signal } = options;
+
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const expiry = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+		// A pending timer must not keep a short-lived process alive.
+		(timer as { unref?: () => void }).unref?.();
+	});
+
+	let onAbort: (() => void) | undefined;
+	const aborted = signal
+		? new Promise<never>((_resolve, reject) => {
+				onAbort = () => reject(signal.reason ?? new Error("aborted"));
+				if (signal.aborted) onAbort();
+				else signal.addEventListener("abort", onAbort, { once: true });
+			})
+		: undefined;
+
+	const pending = work();
+	// One observed promise: if the deadline or the abort wins, a late resolve or
+	// rejection from the abandoned work has nobody left to reach.
+	pending.catch(() => {});
+
+	try {
+		return await Promise.race(aborted ? [pending, expiry, aborted] : [pending, expiry]);
+	} finally {
+		clearTimeout(timer);
+		if (onAbort) signal?.removeEventListener("abort", onAbort);
+	}
+}

package/extensions/document/tool.ts

@@ -18,6 +18,7 @@ import { isInsideReal, realPathOfNearest } from "../../lib/path.ts";
 import { reuseText } from "../../lib/tui/chrome.ts";
 import { elapsedSuffix, reuseCallText, startToolProgress, syncElapsedTimer } from "../../lib/tui/tool.ts";
 import { isFormatEnabled, loadConfig } from "./config.ts";
+import { withDeadline } from "./deadline.ts";
 import type { DocExtractor } from "./extract/file.ts";
 import { detectFormat, supportedExtensions, unsupportedHint, type FormatId } from "./formats.ts";
 import { formatDoc } from "./paging.ts";
@@ -63,6 +64,8 @@ async function statFile(abs: string, display: string, maxFileBytes: number): Pro
 /** Per-format extractor overrides, for tests; the format table supplies the rest. */
 export interface DocToolDeps {
 	extractors?: Partial<Record<FormatId, DocExtractor>>;
+	/** Test seam: replace the configured `document.extractTimeoutMs`. */
+	timeoutMs?: number;
 }
 
 export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void {
@@ -71,7 +74,8 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 		label: "Read document",
 		description:
 			"Read a local PDF, DOCX, DOC, ODT, RTF, or XLSX file and return its extracted text, pageable with " +
-			"startIndex/maxChars. Extraction runs in process, so no external tools are needed.",
+			"startIndex/maxChars. Extraction runs in process, so no external tools are needed; a read that outlasts " +
+			"document.extractTimeoutMs fails with the limit named.",
 		promptSnippet: "Read a PDF, DOCX, DOC, ODT, RTF, or XLSX as text, paged with startIndex/maxChars.",
 		promptGuidelines: [
 			"Use read_doc for .pdf/.docx/.doc/.odt/.rtf/.xlsx; the built-in read tool is for text and images.",
@@ -79,9 +83,7 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 		],
 		parameters: DocParams,
 		outputSchema: DocOutput,
-		exposure: "direct",
-		defaultActive: true,
-		annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
 			const args = params as DocArgs;
@@ -103,8 +105,15 @@ export function registerDocTool(pi: ExtensionAPI, deps: DocToolDeps = {}): void
 
 			const size = await statFile(abs, display, config.maxFileBytes);
 			const extractor = deps.extractors?.[format.id] ?? format.extract;
+			const timeoutMs = deps.timeoutMs ?? config.extractTimeoutMs;
 			startToolProgress(onUpdate);
-			const text = await extractor({ path: abs, signal });
+			const text = await withDeadline(() => extractor({ path: abs, signal }), {
+				timeoutMs,
+				signal,
+				timeoutMessage:
+					`Extraction of ${display} did not finish within ${timeoutMs} ms (document.extractTimeoutMs). ` +
+					`The ${format.label} parser was abandoned; raise the limit or read a smaller file.`,
+			});
 
 			const startIndex = typeof args.startIndex === "number" ? Math.max(0, Math.round(args.startIndex)) : 0;
 			const requested = typeof args.maxChars === "number" ? args.maxChars : config.maxChars;

package/extensions/file-browse/README.md

@@ -22,8 +22,9 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   opens the browser (unless `autoOpen: false`).
 - **Two-pane UI.** A server-rendered tree, directory listings, and file pages,
   progressively enhanced by one first-party script (filter, lazy tree
-  expansion, thumbnail fallback). Below 860px the tree collapses into a
-  `Files` disclosure above the listing. A hairline progress bar tracks whichever
+  expansion, thumbnail fallback). The tree scrolls in its own pane with quick
+  open and the filter pinned above it; below 860px it collapses into a `Files`
+  disclosure above the listing. A hairline progress bar tracks whichever
   column is scrolling (the card body for a file or diff, the main column
   otherwise), and the served folder names the root page.
 - **Rich previews.** Text, rendered Markdown, images (thumbnails), and
@@ -222,11 +223,14 @@ document and the project document (project wins):
   non-matching rows while keeping ancestors, disclosure triangles lazily
   `fetch("/api/tree")`, broken thumbnails fall back to the category icon, the
   listing headers sort in place, the wrap toggle is remembered, and the copy
-  buttons use the clipboard. Without JS the page still browses and renders
-  Markdown, and the JS-only controls (filter, disclosure, actions, quick open)
-  are hidden; the sort buttons lose their pointer so they do not look live. The
-  palette is the shared Bytefly web theme (`lib/web/tokens.ts`), derived from the
-  `bytefly-dark`/`bytefly-light` terminal themes; it follows
+  buttons use the clipboard. On wide screens the tree is its own scroll pane
+  under the pinned filter and quick-open trigger; the sidebar is a `<details>`
+  whose content wrapper has no definite height, so the panel fills it
+  absolutely and the tree flexes inside. Without JS the page still browses and
+  renders Markdown, and the JS-only controls (filter, disclosure, actions, quick
+  open) are hidden; the sort buttons lose their pointer so they do not look
+  live. The palette is the shared Bytefly web theme (`lib/web/tokens.ts`),
+  derived from the `bytefly-dark`/`bytefly-light` terminal themes; it follows
   `prefers-color-scheme` until an explicit choice sets `data-theme` on the root:
   `/theme.js` applies the saved choice in the head before first paint, and the
   header toggle flips and stores it (`pi-web-theme` in `localStorage`, the key
@@ -273,7 +277,7 @@ document and the project document (project wins):
   `--cached` before the first commit), `staged` against the index, and
   `worktree` against the index from the other side. An untracked file renders as
   all-add through `readFileView`, so binary and over-size handling is shared
-  with the file view. `git diff --shortstat` supplies the chip totals and
+  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`.
 - **Streaming responses.** The server streams `filePath` responses and

package/extensions/file-browse/client.ts

@@ -11,7 +11,7 @@
  * and `bun build --no-bundle` needs no separate asset.
  */
 
-import { THEME_TOGGLE_JS } from "../../lib/web/index.ts";
+import { SIDEBAR_COLLAPSE_MAX, THEME_TOGGLE_JS } from "../../lib/web/index.ts";
 
 export const CLIENT_JS = `(function () {
 	"use strict";
@@ -183,7 +183,7 @@ export const CLIENT_JS = `(function () {
 
 	var panel = document.querySelector("details.bf-app__sidebar");
 	if (panel && window.matchMedia) {
-		var mq = window.matchMedia("(max-width: 860px)");
+		var mq = window.matchMedia("(max-width: ${SIDEBAR_COLLAPSE_MAX}px)");
 		var syncSide = function () { panel.open = !mq.matches; };
 		syncSide();
 		if (mq.addEventListener) mq.addEventListener("change", syncSide);
@@ -289,11 +289,11 @@ export const CLIENT_JS = `(function () {
 		});
 	}
 
-	function flash(button, label) {
+	function flash(button, label, message) {
 		var original = button.textContent;
 		button.textContent = label;
 		var status = document.getElementById("copy-status");
-		if (status) status.textContent = label === "copied" ? "Copied to clipboard" : "Copy failed";
+		if (status) status.textContent = message;
 		window.setTimeout(function () { button.textContent = original; }, 1200);
 	}
 
@@ -310,8 +310,8 @@ export const CLIENT_JS = `(function () {
 			}
 			source
 				.then(function (text) { return copyText(text); })
-				.then(function () { flash(button, "copied"); })
-				.catch(function () { flash(button, "failed"); });
+				.then(function () { flash(button, "copied", "Copied to clipboard"); })
+				.catch(function () { flash(button, "failed", "Copy failed"); });
 		});
 	});
 
@@ -483,7 +483,6 @@ export const CLIENT_JS = `(function () {
 			option.id = "palette-option-" + index;
 			option.setAttribute("role", "option");
 			option.setAttribute("data-index", String(index));
-			option.setAttribute("aria-selected", index === 0 ? "true" : "false");
 			appendHighlighted(option, result.path, result.positions);
 			paletteList.appendChild(option);
 		});

package/extensions/file-browse/files.ts

@@ -46,7 +46,6 @@ const TEXT_EXTS = new Set([
 	".ini",
 	".cfg",
 	".conf",
-	".env",
 	".xml",
 	".csv",
 	".tsv",
@@ -89,9 +88,6 @@ const TEXT_EXTS = new Set([
 	".vue",
 	".svelte",
 	".astro",
-	".gitignore",
-	".gitattributes",
-	".editorconfig",
 ]);
 const TEXT_NAMES = new Set([
 	"license",

package/extensions/file-browse/git.ts

@@ -137,8 +137,8 @@ interface RepoState {
 const INSERTIONS = /(\d+) insertions?\(\+\)/;
 const DELETIONS = /(\d+) deletions?\(-\)/;
 
-/** A count from a `--shortstat` line, or `0` when the line does not carry it. */
-function shortstatCount(text: string, pattern: RegExp): number {
+/** A count from a diffstat summary line, or `0` when the line does not carry it. */
+function summaryCount(text: string, pattern: RegExp): number {
 	const match = pattern.exec(text);
 	return match ? Number(match[1]) : 0;
 }
@@ -218,17 +218,16 @@ export function createGitDiff(
 			const current = await state();
 			if (!current) return undefined;
 			const args = diffArgs(effectiveMode(mode, current.hasCommits));
-			const [stat, shortstat] = await Promise.all([
-				run(["diff", "--no-color", "--stat", ...args, "--"], { cwd: root }),
-				run(["diff", "--no-color", "--shortstat", ...args, "--"], { cwd: root }),
-			]);
-			const summary = shortstat.code === 0 ? shortstat.stdout : "";
+			const stat = await run(["diff", "--no-color", "--stat", ...args, "--"], { cwd: root });
+			const output = stat.code === 0 ? stat.stdout : "";
+			const trimmed = output.trimEnd();
+			const summary = trimmed.slice(trimmed.lastIndexOf("\n") + 1);
 			return {
 				mode,
 				files: current.files.filter((file) => inMode(file, mode)),
-				stat: stat.code === 0 ? stat.stdout.trim() : "",
-				insertions: shortstatCount(summary, INSERTIONS),
-				deletions: shortstatCount(summary, DELETIONS),
+				stat: output.trim(),
+				insertions: summaryCount(summary, INSERTIONS),
+				deletions: summaryCount(summary, DELETIONS),
 			};
 		},
 		async file(rel, mode) {

package/extensions/file-browse/html.ts

@@ -12,6 +12,7 @@ import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import {
 	brandLockup,
 	docHead,
+	SIDEBAR_COLLAPSE_MAX,
 	WEB_BASE_CSS,
 	WEB_COMPONENTS_CSS,
 	WEB_LAYOUT_CSS,
@@ -61,7 +62,7 @@ export interface ChangeSummary {
 }
 
 /** Whether a path carries a change marker: a changed file, or a directory above one. */
-export function isChanged(summary: ChangeSummary | undefined, rel: string, isDir: boolean): boolean {
+function isChanged(summary: ChangeSummary | undefined, rel: string, isDir: boolean): boolean {
 	if (!summary || !rel) return false;
 	return isDir ? summary.dirs.has(rel) : summary.files.has(rel);
 }
@@ -169,6 +170,16 @@ body.palette-open{overflow:hidden}
 .browse-keys dt{white-space:nowrap}
 .browse-keys dd{margin:0;color:var(--muted);font-size:var(--fs-sm)}
 .browse-kbd{display:inline-block;min-width:20px;padding:1px 6px;border:1px solid var(--border);border-bottom-width:2px;border-radius:var(--radius-sm);background:var(--surface);color:var(--text);font:var(--fs-xs) var(--font-mono);text-align:center}
+/* Wide screens: pin quick open and the filter, and scroll the tree on its own
+   box. The sidebar is a details element, whose content sits in an anonymous
+   wrapper with no definite height, so the panel fills the sidebar by absolute
+   positioning; below the sidebar breakpoint the disclosure keeps normal page
+   scroll. */
+@media not (max-width:${SIDEBAR_COLLAPSE_MAX}px){
+.browse-sidebar{position:relative;overflow:hidden}
+.browse-side{position:absolute;inset:0;display:flex;flex-direction:column;overflow:hidden}
+.browse-side .bf-tree{flex:1 1 auto;min-height:0;overflow:auto}
+}
 @media (max-width:820px){
 .browse-root{order:9;flex:1 1 100%;direction:ltr;text-align:left}
 }
@@ -238,7 +249,7 @@ ${SPRITE}
   <button type="button" class="bf-btn bf-btn--icon bf-theme-toggle" id="theme-toggle" aria-label="Toggle light and dark theme" title="Toggle light and dark theme"><span class="theme-glyph" aria-hidden="true">☾</span></button>
 </div><div class="browse-progress" aria-hidden="true"><span class="browse-progress__fill" id="progress-fill"></span></div></header>
 <div class="bf-app__body">
-  <details class="bf-app__sidebar" open>
+  <details class="bf-app__sidebar browse-sidebar" open>
     <summary class="bf-panel__summary">Files</summary>
     <aside class="bf-panel browse-side">
       <button type="button" class="browse-quick-open" id="quick-open" aria-haspopup="dialog"><span>quick open</span><kbd>/</kbd></button>
@@ -252,7 +263,7 @@ ${SPRITE}
 ${layout.main}
   </main>
 </div>
-<footer class="bf-app__footer">served from ${escapeHtml(layout.rootLabel)} · read-only · ${layout.footerNote}</footer>
+<footer class="bf-app__footer">served from ${escapeHtml(layout.rootLabel)} · read-only · ${escapeHtml(layout.footerNote)}</footer>
 ${layout.keys && layout.keys.length > 0 ? renderKeysSheet(layout.keys) : ""}
 <script src="/app.js" defer></script>
 </body>
@@ -283,7 +294,7 @@ function renderTreeNode(node: TreeNode, currentRel: string, summary?: ChangeSumm
 	const expanded = node.children.length > 0;
 	const isDir = node.isDir;
 	const spec = isDir ? FOLDER_ICON : languageOf(node.name);
-	const href = isDir ? (node.rel ? `/browse/${encodePath(node.rel)}` : "/browse/") : `/view/${encodePath(node.rel)}`;
+	const href = hrefFor(node);
 	const current = node.rel === currentRel ? ` aria-current="page"` : "";
 	const twisty = isDir
 		? `<button type="button" class="bf-tree__tw bf-tree__tw--toggle" aria-expanded="${expanded}" aria-label="${escapeHtml(node.name)}">${expanded ? "▾" : "▸"}</button>`
@@ -495,7 +506,7 @@ export function renderFilePage(page: FilePage): string {
 		mainClass: rendered ? "browse-page browse-measure" : "browse-page",
 		keys,
 		main: `    <div class="bf-card">${head}${content}</div>\n    ${note}`,
-		footerNote: escapeHtml(page.rel),
+		footerNote: page.rel,
 		git: page.git,
 		summary: page.summary,
 	});
@@ -715,7 +726,7 @@ export function renderFileDiffPage(page: FileDiffPage): string {
 		mainClass: "browse-page",
 		keys,
 		main: `    <div class="bf-card">${head}${content}</div>\n    ${note}`,
-		footerNote: `diff · ${escapeHtml(modeScope(page.mode))}`,
+		footerNote: `diff · ${modeScope(page.mode)}`,
 		git: page.git,
 		summary: page.summary,
 	});
@@ -726,7 +737,6 @@ export interface ErrorPage {
 	status: number;
 	message: string;
 	tree: TreeNode;
-	rel: string;
 	git?: GitStatus;
 }
 

package/extensions/file-browse/router.ts

@@ -7,6 +7,7 @@
  * tested without a socket.
  */
 
+import type { Stats } from "node:fs";
 import { stat } from "node:fs/promises";
 import { THEME_JS } from "../../lib/web/index.ts";
 import { CLIENT_JS } from "./client.ts";
@@ -87,8 +88,8 @@ function jsonResponse(status: number, value: unknown): ServeResponse {
 	};
 }
 
-async function treeFor(ctx: ServeContext, _currentRel: string): Promise<TreeNode> {
-	return buildTree(ctx.root, _currentRel, ctx.config.maxDirEntries);
+async function treeFor(ctx: ServeContext, currentRel: string): Promise<TreeNode> {
+	return buildTree(ctx.root, currentRel, ctx.config.maxDirEntries);
 }
 
 /** Resolve the header's git context, never failing the request. */
@@ -153,18 +154,30 @@ async function errorResponse(
 		status,
 		message,
 		tree,
-		rel: "",
 		git: await gitFor(ctx),
 	});
 	return { status, headers: { ...HTML_SECURITY, ...extra }, body };
 }
 
-async function browse(ctx: ServeContext, rawRel: string): Promise<ServeResponse> {
+/** Resolve a request path once and render the directory or file page it names. */
+async function renderPath(ctx: ServeContext, rawRel: string, raw: boolean): Promise<ServeResponse> {
 	const abs = await resolveRequestPath(ctx.root, rawRel);
 	const rel = relativePath(ctx.root, abs);
-	const info = await stat(abs).catch(() => undefined);
-	if (!info || !info.isDirectory()) return view(ctx, rawRel, false);
+	const info: Stats | undefined = await stat(abs).catch(() => undefined);
+	if (info?.isDirectory()) return directoryResponse(ctx, rel);
+	if (!info) throw new HttpError(404, "That path does not exist.");
+	return fileResponse(ctx, rel, raw);
+}
 
+async function browse(ctx: ServeContext, rawRel: string): Promise<ServeResponse> {
+	return renderPath(ctx, rawRel, false);
+}
+
+async function view(ctx: ServeContext, rawRel: string, raw: boolean): Promise<ServeResponse> {
+	return renderPath(ctx, rawRel, raw);
+}
+
+async function directoryResponse(ctx: ServeContext, rel: string): Promise<ServeResponse> {
 	const listing = await listDirectory(ctx.root, rel, ctx.config.maxDirEntries);
 	const tree = await treeFor(ctx, rel);
 	const git = await gitFor(ctx);
@@ -184,13 +197,7 @@ async function browse(ctx: ServeContext, rawRel: string): Promise<ServeResponse>
 	);
 }
 
-async function view(ctx: ServeContext, rawRel: string, raw: boolean): Promise<ServeResponse> {
-	const abs = await resolveRequestPath(ctx.root, rawRel);
-	const rel = relativePath(ctx.root, abs);
-	const info = await stat(abs).catch(() => undefined);
-	if (info?.isDirectory()) return browse(ctx, rawRel);
-	if (!info) throw new HttpError(404, "That path does not exist.");
-
+async function fileResponse(ctx: ServeContext, rel: string, raw: boolean): Promise<ServeResponse> {
 	const file = await readFileView(ctx.root, rel, ctx.config.maxFileBytes, ctx.config.maxTextLines, ctx.config.markdown);
 	const tree = await treeFor(ctx, rel);
 	const git = await gitFor(ctx);
@@ -375,7 +382,9 @@ export async function handleRequest(
 		if (pathname.startsWith("/raw/")) return await raw(ctx, pathname.slice("/raw/".length));
 		return errorResponse(ctx, 404, "That page does not exist.");
 	} catch (error) {
-		if (error instanceof HttpError) return errorResponse(ctx, error.status, error.message);
-		return errorResponse(ctx, 500, "Something went wrong reading that path.");
+		const status = error instanceof HttpError ? error.status : 500;
+		const message = error instanceof HttpError ? error.message : "Something went wrong reading that path.";
+		if (pathname.startsWith("/api/")) return jsonResponse(status, { error: message });
+		return errorResponse(ctx, status, message);
 	}
 }