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

package/lib/report.ts

@@ -14,11 +14,14 @@
  *
  * Delivery is one shared transcript notice per burst, and a burst is marked
  * reported only after the send succeeded, so a throw leaves it for the next
- * turn. Value-only: every flag lives in the returned closure, never in a module
- * variable, because each extension gets its own module instance.
+ * turn. `registerPendingChannel` is the other half: the seven host hooks that
+ * drive the machine, registered once for `job` and `watch` rather than copied
+ * into each factory. Value-only: every flag lives in the returned closure, never
+ * in a module variable, because each extension gets its own module instance.
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { pruneStaleNotices, type NoticeMessage } from "./notice.ts";
 
 export interface PendingReporterOptions<T> {
@@ -97,3 +100,73 @@ export function createPendingReporter<T>(options: PendingReporterOptions<T>): Pe
 		},
 	};
 }
+
+/** The session-scoped state a channel drives, narrowed to what its hooks need. */
+export interface PendingChannelRuntime {
+	/** Load this session's records; called on every session start. */
+	load(ctx: ExtensionContext): void;
+	/** Repaint the status chip. */
+	setStatus(ctx: ExtensionContext): void;
+	/** Release the session's resources; idempotent. */
+	shutdown(): Promise<void>;
+}
+
+export interface PendingChannelOptions {
+	/** The reporter that turns pending outcomes into notices. */
+	reporter: PendingReporter;
+	/** The runtime whose pending outcomes the notices describe. */
+	runtime: PendingChannelRuntime;
+	/** Runs on every session start, after the runtime loads: arm the report trigger. */
+	onSessionStart?(ctx: ExtensionContext): void;
+	/** Runs before the runtime releases: clear what `onSessionStart` armed. */
+	onSessionShutdown?(): void;
+}
+
+/**
+ * Wire a reporter to the host's session lifecycle.
+ *
+ * The order inside `session_start` is the contract: the reporter forgets the
+ * previous session's busy window, the runtime loads the records, and only then
+ * is the report trigger armed — a reload or a replaced session reuses the same
+ * runtime. A shutdown clears the trigger before the runtime releases the table it
+ * was calling into.
+ */
+export function registerPendingChannel(
+	pi: Pick<ExtensionAPI, "on">,
+	{ reporter, runtime, onSessionStart, onSessionShutdown }: PendingChannelOptions,
+): void {
+	pi.on("session_start", (_event, ctx) => {
+		reporter.sessionStart();
+		runtime.load(ctx);
+		onSessionStart?.(ctx);
+	});
+
+	// Tree navigation does not change the pending records; only repaint.
+	pi.on("session_tree", (_event, ctx) => {
+		runtime.setStatus(ctx);
+	});
+
+	pi.on("agent_start", () => {
+		reporter.agentStart();
+	});
+	pi.on("agent_settled", () => {
+		reporter.agentSettled();
+	});
+
+	// Report what is queued at the start of the next turn, without triggering one.
+	pi.on("before_agent_start", (_event, ctx) => {
+		const reported = reporter.beforeAgentStart();
+		if (!reported) return undefined;
+		runtime.setStatus(ctx);
+		return reported;
+	});
+
+	// Keep stale notices out of later turns. Only this source's notices are
+	// pruned; another source's are left for its own handler.
+	pi.on("context", (event) => reporter.filterContext(event.messages));
+
+	pi.on("session_shutdown", async () => {
+		onSessionShutdown?.();
+		await runtime.shutdown();
+	});
+}

package/lib/tool-result.ts

@@ -1,17 +1,67 @@
 /**
- * The shared shape of a rejected tool call.
+ * The shared shape of a tool result.
  *
- * Extension tools return an `isError: true` result carrying their own `details`
- * type. `toolError` builds the content and the flag so the extensions that
- * reject a call (`job` and `watch`, plus any future tool) agree on the shape.
+ * Every extension tool returns the same envelope: one text block the model
+ * reads, the extension's own `details` for the renderer and the session branch,
+ * and — where the tool declares an `outputSchema` — the JSON mirror Pi calls
+ * `structuredContent`. A rejected call is that envelope marked `isError`, still
+ * carrying the previous state so the model can retry.
+ *
+ * `textResult` and `failedResult` build the two, so the flag and the absent
+ * `structuredContent` are decided once. What stays with the extension is the
+ * text and the mirror: `structuredContent` drops `undefined` field by field and
+ * projects nested objects, so it is written per `details` type rather than
+ * derived. `toolError` / `errorResult` keep the shorthand the
+ * action-and-message tools (`job` and `watch`) share.
  */
 
+import type { JsonValue } from "@earendil-works/pi-ai";
+
 /** One text block in a tool result. */
 export interface ToolErrorContent {
 	type: "text";
 	text: string;
 }
 
+/** A tool result: what the model reads, the extension's details, and its JSON mirror. */
+export interface ToolResult<Details> {
+	content: ToolErrorContent[];
+	details: Details;
+	structuredContent?: Record<string, JsonValue>;
+}
+
+/** A rejected call: the result, marked so the host reports it as an error. */
+export interface ToolFailure<Details> extends ToolResult<Details> {
+	isError: true;
+}
+
+/** The content and details both results share. */
+function envelope<Details>(text: string, details: Details): ToolResult<Details> {
+	return { content: [{ type: "text", text }], details };
+}
+
+/** A successful call. */
+export function textResult<Details>(
+	text: string,
+	details: Details,
+	structuredContent?: Record<string, JsonValue>,
+): ToolResult<Details> {
+	const result = envelope(text, details);
+	return structuredContent === undefined ? result : { ...result, structuredContent };
+}
+
+/** A rejected call, keeping the state the caller had before it. */
+export function failedResult<Details>(
+	text: string,
+	details: Details,
+	structuredContent?: Record<string, JsonValue>,
+): ToolFailure<Details> {
+	const result = envelope(text, details);
+	return structuredContent === undefined
+		? { ...result, isError: true }
+		: { ...result, structuredContent, isError: true };
+}
+
 /** A rejected tool call: the message as content, the extension's details, and the error flag. */
 export function toolError<Details extends { action: string; error: string }>(
 	message: string,

package/lib/tui/README.md

@@ -35,17 +35,24 @@ Reach for a `lib/tui/` primitive before composing your own: `plainRule` /
 `fitCells` for two columns, `LinePane` for a scrollable log, `ListCursor` /
 `IdCursor` for selection, `byRunningFirst` for a live list's order,
 `DockListScreen` for a list that opens a pane, `TailResult` for a tool result
-that lists rows or tails output, and `ConfirmState` before a destructive action.
+that lists rows or tails output, `screenFooter` for a screen's own last three
+rows, and `ConfirmState` before a destructive action.
 
 ## Docked list screens
 
 Every list screen is `dockListFrame`: the header rule, an optional summary and
-its blank line, the body, an optional range row, an optional detail block, and
-the blank-padded hint. The frame owns that spacing, so a screen never hand-rolls
-it — including the blank line above the detail block, which keeps a footnote
-from reading as one more row. A screen that sizes its body through `fitRows`
-counts the block with `detailBlockRows`, or the hint row is pushed off the
-bottom of a short terminal.
+its blank line, the body, an optional range row, an optional detail block, the
+key-hint row, and the closing rule. The frame owns that spacing, so a screen
+never hand-rolls it — including the blank line above the detail block, which
+keeps a footnote from reading as one more row. A screen that sizes its body
+through `fitRows` counts the block with `detailBlockRows`, or the hint row is
+pushed off the bottom of a short terminal.
+
+The closing rule is not decoration: Pi's built-in selectors draw one under the
+list and over the footer, and the editor a docked screen replaces draws its own,
+so a screen that ends on a blank removes the dock's bottom edge. A screen that
+lays out its own rows closes its block with `screenFooter(theme, width, hint)`;
+a screen whose row above the hint varies places `plainRule` itself.
 
 A list that **opens a pane over one row** — `/jobs`, `/watch`, `/agents`,
 `/check` — subclasses [`dock-screen.ts`](./dock-screen.ts) instead of
@@ -92,7 +99,8 @@ Resolve colors through a [`tokens.ts`](./tokens.ts) role
 (`paint(theme, role, text)`), never a literal ANSI sequence, hex value, or Pi
 token named inline; a theme swap must re-skin every surface. Use the shared
 `selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS` instead of retyping
-their literals, and `screenHint` / Pi's `keyHint` for the hint row.
+their literals, `screenHint` / Pi's `keyHint` for the hint row, and
+`screenFooter` for the hint row with its blank and closing rule.
 
 A list accents the focused row's label (`labelRole: selected ? "accent" :
 "label"`); the `❯` marker alone is not enough to tell which row is live. The

package/lib/tui/chrome.ts

@@ -8,9 +8,9 @@
  * the transcript visible.
  *
  * Screens are full-width, terminal-height-aware components. These helpers build
- * the top rule, clamp a screen's body to the terminal, and render the key-hint
- * footer, so each screen keeps its own layout but not its own copy of the
- * arithmetic or hint vocabulary.
+ * the top rule and the closing rule, clamp a screen's body to the terminal, and
+ * render the key-hint footer, so each screen keeps its own layout but not its
+ * own copy of the arithmetic or hint vocabulary.
  *
  * No runtime dependencies beyond `@earendil-works/pi-tui`: the theme is passed
  * in, and the viewport options are explicit.
@@ -20,6 +20,7 @@ import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type EditorTheme, type OverlayOptions } from "@earendil-works/pi-tui";
 import { SEPARATORS } from "./glyphs.ts";
 import { BODY_INDENT } from "./indent.ts";
+import { plainRule } from "./rules.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -88,12 +89,29 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[], ind
 	return truncateToWidth(`${lead}${kept.map(render).join(separator)}`, target);
 }
 
+/**
+ * The bottom of a screen: a blank row, its key-hint row, and the closing rule.
+ *
+ * {@link dockListFrame} ends a docked list screen with this, and a screen that
+ * lays out its own rows — `/context`, the WeChat login and control screens —
+ * closes its block with it too, so no screen spells the three rows out alone. A
+ * screen whose row above the hint varies (a scroll gauge or a blank) places its
+ * own rule with `plainRule` instead.
+ */
+export function screenFooter(theme: Theme, width: number, hint: string): string[] {
+	return ["", hint, plainRule(theme, width)];
+}
+
 /**
  * The sections of a docked list screen, assembled by {@link dockListFrame}.
  * `body`, `range`, and `detail` lines are built (and truncated) by the caller;
  * the frame only places them.
  */
 export interface DockListFrame {
+	/** The active theme, used for the closing rule. */
+	theme: Theme;
+	/** The screen width in columns, used for the closing rule. */
+	width: number;
 	/** The pre-rendered header line, usually `titleRule(theme, width, title)`. */
 	header: string;
 	/** A summary line under the header; a blank line follows it. */
@@ -132,11 +150,14 @@ export function detailBlockRows(detail: readonly string[] | undefined, blank = t
 /**
  * Assemble a docked list screen: the caller's header rule, an optional summary
  * and its blank line, the body, an optional range row, optional detail rows after
- * their own blank line, and the blank-line-padded key-hint footer.
+ * their own blank line, the key-hint row, and the closing rule.
  *
  * This is the convention every docked list screen shares — the bytefly panel,
  * `/jobs`, `/watch`, `/todos`, `/memory`, and `/rewind`. The header line is built
- * by the caller (usually `titleRule`), so the frame never picks a rule style.
+ * by the caller (usually `titleRule`), so the frame never picks the *opening*
+ * rule style; the closing rule is always the muted fill, matching the closing
+ * rule Pi's built-in selectors draw and the bottom border of the editor slot the
+ * screen replaces.
  */
 export function dockListFrame(frame: DockListFrame): string[] {
 	const lines: string[] = [frame.header];
@@ -147,7 +168,7 @@ export function dockListFrame(frame: DockListFrame): string[] {
 		if (frame.detailBlank !== false) lines.push("");
 		lines.push(...frame.detail);
 	}
-	lines.push("", frame.hint, "");
+	lines.push(...screenFooter(frame.theme, frame.width, frame.hint));
 	return lines;
 }
 

package/lib/tui/dock-screen.ts

@@ -33,10 +33,10 @@ import { paint } from "./tokens.ts";
 /** Rows the body shows when the terminal height is unknown. */
 const SCREEN_DEFAULT_ROWS = 14;
 
-/** Fixed rows around the list body: header, summary, blank, blank, hint, blank. */
+/** Fixed rows around the list body: header, summary, blank, blank, hint, closing rule. */
 const LIST_CHROME_ROWS = 6;
 
-/** Fixed rows around a detail body: header, subtitle, blank, blank, hint, blank. */
+/** Fixed rows around a detail body: header, subtitle, blank, blank, hint, closing rule. */
 const DETAIL_CHROME_ROWS = 6;
 
 /** What a detail pane shows: its title, lines, and the one-line subtitle. */
@@ -353,6 +353,8 @@ export abstract class DockListScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, this.options.title),
 			summary: this.summary(rows, w),
 			body,
@@ -389,6 +391,8 @@ export abstract class DockListScreen<T> implements Component {
 		}
 
 		return dockListFrame({
+			theme: this.theme,
+			width: w,
 			header: titleRule(this.theme, w, this.pane.title(this.options.detailTitle)),
 			summary: clip(`  ${paint(this.theme, "faint", this.pane.subtitleLine())}`, w),
 			body,

package/lib/tui/gauge.ts

@@ -26,16 +26,20 @@ export const DEFAULT_GAUGE_THRESHOLDS: GaugeThresholds = { warn: 70, danger: 90
 /**
  * Filled and empty block counts for a percentage across `blocks` cells.
  *
- * The fill floors so the bar reads full only at 100%, and forces one block for
- * any non-zero usage so a small percentage is still visible. A `null` percent
- * (unknown) fills nothing, leaving the caller to decide whether to draw the
- * empty track; a known `0` draws it.
+ * The fill rounds to the nearest cell, so a bar sits no more than half a cell
+ * away from the number printed beside it, and the last cell is kept for 100% so
+ * a bar reads full only at a full value. Any non-zero usage still forces one
+ * block, so a small percentage stays visible. A `null` percent (unknown) fills
+ * nothing, leaving the caller to decide whether to draw the empty track; a known
+ * `0` draws it.
  */
 export function computeGauge(percent: number | null, blocks: number): { filled: number; empty: number } {
 	if (blocks <= 0) return { filled: 0, empty: 0 };
 	if (percent === null) return { filled: 0, empty: blocks };
 	const clamped = Math.max(0, Math.min(100, percent));
-	const filled = Math.max(clamped > 0 ? 1 : 0, Math.floor((clamped / 100) * blocks));
+	const nearest = Math.round((clamped / 100) * blocks);
+	const capped = clamped < 100 ? Math.min(blocks - 1, nearest) : nearest;
+	const filled = Math.max(clamped > 0 ? 1 : 0, capped);
 	return { filled, empty: blocks - filled };
 }
 

package/lib/usage.ts

@@ -0,0 +1,26 @@
+/**
+ * The usage counters this package accounts in.
+ *
+ * A session, a delegated child run, and a priced record are all measured in the
+ * same five numbers, so the list lives here rather than in each caller:
+ * bytefly's footer accumulates them for the session and for its `↳` roll-up, and
+ * `subagent` accumulates them from a child's JSON events.
+ *
+ * `turns` and the context size are deliberately not counters — one is counted
+ * per message, the other is a window occupancy rather than something to sum — so
+ * each owner tracks those beside these.
+ */
+
+/** The counters, in the order a usage line prints them. */
+export const USAGE_COUNTERS = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
+
+/** One counter in a usage accumulator. */
+export type UsageCounter = (typeof USAGE_COUNTERS)[number];
+
+/** A usage accumulator: one running total per counter. */
+export type UsageCounts = Record<UsageCounter, number>;
+
+/** A zeroed accumulator, ready to sum into. */
+export function zeroUsage(): UsageCounts {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}

package/lib/web/README.md

@@ -0,0 +1,131 @@
+# lib/web — the shared browser design system
+
+The tokens, base rules, app shell, `bf-*` components, HTML atoms, and client
+runtime the two loopback pages draw with: the plan review
+([`../../extensions/plan/web-page.ts`](../../extensions/plan/web-page.ts)) and
+file browse ([`../../extensions/file-browse/styles.ts`](../../extensions/file-browse/styles.ts)).
+The module-by-module inventory is the `web/` row of [`../README.md`](../README.md);
+this file is the conventions those modules exist to make easy.
+
+Both pages serve a same-origin document through the shared HTTP layer
+([`../http/index.ts`](../http/index.ts)) under one CSP. The kit is the one policy
+for how that document looks and moves — a second palette, focus ring, or dialog
+is the bug this directory prevents.
+
+## Compose the layers in order
+
+A page concatenates `WEB_BASE_CSS`, `WEB_THEME_CSS`, `WEB_LAYOUT_CSS`,
+`WEB_COMPONENTS_CSS`, then its own page rules. Each block appears **once**: a
+repeated block still renders, so only a count catches it, and every page suite
+counts its own stylesheet (`pages.test.ts`, `web.test.ts`). A page rule is
+namespaced (`review-*`, `browse-*`) and overrides a kit class rather than
+re-declaring it.
+
+## Color is a role
+
+`WEB_THEME_TOKENS` is derived from `themes/bytefly-dark.json` and
+`themes/bytefly-light.json`, so the browser and the TUI cannot drift. Four values
+are computed rather than mapped:
+
+- `--accent-soft` — the accent at 15% (dark) or 10% (light), for a selection or
+  the active nav row.
+- `--on-accent` — the appearance's canvas. A label on the accent fill is dark
+  text on the light-blue dark accent and white on the darker light one.
+- `--scrim` and `--shadow` — per appearance, because a dimming layer and a lifted
+  panel need their own alpha rather than a palette entry.
+
+Components read tokens only: no literal hex or `rgba()` in `components.ts`, and a
+test fails one. Contrast is asserted, not assumed — text, muted, and accent at
+4.5:1 on both surfaces, the primary label at 4.5:1 on the accent fill, `--dim` at
+3:1 because it carries the line-number gutter, and the status colours at 3:1.
+
+The theme layer emits the dark palette at `:root`, the explicit light override,
+the system-light fallback, the `tok-*` syntax rules, and **last** a print block
+that resets to the light palette: paper is white whatever the screen shows.
+
+## The shell
+
+`.bf-app` is a definite-height column — `100vh`, then `100dvh` — so the header,
+sidebar, and main pane scroll inside it instead of the document. `.bf-app__body`
+is a 260px sidebar plus main; at `SIDEBAR_COLLAPSE_MAX` (860) the sidebar becomes
+a `<details>` disclosure and the page returns to normal scrolling. That is the
+only breakpoint the shell owns; a page's own (`820`, `1180`) stays in its
+stylesheet, since a media query cannot read a custom property.
+
+A `<details>` lays its content out in a wrapper with no definite height, so a
+sidebar that must scroll on its own box positions its panel absolutely rather
+than making the panel a flex child. `file-browse` does this; the rule and its
+reason are in `layout.ts`.
+
+## The `bf-*` kit
+
+`bf-` marks the kit: brand and mark, toolbar, title, buttons (`--primary`,
+`--ghost`, `--icon`), chips and their tones, segmented control, field and input,
+textarea, panel, progress, status, note, empty state, dialog (head, body, actions,
+status, input, list, option), shortcut sheet and `bf-kbd`, tree, crumbs, table and
+sort, card, code, media, Markdown body, comment, composer, and quote chip.
+
+States are attributes, not classes, wherever a control has them:
+`aria-pressed`, `aria-current`, `aria-sort`, `aria-expanded`, `hidden`. The base
+layer's `[hidden]{display:none!important}` is what lets a `display:flex`
+component disappear — do not add a page rule to hide it again.
+
+## Element and script contracts
+
+These names are one agreement between a page, its client, and tests:
+
+| Contract | Owner |
+|---|---|
+| `#theme-toggle` with a `.theme-glyph` | `themeToggle()` (`markup.ts`) |
+| `THEME_JS_PATH` served by both routers | `runtime.ts` |
+| `pi-web-theme` in `localStorage` | `WEB_THEME_STORAGE_KEY` |
+| `#keys-dialog` (hidden, `aria-modal`) and `#keys-close` | `keysSheet` (`markup.ts`) |
+| the page's own sheet trigger id | `keysDialogScript(triggerId)` |
+| `window.bfKeys` — `open` / `toggle` / `close` / `isOpen` | `dialogScript` |
+
+`dialogScript(options)` is the one modal implementation: it opens and closes,
+closes on a backdrop click, traps `Tab` inside the panel, closes on `Esc` in the
+capture phase (so a page's keymap cannot peel a different layer first), restores
+focus to whatever opened it, and exposes `window[globalName]`. It renders nothing
+when the element is absent, so a page can embed it unconditionally. A page adds
+only its own confirm button's listener.
+
+`THEME_JS` is the pre-paint bootstrap and lives in the head; `THEME_TOGGLE_JS`
+paints the glyph, follows the system until the reader chooses, and then keeps the
+choice. Neither page reloads for a theme.
+
+## Markup atoms and escaping
+
+`docHead`, `brandLockup`, `themeToggle`, `chip`, `button`, and `keysSheet` return
+strings. Every dynamic **value** goes through `escapeHtml` from
+[`../escape.ts`](../escape.ts); the fields documented as trusted (`css`, an
+`icon` glyph, an attribute key, a client id) are code-authored constants, never
+model or file text. A page that renders its own document follows the same rule.
+
+The kit is HTML and CSS only; plan text stays out of the page markup and arrives
+through the review's JSON island, so the client writes `textContent` and never
+markup.
+
+## Print and forced colours
+
+`base.ts` owns both medias. Print un-constrains the shell and drops the toolbar,
+sidebar, footer, progress bar, skip link, and dialogs; a page adds what its own
+box clips (a card, a code pane, a sticky hunk header). Under
+`forced-colors:active` the hand-drawn task checkbox names system colours and the
+focus ring stays `CanvasText`, because Windows High Contrast replaces colour but
+not a drawn control.
+
+## Keyboard
+
+Every interactive element gets the one focus ring from `base.ts`; a component
+must not declare its own, or the ring disappears surface by surface. A dialog
+traps `Tab`. Within a page, `j`/`k`, arrows, and `?` follow the TUI's vocabulary
+where they mean the same thing; the browse tree is one tab stop with arrows, and
+`Enter` follows the focused link.
+
+## Tests
+
+[`web.test.ts`](./web.test.ts) pins the token anchors, the contrast ratios, each
+emitted block, the atoms' escaping, and every contract above. A page's suite adds
+its own: the stylesheet is shipped once, and the ids its client greps for exist in
+the markup.

package/lib/web/base.ts

@@ -1,6 +1,7 @@
 /**
  * Base rules shared by the Bytefly browser surfaces: box sizing, hidden,
- * links, the focus ring, and the skip-link / screen-reader helpers.
+ * links, the focus ring, the skip-link / screen-reader helpers, and the two
+ * media the kit answers for every page — print and forced colours.
  *
  * Page layout (body display, shells) stays with each page; this layer is the
  * smallest set both pages must agree on.
@@ -16,4 +17,20 @@ a:hover{text-decoration:underline}
 a:focus-visible,button:focus-visible,input:focus-visible,textarea:focus-visible,select:focus-visible,[tabindex]:focus-visible{outline:var(--focus-ring) solid var(--accent);outline-offset:2px}
 .skip{position:absolute;left:-9999px;top:0;z-index:3;padding:var(--space-2) var(--space-4);background:var(--surface);color:var(--text);border:1px solid var(--border);border-radius:var(--radius-md)}
 .skip:focus{left:var(--space-3);top:var(--space-3)}
-.sr-only{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0}`;
+.sr-only{position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0}
+/* A printed page is not a viewport: the shell un-constrains, its chrome goes,
+   and the panes stop scrolling so the document prints whole. */
+@media print{
+.bf-app,.bf-app__body,.bf-app__main,.bf-app__sidebar,.bf-panel{display:block!important;height:auto!important;min-height:0!important;max-height:none!important;overflow:visible!important}
+.bf-toolbar,.bf-app__sidebar,.bf-app__footer,.bf-progress,.skip,.bf-dialog{display:none!important}
+.bf-app__header{position:static!important;border:0!important}
+.bf-app__main{padding:0!important}
+}
+/* Windows High Contrast replaces colour but not a drawn control, so the one
+   hand-drawn box names a system colour and the ring stays visible. */
+@media (forced-colors:active){
+a{color:LinkText}
+:focus-visible{outline-color:CanvasText}
+.bf-md .md-check{border-color:CanvasText}
+.bf-md .md-check:checked{forced-color-adjust:none;background:Highlight;border-color:Highlight}
+}`;

package/lib/web/components.ts

@@ -17,14 +17,13 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-btn{appearance:none;border:1px solid var(--border);border-radius:var(--radius-md);background:transparent;color:var(--text);font:var(--fs-sm) var(--font-ui);padding:5px var(--space-3);cursor:pointer}
 .bf-btn:hover{border-color:var(--accent);color:var(--accent);text-decoration:none}
 .bf-btn[aria-pressed="true"]{border-color:var(--accent);color:var(--accent);background:var(--accent-soft)}
-.bf-btn--primary{background:var(--accent);border-color:var(--accent);color:#fff}
-.bf-btn--primary:hover{filter:brightness(1.06);color:#fff}
+.bf-btn--primary{background:var(--accent);border-color:var(--accent);color:var(--on-accent)}
+.bf-btn--primary:hover{filter:brightness(1.06);color:var(--on-accent)}
 .bf-btn--ghost{border-color:transparent;background:none;padding:0;font:inherit;color:inherit}
 .bf-btn--ghost:hover{color:var(--accent)}
 .bf-btn--icon{min-width:36px;text-align:center;line-height:1}
+.theme-glyph{font-size:var(--fs-md)}
 .bf-btn:disabled{opacity:.5;cursor:default}
-.bf-theme-toggle{min-width:36px;text-align:center;line-height:1}
-.bf-theme-toggle .theme-glyph{font-size:var(--fs-md)}
 .bf-chip{display:inline-flex;align-items:center;gap:5px;font-size:var(--fs-xs);color:var(--muted);white-space:nowrap}
 .bf-chip--accent{color:var(--accent);border:1px solid currentColor;border-radius:var(--radius-pill);padding:2px 10px}
 .bf-chip--success{color:var(--success)}
@@ -51,8 +50,8 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-empty__title{font-size:var(--fs-base);margin:0 0 6px}
 .bf-empty__sub{color:var(--muted);font-size:var(--fs-sm);margin:0 0 var(--space-4)}
 .bf-empty__code{font:var(--fw-bold) 64px/1 var(--font-mono);color:var(--danger)}
-.bf-dialog{position:fixed;inset:0;z-index:5;display:flex;align-items:flex-start;justify-content:center;padding:10vh var(--space-4) var(--space-4);background:rgba(0,0,0,.45)}
-.bf-dialog__panel{width:min(640px,100%);max-height:70vh;display:flex;flex-direction:column;overflow:hidden;background:var(--surface);border:1px solid var(--border-strong);border-radius:var(--radius-lg);box-shadow:0 8px 24px rgba(0,0,0,.35)}
+.bf-dialog{position:fixed;inset:0;z-index:5;display:flex;align-items:flex-start;justify-content:center;padding:10vh var(--space-4) var(--space-4);background:var(--scrim)}
+.bf-dialog__panel{width:min(640px,100%);max-height:70vh;display:flex;flex-direction:column;overflow:hidden;background:var(--surface);border:1px solid var(--border-strong);border-radius:var(--radius-lg);box-shadow:var(--shadow)}
 .bf-dialog__status{margin:0;padding:var(--space-2) var(--space-4);border-top:1px solid var(--border);color:var(--muted);font-size:var(--fs-xs)}
 .bf-dialog__input{appearance:none;border:0;border-bottom:1px solid var(--border);background:transparent;color:var(--text);font:var(--fs-md) var(--font-mono);padding:var(--space-3) var(--space-4);outline:none}
 .bf-dialog__list{list-style:none;margin:0;padding:var(--space-1) 0;overflow:auto;min-height:0}
@@ -61,6 +60,11 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-dialog mark{background:transparent;color:var(--warn);font-weight:var(--fw-semibold)}
 .bf-dialog__head{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-3) var(--space-4);border-bottom:1px solid var(--border)}
 .bf-dialog__head h2{margin:0;font-size:var(--fs-lg)}
+.bf-dialog__body{padding:var(--space-3) var(--space-4);font-size:var(--fs-sm);line-height:var(--lh-relaxed)}
+.bf-dialog__body p{margin:0 0 var(--space-2)}
+.bf-dialog__body p:last-child{margin:0}
+.bf-dialog__hint{color:var(--muted)}
+.bf-dialog__actions{display:flex;justify-content:flex-end;gap:var(--space-2);padding:var(--space-3) var(--space-4);border-top:1px solid var(--border)}
 .bf-keys{display:grid;grid-template-columns:auto 1fr;gap:8px var(--space-4);margin:0;padding:var(--space-4)}
 .bf-keys dt{white-space:nowrap}
 .bf-keys dd{margin:0;color:var(--muted);font-size:var(--fs-sm)}

package/lib/web/layout.ts

@@ -27,6 +27,7 @@
 export const SIDEBAR_COLLAPSE_MAX = 860;
 
 export const WEB_LAYOUT_CSS = `.bf-app{display:flex;flex-direction:column;height:100vh;min-height:0;overflow:hidden;background:var(--canvas);color:var(--text);font:var(--fs-base)/var(--lh-normal) var(--font-ui)}
+.bf-app{height:100dvh}
 .bf-app__header{position:sticky;top:0;z-index:2;flex:0 0 auto;background:var(--surface);border-bottom:1px solid var(--border)}
 .bf-app__body{flex:1 1 auto;min-height:0;display:grid;grid-template-columns:260px minmax(0,1fr)}
 .bf-app__sidebar{display:flex;flex-direction:column;min-width:0;min-height:0;overflow-x:hidden;overflow-y:auto;background:var(--surface);border-right:1px solid var(--border)}
@@ -34,6 +35,7 @@ export const WEB_LAYOUT_CSS = `.bf-app{display:flex;flex-direction:column;height
 .bf-app__footer{flex:0 0 auto;border-top:1px solid var(--border);color:var(--muted);font-size:var(--fs-sm);padding:var(--space-3) var(--space-6)}
 @media (max-width:${SIDEBAR_COLLAPSE_MAX}px){
 .bf-app{height:auto;min-height:100vh;overflow:visible}
+.bf-app{min-height:100dvh}
 .bf-app__body{flex:none;grid-template-columns:1fr}
 .bf-app__sidebar{display:block;position:static;max-height:none;overflow:visible;border-right:0;border-bottom:1px solid var(--border)}
 .bf-app__main{overflow:visible}

package/lib/web/markup.ts

@@ -7,6 +7,7 @@
  */
 
 import { escapeHtml } from "../escape.ts";
+import { THEME_JS_PATH } from "./runtime.ts";
 
 /** Options for {@link docHead}. */
 export interface DocHeadOptions {
@@ -27,7 +28,7 @@ export function docHead(options: DocHeadOptions): string {
 <meta name="color-scheme" content="dark light">
 <title>${escapeHtml(options.title)}</title>
 <style>${options.css}</style>
-<script src="/theme.js"></script>`;
+<script src="${THEME_JS_PATH}"></script>`;
 }
 
 /**