@gavin-hu/my-pi-agent 0.17.0 → 0.19.0

package/extensions/file-browse/{live.ts → live/live.ts}

@@ -3,17 +3,21 @@
  *
  * A page that stays open holds one event stream; this module builds the snapshot
  * it is sent, the frame that carries it, and the channel that fans it out on a
- * tick. The git and diff providers already memoize, so a tick re-reads at most
- * one `git status`, and every read failure degrades to `null`: a status feed
- * must never be able to fail a page or the server that serves it.
+ * tick. A tick costs one `git status` and one `git diff --stat`: the providers'
+ * 2 s memo only coalesces a tick with a page render in the same window, so the
+ * cadence is what bounds the reads. Every read failure degrades to `null`: a
+ * status feed must never be able to fail a page or the server that serves it.
  *
  * The channel opens no socket of its own — the caller hands it a `write`/`end`
  * pair — so the whole feed is tested without one.
  */
 
-import { defaultInterval, defaultTimer } from "../../lib/timer.ts";
-import { changeDirs } from "./diff.ts";
-import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
+import type { EventSink } from "../../../lib/http/index.ts";
+import { defaultInterval, type RepeatTimer } from "../../../lib/timer.ts";
+import { LIVE_MAX_CLIENTS } from "../config/config.ts";
+import { changeDirs } from "../text/diff.ts";
+import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "../git/git.ts";
+import { changeRevision } from "./rev.ts";
 
 /**
  * The changed-path index the pages render from: the totals the changes chip
@@ -50,12 +54,27 @@ export interface LiveChanges {
 	deletions: number;
 	files: string[];
 	dirs: string[];
+	/**
+	 * Identity of this change set, counts included. A page that painted the same
+	 * revision repaints nothing when the next frame arrives.
+	 */
+	rev: string;
+}
+
+/** A change index as it goes over the wire, with its revision. */
+function changesOf(index: ChangeIndex): LiveChanges {
+	const changes = {
+		count: index.count,
+		insertions: index.insertions,
+		deletions: index.deletions,
+		files: [...index.files].sort(),
+		dirs: [...index.dirs].sort(),
+	};
+	return { ...changes, rev: changeRevision(changes) };
 }
 
 /** One status frame's payload. */
 export interface LiveSnapshot {
-	/** Server wall clock when the snapshot was taken, in ms. */
-	at: number;
 	/** How long the server has been listening, in ms. */
 	uptimeMs: number;
 	/** Requests the server has answered so far, this one included. */
@@ -112,15 +131,7 @@ export function createLiveStatus(options: LiveStatusOptions): LiveStatusSource {
 				uptimeMs: Math.max(0, at - options.startedAt),
 				requests: options.requests(),
 				git,
-				changes: index
-					? {
-							count: index.count,
-							insertions: index.insertions,
-							deletions: index.deletions,
-							files: [...index.files].sort(),
-							dirs: [...index.dirs].sort(),
-						}
-					: null,
+				changes: index ? changesOf(index) : null,
 			};
 		},
 	};
@@ -131,61 +142,46 @@ export function frameOf(snapshot: LiveSnapshot): string {
 	return `event: status\ndata: ${JSON.stringify(snapshot)}\n\n`;
 }
 
-/** A connected page: the two things a server can do to its stream. */
-export interface LiveClient {
-	/** Write one frame. */
-	write(frame: string): void;
-	/** End the stream. */
-	end(): void;
-}
-
-/** Starts a repeating tick and returns its cancel. */
-export type LiveTimer = (tick: () => void, intervalMs: number) => () => void;
-
-/** Starts a one-shot delay and returns its cancel. */
-export type LiveTimeout = (run: () => void, delayMs: number) => () => void;
-
-/** The default ticker: a repeating timer that cannot hold the process open. */
-const defaultTicker: LiveTimer = (tick, intervalMs) => defaultInterval(intervalMs, tick);
-
-/** The default grace timer: one shot, and it cannot hold the process open either. */
-const defaultTimeout: LiveTimeout = (run, delayMs) => defaultTimer(delayMs, run);
+/** A connected page, as the channel writes it: the sink's two verbs. */
+export type LiveClient = EventSink;
 
 export interface LiveChannelOptions {
 	/** What each frame carries. */
 	status: LiveStatusSource;
 	/** How far apart the frames are, in ms. */
 	intervalMs: number;
-	/** How long the last page's departure is held before `onIdle` is called, in ms. */
-	idleMs: number;
-	/** Called once the last page has been gone for `idleMs`; omitted, the channel only idles. */
-	onIdle?: () => void;
+	/** How many pages may attach at once; defaults to `LIVE_MAX_CLIENTS`. */
+	maxClients?: number;
 	/** Timer seam; defaults to an unref'd interval. */
-	timer?: LiveTimer;
-	/** Grace seam; defaults to an unref'd timeout. */
-	timeout?: LiveTimeout;
+	timer?: RepeatTimer;
 }
 
 /** The fan-out for one server: pages attach, ticks publish, close ends them. */
 export interface LiveChannel {
 	/** Add a connected page, send it the current status, and return its detach. */
 	attach(client: LiveClient): () => void;
-	/** End every connected page, stop the ticker, and drop a pending idle stop. */
+	/** End every connected page, and stop the ticker. */
 	close(): void;
+	/**
+	 * Whether another page must be refused. The caller asks before it opens the
+	 * stream, so a refusal never has to take back a head it already wrote.
+	 */
+	atCapacity(): boolean;
 }
 
 /**
- * Build a channel for one server. The ticker runs only while at least one page
- * is attached, so an idle server does no status work at all; the idle stop is one
- * timer armed when the last page leaves and cancelled by the next page, so a
- * reload keeps the server and a closed window releases it.
+ * Build a channel for one server. The ticker runs only while at least one page is
+ * attached, so an idle server does no status work at all; the last page leaving
+ * parks it and the next page starts it again. What happens to a server nobody is
+ * reading — the idle grace and the close it leads to — is the server's policy, so
+ * the caller hands it to `lib/http`'s `serveLoopback` instead of configuring it
+ * here.
  */
 export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
-	const timer = options.timer ?? defaultTicker;
-	const timeout = options.timeout ?? defaultTimeout;
+	const timer = options.timer ?? defaultInterval;
+	const maxClients = options.maxClients ?? LIVE_MAX_CLIENTS;
 	const clients = new Set<LiveClient>();
 	let cancel: (() => void) | undefined;
-	let cancelIdle: (() => void) | undefined;
 	let inFlight = false;
 
 	const stop = (): void => {
@@ -193,34 +189,9 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 		cancel = undefined;
 	};
 
-	const cancelIdleStop = (): void => {
-		cancelIdle?.();
-		cancelIdle = undefined;
-	};
-
-	const armIdleStop = (): void => {
-		if (!options.onIdle || cancelIdle) return;
-		cancelIdle = timeout(() => {
-			cancelIdle = undefined;
-			options.onIdle?.();
-		}, options.idleMs);
-	};
-
-	/** Nobody is reading a frame any more: park the ticker and start the grace. */
-	const pageLeft = (): void => {
-		stop();
-		armIdleStop();
-	};
-
 	const send = (frame: string): void => {
-		for (const client of clients) {
-			try {
-				client.write(frame);
-			} catch {
-				clients.delete(client);
-			}
-		}
-		if (clients.size === 0) pageLeft();
+		for (const client of clients) client.write(frame);
+		if (clients.size === 0) stop();
 	};
 
 	// One snapshot serves every attached page, so a tick is one git read and one
@@ -237,20 +208,21 @@ export function createLiveChannel(options: LiveChannelOptions): LiveChannel {
 
 	return {
 		attach(client) {
-			cancelIdleStop();
 			clients.add(client);
-			cancel ??= timer(() => void publish(), options.intervalMs);
+			cancel ??= timer(options.intervalMs, () => void publish());
 			void publish();
 			return () => {
 				if (!clients.delete(client)) return;
-				if (clients.size === 0) pageLeft();
+				if (clients.size === 0) stop();
 			};
 		},
 		close() {
-			cancelIdleStop();
 			stop();
 			for (const client of clients) client.end();
 			clients.clear();
 		},
+		atCapacity() {
+			return clients.size >= maxClients;
+		},
 	};
 }

package/extensions/file-browse/live/rev.ts

@@ -0,0 +1,42 @@
+/**
+ * Revisions for the browse live status.
+ *
+ * A revision is a short digest of something a page already drew — the change set
+ * a frame carries, or the names a listing holds — so a client can tell "nothing
+ * moved" from "paint again" without comparing the payload it was sent. A
+ * collision costs one skipped repaint and is corrected by the next frame or a
+ * reload, which is the trade a 12-character digest makes for a small frame.
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * A digest of the parts, cut to 12 hex characters. The parts are joined with NUL,
+ * which no filename can contain, so two different lists cannot run together into
+ * the same text.
+ */
+function digest(parts: readonly string[]): string {
+	return createHash("sha1").update(parts.join("\u0000")).digest("hex").slice(0, 12);
+}
+
+/** The change set a frame carries: its totals and paths, in a stable order. */
+export interface RevisionInput {
+	count: number;
+	insertions: number;
+	deletions: number;
+	files: readonly string[];
+	dirs: readonly string[];
+}
+
+/**
+ * The revision of a change set. The totals are part of it, so an edit that moves
+ * no path still moves the revision and the chip's `+A −D` stays honest.
+ */
+export function changeRevision(changes: RevisionInput): string {
+	return digest([`${changes.count}:${changes.insertions}:${changes.deletions}`, ...changes.files, ...changes.dirs]);
+}
+
+/** The revision of a listing's names, independent of the order they arrived in. */
+export function listingRevision(names: readonly string[]): string {
+	return digest([...names].sort());
+}

package/extensions/file-browse/{router.ts → transport/router.ts}

@@ -19,13 +19,14 @@ import {
 	parseRequestUrl,
 	scriptHeaders,
 	type ServeResponse,
-} from "../../lib/http/index.ts";
-import { THEME_JS, THEME_JS_PATH } from "../../lib/web/index.ts";
-import { CLIENT_JS } from "./client.ts";
-import type { ServeConfig } from "./config.ts";
-import { isDiffMode, type DiffMode } from "./diff.ts";
-import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "./git.ts";
-import { changeIndexOf, type LiveStatusSource } from "./live.ts";
+} from "../../../lib/http/index.ts";
+import { THEME_JS, THEME_JS_PATH } from "../../../lib/web/index.ts";
+import { CLIENT_JS } from "../view/client.ts";
+import type { LivePage } from "../view/chrome.ts";
+import type { ServeConfig } from "../config/config.ts";
+import { isDiffMode, type DiffMode } from "../text/diff.ts";
+import type { DiffList, GitDiffProvider, GitStatus, GitStatusProvider } from "../git/git.ts";
+import { changeIndexOf, type LiveStatusSource } from "../live/live.ts";
 import {
 	buildFileIndex,
 	buildTree,
@@ -37,12 +38,19 @@ import {
 	type DirEntry,
 	type FileIndexProvider,
 	type TreeNode,
-} from "./files.ts";
-import { FOLDER_ICON, iconHref, languageOf } from "./icons.ts";
-import { fuzzySearch } from "./fuzzy.ts";
-import { renderDirectoryPage, renderDiffPage, renderErrorPage, renderFileDiffPage, renderFilePage } from "./html.ts";
-import type { ChangeSummary } from "./html.ts";
-import { encodePath, HttpError, relativePath, resolveDecodedPath, resolveRequestPath } from "./paths.ts";
+} from "../files/files.ts";
+import { FOLDER_ICON, iconHref, languageOf } from "../view/icons.ts";
+import { fuzzySearch } from "../text/fuzzy.ts";
+import {
+	renderDirectoryPage,
+	renderDiffPage,
+	renderErrorPage,
+	renderFileDiffPage,
+	renderFilePage,
+} from "../view/html.ts";
+import type { ChangeSummary } from "../view/html.ts";
+import { encodePath, HttpError, relativePath, resolveDecodedPath, resolveRequestPath } from "../files/paths.ts";
+import { listingRevision } from "../live/rev.ts";
 
 export interface ServeContext {
 	root: string;
@@ -108,9 +116,13 @@ function summaryOf(list: DiffList): ChangeSummary {
 	};
 }
 
-/** The live chrome a page renders, or `undefined` when live status is off. */
-function liveOf(ctx: ServeContext): { intervalMs: number } | undefined {
-	return ctx.config.live && ctx.live ? { intervalMs: ctx.config.liveIntervalMs } : undefined;
+/**
+ * The live chrome a page renders, or `undefined` when live status is off. A
+ * listing page also passes the revision of what it drew, which is what its
+ * reload control compares against; every other page has nothing to compare.
+ */
+function liveOf(ctx: ServeContext, folder?: { dir: string; rev: string }): LivePage | undefined {
+	return ctx.config.live && ctx.live ? { intervalMs: ctx.config.liveIntervalMs, ...folder } : undefined;
 }
 
 /** The `head` change summary, for the header chip, tree markers, and file action. */
@@ -184,7 +196,10 @@ async function directoryResponse(ctx: ServeContext, rel: string): Promise<ServeR
 			maxThumbBytes: ctx.config.maxThumbBytes,
 			git,
 			summary: changes,
-			live: liveOf(ctx),
+			live: liveOf(
+				ctx,
+				listing.truncated ? undefined : { dir: rel, rev: listingRevision(listing.entries.map((entry) => entry.name)) },
+			),
 		}),
 	);
 }
@@ -312,6 +327,17 @@ async function treeApi(ctx: ServeContext, decodedPath: string): Promise<ServeRes
 	return jsonResponse(200, { path: rel, entries: listing.entries.map(treeApiEntry) });
 }
 
+/** The revision of one folder's listing: what a page's reload control compares against. */
+async function dirRevApi(ctx: ServeContext, decodedPath: string): Promise<ServeResponse> {
+	const abs = await resolveDecodedPath(ctx.root, decodedPath);
+	const rel = relativePath(ctx.root, abs);
+	const listing = await listDirectory(ctx.root, rel, ctx.config.maxDirEntries);
+	// A truncated listing is a prefix whose boundary moves, so its revision is not
+	// comparable with what the page drew: `null` says "cannot tell".
+	const names = listing.entries.map((entry) => entry.name);
+	return jsonResponse(200, { path: rel, rev: listing.truncated ? null : listingRevision(names) });
+}
+
 /** Fuzzy file search for the quick-open palette, over the cached index. */
 async function filesApi(ctx: ServeContext, query: string): Promise<ServeResponse> {
 	const index = ctx.index ? await ctx.index() : await buildFileIndex(ctx.root, ctx.config.maxIndexEntries);
@@ -355,6 +381,7 @@ export async function handleRequest(
 		if (pathname === THEME_JS_PATH) return { status: 200, headers: scriptHeaders(), body: THEME_JS };
 		if (pathname === "/favicon.ico") return { status: 204, headers: pageHeaders(), body: "" };
 		if (pathname === "/api/tree") return await treeApi(ctx, search.get("path") ?? "");
+		if (pathname === "/api/dir-rev") return await dirRevApi(ctx, search.get("path") ?? "");
 		if (pathname === "/api/files") return await filesApi(ctx, search.get("q") ?? "");
 		if (pathname === "/events") return liveEvents(ctx);
 		const rawMode = search.get("mode");

package/extensions/file-browse/transport/server.ts

@@ -0,0 +1,110 @@
+/**
+ * The HTTP server for the browse extension.
+ *
+ * Wraps the pure `handleRequest` in `lib/http`'s loopback server: it resolves the
+ * root once, feeds the live status channel, and exposes an idempotent `close()`.
+ * The request handler is injectable so tests can avoid a socket when they only
+ * need routing.
+ *
+ * What stays here is this extension's own policy: the request handler, its
+ * request count, the catch that turns a thrown handler into a plain-text 500, the
+ * cap that refuses a page rather than opening a stream for it, and how long a
+ * server with nobody reading it is worth keeping.
+ */
+
+import { realpathSync } from "node:fs";
+import { type ServeResponse, serveLoopback, textResponse } from "../../../lib/http/index.ts";
+import { IDLE_STOP_MS, type ServeConfig } from "../config/config.ts";
+import { createFileIndex } from "../files/files.ts";
+import type { GitDiffProvider, GitStatusProvider } from "../git/git.ts";
+import { createLiveChannel, createLiveStatus } from "../live/live.ts";
+import { handleRequest, type ServeContext } from "./router.ts";
+
+export interface FileServer {
+	/** Origin URL, e.g. `http://127.0.0.1:49152/`. */
+	url: string;
+	/** The bound port. */
+	port: number;
+	/** Resolved absolute root that is actually served. */
+	root: string;
+	/** Stop listening. Safe to call more than once or before `listen` settles. */
+	close(): Promise<void>;
+}
+
+export interface FileServerOptions {
+	root: string;
+	config: ServeConfig;
+	/** Read-only git context for the page header; omitted when unavailable. */
+	git?: GitStatusProvider;
+	/** Read-only diff provider for the change and diff views; omitted when unavailable. */
+	diff?: GitDiffProvider;
+	/** Called once the last page has been gone for `idleStopMs`; omitted, the server waits for `close()`. */
+	onIdle?: () => void;
+	/** Grace before `onIdle`, in ms; defaults to `IDLE_STOP_MS`. */
+	idleStopMs?: number;
+	/** Override the request handler (tests). */
+	handler?: typeof handleRequest;
+}
+
+/** Start a read-only server rooted at `options.root` on 127.0.0.1. */
+export async function createFileServer(options: FileServerOptions): Promise<FileServer> {
+	const root = realpathSync.native(options.root);
+	const { config } = options;
+	// The status feed's two server-owned facts: how long it has been up, and how
+	// many requests it has answered. Both are read per frame, never cached.
+	let requests = 0;
+	const status = config.live
+		? createLiveStatus({
+				git: options.git,
+				diff: config.gitDiff ? options.diff : undefined,
+				startedAt: Date.now(),
+				requests: () => requests,
+			})
+		: undefined;
+	const live = status ? createLiveChannel({ status, intervalMs: config.liveIntervalMs }) : undefined;
+	const context: ServeContext = {
+		root,
+		config,
+		git: options.git,
+		diff: options.diff,
+		index: createFileIndex(root, config.maxIndexEntries),
+		live: status,
+	};
+	const handler = options.handler ?? handleRequest;
+
+	const server = await serveLoopback({
+		ports: [config.port],
+		idle: options.onIdle === undefined ? undefined : { ms: options.idleStopMs ?? IDLE_STOP_MS, onIdle: options.onIdle },
+		handler: async (request) => {
+			requests += 1;
+			let result: ServeResponse;
+			try {
+				result = await handler(context, request.method, request.url, request.headers);
+			} catch {
+				return { result: textResponse(500, "Internal error") };
+			}
+			if (!result.stream || !live || request.method.toUpperCase() === "HEAD") return { result };
+			// Checked before the head is written: a refusal must not leave a stream the
+			// client would wait on. `204` is the one status an event source does not
+			// reconnect after, so a page beyond the cap goes quiet instead of retrying.
+			if (live.atCapacity()) {
+				return { result: { status: 204, headers: { "Cache-Control": "no-store" }, body: "" } };
+			}
+			return {
+				result,
+				openSink: (sink) => live.attach({ write: (frame) => sink.write(frame), end: () => sink.end() }),
+			};
+		},
+	});
+
+	return {
+		url: `${server.origin}/`,
+		port: server.port,
+		root,
+		close: async () => {
+			// End the streams first, so a connected page does not hold the close open.
+			live?.close();
+			await server.close();
+		},
+	};
+}

package/extensions/file-browse/view/chrome.ts

@@ -0,0 +1,83 @@
+/**
+ * The header chrome for the browse pages.
+ *
+ * The chips the toolbar carries — the git branch, the change totals, the live
+ * connection state — and the footer's live line. Everything here is pure string
+ * building over an escaped view model: a branch name, a count, and a status word
+ * are all text a repository can choose, so each one crosses `escapeHtml` before
+ * it reaches the page. The page shell and the page bodies stay in `html.ts`.
+ */
+
+import { escapeHtml } from "../../../lib/escape.ts";
+import { GLYPHS } from "../../../lib/tui/glyphs.ts";
+import type { GitStatus } from "../git/git.ts";
+import type { ChangeIndex } from "../live/live.ts";
+
+/** The header's git chip: the branch, or the detached head; changes are the changes chip's job. */
+export function renderGit(git: GitStatus | undefined): string {
+	if (!git) return "";
+	const name = git.branch ?? git.head;
+	if (!name) return "";
+	const glyph = git.branch ? GLYPHS.branch : GLYPHS.detached;
+	const aria = git.branch ? `git branch ${git.branch}` : `git detached at ${git.head ?? ""}`;
+	return `<span class="bf-chip browse-git" title="${escapeHtml(aria)}" aria-label="${escapeHtml(aria)}"><span class="browse-git__glyph" aria-hidden="true">${escapeHtml(glyph)}</span><span class="browse-git__name">${escapeHtml(name)}</span></span>`;
+}
+
+/** The live chrome a page renders: how often its stream is sent a frame. */
+export interface LivePage {
+	intervalMs: number;
+	/** Root-relative folder the page listed; absent on a page with no listing to check. */
+	dir?: string;
+	/** Revision of the names that listing drew, which the reload control compares against. */
+	rev?: string;
+}
+
+/**
+ * The header's live controls: the connection chip, and the reload control the
+ * client reveals once the folder the page drew has changed on disk. Both start
+ * hidden, so a page with JS off — or with live status disabled — never shows a
+ * state or a control it cannot keep true; the reload control is not rendered at
+ * all when the page has no listing revision to compare.
+ *
+ * The chip is deliberately not a `role="status"` region: the header is where a
+ * reader looks for the page's state, not a place to announce every change to it.
+ */
+export function renderLiveChrome(live: LivePage | undefined): string {
+	if (!live) return "";
+	const rev =
+		live.rev === undefined ? "" : ` data-dir="${escapeHtml(live.dir ?? "")}" data-rev="${escapeHtml(live.rev)}"`;
+	const chip = `<span class="bf-chip bf-chip--accent browse-live" id="live-state" title="Live status from the browse server" data-interval="${live.intervalMs}"${rev} hidden><span class="browse-live__glyph" aria-hidden="true">${escapeHtml(GLYPHS.browse)}</span><span class="browse-live__text">connecting</span></span>`;
+	if (live.rev === undefined) return chip;
+	return `${chip}<button type="button" class="bf-chip bf-chip--warn browse-reload" id="reload-hint" title="This folder changed on disk" hidden>⟳ reload</button>`;
+}
+
+/**
+ * The footer's live line, hidden until the first frame: uptime and requests are
+ * server facts the rendered page does not know at build time.
+ */
+export function renderLiveStatus(): string {
+	return `<span class="browse-live-line" id="live-status" hidden></span>`;
+}
+
+/**
+ * The header's changes chip, linking to the diff overview. With live status on,
+ * a hidden shell is always rendered so the chip can appear and disappear as the
+ * working tree changes, without the client inserting elements into the header.
+ */
+export function renderChanges(summary: ChangeIndex | undefined, live: LivePage | undefined): string {
+	const count = summary?.count ?? 0;
+	if (count <= 0) {
+		return live
+			? `<a class="bf-chip browse-diff" id="browse-changes" href="/diff" title="View uncommitted changes" hidden></a>`
+			: "";
+	}
+	const label = `${count} change${count === 1 ? "" : "s"}`;
+	const insertions = summary?.insertions ?? 0;
+	const deletions = summary?.deletions ?? 0;
+	const totals =
+		insertions + deletions > 0
+			? ` <span class="browse-diff-totals"><span class="browse-diff-add">+${insertions}</span> <span class="browse-diff-del">−${deletions}</span></span>`
+			: "";
+	const aria = `${label} against HEAD${insertions + deletions > 0 ? `, ${insertions} insertions and ${deletions} deletions` : ""}`;
+	return `<a class="bf-chip browse-diff" id="browse-changes" href="/diff" title="View uncommitted changes" aria-label="${escapeHtml(aria)}"><span class="browse-diff__dot" aria-hidden="true">●</span>${escapeHtml(label)}${totals}</a>`;
+}

package/extensions/file-browse/{client.ts → view/client.ts}

@@ -12,7 +12,7 @@
  * and `bun build --no-bundle` needs no separate asset.
  */
 
-import { keysDialogScript, THEME_TOGGLE_JS } from "../../lib/web/index.ts";
+import { keysDialogScript, THEME_TOGGLE_JS } from "../../../lib/web/index.ts";
 import { LIVE_CLIENT_JS } from "./live-client.ts";
 import { PALETTE_CLIENT_JS } from "./palette.ts";
 import { TREE_CLIENT_JS } from "./tree.ts";
@@ -148,6 +148,65 @@ ${TREE_CLIENT_JS}
 
 ${PALETTE_CLIENT_JS}
 
+	// A code reference: the file's path and the lines the reader selected. A click on
+	// the button collapses the selection before its click handler runs, so a new
+	// selection replaces the stored one and a collapse leaves it alone.
+	var reference = null;
+
+	function lineNode(node) {
+		var element = node && node.nodeType === 3 ? node.parentElement : node;
+		return element && element.closest ? element.closest(".bf-code__line") : null;
+	}
+
+	function referenceText() {
+		if (!reference || !reference.path) return "";
+		var span = reference.start === reference.end ? String(reference.start) : reference.start + "-" + reference.end;
+		return reference.path + ":" + span;
+	}
+
+	function captureReference() {
+		var button = document.getElementById("copy-reference");
+		if (!button) return;
+		var selection = window.getSelection && window.getSelection();
+		if (!selection || selection.isCollapsed || selection.rangeCount === 0) return;
+		var range = selection.getRangeAt(0);
+		var from = lineNode(range.startContainer);
+		var to = lineNode(range.endContainer);
+		if (!from || !to) return;
+		var pre = from.closest("pre[data-path]");
+		if (!pre || pre !== to.closest("pre[data-path]")) return;
+		var lines = Array.prototype.slice.call(pre.querySelectorAll(".bf-code__line"));
+		var first = lines.indexOf(from);
+		var last = lines.indexOf(to);
+		if (first < 0 || last < 0) return;
+		reference = {
+			path: pre.getAttribute("data-path") || "",
+			start: Math.min(first, last) + 1,
+			end: Math.max(first, last) + 1
+		};
+		button.disabled = false;
+		button.title = "Copy " + referenceText();
+	}
+
+	function copyReference() {
+		var text = referenceText();
+		var button = document.getElementById("copy-reference");
+		if (!text) {
+			var status = document.getElementById("copy-status");
+			if (status) status.textContent = "Select lines in the code to copy a reference.";
+			return;
+		}
+		copyText(text)
+			.then(function () { if (button) flash(button, "copied", "Copied " + text); })
+			.catch(function () { if (button) flash(button, "failed", "Copy failed"); });
+	}
+
+	if (document.getElementById("copy-reference")) {
+		document.getElementById("copy-reference").addEventListener("click", copyReference);
+		document.addEventListener("mouseup", captureReference);
+		document.addEventListener("keyup", captureReference);
+	}
+
 	// Keyboard: the shared shortcut sheet, the per-page actions the server
 	// rendered, and hunk-to-hunk navigation through a diff.
 	${keysDialogScript("keys-open")}
@@ -256,6 +315,9 @@ ${PALETTE_CLIENT_JS}
 		} else if (event.key === "u" && wrapButton) {
 			event.preventDefault();
 			wrapButton.click();
+		} else if (event.key === "y" && document.getElementById("copy-reference")) {
+			event.preventDefault();
+			copyReference();
 		} else if (event.key === "r" && document.querySelector(".bf-card__actions .bf-segmented")) {
 			event.preventDefault();
 			toggleRaw();