@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/lib/session-roster.ts

@@ -4,7 +4,7 @@
  * The Team tab lists teammates, and `session-bus` owns those records. Neither
  * extension may import the other, and the board must keep working when the bus is
  * not loaded — so the records are read where the bus already put them,
- * `<agentDir>/session-bus/<repo-key>/`, as files rather than through its code. The
+ * `<agent-dir>/session-bus/<repo-key>/`, as files rather than through its code. The
  * directory names, the record fields this reader trusts, and the liveness rule live
  * here once, and `session-bus` imports them, so a layout change cannot land in one
  * copy and not the other.
@@ -158,6 +158,48 @@ async function mailCount(dir: string, stem: string): Promise<number> {
 	}
 }
 
+/**
+ * One session's own label, found by the id it belongs to.
+ *
+ * The record is filed under the repository's key, which a caller without a board store
+ * would have to resolve with git first — and a footer asking for a name that may not
+ * exist should not cost two subprocesses at every session start. So the bus root is
+ * walked instead and the record is matched on its id: a session id belongs to one
+ * session, so the first record that names it is the answer wherever the bus filed it.
+ *
+ * Every miss is ordinary: a machine with no bus, or with records for other sessions
+ * only, answers `undefined` rather than an error.
+ */
+export async function readSessionLabel(agentDir: string, id: string): Promise<string | undefined> {
+	const root = join(agentDir, BUS_DIR_NAME);
+	let keys: string[];
+	try {
+		keys = await readdir(root);
+	} catch {
+		return undefined;
+	}
+	for (const key of keys) {
+		const dir = join(root, key, SESSIONS_DIR_NAME);
+		let names: string[];
+		try {
+			names = await readdir(dir);
+		} catch {
+			continue;
+		}
+		for (const name of names) {
+			if (!name.endsWith(".json")) continue;
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(await readFile(join(dir, name), "utf-8"));
+			} catch {
+				continue;
+			}
+			if (isSessionPayload(parsed) && parsed.id === id) return parsed.label;
+		}
+	}
+	return undefined;
+}
+
 /**
  * Every session the bus has recorded for one repository, or `undefined` when the bus
  * has never been used here.

package/lib/session-tool.ts

@@ -2,7 +2,7 @@
  * The `session` tool, as the extensions that are not `session-bus` call it.
  *
  * `board` and `team` are the user's surface for the team; the bus is the transport
- * underneath, and neither may import it (`test/structure.test.ts`). So the one place
+ * underneath, and neither may import it (`test/boundaries.test.ts`). So the one place
  * that turns a call into a typed answer lives here, next to the tool's name in
  * `lib/tool-names.ts` — two copies would be two copies of the details-shape
  * knowledge, and a bus that renamed a field would be broken in one of them.
@@ -59,9 +59,10 @@ export const TEAM_JOIN_REQUEST = "my-pi-agent/team-join/request";
  * What a join asks for.
  *
  * `label` is the name to be on the team as; without one the bus settles its own. `name`
- * is the separate question of whether that label also becomes Pi's session name — the
- * footer and `/resume` — and it is opt-in, because a join is not a rename: only
- * `/team join <label>` means "call me this from now on".
+ * is the separate question of whether that label also becomes Pi's session name — what
+ * `/resume` lists — and it is opt-in, because a join is not a rename: only
+ * `/team join <label>` means "call me this from now on". The footer needs no opt-in: it
+ * draws the label itself, so a plain join moves what the bar names this session.
  */
 export interface TeamJoinInput {
 	label?: string;

package/lib/stray-fields.ts

@@ -18,6 +18,8 @@
  * Value-only, as `lib/` must be: the tables are the callers'.
  */
 
+import { listOf } from "./format.ts";
+
 /** The fields each action reads, keyed in the order the actions are documented. */
 export type ActionFields = Readonly<Record<string, readonly string[]>>;
 
@@ -38,8 +40,11 @@ export function strayField(action: string, args: Record<string, unknown>, fields
 	const named = (field: string): string => {
 		const taking = Object.keys(fields).filter((candidate) => fields[candidate]?.includes(field));
 		if (taking.length === 0) return `${field} belongs to no action`;
-		const verbs = taking.map((one) => `\`${one}\``).join(" and ");
-		return `${verbs} ${taking.length === 1 ? "takes" : "take"} ${stray.length === 1 ? "it" : field}`;
+		const verbs = taking.map((one) => `\`${one}\``);
+		// Two read as "a and b"; three or more take the serial comma, or the list stops saying
+		// where one verb ends and the next begins.
+		const list = verbs.length === 2 ? verbs.join(" and ") : listOf(verbs, "and");
+		return `${list} ${taking.length === 1 ? "takes" : "take"} ${stray.length === 1 ? "it" : field}`;
 	};
 	return `${action} does not act on ${stray.join(", ")}: ${stray.map(named).join("; ")}.`;
 }

package/lib/tool-names.ts

@@ -17,11 +17,12 @@ export const TODO_TOOL = "todo";
 export const GOAL_TOOL = "goal";
 
 /**
- * The `enter_plan_mode` tool. `plan` registers it, and `goal` offers the same
- * phase to the user, so the name is shared: the request channel and the
- * registration probe both look it up.
+ * The `plan` tool. `plan` registers it and `goal` offers the same phase to the user,
+ * so the name is shared: the request channel and the registration probe both look
+ * it up. Its actions are the planning verbs, so one name replaces the five tools
+ * that used to spell them.
  */
-export const PLAN_ENTER_TOOL = "enter_plan_mode";
+export const PLAN_TOOL = "plan";
 
 /** The `subagent` tool, which plan mode pins to read-only delegation. */
 export const SUBAGENT_TOOL = "subagent";
@@ -52,12 +53,6 @@ export const SUBAGENT_READ_ONLY_PARAM = "readOnly";
  */
 export const BOARD_TOOL = "board";
 
-/**
- * The one `board` action that reads. Plan mode admits it and refuses the rest, which
- * is the distinction the tool's `readOnlyHint` cannot carry: the same tool writes.
- */
-export const BOARD_READ_ACTION = "list";
-
 /**
  * The `read_doc` tool. `file-read` registers it, and the plan, rewind, and
  * subagent reader lists carry the name, so the document reader is one reader

package/lib/tui/README.md

@@ -111,17 +111,32 @@ clipped mid-word at the widths the screen runs at.
 
 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, `screenHint` / Pi's `keyHint` for the hint row, and
-`screenFooter` for the hint row with its blank and closing rule.
+token named inline; a theme swap must re-skin every surface. The role table is
+the one place a Pi token is named, its tool vocabulary (`toolTitle`,
+`toolOutput`) included, so a renderer draws a tool block the way it draws a
+list. Use the shared `selectionMarker`, `GLYPHS`, `SEPARATORS`, and `STATUS_KEYS`
+instead of retyping 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
-hint row colors by role, not by taste: `accent` for the screen's primary action,
-`warning` for one that discards state (a revert, a kill, a stop, a clear, a
-forget), and `error` for one that ends the session. Keys that navigate, scroll,
-or select stay dim, so a colored key is one worth a second thought.
+hint row colors by role, not by taste — `ScreenHint.color` is a `TuiRole`:
+`accent` for the screen's primary action, `warn` for one that discards state (a
+revert, a kill, a stop, a clear, a forget), and `bad` for one that ends the
+session. Keys that navigate, scroll, or select stay `faint`, so a colored key is
+one worth a second thought.
+
+## A hue identifies, a verdict judges
+
+`ok` / `warn` / `bad` say how something *is*, and a surface that shows them is
+making a judgement. `hue1`…`hue5` — blue, purple, pink, green, amber — say only
+which category a row belongs to, which is what a table or a bar needs to be
+told apart at a glance. They are the same tokens in places (green is `success`,
+amber is `warning`), so the two vocabularies do not mix on one surface: a screen
+that paints hues keeps its verdicts to the gauge, a status word, or a feedback
+line, and a hue never lands in a slot that also carries a judgement. Color is
+redundant there — the label, the order, and the printed number already say what
+the hue repeats — so nothing may be encoded by hue alone.
 
 ## Width is columns
 

package/lib/tui/chrome.ts

@@ -16,11 +16,12 @@
  * in, and the viewport options are explicit.
  */
 
-import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import type { Theme } 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";
+import { paint, type TuiRole } from "./tokens.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -61,15 +62,15 @@ export function viewportRows(source: ViewportRowsSource | undefined, options: Vi
 }
 
 /**
- * One key-hint entry: plain dim text, or text in a chosen semantic color so a
- * primary action (approve, submit) stands out from the scroll hints.
+ * One key-hint entry: plain faint text, or text in a chosen role so a primary
+ * action (approve, submit) stands out from the scroll hints.
  */
-export type ScreenHint = string | { text: string; color?: ThemeColor };
+export type ScreenHint = string | { text: string; color?: TuiRole };
 
 /**
  * A key-hint footer indented by `indent` columns (default `BODY_INDENT`, which
- * hangs it under a screen's title rule), joined with ` · `. Plain hints are dim;
- * an object hint uses its color (dim when omitted). Hints are added while they
+ * hangs it under a screen's title rule), joined with ` · `. Plain hints are
+ * `faint`; an object hint names a role (`faint` when omitted). Hints are added while they
  * fit, so a narrow terminal drops whole keys instead of truncating one in half.
  * The first hint is always kept; the result is clipped to `width`.
  */
@@ -78,8 +79,8 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[], ind
 	// Keep a column for the hint itself, however deep the caller indents.
 	const lead = " ".repeat(Math.max(0, Math.min(Math.floor(indent), target - 1)));
 	const render = (hint: ScreenHint): string =>
-		typeof hint === "string" ? theme.fg("dim", hint) : theme.fg(hint.color ?? "dim", hint.text);
-	const separator = theme.fg("dim", SEPARATORS.item);
+		typeof hint === "string" ? paint(theme, "faint", hint) : paint(theme, hint.color ?? "faint", hint.text);
+	const separator = paint(theme, "faint", SEPARATORS.item);
 	const kept: ScreenHint[] = [];
 	for (const hint of hints) {
 		const candidate = [...kept, hint].map(render).join(separator);
@@ -196,16 +197,16 @@ export function toolDetails<T extends object>(details: unknown): T | undefined {
 	return Object.keys(details).length > 0 ? (details as T) : undefined;
 }
 
-/** Minimal editor theme for an extension-owned inline editor, on semantic tokens. */
+/** Minimal editor theme for an extension-owned inline editor, on semantic roles. */
 export function editorTheme(theme: Theme): EditorTheme {
 	return {
-		borderColor: (text) => theme.fg("borderMuted", text),
+		borderColor: (text) => paint(theme, "rule", text),
 		selectList: {
-			selectedPrefix: (text) => theme.fg("accent", text),
-			selectedText: (text) => theme.fg("accent", text),
-			description: (text) => theme.fg("muted", text),
-			scrollInfo: (text) => theme.fg("dim", text),
-			noMatch: (text) => theme.fg("warning", text),
+			selectedPrefix: (text) => paint(theme, "accent", text),
+			selectedText: (text) => paint(theme, "accent", text),
+			description: (text) => paint(theme, "meta", text),
+			scrollInfo: (text) => paint(theme, "faint", text),
+			noMatch: (text) => paint(theme, "warn", text),
 		},
 	};
 }

package/lib/tui/cursor.ts

@@ -20,6 +20,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
 import { viewportRows, type ViewportRowsSource } from "./chrome.ts";
 import { GLYPHS } from "./glyphs.ts";
+import { paint } from "./tokens.ts";
 
 /**
  * Rows that fit for a list of `itemCount`, reserving one extra line when the
@@ -76,11 +77,11 @@ export function wheelDelta(event: TuiMouseEvent): number | undefined {
 
 /** The `❯ ` selection marker (accent) or a same-width blank. */
 export function selectionMarker(theme: Theme, selected: boolean): string {
-	return selected ? theme.fg("accent", `${GLYPHS.prompt} `) : "  ";
+	return selected ? paint(theme, "accent", `${GLYPHS.prompt} `) : "  ";
 }
 
 /**
- * One dim, two-space-indented range row: `showing A–B of N` by default, or
+ * One faint, two-space-indented range row: `showing A–B of N` by default, or
  * `line A–B of N` for a log pane. Clipped to `width`.
  */
 export function formatRange(
@@ -90,7 +91,7 @@ export function formatRange(
 ): string {
 	const label = range.label ?? "showing";
 	const text = `  ${label} ${range.start + 1}–${range.end} of ${range.total}`;
-	return truncateToWidth(theme.fg("dim", text), Math.max(1, width));
+	return truncateToWidth(paint(theme, "faint", text), Math.max(1, width));
 }
 
 /**
@@ -247,6 +248,20 @@ export function isCloseKey(data: string): boolean {
 	return matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"));
 }
 
+/** Shift+Tab arrives as this sequence on terminals without the Kitty protocol. */
+export const SHIFT_TAB = "\u001b[Z";
+
+/**
+ * Whether `data` is Shift+Tab, in either encoding.
+ *
+ * `matchesKey` decodes the Kitty and modifyOtherKeys forms but not the legacy
+ * `\u001b[Z` one, so every screen or editor that binds Shift+Tab needs both tests;
+ * this is that one test.
+ */
+export function isShiftTab(data: string): boolean {
+	return data === SHIFT_TAB || matchesKey(data, Key.shift("tab"));
+}
+
 /**
  * The next scroll offset for a standard navigation key, or `undefined` when
  * `data` is not a navigation key.

package/lib/tui/glyphs.ts

@@ -8,6 +8,7 @@
  */
 
 import { keyText, type Theme } from "@earendil-works/pi-coding-agent";
+import { paint } from "./tokens.ts";
 
 /**
  * Leading glyphs for status chips, footer segments, and transcript rails.
@@ -50,6 +51,7 @@ export const GLYPHS = {
 	prev: "‹",
 	next: "›",
 	update: "↑",
+	autoMode: "▶",
 	prompt: "❯",
 } as const;
 
@@ -82,25 +84,25 @@ export const STATUS_KEYS = {
  */
 export const EXPAND_KEYBINDING = "app.tools.expand";
 
-/** The bound expand key, styled dim, or `""` when the binding is unknown. */
+/** The bound expand key, in the faint role, or `""` when the binding is unknown. */
 export function expandKey(theme: Theme): string {
 	const key = keyText(EXPAND_KEYBINDING);
-	return key ? theme.fg("dim", key) : "";
+	return key ? paint(theme, "faint", key) : "";
 }
 
 /**
- * Pi's key-hint format: the key dim, its description muted. An unbound key
+ * Pi's key-hint format: the key faint, its description meta. An unbound key
  * (`""`) yields `""`, so a hint never prints a stray description.
  */
 export function keyHintText(theme: Theme, key: string, description: string): string {
-	return key ? theme.fg("dim", key) + theme.fg("muted", ` ${description}`) : "";
+	return key ? paint(theme, "faint", key) + paint(theme, "meta", ` ${description}`) : "";
 }
 
 /**
- * The built-in-style expand affordance: a muted `(ctrl+o to expand)` with the
- * key in dim. Degrades to `(to expand)` when the binding is unknown.
+ * The built-in-style expand affordance: a meta `(ctrl+o to expand)` with the
+ * key in faint. Degrades to `(to expand)` when the binding is unknown.
  */
 export function expandHint(theme: Theme): string {
 	const hint = keyHintText(theme, keyText(EXPAND_KEYBINDING), "to expand)");
-	return theme.fg("muted", "(") + (hint || theme.fg("muted", "to expand)"));
+	return paint(theme, "meta", "(") + (hint || paint(theme, "meta", "to expand)"));
 }

package/lib/tui/tokens.ts

@@ -5,9 +5,16 @@
  * A component names a role (`title`, `meta`, `bad`) and the active theme
  * supplies the color, so switching themes re-skins every surface without a
  * component changing. The mapping is deliberately indirect: Pi's token set is
- * closed, so the kit only ever references it, never a literal color.
+ * closed, so the kit only ever references it, never a literal color — and this
+ * table is the one place it does, tool vocabulary included, so a remap here
+ * reaches every surface the kit and the renderers draw.
  *
  * Value-only: one frozen lookup table and pure helpers.
+ *
+ * Two vocabularies live here and they do not mix: `ok`/`warn`/`bad` are verdicts —
+ * they say how something *is* — and `hue1`…`hue5` are categories, which say only
+ * "this is not those". A surface that shows hues keeps its verdicts to the places
+ * that earn one, because a reader cannot tell a borrowed green from a judgement.
  */
 
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
@@ -35,7 +42,24 @@ export type TuiRole =
 	/** Error. */
 	| "bad"
 	/** Neutral notice. */
-	| "info";
+	| "info"
+	/**
+	 * A category hue: identity, never a verdict.
+	 *
+	 * Blue, purple, pink, green, and amber are the shipped palette's five colourful
+	 * tokens, so a categorical surface reads as a chart. Green and amber are the same
+	 * tokens `ok` and `warn` resolve to — that is the cost of Pi's closed token set —
+	 * which is why a hue never appears in a slot that also carries a judgement.
+	 */
+	| "hue1"
+	| "hue2"
+	| "hue3"
+	| "hue4"
+	| "hue5"
+	/** A tool call's own name: the transcript block's only accent. */
+	| "toolTitle"
+	/** A tool result's body text. */
+	| "toolOutput";
 
 /** Role -> theme color. The single place the kit names a Pi token. */
 export const TUI_TOKENS: Readonly<Record<TuiRole, ThemeColor>> = {
@@ -50,6 +74,13 @@ export const TUI_TOKENS: Readonly<Record<TuiRole, ThemeColor>> = {
 	warn: "warning",
 	bad: "error",
 	info: "muted",
+	hue1: "accent",
+	hue2: "mdListBullet",
+	hue3: "mdCode",
+	hue4: "success",
+	hue5: "warning",
+	toolTitle: "toolTitle",
+	toolOutput: "toolOutput",
 };
 
 /** Paint `text` in a role's color. */

package/lib/tui/tool.ts

@@ -31,9 +31,9 @@ export interface ToolMessageResult {
 	isError?: boolean;
 }
 
-/** The bold tool name in Pi's tool-title token, the block's only accent. */
+/** The bold tool name in the toolTitle role, the block's only accent. */
 export function toolCallTitle(theme: Theme, name: string): string {
-	return theme.fg("toolTitle", theme.bold(name));
+	return paint(theme, "toolTitle", theme.bold(name));
 }
 
 /**
@@ -275,7 +275,7 @@ export class TailResult<Row> implements Component {
 			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)));
+		for (const line of input.lines) lines.push(paint(this.theme, "toolOutput", clip(line, w)));
 		return lines;
 	}
 }

package/lib/web/README.md

@@ -42,6 +42,27 @@ What stays page-side: what a status *says*. `paintStatus` owns the text, its too
 the `bf-status--<tone>` class; the board composes `live · 3m` and appends its own class.
 A shared runtime that also decided the wording would be a second copy of the page's voice.
 
+## One inline Markdown renderer, spliced in
+
+Two served pages read Markdown written by a model or a person: the plan review's document
+and the board's card notes. Both need the same two answers — what an inline token is, and
+which target a link may point at — so `markdown.ts` holds one body of each and exports
+`INLINE_MARKDOWN_JS` for a bundle to splice. The review page's block half
+([`../../extensions/plan/web-markdown.ts`](../../extensions/plan/web-markdown.ts)) calls
+`renderInline` for the text inside a block; the board calls it for each note. A page that
+writes its own is how one of them starts accepting a `javascript:` target the other refuses.
+
+The renderer appends a text node or one of four atoms — `code`, `strong`, `em`, `a` — and
+never parses markup, so the board's rule that a stored field is never `innerHTML` holds with
+Markdown in play. A link is made only when `safeHref` allows the target: `http`, `https`, or
+`mailto`, no credentials, and no protocol-relative or disguised relative target, resolved
+against the page's own URL at call time.
+
+The body is JavaScript on purpose, like the runtime's: no annotation survives into the
+string, and no backtick or `${` may appear in one. It is the inline half only — a card note
+is one sanitized line, so inline is the whole of it, while blocks, tables, and fenced code
+stay the review page's own half.
+
 ## Name a class once, in a table
 
 A page's document is TypeScript and its client is a string inside a template literal, so

package/lib/web/components.ts

@@ -28,6 +28,8 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-btn:disabled{opacity:.5;cursor:default}
 .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}
+/* A field the card carries rather than a state it is in: the same pill, worn quietly. */
+.bf-chip--outline{color:var(--muted);border:1px solid currentColor;border-radius:var(--radius-pill);padding:2px 10px}
 .bf-chip--success{color:var(--success)}
 .bf-chip--warn{color:var(--warn)}
 .bf-chip--danger{color:var(--danger)}
@@ -35,7 +37,7 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-segmented__item{appearance:none;border:0;border-radius:0;background:transparent;color:var(--text);font:var(--fs-xs) var(--font-ui);padding:5px var(--space-3);cursor:pointer}
 .bf-segmented__item+.bf-segmented__item{border-left:1px solid var(--border)}
 .bf-segmented__item:hover{color:var(--accent);text-decoration:none}
-.bf-segmented__item[aria-current="page"],.bf-segmented__item[aria-pressed="true"]{background:var(--accent-soft);color:var(--accent)}
+.bf-segmented__item[aria-current="page"],.bf-segmented__item[aria-selected="true"],.bf-segmented__item[aria-pressed="true"]{background:var(--accent-soft);color:var(--accent)}
 .bf-input{border:0;background:transparent;color:var(--text);font:var(--fs-sm) var(--font-mono);width:100%;outline:none}
 .bf-field{display:flex;align-items:center;gap:var(--space-1);background:var(--canvas);border:1px solid var(--border);border-radius:var(--radius-md);padding:var(--space-1) var(--space-2);color:var(--muted);font-size:var(--fs-sm)}
 /* The field is the control: ringing the input inside it drew a border within a border. */
@@ -73,6 +75,8 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .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)}
+/* One line under the table, for a rule that is not a key: what an open dialog keeps. */
+.bf-keys__note{margin:0;padding:0 var(--space-4) var(--space-4);color:var(--muted);font-size:var(--fs-xs)}
 .bf-kbd{display:inline-block;min-width:20px;padding:1px 6px;border:1px solid var(--border);border-bottom-width:2px;border-radius:var(--radius-sm);background:var(--surface);color:var(--text);font:var(--fs-xs) var(--font-mono);text-align:center}
 .bf-tree{font-family:var(--font-mono);font-size:var(--fs-sm);overflow-x:auto}
 .bf-tree ul{list-style:none;margin:0;padding-left:14px}

package/lib/web/index.ts

@@ -8,6 +8,7 @@ export * from "./base.ts";
 export * from "./client-runtime.ts";
 export * from "./components.ts";
 export * from "./layout.ts";
+export * from "./markdown.ts";
 export * from "./markup.ts";
 export * from "./names.ts";
 export * from "./runtime.ts";

package/lib/web/markdown.ts

@@ -0,0 +1,83 @@
+/**
+ * Inline Markdown, for every served page: one renderer and one link policy.
+ *
+ * Two pages read Markdown written by a model or a person — the plan review's document and
+ * the board's card notes — and each needs the same two answers: what an inline token is,
+ * and which target a link may point at. A second copy of either is how one page starts
+ * accepting a `javascript:` target the other refuses, so the body lives here and each page
+ * splices it into its own bundle.
+ *
+ * The renderer appends **text nodes and four elements only** — `code`, `strong`, `em`, and
+ * `a` — so plan, comment, and note text never becomes markup and no page needs `innerHTML`.
+ * A link is made only for a target `safeHref` allows: `http`, `https`, or `mailto`, no
+ * credentials, and no protocol-relative or disguised relative target.
+ *
+ * It is the inline half only. A card note is one sanitized line, so inline is the whole of
+ * it; the review page's blocks, tables, fenced code, and lists are its own half, and they
+ * call `renderInline` for the text inside each.
+ *
+ * The body is JavaScript: no annotation survives into a string, and no backtick or `${`
+ * may appear in one. `base` is the page's own URL at call time, which is what makes a
+ * target that only looks relative land as text.
+ */
+export const INLINE_MARKDOWN_JS = String.raw`  // A link is rendered only for an http(s) or mailto target. Resolving against
+  // the review origin is what catches a target that only looks relative: the
+  // URL parser strips a tab or newline, so "/\t/evil.com" is cross-origin once
+  // it is parsed, and a disguised target must stay text.
+  function safeHref(url, base) {
+    var trimmed = String(url).trim();
+    if (!trimmed || /^\/\//.test(trimmed)) return null;
+    var resolved;
+    try { resolved = new URL(trimmed, base); } catch (error) { return null; }
+    if (resolved.protocol === "mailto:") return trimmed;
+    if (resolved.protocol !== "http:" && resolved.protocol !== "https:") return null;
+    if (resolved.username || resolved.password) return null;
+    if (resolved.origin === new URL(base).origin) return resolved.href;
+    return /^https?:\/\//i.test(trimmed) ? resolved.href : null;
+  }
+
+  // Inline token order matters: code, emphasis, and links are matched before a
+  // bare URL, so a URL inside a link target or a code span is never re-split.
+  var INLINE = /(\x60[^\x60]+\x60|\*\*[^*]+\*\*|\*[^*]+\*|\[[^\]]+\]\([^)]+\)|(?:https?:\/\/|www\.)[^\s<]+)/g;
+
+  function renderInline(container, text) {
+    String(text).split(INLINE).forEach(function (part) {
+      if (!part) return;
+      var match;
+      if ((match = /^\x60([^\x60]+)\x60$/.exec(part))) {
+        var code = el("code"); code.textContent = match[1]; container.appendChild(code); return;
+      }
+      if ((match = /^\*\*([^*]+)\*\*$/.exec(part))) {
+        var strong = el("strong"); strong.textContent = match[1]; container.appendChild(strong); return;
+      }
+      if ((match = /^\*([^*]+)\*$/.exec(part))) {
+        var em = el("em"); em.textContent = match[1]; container.appendChild(em); return;
+      }
+      if ((match = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(part))) {
+        var href = safeHref(match[2], location.href);
+        if (!href) { container.appendChild(document.createTextNode(part)); return; }
+        var link = el("a"); link.textContent = match[1]; link.href = href; link.target = "_blank"; link.rel = "noreferrer noopener";
+        container.appendChild(link); return;
+      }
+      // GFM extended autolink: a bare http(s) or www. URL in running text.
+      if ((match = /^(?:https?:\/\/|www\.)[^\s<]+$/.exec(part))) {
+        var url = match[0].replace(/[.,;:!?*_~]+$/, "");
+        while (url.charAt(url.length - 1) === ")" && (url.match(/\(/g) || []).length < (url.match(/\)/g) || []).length) {
+          url = url.slice(0, -1).replace(/[.,;:!?*_~]+$/, "");
+        }
+        var dot = url.indexOf(".");
+        var target = /^www\./i.test(url) ? "http://" + url : url;
+        var safe = dot > 0 && /\.[^./]/.test(url.slice(dot)) ? safeHref(target, location.href) : null;
+        if (safe) {
+          var auto = el("a");
+          auto.textContent = url;
+          auto.href = safe;
+          auto.target = "_blank";
+          auto.rel = "noreferrer noopener";
+          container.appendChild(auto);
+          return;
+        }
+      }
+      container.appendChild(document.createTextNode(part));
+    });
+  }`;

package/lib/web/markup.ts

@@ -219,7 +219,7 @@ export interface KeyHint {
  * for the sheet, `#keys-close` for its own close button — and the trigger button
  * is the page's own concern, since the two pages name it differently.
  */
-export function keysSheet(rows: readonly KeyHint[]): string {
+export function keysSheet(rows: readonly KeyHint[], note?: string): string {
 	const kbd = (key: string): string => `<kbd class="bf-kbd">${escapeHtml(key)}</kbd>`;
 	const body = rows
 		.map((row) => {
@@ -231,6 +231,7 @@ export function keysSheet(rows: readonly KeyHint[]): string {
 <div class="bf-dialog__panel" role="dialog" aria-modal="true" aria-labelledby="keys-title">
 <div class="bf-dialog__head"><h2 id="keys-title">Keyboard shortcuts</h2><span class="bf-spacer"></span><button type="button" class="bf-btn" id="keys-close">Close</button></div>
 <dl class="bf-keys">${body}</dl>
+${note === undefined ? "" : `<p class="bf-keys__note">${escapeHtml(note)}</p>`}
 </div>
 </div>`;
 }

package/lib/web/runtime.ts

@@ -156,20 +156,19 @@ export function dialogScript(options: DialogOptions): string {
   });
 
   // Tab cycles inside the dialog: leaving it would put focus behind the scrim,
-  // where the page looks inert but is not.
+  // where the page looks inert but is not. Every Tab is redirected rather than only
+  // the two that wrap, because the panel is the first node and the *container* of the
+  // others: a browser's own backwards step from the last node has no sibling to land
+  // on and walks out of the dialog instead.
   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();
-    }
+    var at = nodes.indexOf(document.activeElement);
+    var step = event.shiftKey ? -1 : 1;
+    var next = at === -1 ? (event.shiftKey ? nodes.length - 1 : 0) : (at + step + nodes.length) % nodes.length;
+    event.preventDefault();
+    nodes[next].focus();
   });
 
   // Capture, so Esc closes the dialog before a page handler peels another layer.