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

package/lib/session-tool.ts

@@ -0,0 +1,184 @@
+/**
+ * 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
+ * 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.
+ *
+ * There are two transports, and the difference is the context, not the caller's
+ * choice: `join` travels as an in-process request on `pi.events` because a *command*
+ * context has no `ctx.executeTool` — the same constraint `lib/plan-entry.ts` exists
+ * for — while `peers` and `send` are nested tool calls, which only ever run inside a
+ * tool. One function either way, so a caller never has to know which it is holding.
+ *
+ * Every function returns a result and none throws: "the bus is not loaded", "a plan
+ * is open", and "that label is taken" are all answers a caller reports, not reasons
+ * to abandon a board write or a card operation that has nothing to do with the bus.
+ *
+ * This module is the *caller* side only. Reading the bus's records from disk is
+ * `session-roster.ts`, which is what works when the bus is not loaded at all.
+ */
+
+import type { ExtensionAPI, ExtensionContext, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { messageOf } from "./errors.ts";
+import { watchingOf } from "./session-roster.ts";
+import { SESSION_TOOL } from "./tool-names.ts";
+
+/**
+ * The `session send` text limit, which is also the longest handoff or offer.
+ *
+ * It is copied from the bus's protocol rather than imported — the dependency runs one
+ * way — and it lives here so `team` and `board` clip to one number instead of two.
+ */
+export const MAX_MESSAGE_TEXT = 4_000;
+
+/** Whether a session is listening for mail, and whether it raises a turn. */
+export interface Watching {
+	armed: boolean;
+	wake: boolean;
+}
+
+/** One session the bus lists. */
+export interface Peer {
+	id: string;
+	label: string;
+	/** Absent when the record does not say, which is not the same as "not listening". */
+	listening?: boolean;
+}
+
+/** What a join did: the label it landed on, and whether mail will reach the session. */
+export type JoinResult = { ok: true; label: string; watching: Watching } | { ok: false; error: string };
+
+/** EventBus channel on which a caller asks `session-bus` to join the team for it. */
+export const TEAM_JOIN_REQUEST = "my-pi-agent/team-join/request";
+
+/** What a caller sends on {@link TEAM_JOIN_REQUEST}. */
+export interface TeamJoinRequest {
+	/** The caller's context; the bus starts and names through it. */
+	ctx: ExtensionContext;
+	/** What to join as and how to listen. */
+	input: { label?: string; wake?: boolean; listen?: boolean };
+	/** Called once, when the bus has answered. */
+	respond(result: JoinResult): void;
+}
+
+/** What a send did. */
+export type SendResult = { ok: true; delivered: string[] } | { ok: false; error: string };
+
+/** One nested call's answer: the details on success, the sentence on failure. */
+type Answer = { details: Record<string, unknown> } | { error: string };
+
+/**
+ * Call the `session` tool once.
+ *
+ * A nested call reports failure in its result rather than by rejecting; a rejection
+ * is still caught, because a bus that is not registered at all throws before the
+ * tool runs and the caller deserves the sentence rather than an exception.
+ */
+async function call(ctx: ExtensionToolContext, args: Record<string, unknown>): Promise<Answer> {
+	const outcome = await ctx.executeTool(SESSION_TOOL, args).catch((error: unknown) => ({
+		isError: true as const,
+		result: { content: [{ type: "text", text: messageOf(error) }], details: undefined },
+	}));
+	if (outcome.isError) return { error: nestedMessage(outcome.result) };
+	const details = outcome.result.details;
+	return { details: typeof details === "object" && details !== null ? (details as Record<string, unknown>) : {} };
+}
+
+/** The message a failed nested call carries, or a sentence that says only that it failed. */
+function nestedMessage(result: { content?: Array<{ type: string; text?: string }> } | undefined): string {
+	const text = result?.content?.find((block) => block.type === "text")?.text;
+	return text !== undefined && text !== "" ? text.replace(/^Error:\s*/, "") : "the session bus did not answer.";
+}
+
+/**
+ * How an extension joins the team, whatever kind of context it is holding.
+ *
+ * Two extensions ask — `board` when the page opens or a card is worked, `team` for
+ * `/team join` — and both hold a command or a tool context, so the request is the one
+ * transport that works from either.
+ */
+export interface TeamJoin {
+	/** Join the team, naming this session when `label` is given. Never throws. */
+	join(ctx: ExtensionContext, label?: string): Promise<JoinResult>;
+}
+
+/** The production join, bound to one extension's `pi`. */
+export function createTeamJoin(pi: Pick<ExtensionAPI, "events" | "getAllTools">): TeamJoin {
+	return {
+		join: (ctx, label) => join(pi, ctx, label === undefined ? {} : { label }),
+	};
+}
+
+/**
+ * Join the team: on the bus, named when a label is given, and listening for mail.
+ *
+ * One call for all three, because that is one act — see `join` in
+ * `extensions/session-bus` — and one transport for both kinds of caller: the request
+ * travels on `pi.events` and the bus answers it.
+ *
+ * With no bus loaded there is no listener, so the answer is the sentence the caller
+ * reports rather than a promise that never settles: the `session` tool's presence is
+ * the same check `lib/plan-entry.ts` makes, and the listener always answers.
+ */
+export async function join(
+	pi: Pick<ExtensionAPI, "events" | "getAllTools">,
+	ctx: ExtensionContext,
+	input: { label?: string; wake?: boolean; listen?: boolean } = {},
+): Promise<JoinResult> {
+	if (!pi.getAllTools().some((tool) => tool.name === SESSION_TOOL)) {
+		return { ok: false, error: "the session bus is not loaded" };
+	}
+	return new Promise<JoinResult>((resolve) => {
+		let settled = false;
+		const respond = (result: JoinResult): void => {
+			if (settled) return;
+			settled = true;
+			resolve(result);
+		};
+		pi.events.emit(TEAM_JOIN_REQUEST, { ctx, input, respond } satisfies TeamJoinRequest);
+	});
+}
+
+/**
+ * Every session the bus lists, or `undefined` when it cannot answer.
+ *
+ * Named `listPeers` rather than `peers` so it cannot be mistaken for a caller's own
+ * formatting helper — `wechat`'s doctor has one — and a caller reads the verb.
+ *
+ * A caller renders "the record does not say" differently from "nobody is here", so a
+ * failed read is not an empty list.
+ */
+export async function listPeers(ctx: ExtensionToolContext): Promise<Peer[] | undefined> {
+	const answer = await call(ctx, { action: "status" });
+	if ("error" in answer) return undefined;
+	const status = answer.details.status;
+	if (typeof status !== "object" || status === null) return undefined;
+	const sessions = (status as { sessions?: unknown }).sessions;
+	if (!Array.isArray(sessions)) return undefined;
+	const peers: Peer[] = [];
+	for (const entry of sessions) {
+		if (typeof entry !== "object" || entry === null) continue;
+		const { id, label, watching } = entry as Record<string, unknown>;
+		if (typeof id !== "string" || typeof label !== "string") continue;
+		const state = watchingOf(watching);
+		peers.push({ id, label, ...(state === undefined ? {} : { listening: state.armed }) });
+	}
+	return peers;
+}
+
+/** Send one message, and report the labels a message file was written for. */
+export async function send(
+	ctx: ExtensionToolContext,
+	input: { kind: "handoff" | "event"; to: string; text: string },
+): Promise<SendResult> {
+	const answer = await call(ctx, { action: "send", kind: input.kind, to: input.to, text: input.text });
+	if ("error" in answer) return { ok: false, error: answer.error };
+	const delivered = answer.details.delivered;
+	return {
+		ok: true,
+		delivered: Array.isArray(delivered) ? delivered.filter((label): label is string => typeof label === "string") : [],
+	};
+}

package/lib/spawn.ts

@@ -8,11 +8,14 @@
  *
  * IO is split from the decision: {@link spawnOptions} and {@link killPlan} are
  * pure and testable on every platform, while {@link defaultSpawn} and
- * {@link defaultKillTree} execute them. Value-only, like every `lib/` module:
- * no module state, and each caller keeps its own children.
+ * {@link defaultKillTree} execute them. The liveness pair — {@link isPidAlive}
+ * and {@link startTokenOf} — is here too, because asking whether a process is
+ * still the one a record named is the same question as killing it: `job` guards
+ * a reattached pid with it, and so does the session roster. Value-only, like
+ * every `lib/` module: no module state, and each caller keeps its own children.
  */
 
-import { spawn as nodeSpawn, spawnSync } from "node:child_process";
+import { execFileSync, spawn as nodeSpawn, spawnSync } from "node:child_process";
 import type { Readable } from "node:stream";
 
 /**
@@ -124,6 +127,37 @@ export function isPidAlive(pid: number, probe: KillProbe = process.kill): boolea
 	}
 }
 
+/** Whether a pid is still alive. */
+export type LivenessFn = (pid: number) => boolean;
+
+/**
+ * Best-effort OS start-time token for a pid, used to detect pid reuse.
+ *
+ * Returns undefined when the platform cannot provide one (for example Windows, or a
+ * process that is already gone), in which case callers fall back to liveness alone.
+ */
+export type StartTokenFn = (pid: number) => string | undefined;
+
+/**
+ * Default start-time token via `ps`. Undefined where `ps` is unavailable.
+ *
+ * It spawns a process, so a caller asks for it only where liveness alone cannot
+ * decide: a pid that is alive may be a different program than the one a record
+ * named, and nothing cheaper than the start time can tell them apart.
+ */
+export const startTokenOf: StartTokenFn = (pid) => {
+	try {
+		const out = execFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 2000,
+		});
+		const text = out.toString().trim();
+		return text || undefined;
+	} catch {
+		return undefined;
+	}
+};
+
 /** The host seams {@link applyKillPlan} runs through. */
 export interface KillSeams {
 	/** Signal one pid; throws when the pid is gone or not ours. */

package/lib/stray-fields.ts

@@ -0,0 +1,45 @@
+/**
+ * A field a tool call carries but its action does not act on.
+ *
+ * An action-shaped tool publishes one flat parameter object, so every field is
+ * offered to every action at once; that is harmless only while each action reads
+ * its own. A field that reaches an action which never reads it used to be dropped
+ * in silence — `board add` with `dependsOn` wrote the card without the link and
+ * answered success, and `team offer` with `to` broadcast to every live session
+ * while the caller believed it had named one. The caller could not tell what was
+ * recorded from what was ignored, and nothing in the result said which.
+ *
+ * So the table of what each action reads lives with the tool (`ACTION_FIELDS`),
+ * and this is the sentence a call is refused with: it names every stray field and
+ * the action that does take it, which makes the retry one call away. The table is
+ * keyed in the order the actions are documented, because that order is how the
+ * message lists the verbs that take a field.
+ *
+ * Value-only, as `lib/` must be: the tables are the callers'.
+ */
+
+/** The fields each action reads, keyed in the order the actions are documented. */
+export type ActionFields = Readonly<Record<string, readonly string[]>>;
+
+/**
+ * Why a call carries a field its action does not act on, or nothing when it is clean.
+ *
+ * `undefined` is not a stray: an optional field the caller left out was never passed,
+ * and a schema makes every unset one `undefined`.
+ */
+export function strayField(action: string, args: Record<string, unknown>, fields: ActionFields): string | undefined {
+	const mine = fields[action] ?? [];
+	const stray = Object.entries(args)
+		.filter(([field, value]) => value !== undefined && field !== "action" && !mine.includes(field))
+		.map(([field]) => field);
+	if (stray.length === 0) return undefined;
+	// One stray reads as "takes it"; several need their names, or the sentence stops
+	// saying which field goes where.
+	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}`;
+	};
+	return `${action} does not act on ${stray.join(", ")}: ${stray.map(named).join("; ")}.`;
+}

package/lib/tool-names.ts

@@ -4,8 +4,9 @@
  * Tool names are otherwise owned by the extension that registers the tool, and
  * no extension imports another's modules (see this directory's README). When an
  * orchestrating tool calls another extension's tool through `ctx.executeTool`,
- * or reads another extension's registered parameter schema, the shared name
- * lives here so a rename breaks the build on both sides instead of silently
+ * reads another extension's registered parameter schema, lists the name in a
+ * read-only policy, or passes it on a child's `--tools` allowlist, the shared
+ * name lives here so a rename breaks the build on both sides instead of silently
  * disabling the integration.
  */
 
@@ -31,9 +32,44 @@ export const SUBAGENT_TOOL = "subagent";
  */
 export const ASK_USER_QUESTION_TOOL = "ask_user_question";
 
+/**
+ * The `session` tool. `session-bus` registers it, and `team` calls it through
+ * `ctx.executeTool` to send a handoff, so a rename breaks both sides.
+ */
+export const SESSION_TOOL = "session";
+
 /**
  * Parameter on the `subagent` tool that forces every spawned agent to a
  * read-only tool set. Plan mode sets it on every call while planning, and
  * refuses a `subagent` whose schema does not declare it.
  */
 export const SUBAGENT_READ_ONLY_PARAM = "readOnly";
+
+/**
+ * The `board` tool: the shared feature list. Plan mode keeps it active because its
+ * `list` action is a read of the repository's cards, so the name is shared while the
+ * write actions stay the board's to refuse.
+ */
+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
+ * everywhere instead of three spellings.
+ */
+export const READ_DOC_TOOL = "read_doc";
+
+/**
+ * The `web_search` tool. `web-access` registers it; plan's and subagent's reader
+ * lists carry the name, so a rename cannot silently drop the web reader.
+ */
+export const WEB_SEARCH_TOOL = "web_search";
+
+/** The `web_fetch` tool, shared the same way as {@link WEB_SEARCH_TOOL}. */
+export const WEB_FETCH_TOOL = "web_fetch";

package/lib/tui/glyphs.ts

@@ -30,6 +30,7 @@ export const GLYPHS = {
 	jobsFailure: "✗",
 	stopped: "⊘",
 	browse: "◉",
+	board: "⊞",
 	delegation: "↳",
 	wechat: "✆",
 	gaugeFull: "▰",
@@ -56,10 +57,9 @@ export const GLYPHS = {
 /** Columns between a rail body glyph and its text. */
 export const GLYPH_GAP = 1;
 
-/** Padding used to join (`item`) or group (`group`) UI segments. */
+/** Padding used to join UI segments. */
 export const SEPARATORS = {
 	item: " · ",
-	group: ` ${GLYPHS.divider} `,
 } as const;
 
 /** `ctx.ui.setStatus` keys; one per extension that publishes a chip. */
@@ -71,6 +71,7 @@ export const STATUS_KEYS = {
 	watch: "watch",
 	watchMatches: "watch-matches",
 	browse: "browse",
+	board: "board",
 	rewind: "rewind",
 	agents: "agents",
 	wechat: "wechat",

package/lib/web/README.md

@@ -3,7 +3,7 @@
 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)).
+file browse ([`../../extensions/file-browse/view/styles.ts`](../../extensions/file-browse/view/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.
 
@@ -21,6 +21,47 @@ 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.
 
+## One browser runtime, spliced in
+
+Three surfaces render pages from a bundle held as a template literal, and each had written
+the same three helpers for itself: an element builder, a "did this key land in a field?"
+test, and a status line's paint. No type checker and no AST scan compares text inside a
+string, so the plan's `el(tag, className)` and the board's `el(tag, className, text)` were
+two builders, and the plan compared `INPUT` where the board lowercased the tag.
+
+`client-runtime.ts` holds one body of each, as ordinary TypeScript, and exports
+`CLIENT_RUNTIME_JS` — the four functions as source, in the order a client reads them. A
+page carries it the way it carries `plural` and its class table: the source crosses the
+boundary, and the page runs the function instead of a copy of it.
+
+The bodies are JavaScript on purpose — no annotation survives into the string, and no
+backtick or `${` may appear in one. The DOM is reached through `globalThis`, because this
+project compiles without a DOM lib; the cast names the guarantee the page makes.
+
+What stays page-side: what a status *says*. `paintStatus` owns the text, its tooltip, and
+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.
+
+## Name a class once, in a table
+
+A page's document is TypeScript and its client is a string inside a template literal, so
+the two halves cannot import from each other: a class name used to be a literal in each,
+and one assembled at runtime (`"board-card__reason" + kind`) could not be found by
+reading either half. That is how a class reaches a stylesheet with no rule behind it —
+an unstyled element, and nothing fails.
+
+So a page declares its vocabulary once, in a `ClassNames` table beside its own modules,
+and both halves read it: the document interpolates `${N.toolbar}`, the bundle carries
+`namesScript(table)`. A name is then a symbol, and a test can compare the set a page
+wears with the set its stylesheet draws, in both directions.
+
+`namesScript` is the boundary, and it throws rather than trusting a caller: a value must
+be `KEBAB` — lowercase, hyphenated — because the table is spliced into a template
+literal, and a backtick would end the string while `${` would interpolate at build time.
+The global it binds must be a JavaScript `IDENTIFIER`. The table's *keys* are the page's
+own English; its *values* are what CSS matches, and nothing else in the page may spell
+one.
+
 ## Color is a role
 
 `WEB_THEME_TOKENS` is derived from `themes/bytefly-dark.json` and
@@ -34,7 +75,10 @@ are computed rather than mapped:
 - `--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
+`--raised` is the one derived neutral: `--surface` mixed 6% (dark) or 3% (light)
+toward `--text`, for a block that has to read as a plane above the page rather than
+as an outline — the light step is smaller because a darker accent on a lighter step
+falls below AA. 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.
@@ -96,8 +140,17 @@ 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
+`docHead`, `brandLockup`, `markIcon`, `tabTitle`, `themeToggle`, `chip`, `button`, and
+`keysSheet` return strings. `docHead` links the mark as the tab icon — two SVG
+data URIs from the same blocks the lockup draws, the dark one plain and the light
+one behind `prefers-color-scheme` — because an icon is its own document and
+cannot read the page's tokens.
+
+`tabTitle` is where the three served pages' tab titles agree: `<page> · <subject> ·
+<count>`, the page's name lowercase and the same word its `brandLockup` carries, a part
+the page does not have left out rather than drawn empty. The board's count is live, so
+its page repaints the title on every frame and the body crosses into the bundle as
+`TAB_TITLE_JS`, the way `plural` does — one shape for the string, not two. 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.

package/lib/web/client-runtime.ts

@@ -0,0 +1,123 @@
+/**
+ * The browser runtime both page clients splice into their bundles: the element builder,
+ * the "is the user typing?" test, the status line, and the JSON POST.
+ *
+ * Two surfaces had written each of these for themselves, and because a bundle is a
+ * template literal no type checker and no AST scan ever compared them: the plan's
+ * `el(tag, className)` and the board's `el(tag, className, text)` were two builders, and
+ * the plan's `typing` compared `INPUT` where the board's lowercased the tag. Both are
+ * now one body, written here as real TypeScript, and each client carries the *source*
+ * (`CLIENT_RUNTIME_JS`) the same way it carries `plural` and the class table.
+ *
+ * The functions are plain JavaScript on purpose: their text is spliced into a bundle, so
+ * no annotation may survive into the string and no backtick or `${` may appear in a body.
+ * The DOM is reached through `globalThis`, because this project compiles without a DOM
+ * lib — the cast names the guarantee the page makes: it is a browser, and it has one.
+ */
+
+/**
+ * The pieces of a DOM node the runtime touches, and the ones a page client needs beyond
+ * it. The page supplies the real thing; this is the shape its bundle is typed against.
+ */
+export interface ClientNode {
+	className: string;
+	textContent: string | null;
+	title: string;
+	hidden: boolean;
+	href: string;
+	id: string;
+	style: { width: string };
+	type: string;
+	scrollTop: number;
+	contains(other: ClientNode | null): boolean;
+	focus(): void;
+	classList: { add(name: string): void; remove(name: string): void; toggle(name: string, on?: boolean): void };
+	setAttribute(name: string, value: string): void;
+	getAttribute(name: string): string | null;
+	removeAttribute(name: string): void;
+	appendChild(child: ClientNode): void;
+	remove(): void;
+	replaceChildren(): void;
+	querySelector(selector: string): ClientNode | null;
+	querySelectorAll(selector: string): ArrayLike<ClientNode>;
+	scrollIntoView?(options?: { block?: string }): void;
+	addEventListener(type: string, listener: (event: { target?: unknown }) => void): void;
+}
+
+/** What `document.createElement` has to answer for these helpers. */
+interface RuntimeDocument {
+	createElement(tag: string): ClientNode;
+}
+
+/**
+ * One element with an optional class and text.
+ *
+ * `text` is set as `textContent`, never parsed: a card title and a plan's prose are both
+ * model- or user-written, and the one property that cannot execute is the one to use.
+ */
+export function el(tag: string, className?: string, text?: string | null): ClientNode {
+	// Reached through `globalThis` and cast here, because this project compiles without a
+	// DOM lib; the cast names what the page guarantees — it is a browser, and it has one.
+	const node = (globalThis as unknown as { document: RuntimeDocument }).document.createElement(tag);
+	if (className) node.className = className;
+	if (text !== undefined && text !== null) node.textContent = String(text);
+	return node;
+}
+
+/**
+ * Whether a key event landed in a field, where every key is text rather than a shortcut.
+ *
+ * The tag is lowercased once, so a document parsed as XHTML (`tagName` upper case) and a
+ * page built by `createElement` (`tagName` lower case) both answer the same.
+ */
+export function typing(target: { tagName?: string; isContentEditable?: boolean }): boolean {
+	if (!target || !target.tagName) return target?.isContentEditable === true;
+	const tag = target.tagName.toLowerCase();
+	return tag === "input" || tag === "textarea" || tag === "select" || target.isContentEditable === true;
+}
+
+/**
+ * Paint a status line: its text, the same text as its tooltip, and its tone's class.
+ *
+ * The status slot is the page's own id, so the caller passes the node; what is shared is
+ * the rule that a tone is a `bf-status--*` class and that the text is also the title (a
+ * clamped line has no other way to be read).
+ */
+export function paintStatus(node: ClientNode, text: string, kind?: string): void {
+	node.textContent = text || "";
+	node.title = text || "";
+	node.className = kind ? "bf-status bf-status--" + kind : "bf-status";
+}
+
+/** One answer from the server: whether it accepted, its status, and its parsed body. */
+interface PostResult {
+	ok: boolean;
+	status: number;
+	body: unknown;
+}
+
+/**
+ * POST JSON and read the reply's body, whatever the status.
+ *
+ * A page that only honoured the happy path would report `server returned 409` where the
+ * server had said *why*, so the body is parsed on both branches and the caller decides.
+ */
+export function postJson(url: string, payload: unknown): Promise<PostResult> {
+	return fetch(url, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(payload),
+	}).then((response: { ok: boolean; status: number; json(): Promise<unknown> }) =>
+		response.json().then(
+			(body: unknown): PostResult => ({ ok: response.ok, status: response.status, body }),
+			(): PostResult => ({ ok: response.ok, status: response.status, body: null }),
+		),
+	);
+}
+
+/**
+ * The runtime, as a bundle receives it: four bodies, in the order a client reads them.
+ *
+ * `test` holds each to its module body and proves the string is safe to splice.
+ */
+export const CLIENT_RUNTIME_JS = [el, typing, paintStatus, postJson].map(String).join("\n\n");

package/lib/web/components.ts

@@ -18,6 +18,8 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .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:var(--on-accent)}
+.bf-btn--danger{border-color:var(--danger);color:var(--danger)}
+.bf-btn--danger:hover{border-color:var(--danger);background:var(--danger);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)}
@@ -36,6 +38,9 @@ export const WEB_COMPONENTS_CSS = `.bf-brand{display:inline-flex;align-items:cen
 .bf-segmented__item[aria-current="page"],.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. */
+.bf-field:focus-within{outline:var(--focus-ring) solid var(--accent);outline-offset:2px}
+.bf-field .bf-input:focus-visible{outline:none}
 .bf-textarea{width:100%;min-height:72px;padding:var(--space-2);font:inherit;color:var(--text);background:var(--canvas);border:1px solid var(--border);border-radius:var(--radius-md);resize:vertical}
 .bf-panel{min-width:0;overflow:auto;overscroll-behavior:contain}
 .bf-panel__summary{display:none}

package/lib/web/index.ts

@@ -1,12 +1,14 @@
 /**
  * The Bytefly web brand system: tokens, base rules, components, layout,
- * runtime, and markup atoms. Import from `lib/web/index.ts` rather than a
- * leaf module so the surface reads as one kit.
+ * runtime, markup atoms, and the class-name table a page's bundle carries. Import
+ * from `lib/web/index.ts` rather than a leaf module so the surface reads as one kit.
  */
 
 export * from "./base.ts";
+export * from "./client-runtime.ts";
 export * from "./components.ts";
 export * from "./layout.ts";
 export * from "./markup.ts";
+export * from "./names.ts";
 export * from "./runtime.ts";
 export * from "./tokens.ts";