@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/extensions/bytefly/working/register.ts

@@ -0,0 +1,88 @@
+/**
+ * bytefly's live working timer.
+ *
+ * Pi's working row shows a static `Working`, so a long run reads the same as a
+ * short one. This surface advances the message once a second while the row is
+ * up, and hands it back to Pi when the row comes down.
+ *
+ * The timer is tied to the row's visibility. The host shows the working
+ * indicator in its own `turn_start` handler and clears it at `agent_end`
+ * (`interactive-mode.js`), so the tick starts at `turn_start` and stops at
+ * `agent_end` — the two moments the row appears and disappears. Turns inside
+ * one run do not restart it: the host leaves the same indicator up across
+ * turns, and `start` is a no-op while it is counting.
+ *
+ * Compaction and auto-retry also replace the row, but both run outside this
+ * window (`auto_retry_start` follows `agent_end`; the before-settle compaction
+ * runs after it), and neither is an extension event, so there is nothing to
+ * hook and nothing to undo.
+ *
+ * The handle is global (`setWorkingMessage` drives the single working row), so
+ * the tick is cancelled and the message reset on stop and, belt and braces, on
+ * `session_shutdown` — the factory itself only registers.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { WORKING_CONFIG } from "./config.ts";
+import { workingCounter } from "./format.ts";
+
+/** Host seams, injected by tests so the tick is deterministic. */
+export interface WorkingDeps {
+	/** The clock the count is read from. */
+	now?: () => number;
+	/** Start the repeating tick; returns a cancel handle. */
+	schedule?: (tick: () => void, intervalMs: number) => () => void;
+}
+
+/** A repeating timer that never holds the process open on its own. */
+function defaultSchedule(tick: () => void, intervalMs: number): () => void {
+	const timer = setInterval(tick, intervalMs);
+	(timer as { unref?: () => void }).unref?.();
+	return () => clearInterval(timer);
+}
+
+/** Register the timer; it runs only in interactive (`tui`) sessions. */
+export function registerWorkingTimer(pi: ExtensionAPI, deps: WorkingDeps = {}): void {
+	const now = deps.now ?? (() => Date.now());
+	const schedule = deps.schedule ?? defaultSchedule;
+	let cancel: (() => void) | undefined;
+	let startedAt = 0;
+	// A boolean, not `startedAt === 0`: an injected clock is allowed to start at 0.
+	let active = false;
+
+	/** Stop the tick and hand the working message back to Pi. Idempotent. */
+	const stop = (ctx: ExtensionContext): void => {
+		cancel?.();
+		cancel = undefined;
+		if (!active) return;
+		active = false;
+		ctx.ui.setWorkingMessage(undefined);
+	};
+
+	/** Start the count for the current turn; a no-op while already counting. */
+	const start = (ctx: ExtensionContext): void => {
+		if (active) return;
+		startedAt = now();
+		active = true;
+		const tick = (): void => {
+			ctx.ui.setWorkingMessage(workingCounter(now() - startedAt));
+		};
+		tick();
+		cancel = schedule(tick, WORKING_CONFIG.intervalMs);
+	};
+
+	// The host shows the working indicator on its own `turn_start` handler, so
+	// this is the first frame the row is up.
+	pi.on("turn_start", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		start(ctx);
+	});
+
+	// The host clears the working indicator at `agent_end`.
+	pi.on("agent_end", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		stop(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => stop(ctx));
+}

package/extensions/document/README.md

@@ -8,6 +8,12 @@
 the effective working directory with the same symlink-aware guard the built-in
 path tools use.
 
+## Tool rendering
+
+How the `read_doc` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/read_doc.png" alt="The read_doc tool's result: the call line and an indented body with the file path, format, size, and the extracted text preview" width="100%">
+
 ## Quickstart
 
 ```bash
@@ -76,19 +82,20 @@ interactive transcript (and HTML exports).
 
 The call line carries the path (`~`-shortened, OSC-8 linked when the terminal
 supports it) and any paging options. The result line drops the path — it is
-already on the call line — and leads with the format and a humanized range:
+already on the call line — and leads with the format and the character range,
+grouped so a `k` suffix never sits on one bound and not the other:
 
 ```
 read_doc ~/docs/spec.pdf (from 40k, max 80k)
-PDF · 1–40k of 42k chars · more at 40k · ctrl+o
+PDF · chars 40,001–120,000 of 250,000 · next at 120,000 · ctrl+o
 ```
 
 Expanded adds a blank line before the preview body, matching the built-in
 header/output gap:
 
 ```
-read_doc ~/docs/spec.pdf
-PDF · 1–40k of 42k chars · more at 40k
+read_doc ~/docs/spec.pdf (from 40k, max 80k)
+PDF · chars 40,001–120,000 of 250,000 · next at 120,000
 
 Chapter 1
 This specification defines ...
@@ -218,7 +225,7 @@ config defaults, and error listing all derive from 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`). |
 | 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/ui.ts`). |
+| 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`). |
 | Config | The `document` section of the shared `bytefly.json` via `loadConfigSection` (`~/.pi/agent`, `<cwd>/.pi`). |
 
 ## Design notes

package/extensions/document/paging.ts

@@ -6,7 +6,7 @@
  * the clean slice; the text adds a header and any truncation note.
  */
 
-import { formatTokens } from "../../lib/format.ts";
+import { formatCount } from "../../lib/format.ts";
 import type { FormatId } from "./formats.ts";
 
 export interface DocPageInput {
@@ -72,9 +72,9 @@ export interface DocSummaryInput {
 export interface DocSummary {
 	/** Uppercase format id, e.g. `PDF`. */
 	format: string;
-	/** Range detail, e.g. `1–40k of 42k chars`. */
+	/** Range detail, e.g. `chars 1–40,000 of 42,478`. */
 	detail: string;
-	/** `more at N` when truncated, `complete` for a non-first final page. */
+	/** `next at N` when truncated, `complete` for a non-first final page. */
 	note?: string;
 	/** Whether more text remains; the renderer colours the note with this. */
 	truncated: boolean;
@@ -83,9 +83,9 @@ export interface DocSummary {
 /**
  * Describe a `read_doc` result for the transcript, without theme colours.
  *
- * Counts are humanized. A complete first read shows the total; a paged read
- * shows the returned range so a truncated result is never mistaken for the
- * whole document.
+ * A complete first read shows the total; a paged read shows the returned range
+ * and where to continue, so a truncated result is never mistaken for the whole
+ * document.
  */
 export function summarizeDoc(input: DocSummaryInput): DocSummary {
 	const format = input.format.toUpperCase();
@@ -93,18 +93,18 @@ export function summarizeDoc(input: DocSummaryInput): DocSummary {
 	if (input.startIndex >= input.chars) {
 		return {
 			format,
-			detail: `no text at ${formatTokens(input.startIndex)} of ${formatTokens(input.chars)} chars`,
+			detail: `no text at ${formatCount(input.startIndex)} of ${formatCount(input.chars)} chars`,
 			truncated: false,
 		};
 	}
 	if (input.startIndex <= 0 && !input.truncated) {
-		return { format, detail: `${formatTokens(input.chars)} chars`, truncated: false };
+		return { format, detail: `${formatCount(input.chars)} chars`, truncated: false };
 	}
-	const range = `${formatTokens(input.startIndex + 1)}–${formatTokens(input.nextIndex)} of ${formatTokens(input.chars)} chars`;
+	const range = `chars ${formatCount(input.startIndex + 1)}–${formatCount(input.nextIndex)} of ${formatCount(input.chars)}`;
 	return {
 		format,
 		detail: range,
-		note: input.truncated ? `more at ${formatTokens(input.nextIndex)}` : "complete",
+		note: input.truncated ? `next at ${formatCount(input.nextIndex)}` : "complete",
 		truncated: input.truncated,
 	};
 }

package/extensions/document/render.ts

@@ -2,11 +2,11 @@
  * Transcript rendering for `read_doc`.
  *
  * Theme-aware formatting only: the tool definition in `tool.ts` wires these to
- * `renderCall` / `renderResult`. The call line carries the path (accent,
+ * `renderCall` / `renderResult`. The call line carries the path (body colour,
  * `~`-shortened, OSC-8 linked when the terminal supports it); the result line
- * leads with the format and a humanized range, so the path is never repeated.
- * The expanded view appends a sanitized, line-capped preview of the extracted
- * text. Every field is sanitized before a theme colour is applied.
+ * leads with the format and the exact character range, so the path is never
+ * repeated. The expanded view appends a sanitized, line-capped preview of the
+ * extracted text. Every field is sanitized before a theme colour is applied.
  */
 
 import { isAbsolute, resolve } from "node:path";
@@ -14,19 +14,20 @@ import { pathToFileURL } from "node:url";
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { getCapabilities, hyperlink } from "@earendil-works/pi-tui";
 import { formatTokens, sanitizeLine, shortenPath, stripControlChars } from "../../lib/format.ts";
-import { expandKey, SEPARATORS } from "../../lib/ui.ts";
+import { expandKey, SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import { summarizeDoc } from "./paging.ts";
 import { TOOL_NAME, type DocArgs, type DocResult } from "./schema.ts";
 
 /** Lines of extracted text shown in the expanded preview. */
 export const PREVIEW_LINES = 20;
 
-/** Render the argument path: accent, `~`-shortened, OSC-8 linked when supported. */
+/** Render the argument path: body colour, `~`-shortened, OSC-8 linked when supported. */
 export function renderDocPath(rawPath: string | undefined, theme: Theme, cwd: string): string {
-	if (typeof rawPath !== "string") return theme.fg("error", "[invalid arg]");
+	if (typeof rawPath !== "string") return paint(theme, "bad", "[invalid arg]");
 	const value = sanitizeLine(rawPath);
 	if (!value) return theme.fg("toolOutput", "...");
-	const styled = theme.fg("accent", shortenPath(value));
+	const styled = paint(theme, "label", shortenPath(value));
 	if (!getCapabilities().hyperlinks) return styled;
 	const abs = isAbsolute(value) ? value : resolve(cwd, value);
 	return hyperlink(styled, pathToFileURL(abs).href);
@@ -63,7 +64,7 @@ export function formatDocCall(args: DocArgs, theme: Theme, context: { cwd: strin
 	const options: string[] = [];
 	if (typeof startIndex === "number" && startIndex > 0) options.push(`from ${formatTokens(startIndex)}`);
 	if (typeof maxChars === "number") options.push(`max ${formatTokens(maxChars)}`);
-	if (options.length > 0) text += theme.fg("toolOutput", ` (${options.join(", ")})`);
+	if (options.length > 0) text += paint(theme, "faint", ` (${options.join(", ")})`);
 	return text;
 }
 
@@ -72,7 +73,7 @@ export function formatDocCall(args: DocArgs, theme: Theme, context: { cwd: strin
  * expanded, a sanitized preview of the extracted text.
  */
 export function formatDocResult(result: DocRenderResult, options: DocRenderOptions, theme: Theme): string {
-	if (options.isPartial) return theme.fg("warning", "Reading...");
+	if (options.isPartial) return paint(theme, "warn", "Reading...");
 
 	const isError = result.isError ?? false;
 	const details = result.details as DocResult | undefined;
@@ -81,23 +82,23 @@ export function formatDocResult(result: DocRenderResult, options: DocRenderOptio
 		const first = result.content[0];
 		const message = first?.type === "text" && first.text ? first.text : "Read failed";
 		const safe = sanitizeLine(message.startsWith("Error:") ? message : `Error: ${message}`);
-		return theme.fg("error", safe);
+		return paint(theme, "bad", safe);
 	}
 
 	const summary = summarizeDoc(details);
-	const sep = theme.fg("dim", SEPARATORS.item);
-	let text = theme.fg("muted", summary.format) + sep + theme.fg("toolOutput", summary.detail);
-	if (summary.note) text += theme.fg(summary.truncated ? "accent" : "dim", SEPARATORS.item + summary.note);
+	const sep = paint(theme, "faint", SEPARATORS.item);
+	let text = paint(theme, "meta", summary.format) + sep + theme.fg("toolOutput", summary.detail);
+	if (summary.note) text += paint(theme, summary.truncated ? "accent" : "faint", SEPARATORS.item + summary.note);
 
 	if (details.text.length > 0) {
 		if (options.expanded) {
 			const { body, moreLines } = previewText(details.text, PREVIEW_LINES);
 			// Blank line before the body, matching the built-ins' header/output gap.
 			text += `\n\n${theme.fg("toolOutput", body)}`;
-			if (moreLines > 0) text += `\n${theme.fg("muted", `... (${moreLines} more lines)`)}`;
+			if (moreLines > 0) text += `\n${paint(theme, "meta", `... (${moreLines} more lines)`)}`;
 		} else {
 			const hint = expandKey(theme);
-			if (hint) text += theme.fg("muted", SEPARATORS.item) + hint;
+			if (hint) text += paint(theme, "meta", SEPARATORS.item) + hint;
 		}
 	}
 

package/extensions/document/tool.ts

@@ -15,7 +15,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolveEffectiveCwd } from "../../lib/env.ts";
 import { sanitizeLine, shortenPath } from "../../lib/format.ts";
 import { isInsideReal, realPathOfNearest } from "../../lib/path.ts";
-import { reuseText } from "../../lib/tui.ts";
+import { reuseText } from "../../lib/tui/chrome.ts";
 import { isFormatEnabled, loadConfig } from "./config.ts";
 import type { DocExtractor } from "./extract/file.ts";
 import { detectFormat, supportedExtensions, unsupportedHint, type FormatId } from "./formats.ts";

package/extensions/file-browse/README.md

@@ -4,7 +4,8 @@
 directory, opens the default browser at it, and prints the URL. The page is a
 two-pane file browser: a collapsible path tree on the left, directory listings
 and file views on the right, with image thumbnails, rendered Markdown,
-highlighted code, per-language icons, and a fuzzy quick-open palette. It is
+highlighted code, per-language icons, a fuzzy quick-open palette, and a
+read-only git diff view. It is
 bound to `127.0.0.1`
 and ships no dependencies — `node:http` plus one small vanilla script.
 
@@ -22,7 +23,9 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
 - **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.
+  `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
   binary/over-size download cards, with per-language icons.
 - **First-party syntax highlighting.** Code files render with keywords,
@@ -33,8 +36,11 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
   Python (`py`, `pyw`, `pyi`), Java, YAML (`yaml`, `yml`), and SQL. Other text
   types stay plain.
 - **Rendered Markdown.** `.md`/`.markdown` files render as headings, lists,
-  tables, code, inline and reference links, and images, with a one-click
-  **raw** view (`?raw=1`). Tables size their columns to the content and scroll
+  tables, code, inline and reference links, bare-URL autolinks, and images, with
+  a one-click **raw** view (`?raw=1`). The body follows GitHub's Markdown content
+  column: one centred measure of at most 1012px carrying headings, prose,
+  tables, code, and images, with wide tables scrolling inside it. Tables size
+  their columns to the content and scroll
   when wide, and named and numeric character references are decoded. Fenced code
   blocks are syntax-highlighted when the fence names a supported language.
   Headings get stable anchor ids, so in-document `#anchor` links and a table of
@@ -51,9 +57,24 @@ pi -e .                                    # load the whole @gavin-hu/my-pi-agen
 - **Quick open.** `/` (or `Ctrl/Cmd+K`, or the sidebar button) opens a fuzzy
   path finder over a capped index of the tree, with keyboard navigation and a
   highlighted match; Enter opens the file.
+- **Keyboard.** `/` or `Ctrl/Cmd+K` opens quick open, `u` toggles line wrapping,
+  `r` switches rendered and raw Markdown, `n`/`p` step between a diff's hunks,
+  and `?` opens a shortcut sheet. A diff's hunk headers pin to the top of the
+  code viewport while its body scrolls.
 - **Read-only and loopback-scoped.** No editing, no writing, no LAN exposure.
 - **Git context.** A read-only header chip shows the checked-out branch (or
-  detached head) and a dirty marker, and reflows on narrow screens.
+  detached head) and reflows on narrow screens. Uncommitted changes are stated
+  once, by the changes chip below; turn the diff view off (`gitDiff: false`) and
+  the header reports no changes at all.
+- **Git diff view.** A `● N changes +A −D` chip links to `/diff`, a change
+  overview with `git diff --stat` and a per-file status table, and `/diff/<rel>`
+  renders one file's unified diff, whose head carries its own `+A −D` and hunk
+  count. Changed lines are syntax-highlighted with the
+  file's language, and dirty files and their directories carry a marker in the
+  listing and the tree. The scope is switchable between `head` / `staged` /
+  `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.
 - **No dependencies.** `node:http` plus the inline sprite, CSS, and client
   script.
 
@@ -93,6 +114,8 @@ reflects only this session's server, with no cross-session sharing.
 | `/view/<rel>` | tree + file page (text, Markdown, image, binary, or over-size) |
 | `/view/<rel>?raw=1` | raw Markdown/text source instead of the rendered view |
 | `/raw/<rel>` | raw bytes, streamed; downloads and image sources |
+| `/diff[?mode=head\|staged\|worktree]` | changed-file overview with `--stat` |
+| `/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 |
 | `/app.js` | the first-party client script |
@@ -115,7 +138,10 @@ document and the project document (project wins):
   "maxDirEntries": 2000,     // listed entries before truncation
   "thumbnails": true,
   "markdown": true,          // render Markdown files as formatted HTML
-  "maxIndexEntries": 20000   // files collected for quick open before truncation
+  "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
 }
 ```
 
@@ -142,8 +168,11 @@ document and the project document (project wins):
   attributes; only the fixed `tok-*` class names reach the page.
 - **Caps.** `maxFileBytes` (inline rendering), `maxTextLines` (rendered lines),
   `maxThumbBytes` (thumbnails), and `maxDirEntries` (listings) bound every read.
-- **Git reads.** The header chip runs read-only git (`rev-parse`, `status
-  --porcelain`) with a timeout and a short cache; any failure simply omits it.
+- **Git reads.** The header chip and the diff view run read-only git
+  (`rev-parse`, `status --porcelain=v1 -z`, `diff --stat`, `diff -U<n>`) with a
+  timeout and a short cache; any failure simply omits the chip or the diff. A
+  per-file diff sets `GIT_LITERAL_PATHSPECS=1`, so a filename containing glob
+  characters is matched literally.
 - **Read-only.** Nothing is ever written.
 
 ## Limitations
@@ -237,6 +266,16 @@ document and the project document (project wins):
   `maxIndexEntries`, and is cached per server for 10 s by `createFileIndex`. The
   palette is a `dialog`/`combobox`/`listbox` with `aria-activedescendant` and
   `Esc` / arrow / `Enter` handling.
+- **Diff view.** `git.ts` extends the read-only provider set with a TTL-cached
+  `git status --porcelain=v1 -z` and a per-mode `git diff`; `diff.ts` parses the
+  unified diff and the porcelain records into plain view models, so `router.ts`
+  and `html.ts` stay pure. `head` compares against `HEAD` (falling back to
+  `--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
+  `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
   suppresses bodies for `HEAD`, so large `/raw` files are not buffered.
 - **Root confinement over feature breadth.** The root is deliberately confined
@@ -254,6 +293,7 @@ document and the project document (project wins):
 | [`../../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 |
+| `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) |
 | `git.ts` | Read-only branch/dirty provider for the header chip |
@@ -275,8 +315,12 @@ highlighting, safety, and path resolution),
 the icon mapping and sprite, HTML escaping/encoding/rendering, the client script
 and its serving, the platform browser commands with an injected spawn, the router
 (routes, `/api/tree`, `/api/files`, `?raw=1`, status codes, `Host`, `HEAD`, `/raw`
-headers)
+headers, and the `/diff` view routes and mode validation)
 without a socket, a real `127.0.0.1:0` server, the session-port lifecycle (fixed
 on first start, reused, and re-rolled after a conflict), the git status provider
-(branch, dirty, detached, non-repo, failure, and TTL cache), and the command
+(branch, dirty, detached, non-repo, failure, and TTL cache), the git diff parser
+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
 lifecycle with injected seams.

package/extensions/file-browse/client.ts

@@ -525,7 +525,96 @@ export const CLIENT_JS = `(function () {
 		if (result) window.location.assign("/view/" + encodeSegments(result.path));
 	}
 
+	// Keyboard: a shortcut sheet, the per-page actions the server rendered, and
+	// hunk-to-hunk navigation through a diff.
+	var keysDialog = document.getElementById("keys-dialog");
+	var keysButton = document.getElementById("keys-open");
+	var hunkAnchors = Array.prototype.slice.call(document.querySelectorAll("[data-hunk]"));
+	var progressFill = document.getElementById("progress-fill");
+
+	function toggleKeys(force) {
+		if (!keysDialog) return;
+		var open = force !== undefined ? force : keysDialog.hidden;
+		keysDialog.hidden = !open;
+		if (open) {
+			var close = document.getElementById("keys-close");
+			if (close) close.focus();
+		}
+	}
+
+	function toggleRaw() {
+		var next = document.querySelector(".bf-card__actions .bf-segmented a.bf-segmented__item:not([aria-current])");
+		if (next) window.location.assign(next.getAttribute("href") || next.href);
+	}
+
+	// The hunk whose header is pinned (or last passed), then one step either way.
+	function moveHunk(delta) {
+		if (hunkAnchors.length === 0) return;
+		var scroller = primaryScroller();
+		// The line a pinned hunk header sticks to: the code viewport's top inset
+		// by its padding. With no scrolling pane (narrow screens) the page is the
+		// viewport, so the anchor is the window top.
+		var lineTop = 8;
+		if (scroller) lineTop = scroller.getBoundingClientRect().top + (parseFloat(getComputedStyle(scroller).paddingTop) || 0);
+		var current = -1;
+		for (var index = 0; index < hunkAnchors.length; index++) {
+			if (hunkAnchors[index].getBoundingClientRect().top <= lineTop + 2) current = index;
+		}
+		var next = Math.max(0, Math.min(hunkAnchors.length - 1, current + delta));
+		if (scroller) scroller.scrollTop += hunkAnchors[next].getBoundingClientRect().top - lineTop;
+		else hunkAnchors[next].scrollIntoView({ block: "start" });
+	}
+
+	// The page's primary scroller: the card body for a file or diff, the main
+	// column otherwise.
+	function primaryScroller() {
+		var candidates = [
+			document.getElementById("main"),
+			document.querySelector(".bf-md"),
+			document.querySelector("pre.bf-code")
+		];
+		var best = null;
+		var bestRange = 0;
+		candidates.forEach(function (node) {
+			if (!node) return;
+			var range = node.scrollHeight - node.clientHeight;
+			if (range > bestRange) { bestRange = range; best = node; }
+		});
+		return bestRange > 0 ? best : null;
+	}
+
+	function updateProgress() {
+		if (!progressFill) return;
+		var scroller = primaryScroller();
+		var doc = document.scrollingElement || document.documentElement;
+		var top = doc ? doc.scrollTop : 0;
+		var height = doc ? doc.scrollHeight : 0;
+		var view = doc ? doc.clientHeight : 0;
+		if (scroller) { top = scroller.scrollTop; height = scroller.scrollHeight; view = scroller.clientHeight; }
+		var max = height - view;
+		var percent = max > 0 ? Math.min(100, Math.max(0, (top / max) * 100)) : 0;
+		progressFill.style.width = percent + "%";
+	}
+
+	if (keysButton) keysButton.addEventListener("click", function () { toggleKeys(); });
+	if (keysDialog) {
+		keysDialog.addEventListener("click", function (event) {
+			if (event.target === keysDialog) toggleKeys(false);
+		});
+		var keysClose = document.getElementById("keys-close");
+		if (keysClose) keysClose.addEventListener("click", function () { toggleKeys(false); });
+	}
+
+	window.addEventListener("scroll", updateProgress, true);
+	window.addEventListener("resize", updateProgress);
+	updateProgress();
+
 	document.addEventListener("keydown", function (event) {
+		if (event.key === "Escape" && keysDialog && !keysDialog.hidden) {
+			event.preventDefault();
+			toggleKeys(false);
+			return;
+		}
 		if (paletteOpen()) {
 			if (event.key === "Escape") {
 				event.preventDefault();
@@ -533,15 +622,34 @@ export const CLIENT_JS = `(function () {
 			}
 			return;
 		}
+		if (keysDialog && !keysDialog.hidden) return;
 		var target = event.target;
 		var editable = target && (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable);
 		if (editable) return;
-		if (event.key === "/" && !event.metaKey && !event.ctrlKey && !event.altKey) {
+		if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === "k") {
 			event.preventDefault();
 			openPalette();
-		} else if ((event.ctrlKey || event.metaKey) && event.key.toLowerCase() === "k") {
+			return;
+		}
+		if (event.metaKey || event.ctrlKey || event.altKey) return;
+		if (event.key === "/") {
 			event.preventDefault();
 			openPalette();
+		} else if (event.key === "?") {
+			event.preventDefault();
+			toggleKeys();
+		} else if (event.key === "u" && wrapButton) {
+			event.preventDefault();
+			wrapButton.click();
+		} else if (event.key === "r" && document.querySelector(".bf-card__actions .bf-segmented")) {
+			event.preventDefault();
+			toggleRaw();
+		} else if (event.key === "n" && hunkAnchors.length > 0) {
+			event.preventDefault();
+			moveHunk(1);
+		} else if (event.key === "p" && hunkAnchors.length > 0) {
+			event.preventDefault();
+			moveHunk(-1);
 		}
 	});
 

package/extensions/file-browse/config.ts

@@ -28,6 +28,12 @@ export interface ServeConfig {
 	markdown: boolean;
 	/** Files collected for the quick-open index before it is truncated. */
 	maxIndexEntries: number;
+	/** Offer the read-only git diff view. */
+	gitDiff: boolean;
+	/** Unified diff context lines. */
+	diffContext: number;
+	/** Diff lines rendered before the view is truncated. */
+	maxDiffLines: number;
 }
 
 export const DEFAULT_CONFIG: ServeConfig = {
@@ -40,6 +46,9 @@ export const DEFAULT_CONFIG: ServeConfig = {
 	thumbnails: true,
 	markdown: true,
 	maxIndexEntries: 20000,
+	gitDiff: true,
+	diffContext: 3,
+	maxDiffLines: 4000,
 };
 
 /** Base of the per-session port range. */
@@ -73,6 +82,9 @@ export function normalizeConfig(
 		thumbnails: bool(raw.thumbnails, base.thumbnails),
 		markdown: bool(raw.markdown, base.markdown),
 		maxIndexEntries: clampInteger(raw.maxIndexEntries, base.maxIndexEntries, 1, 1_000_000),
+		gitDiff: bool(raw.gitDiff, base.gitDiff),
+		diffContext: clampInteger(raw.diffContext, base.diffContext, 0, 100),
+		maxDiffLines: clampInteger(raw.maxDiffLines, base.maxDiffLines, 1, 1_000_000),
 	};
 }