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

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/tui/line-pane.ts

@@ -45,6 +45,11 @@ export class LinePane {
 	visible = 1;
 	/** Whether the view is parked at the tail; set false once the user scrolls up. */
 	follow = true;
+	/**
+	 * Whether this pane follows its tail. A log does; a prose or list pane does not:
+	 * it opens at the top and never reports `following`/`paused`.
+	 */
+	tail = true;
 
 	private buffer: string[] = [];
 	private label = "";
@@ -66,16 +71,21 @@ export class LinePane {
 		return Math.max(0, this.buffer.length - this.visible);
 	}
 
-	/** Open the pane on a row, reset to the tail. */
-	open(id: string, source: PaneSource): void {
+	/** Open the pane on a row, reset to the tail for a log, or to the top for prose. */
+	open(id: string, source: PaneSource, tail = true): void {
 		this.id = id;
 		this.buffer = [];
 		this.label = "";
 		this.subtitle = undefined;
 		this.more = false;
 		this.scroll = 0;
-		this.follow = true;
+		this.tail = tail;
+		this.follow = tail;
 		this.update(source);
+		if (!tail) {
+			this.follow = false;
+			this.scroll = 0;
+		}
 	}
 
 	/** Close the pane and drop its buffer. */
@@ -87,6 +97,7 @@ export class LinePane {
 		this.more = false;
 		this.scroll = 0;
 		this.follow = true;
+		this.tail = true;
 	}
 
 	/**
@@ -127,7 +138,7 @@ export class LinePane {
 		const parts: string[] = [];
 		if (this.subtitle) parts.push(this.subtitle);
 		if (this.more && this.buffer.length > 0) parts.push(`showing last ${this.buffer.length} lines`);
-		if (this.buffer.length > 0) parts.push(this.follow ? "following" : "paused");
+		if (this.tail && this.buffer.length > 0) parts.push(this.follow ? "following" : "paused");
 		return parts.join(" · ");
 	}
 

package/lib/tui/tool.ts

@@ -200,18 +200,29 @@ export function earlierHint(theme: Theme, hidden: number, label: string): string
 /** The row renderer a {@link TailResult} list uses: the extension's row grammar at a width. */
 export type TailRowLine<Row> = (row: Row, width: number, theme: Theme) => string;
 
-/** What a {@link TailResult} draws: the caller's rows plus a hidden count, or a bounded tail. */
+/** One group of rows inside a {@link TailResult}, under an optional faint heading. */
+export interface TailSection<Row> {
+	/** A faint heading above the rows, e.g. `Claims`; omit for the block's primary list. */
+	label?: string;
+	rows: readonly Row[];
+	more: number;
+	rowLine: TailRowLine<Row>;
+}
+
+/** What a {@link TailResult} draws: the caller's rows plus a hidden count, a headed row list, or a bounded tail. */
 export type TailResultInput<Row> =
 	| { kind: "list"; rows: readonly Row[]; more: number; rowLine: TailRowLine<Row> }
+	| { kind: "sections"; sections: readonly TailSection<Row>[] }
 	| { kind: "lines"; lines: readonly string[]; earlier: number; earlierLabel: string };
 
 /**
  * The transcript result block a tool that lists rows or tails output shares.
  *
  * One leading blank line per the block grammar, then either the caller's rows
- * (already ordered and capped) with a "more" note, or the themed tail with an
- * "earlier" note. The caller owns the row renderer, so the extension's own row
- * grammar — a peer-session tag, a status glyph — stays with its vocabulary.
+ * (already ordered and capped) with a "more" note, one headed group of rows per
+ * section, or the themed tail with an "earlier" note. The caller owns the row
+ * renderer, so the extension's own row grammar — a peer-session tag, a status
+ * glyph — stays with its vocabulary.
  */
 export class TailResult<Row> implements Component {
 	private input: TailResultInput<Row>;
@@ -239,6 +250,14 @@ export class TailResult<Row> implements Component {
 			if (input.more > 0) lines.push(clip(`  ${overflowHint(this.theme, input.more)}`, w));
 			return lines;
 		}
+		if (input.kind === "sections") {
+			for (const section of input.sections) {
+				if (section.label) lines.push(clip(paint(this.theme, "faint", section.label), w));
+				for (const row of section.rows) lines.push(section.rowLine(row, w, this.theme));
+				if (section.more > 0) lines.push(clip(`  ${overflowHint(this.theme, section.more)}`, w));
+			}
+			return lines;
+		}
 		if (input.earlier > 0) lines.push(clip(earlierHint(this.theme, input.earlier, input.earlierLabel), w));
 		for (const line of input.lines) lines.push(this.theme.fg("toolOutput", clip(line, w)));
 		return lines;

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);overflow:auto;min-height:0}
+.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>`;
 }
 
 /**

package/lib/web/runtime.ts

@@ -10,10 +10,16 @@
 /** localStorage key for the browser's explicit light/dark choice, shared by both surfaces. */
 export const WEB_THEME_STORAGE_KEY = "pi-web-theme";
 
+/**
+ * Where both routers serve {@link THEME_JS}. `docHead` emits the same path, so
+ * the script tag and the route cannot drift apart.
+ */
+export const THEME_JS_PATH = "/theme.js";
+
 /**
  * A tiny head script that applies the saved theme before the body is painted,
- * so an explicit choice does not flash the system theme on load. Served as
- * `/theme.js` and shared by both pages.
+ * so an explicit choice does not flash the system theme on load. Served at
+ * {@link THEME_JS_PATH} and shared by both pages.
  */
 export const THEME_JS = `(function(){try{var t=localStorage.getItem("${WEB_THEME_STORAGE_KEY}");if(t==="light"||t==="dark")document.documentElement.setAttribute("data-theme",t);}catch(e){}})();`;
 
@@ -67,52 +73,124 @@ export const THEME_TOGGLE_JS = String.raw`(function () {
   }
 })();`;
 
+/** Options for {@link dialogScript}. */
+export interface DialogOptions {
+	/** Id of the dialog root: the element carrying `.bf-dialog` and `hidden`. */
+	dialogId: string;
+	/** Id of the dialog's own close button, when the markup has one. */
+	closeId?: string;
+	/** Id of the page's trigger button, when the dialog opens from one. */
+	triggerId?: string;
+	/** Property to expose on `window`, so the page can open and close it. */
+	globalName?: string;
+}
+
+/** Everything inside a dialog that can take focus, in DOM order. */
+const FOCUSABLE =
+	'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
 /**
- * The `?` keyboard sheet's wiring, shared by both clients.
- *
- * It owns the sheet's pointer behavior — the page's trigger button, the sheet's
- * own close button, and a click on the backdrop — and nothing else: each page
- * keeps its own keyboard policy in its keydown handler, because the two differ
- * (the review peels `Esc` through a composer first), and calls in through
- * `window.bfKeys`.
+ * The wiring every modal in the kit shares: open and close, the backdrop, the
+ * `Tab` trap, `Esc`, and focus returning to whatever opened it.
  *
- * `triggerId` is the page's own shortcut button, since browse opens the sheet
- * from `#keys-open` and review from `#shortcuts`. The sheet's ids are the fixed
- * contract in `keysSheet` (`lib/web/markup.ts`).
+ * A dialog is modal before this script runs too — `aria-modal` and `hidden` are
+ * in the markup — so a page without JavaScript still shows it closed rather
+ * than half-open.
  *
- * Value-only: the open state is the dialog's own `hidden` attribute, so this
- * module holds nothing.
+ * Value-only: the open state is the dialog's own `hidden` attribute, and the
+ * element that opened it lives in this script's closure.
  */
-export function keysDialogScript(triggerId: string): string {
+export function dialogScript(options: DialogOptions): string {
+	const trigger = options.triggerId ? `document.getElementById("${options.triggerId}")` : "null";
+	const closer = options.closeId ? `document.getElementById("${options.closeId}")` : "null";
+	const expose = options.globalName
+		? `window.${options.globalName} = {
+    open: function () { toggle(true); },
+    toggle: toggle,
+    close: function () { toggle(false); },
+    isOpen: isOpen
+  };`
+		: "";
 	return `(function () {
   "use strict";
-  var dialog = document.getElementById("keys-dialog");
+  var dialog = document.getElementById("${options.dialogId}");
   if (!dialog) return;
+  var opener = null;
 
   function isOpen() {
     return !dialog.hidden;
   }
+  // A button inside a closed dialog has no boxes, so the rects are the test that
+  // survives a hidden attribute, a collapsed panel, and a stylesheet swap alike.
+  function focusables() {
+    return Array.prototype.filter.call(dialog.querySelectorAll('${FOCUSABLE}'), function (node) {
+      return node.getClientRects && node.getClientRects().length > 0;
+    });
+  }
   function toggle(force) {
     var open = force === undefined ? dialog.hidden : force;
+    if (open === isOpen()) return;
     dialog.hidden = !open;
     if (open) {
-      var close = document.getElementById("keys-close");
-      if (close && close.focus) close.focus();
+      opener = document.activeElement;
+      var first = focusables()[0];
+      if (first) first.focus();
+    } else if (opener && opener.focus) {
+      opener.focus();
+      opener = null;
     }
   }
 
-  var trigger = document.getElementById("${triggerId}");
+  var trigger = ${trigger};
   if (trigger) trigger.addEventListener("click", function () { toggle(); });
-  var closer = document.getElementById("keys-close");
+  var closer = ${closer};
   if (closer) closer.addEventListener("click", function () { toggle(false); });
   dialog.addEventListener("click", function (event) {
     if (event.target === dialog) toggle(false);
   });
 
-  window.bfKeys = {
-    toggle: toggle,
-    close: function () { toggle(false); },
-    isOpen: isOpen
-  };
+  // Tab cycles inside the dialog: leaving it would put focus behind the scrim,
+  // where the page looks inert but is not.
+  dialog.addEventListener("keydown", function (event) {
+    if (event.key !== "Tab") return;
+    var nodes = focusables();
+    if (nodes.length === 0) { event.preventDefault(); return; }
+    var first = nodes[0];
+    var last = nodes[nodes.length - 1];
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  });
+
+  // Capture, so Esc closes the dialog before a page handler peels another layer.
+  document.addEventListener("keydown", function (event) {
+    if (event.key !== "Escape" || !isOpen()) return;
+    toggle(false);
+    event.preventDefault();
+    event.stopPropagation();
+  }, true);
+
+  ${expose}
 })();`;
 }
+
+/**
+ * The `?` keyboard sheet's wiring, shared by both clients.
+ *
+ * `triggerId` is the page's own shortcut button, since browse opens the sheet
+ * from `#keys-open` and review from `#shortcuts`. The sheet's ids are the fixed
+ * contract in `keysSheet` (`lib/web/markup.ts`), and the page's keydown handler
+ * calls in through `window.bfKeys`.
+ */
+export function keysDialogScript(triggerId: string): string {
+	return dialogScript({
+		dialogId: "keys-dialog",
+		closeId: "keys-close",
+		triggerId,
+		globalName: "bfKeys",
+	});
+}

package/lib/web/tokens.ts

@@ -21,12 +21,11 @@ interface ThemeJson {
 const DARK = darkTheme as unknown as ThemeJson;
 const LIGHT = lightTheme as unknown as ThemeJson;
 
-/** Web custom property -> Bytefly theme var. `--accent-soft` is derived. */
+/** Web custom property -> Bytefly theme var. `--accent-soft`, `--on-accent`, `--scrim`,
+ * and `--shadow` are derived, so no appearance-only colour enters the kit. */
 const VAR_TOKENS: ReadonlyArray<readonly [string, string]> = [
 	["--canvas", "canvas"],
 	["--surface", "canvasSubtle"],
-	["--surface-raised", "selectionBg"],
-	["--selected", "selectionBg"],
 	["--border", "borderMuted"],
 	["--border-strong", "border"],
 	["--text", "text"],
@@ -90,19 +89,34 @@ function rgba(hex: string, alpha: number): string {
 	return `rgba(${r},${g},${b},${alpha})`;
 }
 
+/**
+ * Overlays are not palette entries: a scrim dims what is behind it and a shadow
+ * lifts a panel off it, so each appearance needs its own alpha rather than the
+ * theme's colours.
+ */
+const OVERLAYS: Record<"dark" | "light", { scrim: string; shadow: string }> = {
+	dark: { scrim: "rgba(0,0,0,.5)", shadow: "0 8px 24px rgba(0,0,0,.4)" },
+	light: { scrim: "rgba(15,23,42,.3)", shadow: "0 8px 24px rgba(15,23,42,.14)" },
+};
+
 /** The full custom-property set for one appearance. */
-function paletteOf(theme: ThemeJson, accentAlpha: number): Record<string, string> {
+function paletteOf(theme: ThemeJson, appearance: "dark" | "light", accentAlpha: number): Record<string, string> {
 	const palette: Record<string, string> = {};
 	for (const [token, name] of VAR_TOKENS) palette[token] = theme.vars[name];
 	palette["--accent-soft"] = rgba(palette["--accent"] ?? "#000000", accentAlpha);
+	// A label on the accent fill is the canvas colour: a light blue button takes dark
+	// text, and the same derivation gives white on the light theme's darker blue.
+	palette["--on-accent"] = palette["--canvas"];
+	palette["--scrim"] = OVERLAYS[appearance].scrim;
+	palette["--shadow"] = OVERLAYS[appearance].shadow;
 	for (const [token, name] of SYNTAX_TOKENS) palette[token] = resolve(theme, theme.colors[name] ?? "");
 	return palette;
 }
 
 /** Every token value per appearance, for tests and for building the CSS. */
 export const WEB_THEME_TOKENS: { dark: Record<string, string>; light: Record<string, string> } = {
-	dark: paletteOf(DARK, 0.15),
-	light: paletteOf(LIGHT, 0.1),
+	dark: paletteOf(DARK, "dark", 0.15),
+	light: paletteOf(LIGHT, "light", 0.1),
 };
 
 /** `a{color:var(--tok-keyword)}…` for each syntax token. */
@@ -125,4 +139,6 @@ export const WEB_THEME_CSS = `:root{${declarations(WEB_THEME_TOKENS.dark)};${SCA
 :root[data-theme="light"]{${declarations(WEB_THEME_TOKENS.light)};color-scheme:light}
 :root[data-theme="dark"]{color-scheme:dark}
 @media (prefers-color-scheme:light){:root:not([data-theme]){${declarations(WEB_THEME_TOKENS.light)};color-scheme:light}}
-${SYNTAX_RULES}`;
+${SYNTAX_RULES}
+/* Paper is white: print the light palette whatever the screen is showing. */
+@media print{:root{${declarations(WEB_THEME_TOKENS.light)};color-scheme:light}}`;