@gavin-hu/my-pi-agent 0.8.0 → 0.9.0

package/extensions/bytefly/panel/tui.ts

@@ -5,33 +5,29 @@
  * The component is derived: it rebuilds the merged model from the picker
  * runtime and the current reports on every render, keeps the focused row's key
  * across rebuilds, and requests a repaint only after an input changes state.
- * Screen chrome and scroll math come from `lib/tui.ts` and `lib/list-cursor.ts`.
- * A row without a report renders no glyph and no summary, never a false `ok`.
+ * The screen is drawn from the design system — a label-first `titleRule`, one
+ * `listRow` grammar, one `checkbox` — and its scroll math from
+ * `lib/tui/cursor.ts`. A row without a report renders no glyph and no summary,
+ * never a false `ok`.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import {
-	Key,
-	matchesKey,
-	truncateToWidth,
-	visibleWidth,
-	type Component,
-	type TuiMouseEvent,
-	type TuiMouseEventResult,
-} from "@earendil-works/pi-tui";
+import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { sanitizeLine } from "../../../lib/format.ts";
-import {
-	fitRows,
-	formatRange,
-	isCloseKey,
-	ListCursor,
-	navIntent,
-	selectionMarker,
-	wheelDelta,
-} from "../../../lib/list-cursor.ts";
+import { dockListFrame, screenHint, type ViewportRowsSource } from "../../../lib/tui/chrome.ts";
+import { clip, fitCells } from "../../../lib/tui/columns.ts";
+import { fitRows, formatRange, isCloseKey, ListCursor, navIntent, wheelDelta } from "../../../lib/tui/cursor.ts";
+import { checkbox, emptyState, listRow } from "../../../lib/tui/rows.ts";
+import { titleRule } from "../../../lib/tui/rules.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
 import type { ExtensionReport } from "../../../lib/requirements.ts";
-import { dockListFrame, screenHint, type ViewportRowsSource } from "../../../lib/tui.ts";
-import { detailLines as reportDetailLines, reportSeverity, reportSummary, severityGlyph } from "../doctor/format.ts";
+import {
+	detailLines as reportDetailLines,
+	reportSeverity,
+	reportSummary,
+	severityGlyphChar,
+	severityRole,
+} from "../doctor/format.ts";
 import type { ExtensionsPickerRuntime } from "../picker/runtime.ts";
 import { summarySegments } from "./format.ts";
 import { buildPanelModel } from "./join.ts";
@@ -283,50 +279,37 @@ export class PanelComponent implements Component {
 		return { handled: true };
 	}
 
+	/** The headline: whole segments only, so a narrow screen drops a count. */
 	private summary(width: number, model: PanelModel): string {
 		const segments = summarySegments(model, this.options.runtime.scope(), {
 			filter: this.options.filter,
 			compact: width < 72,
 		});
-		const separator = this.theme.fg("dim", " · ");
-		const kept: string[] = [];
-		for (const segment of segments) {
-			const styled = this.theme.fg(segment.color, segment.text);
-			if (kept.length > 0 && visibleWidth(`  ${[...kept, styled].join(separator)}`) > width) break;
-			kept.push(styled);
-		}
-		return truncateToWidth(`  ${kept.join(separator)}`, width, "…");
+		const separator = paint(this.theme, "faint", " · ");
+		const styled = segments.map((segment) => paint(this.theme, segment.color, segment.text));
+		return clip(`  ${fitCells(styled, Math.max(1, width - 2), separator)}`, width);
 	}
 
 	private groupLine(entry: Extract<PanelEntry, { kind: "group" }>, width: number): string {
-		const label = this.theme.fg("muted", sanitizeLine(entry.label));
-		const count = this.theme.fg("dim", `(${entry.count})`);
-		return truncateToWidth(`  ${label} ${count}`, width, "…");
+		const label = paint(this.theme, "meta", sanitizeLine(entry.label));
+		const count = paint(this.theme, "faint", `(${entry.count})`);
+		return clip(`  ${label} ${count}`, width);
 	}
 
 	private rowLine(row: PanelRow, selected: boolean, width: number): string {
-		const checkbox = row.item
-			? row.item.enabled
-				? this.theme.fg("success", "[x]")
-				: this.theme.fg("dim", "[ ]")
-			: this.theme.fg("dim", "   ");
 		const severity = row.report ? reportSeverity(row.report) : undefined;
-		const glyph = severity ? severityGlyph(severity, this.theme) : " ";
-		const label = sanitizeLine(row.label);
-		const styled = selected
-			? this.theme.fg("accent", label)
-			: row.item && !row.item.enabled
-				? this.theme.fg("dim", label)
-				: label;
-		const summary = row.report ? reportSummary(row.report) : "";
-		const head = `${selectionMarker(this.theme, selected)}${checkbox} ${glyph} `;
-		if (!summary) return truncateToWidth(`${head}${styled}`, width, "…");
-
-		const available = Math.max(1, width - visibleWidth(head) - visibleWidth(summary) - 1);
-		const name = truncateToWidth(styled, available, "…");
-		const pad = " ".repeat(Math.max(0, available - visibleWidth(name)));
-		const tone = severity === "missing" ? "error" : severity === "degraded" ? "warning" : "dim";
-		return truncateToWidth(`${head}${name}${pad} ${this.theme.fg(tone, summary)}`, width, "…");
+		return listRow(this.theme, width, {
+			selected,
+			// A reported-only row has no enable pattern, but still reserves the box
+			// column so the list stays aligned.
+			leading: row.item ? checkbox(this.theme, row.item.enabled) : " ",
+			glyph: severity ? severityGlyphChar(severity) : " ",
+			glyphRole: severity ? severityRole(severity) : "faint",
+			label: sanitizeLine(row.label),
+			labelRole: selected ? "accent" : row.item && !row.item.enabled ? "faint" : "label",
+			trailing: row.report ? reportSummary(row.report) : undefined,
+			trailingRole: severity === "missing" ? "bad" : severity === "degraded" ? "warn" : "faint",
+		});
 	}
 
 	/** The focused row's label, findings, and the pending-changes note. */
@@ -334,19 +317,14 @@ export class PanelComponent implements Component {
 		const lines: string[] = [];
 		if (row?.report) {
 			const tail = reportSummary(row.report);
-			lines.push(
-				truncateToWidth(
-					`  ${this.theme.fg("muted", sanitizeLine(row.label))} ${this.theme.fg("dim", "—")} ${this.theme.fg(row.report.enabled ? "muted" : "warning", tail)}`,
-					width,
-					"…",
-				),
-			);
+			const head = `${paint(this.theme, "meta", sanitizeLine(row.label))} ${paint(this.theme, "faint", "—")} ${paint(this.theme, row.report.enabled ? "meta" : "warn", tail)}`;
+			lines.push(clip(`  ${head}`, width));
 			if (budget > 0) lines.push(...reportDetailLines(row.report, this.theme, width, budget, this.showDetail));
 		} else if (row?.item) {
-			lines.push(truncateToWidth(`  ${this.theme.fg("muted", sanitizeLine(row.item.path))}`, width, "…"));
+			lines.push(clip(`  ${paint(this.theme, "meta", sanitizeLine(row.item.path))}`, width));
 		}
 		if (this.options.runtime.isDirty()) {
-			lines.push(truncateToWidth(`  ${this.theme.fg("warning", "Saved · reload to apply")}`, width, "…"));
+			lines.push(clip(`  ${paint(this.theme, "warn", "Saved · reload to apply")}`, width));
 		}
 		return lines;
 	}
@@ -356,14 +334,13 @@ export class PanelComponent implements Component {
 		const model = this.model();
 		const entries = entriesOf(model);
 		const summary = this.summary(w, model);
+		const header = titleRule(this.theme, w, "bytefly");
 
 		if (entries.length === 0) {
 			return dockListFrame({
-				theme: this.theme,
-				width: w,
-				title: "bytefly",
+				header,
 				summary,
-				body: [truncateToWidth(`  ${this.theme.fg("dim", "No extensions found.")}`, w)],
+				body: emptyState(this.theme, w, { label: "No extensions found." }),
 				hint: screenHint(this.theme, w, ["Esc close"]),
 			});
 		}
@@ -394,9 +371,7 @@ export class PanelComponent implements Component {
 		}
 
 		return dockListFrame({
-			theme: this.theme,
-			width: w,
-			title: "bytefly",
+			header,
 			summary,
 			body,
 			range: this.cursor.clipped(entries.length)

package/extensions/bytefly/separator/config.ts

@@ -2,11 +2,12 @@
  * Tuning for bytefly's turn separator.
  *
  * Edit this file to change how the line between completed turns looks. The
- * glyphs and colors are plain theme tokens, so the line follows the active
- * theme automatically.
+ * glyph and the colors are plain design-system roles, so the line follows the
+ * active theme automatically.
  */
 
-import { GLYPHS } from "../../../lib/ui.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import type { TuiRole } from "../../../lib/tui/tokens.ts";
 
 export const CONFIG = {
 	/** Custom entry type. Changing it orphans separators recorded by an older build. */
@@ -17,8 +18,15 @@ export const CONFIG = {
 	labelPrefix: "turn",
 	/** Spaces on each side of the label. */
 	pad: 1,
-	/** Theme token for the dashes. */
-	dashColor: "border",
-	/** Theme token for the label. */
-	labelColor: "muted",
-} as const;
+	/** Role for the dashes. */
+	dashRole: "ruleStrong",
+	/** Role for the label. */
+	labelRole: "meta",
+} as const satisfies {
+	customType: string;
+	glyph: string;
+	labelPrefix: string;
+	pad: number;
+	dashRole: TuiRole;
+	labelRole: TuiRole;
+};

package/extensions/bytefly/separator/format.ts

@@ -1,50 +1,23 @@
 /**
  * Pure formatting for bytefly's turn separator line.
  *
- * `separatorParts` decides the layout from a plain turn number and a column
- * count; `separatorLine` applies theme colors. Neither touches Pi state, so
- * both are cheap to unit test.
+ * The centered `╌╌╌ turn N ╌╌╌` layout comes from the design system's
+ * `centeredRule`, so this module only names the turn; the shared rule owns the
+ * centering, the degradation, and the colors.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { centeredRule } from "../../../lib/tui/rules.ts";
 import { CONFIG } from "./config.ts";
-import type { SeparatorParts } from "./types.ts";
 
-/** ` turn N ` — the label printed in the middle of the line. */
-export function separatorLabel(turn: number): string {
-	const pad = " ".repeat(CONFIG.pad);
-	return `${pad}${CONFIG.labelPrefix} ${turn}${pad}`;
-}
-
-/**
- * Split `width` columns into centered dashes and a label.
- *
- * When the label does not fit, the line degrades to a plain dashed rule so it
- * never overflows the transcript.
- */
-export function separatorParts(turn: number, width: number): SeparatorParts {
-	const target = Math.max(1, Math.floor(width));
-	const label = separatorLabel(turn);
-	const labelWidth = visibleWidth(label);
-
-	if (labelWidth >= target) {
-		return { left: CONFIG.glyph.repeat(target), label: "", right: "" };
-	}
-
-	const remaining = target - labelWidth;
-	const left = Math.floor(remaining / 2);
-	const right = remaining - left;
-	return {
-		left: CONFIG.glyph.repeat(left),
-		label,
-		right: CONFIG.glyph.repeat(right),
-	};
-}
-
-/** One rendered line: colored dashes around a colored label. */
+/** One rendered line: the centered turn rule, colored by role. */
 export function separatorLine(turn: number, width: number, theme: Theme): string[] {
-	const { left, label, right } = separatorParts(turn, width);
-	const dashes = (text: string) => (text ? theme.fg(CONFIG.dashColor, text) : "");
-	return [dashes(left) + (label ? theme.fg(CONFIG.labelColor, label) : "") + dashes(right)];
+	return [
+		centeredRule(theme, width, `${CONFIG.labelPrefix} ${turn}`, {
+			glyph: CONFIG.glyph,
+			pad: CONFIG.pad,
+			fillRole: CONFIG.dashRole,
+			labelRole: CONFIG.labelRole,
+		}),
+	];
 }

package/extensions/bytefly/separator/types.ts

@@ -10,13 +10,3 @@ export interface TurnSeparatorData {
 	/** 1-based index of the completed user turn this separator follows. */
 	turn: number;
 }
-
-/** A separator line split into its dashes and label. */
-export interface SeparatorParts {
-	/** Dashes before the label. */
-	left: string;
-	/** The centred `turn N` label. */
-	label: string;
-	/** Dashes after the label. */
-	right: string;
-}

package/extensions/document/README.md

@@ -218,7 +218,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/render.ts

@@ -14,7 +14,8 @@ 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";
 
@@ -23,10 +24,10 @@ export const PREVIEW_LINES = 20;
 
 /** Render the argument path: accent, `~`-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, "accent", shortenPath(value));
 	if (!getCapabilities().hyperlinks) return styled;
 	const abs = isAbsolute(value) ? value : resolve(cwd, value);
 	return hyperlink(styled, pathToFileURL(abs).href);
@@ -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,12 +36,17 @@ 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. Raw
-  HTML in the source is escaped, never executed, and external images are shown
-  as links rather than fetched.
+  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
+  contents work, and a document with four or more headings gets an **On this
+  page** outline. Raw HTML in the source is escaped, never executed, and
+  external images are shown as links rather than fetched.
 - **Sortable listings.** The Name / Size / Modified headers sort the current
   directory, directories first, and the choice is remembered per browser.
 - **Copy and wrap.** Copy a file's root-relative path or its contents, and
@@ -49,9 +57,22 @@ 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.
+- **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.
 
@@ -91,6 +112,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 |
@@ -113,7 +136,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
 }
 ```
 
@@ -140,8 +166,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
@@ -209,8 +238,12 @@ document and the project document (project wins):
   the full `[text][id]`, collapsed `[text][]`, and shortcut `[text]` forms, and
   numeric and common named character references are resolved. The Rendered/Raw
   switch is a server-side `?raw=1`
-  link, so it works without JavaScript. Set `markdown: false` to fall back to
-  the plain-text view. A fenced code block whose info string names a supported
+  link, so it works without JavaScript. Headings are demoted one level so the
+  card title stays the page's only `h1`, and each gets a slug `id` (unique in
+  the document); `renderMarkdownDocument` returns the heading list and `html.ts`
+  renders an **On this page** disclosure for four or more headings. Set
+  `markdown: false` to fall back to the plain-text view. A fenced code block
+  whose info string names a supported
   language is highlighted through `lib/highlight.ts` (either an extension or a
   long-form alias, `fenceLanguage`); an absent or unknown language stays plain.
 - **Syntax highlighting.** `lib/highlight.ts` is a first-party, escape-first
@@ -231,6 +264,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
@@ -248,6 +291,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 |
@@ -269,8 +313,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.