@gavin-hu/my-pi-agent 0.8.0 → 0.9.0

package/extensions/web-access/fetch/tool.ts

@@ -11,8 +11,9 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { formatTokens } from "../../../lib/format.ts";
-import { reuseText } from "../../../lib/tui.ts";
-import { SEPARATORS } from "../../../lib/ui.ts";
+import { reuseText } from "../../../lib/tui/chrome.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { SEPARATORS } from "../../../lib/tui/glyphs.ts";
 import { charLength } from "../text.ts";
 import { oneLine } from "../transcript.ts";
 import { createPageCache, type PageCache } from "./cache.ts";
@@ -204,9 +205,9 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 		renderCall(args, theme, context) {
 			const { url, find, startIndex } = args as WebFetchArgs;
 			const text = reuseText(context?.lastComponent);
-			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("accent", oneLine(url ?? ""));
-			if (find?.length) line += theme.fg("dim", ` find ${find.map((f) => `"${oneLine(f)}"`).join(", ")}`);
-			else if (startIndex) line += theme.fg("dim", ` (from ${startIndex})`);
+			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "accent", oneLine(url ?? ""));
+			if (find?.length) line += paint(theme, "faint", ` find ${find.map((f) => `"${oneLine(f)}"`).join(", ")}`);
+			else if (startIndex) line += paint(theme, "faint", ` (from ${startIndex})`);
 			text.setText(line);
 			return text;
 		},
@@ -216,21 +217,21 @@ export function registerFetchTool(pi: ExtensionAPI, deps: FetchToolDeps = {}): v
 			const page = result.details as FetchResponse | undefined;
 			if (page?.error) {
 				const message = oneLine(page.error);
-				text.setText(theme.fg("error", message.startsWith("Error:") ? message : `Error: ${message}`));
+				text.setText(paint(theme, "bad", message.startsWith("Error:") ? message : `Error: ${message}`));
 				return text;
 			}
 			if (!page || result.isError) {
 				const first = result.content[0];
 				const message = oneLine(first?.type === "text" ? first.text : "Fetch failed");
-				text.setText(theme.fg("error", message.startsWith("Error:") ? message : `Error: ${message}`));
+				text.setText(paint(theme, "bad", message.startsWith("Error:") ? message : `Error: ${message}`));
 				return text;
 			}
 
 			const label = oneLine(page.title || page.finalUrl);
-			let line = theme.fg("muted", label);
-			if (page.matches.length > 0) line += theme.fg("dim", `${SEPARATORS.item}${page.matches.length} match(es)`);
-			else line += theme.fg("dim", `${SEPARATORS.item}${formatTokens(page.totalChars)} chars`);
-			if (page.cached) line += theme.fg("dim", " (cached)");
+			let line = paint(theme, "meta", label);
+			if (page.matches.length > 0) line += paint(theme, "faint", `${SEPARATORS.item}${page.matches.length} match(es)`);
+			else line += paint(theme, "faint", `${SEPARATORS.item}${formatTokens(page.totalChars)} chars`);
+			if (page.cached) line += paint(theme, "faint", " (cached)");
 			text.setText(line);
 			return text;
 		},

package/extensions/web-access/search/tool.ts

@@ -10,8 +10,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadSearchConfig } from "../config.ts";
 import { oneLine } from "../transcript.ts";
-import { reuseText } from "../../../lib/tui.ts";
-import { expandHint, SEPARATORS } from "../../../lib/ui.ts";
+import { reuseText } from "../../../lib/tui/chrome.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { expandHint, SEPARATORS } from "../../../lib/tui/glyphs.ts";
 import { formatResults } from "./format.ts";
 import { createThrottle, runSearch, type SearchDeps } from "./search.ts";
 import { resolveRequest, WebSearchOutput, WebSearchParams, type SearchResponse, type WebSearchArgs } from "./schema.ts";
@@ -68,8 +69,8 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 		renderCall(args, theme, context) {
 			const { query, maxResults } = args as WebSearchArgs;
 			const text = reuseText(context?.lastComponent);
-			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("accent", oneLine(query ?? ""));
-			if (maxResults) line += theme.fg("dim", ` (${maxResults} results)`);
+			let line = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "accent", oneLine(query ?? ""));
+			if (maxResults) line += paint(theme, "faint", ` (${maxResults} results)`);
 			text.setText(line);
 			return text;
 		},
@@ -80,11 +81,11 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 			if (!details || result.isError) {
 				const first = result.content[0];
 				const message = first?.type === "text" ? first.text : "Search failed";
-				text.setText(theme.fg("error", `Error: ${oneLine(message)}`));
+				text.setText(paint(theme, "bad", `Error: ${oneLine(message)}`));
 				return text;
 			}
 			if (details.provider === "none") {
-				text.setText(theme.fg("dim", `No results for "${oneLine(details.query)}".`));
+				text.setText(paint(theme, "faint", `No results for "${oneLine(details.query)}".`));
 				return text;
 			}
 
@@ -92,19 +93,21 @@ export function registerSearchTool(pi: ExtensionAPI, deps: SearchDeps = {}): voi
 			// A blank line separates the call header from the result body.
 			const lines: string[] = [
 				"",
-				theme.fg("dim", `via ${details.provider}${SEPARATORS.item}${count} result${count === 1 ? "" : "s"}`),
+				paint(theme, "faint", `via ${details.provider}${SEPARATORS.item}${count} result${count === 1 ? "" : "s"}`),
 			];
-			if (details.answer) lines.push(`${theme.fg("dim", "answer")} ${theme.fg("muted", oneLine(details.answer, 160))}`);
+			if (details.answer)
+				lines.push(`${paint(theme, "faint", "answer")} ${paint(theme, "meta", oneLine(details.answer, 160))}`);
 
 			const shown = options.expanded ? details.results : details.results.slice(0, 5);
-			const indent = theme.fg("dim", "   ");
+			const indent = paint(theme, "faint", "   ");
 			for (const [index, item] of shown.entries()) {
-				lines.push(`${theme.fg("accent", `${index + 1}.`)} ${theme.fg("muted", oneLine(item.title, 100))}`);
-				lines.push(`${indent}${theme.fg("dim", oneLine(item.url, 100))}`);
-				if (options.expanded && item.snippet) lines.push(`${indent}${theme.fg("muted", oneLine(item.snippet, 160))}`);
+				lines.push(`${paint(theme, "accent", `${index + 1}.`)} ${paint(theme, "meta", oneLine(item.title, 100))}`);
+				lines.push(`${indent}${paint(theme, "faint", oneLine(item.url, 100))}`);
+				if (options.expanded && item.snippet)
+					lines.push(`${indent}${paint(theme, "meta", oneLine(item.snippet, 160))}`);
 			}
 			const extra = count - shown.length;
-			if (extra > 0) lines.push(`${theme.fg("dim", `+${extra} more`)} ${expandHint(theme)}`);
+			if (extra > 0) lines.push(`${paint(theme, "faint", `+${extra} more`)} ${expandHint(theme)}`);
 			text.setText(lines.join("\n"));
 			return text;
 		},

package/extensions/wechat/README.md

@@ -252,8 +252,8 @@ status, which is what the old start/stop guidance used to do.
 | `outbound.ts` | Upload and send a local file: hash, encrypt, `getUploadUrl`, upload, `sendFileMessage`. |
 | `login.ts` | QR login state machine. |
 | `qrcode.ts` | QR matrix → Unicode half-block terminal lines. |
-| `login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`). |
-| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`) and the pure one-line/body renderers. |
+| `login-screen.ts` | The `/wechat login` screen (`ctx.ui.custom`), drawn from the `lib/tui/` kit (`titleRule`, `clip`, `isCloseKey`). |
+| `status-screen.ts` | The `/wechat` control screen (`ctx.ui.custom`) and the pure one-line/body renderers, drawn from the `lib/tui/` kit (`titleRule`, `keyValueRow`, `paint`). |
 | `config.ts` | The `wechat` section of `bytefly.json` loading and normalization. |
 | `credentials.ts` | `credentials.json` (`0600`, multi-account). |
 | `state.ts` | `state.json` (cursor, owner, per-peer tokens). |

package/extensions/wechat/index.ts

@@ -14,7 +14,8 @@
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 import { isExtensionEnabled } from "../../lib/env.ts";
-import { GLYPHS, STATUS_KEYS } from "../../lib/ui.ts";
+import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import { createBridge, type Bridge, type BridgeState } from "./bridge.ts";
 import { createFetchRunner, WechatClient } from "./client.ts";
 import { registerCommands, type CommandDeps } from "./commands.ts";
@@ -34,9 +35,9 @@ import { registerTools } from "./tools.ts";
 export function wechatChip(theme: Theme, state: BridgeState): string | undefined {
 	switch (state) {
 		case "running":
-			return theme.fg("success", `${GLYPHS.wechat} wechat`);
+			return paint(theme, "ok", `${GLYPHS.wechat} wechat`);
 		case "expired":
-			return theme.fg("error", `${GLYPHS.wechat} wechat expired`);
+			return paint(theme, "bad", `${GLYPHS.wechat} wechat expired`);
 		case "stopped":
 			return undefined;
 	}

package/extensions/wechat/login-screen.ts

@@ -7,8 +7,11 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, type Component, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import { screenHeader, screenHint } from "../../lib/tui.ts";
+import { type Component, visibleWidth } from "@earendil-works/pi-tui";
+import { screenHint } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { isCloseKey } from "../../lib/tui/cursor.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
 
 export interface LoginViewState {
 	/** Raw `get_qrcode_status` value, or `wait` before the first poll. */
@@ -51,7 +54,7 @@ export function loginBody(state: LoginViewState, width: number): string[] {
 			lines.push(state.url.slice(index, index + target));
 		}
 	}
-	return lines.map((line) => truncateToWidth(line, target));
+	return lines.map((line) => clip(line, target));
 }
 
 export interface LoginScreenOptions {
@@ -69,7 +72,7 @@ export class LoginScreenComponent implements Component {
 	constructor(private readonly options: LoginScreenOptions) {}
 
 	handleInput(data: string): void {
-		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+		if (isCloseKey(data)) {
 			this.options.onCancel();
 		}
 	}
@@ -81,7 +84,7 @@ export class LoginScreenComponent implements Component {
 		const target = Math.max(1, width);
 		const theme = this.options.theme;
 		return [
-			screenHeader(theme, target, "wechat · login"),
+			titleRule(theme, target, "wechat · login"),
 			"",
 			...loginBody(this.options.state(), target),
 			"",

package/extensions/wechat/status-screen.ts

@@ -10,8 +10,13 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { Key, matchesKey, truncateToWidth, type Component } from "@earendil-works/pi-tui";
-import { screenHeader, screenHint, type ScreenHint } from "../../lib/tui.ts";
+import type { Component } from "@earendil-works/pi-tui";
+import { screenHint, type ScreenHint } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { isCloseKey } from "../../lib/tui/cursor.ts";
+import { keyValueRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import type { BridgeStatus } from "./bridge.ts";
 import { peerLabel } from "./format.ts";
 import type { BotCredentials } from "./types.ts";
@@ -72,18 +77,32 @@ export function statusLine(view: StatusView): string {
 /** Label column width in the screen body. */
 const LABEL_WIDTH = 11;
 
-function row(theme: Theme, label: string, value: string): string {
-	return `  ${theme.fg("muted", label.padEnd(LABEL_WIDTH))}${value}`;
+/** One body row: a `meta` label column and a value in `valueRole`. */
+function row(theme: Theme, width: number, label: string, value: string, valueRole: TuiRole = "label"): string {
+	return keyValueRow(theme, width, { label, value, labelWidth: LABEL_WIDTH, labelRole: "meta", valueRole });
 }
 
-function connectionText(theme: Theme, connection: StatusConnection): string {
+/** The connection word, uncolored; {@link row} paints it. */
+function connectionText(connection: StatusConnection): string {
 	switch (connection) {
 		case "open":
-			return theme.fg("success", "open");
+			return "open";
 		case "expired":
-			return theme.fg("error", "expired");
+			return "expired";
 		case "closed":
-			return theme.fg("muted", "closed");
+			return "closed";
+	}
+}
+
+/** The design role the connection word is drawn in. */
+function connectionRole(connection: StatusConnection): TuiRole {
+	switch (connection) {
+		case "open":
+			return "ok";
+		case "expired":
+			return "bad";
+		case "closed":
+			return "meta";
 	}
 }
 
@@ -91,28 +110,28 @@ function connectionText(theme: Theme, connection: StatusConnection): string {
 export function statusBody(view: StatusView, theme: Theme, width: number): string[] {
 	const target = Math.max(1, width);
 	const lines = [
-		row(theme, "Account", view.account ?? theme.fg("muted", "not logged in")),
-		row(theme, "Connection", connectionText(theme, view.connection)),
+		row(theme, target, "Account", view.account ?? "not logged in", view.account ? "label" : "meta"),
+		row(theme, target, "Connection", connectionText(view.connection), connectionRole(view.connection)),
 	];
 	if (view.bridge) {
-		if (view.owner && view.owner !== view.account) lines.push(row(theme, "Owner", view.owner));
-		lines.push(row(theme, "Peers", String(view.peers)));
-		lines.push(row(theme, "Queued", String(view.queued)));
-		if (view.refused > 0) lines.push(row(theme, "Refused", String(view.refused)));
-		if (view.mediaDropped > 0) lines.push(row(theme, "Media", `${view.mediaDropped} dropped`));
-		if (view.promptPending) lines.push(row(theme, "Prompt", theme.fg("accent", "waiting for a reply")));
+		if (view.owner && view.owner !== view.account) lines.push(row(theme, target, "Owner", view.owner));
+		lines.push(row(theme, target, "Peers", String(view.peers), "meta"));
+		lines.push(row(theme, target, "Queued", String(view.queued), "meta"));
+		if (view.refused > 0) lines.push(row(theme, target, "Refused", String(view.refused), "meta"));
+		if (view.mediaDropped > 0) lines.push(row(theme, target, "Media", `${view.mediaDropped} dropped`, "meta"));
+		if (view.promptPending) lines.push(row(theme, target, "Prompt", "waiting for a reply", "accent"));
 	}
 	if (view.connection === "expired") {
 		lines.push("");
-		lines.push(`  ${theme.fg("error", "Session expired — press l to log in again.")}`);
+		lines.push(clip(`  ${paint(theme, "bad", "Session expired — press l to log in again.")}`, target));
 	} else if (view.connection === "closed" && view.account) {
 		lines.push("");
-		lines.push(`  ${theme.fg("muted", "Not connected — press l to log in again.")}`);
+		lines.push(clip(`  ${paint(theme, "meta", "Not connected — press l to log in again.")}`, target));
 	} else if (view.connection === "closed") {
 		lines.push("");
-		lines.push(`  ${theme.fg("muted", "Run /wechat login to connect an account.")}`);
+		lines.push(clip(`  ${paint(theme, "meta", "Run /wechat login to connect an account.")}`, target));
 	}
-	return lines.map((line) => truncateToWidth(line, target));
+	return lines;
 }
 
 export interface StatusScreenOptions {
@@ -140,7 +159,7 @@ export class StatusScreenComponent implements Component {
 	}
 
 	handleInput(data: string): void {
-		if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+		if (isCloseKey(data)) {
 			this.options.onClose("close");
 			return;
 		}
@@ -166,7 +185,7 @@ export class StatusScreenComponent implements Component {
 		const target = Math.max(1, width);
 		const theme = this.options.theme;
 		return [
-			screenHeader(theme, target, "wechat · control"),
+			titleRule(theme, target, "wechat · control"),
 			"",
 			...statusBody(this.options.view(), theme, target),
 			"",

package/extensions/wechat/tools.ts

@@ -11,7 +11,8 @@ import type { JsonValue } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { sanitizeLine } from "../../lib/format.ts";
-import { reuseText, toolDetails } from "../../lib/tui.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import type { Bridge } from "./bridge.ts";
 
 export const TOOL_NAME = "send_wechat";
@@ -85,7 +86,7 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 			const text = reuseText(context.lastComponent);
 			const body = (args as { text?: unknown }).text;
 			const label = context.argsComplete && typeof body === "string" ? sanitizeLine(body) : "…";
-			text.setText(theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + theme.fg("muted", label));
+			text.setText(theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "meta", label));
 			return text;
 		},
 
@@ -93,16 +94,16 @@ export function registerTools(pi: ExtensionAPI, deps: ToolDeps): void {
 			const text = reuseText(context.lastComponent);
 			const details = toolDetails<{ sent?: boolean; error?: string }>(result.details);
 			if (details?.sent) {
-				text.setText(theme.fg("success", "sent to WeChat owner"));
+				text.setText(paint(theme, "ok", "sent to WeChat owner"));
 				return text;
 			}
 			if (details?.error) {
-				text.setText(theme.fg("error", `Error: ${sanitizeLine(details.error)}`));
+				text.setText(paint(theme, "bad", `Error: ${sanitizeLine(details.error)}`));
 				return text;
 			}
 			// Pi's rejection result carries `{}`; show its message instead.
 			const first = result.content[0];
-			text.setText(first?.type === "text" ? first.text : theme.fg("error", "Error: send failed"));
+			text.setText(first?.type === "text" ? first.text : paint(theme, "bad", "Error: send failed"));
 			return text;
 		},
 	});

package/extensions/worktree/enter.ts

@@ -7,7 +7,7 @@ import { appendFileSync, existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isInside } from "../../lib/path.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { loadConfig, type WorktreeConfig } from "./config.ts";
 import { WorktreeCancelledError } from "./errors.ts";
 import {

package/extensions/worktree/index.ts

@@ -24,7 +24,7 @@ import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
-import { GLYPHS } from "../../lib/ui.ts";
+import { GLYPHS } from "../../lib/tui/glyphs.ts";
 import { canonicalize, checkCheckout, repoRoot, unlockWorktree } from "./git.ts";
 import { analyzeBashCommand, guardFileTool } from "./guard.ts";
 import {

package/extensions/worktree/runtime.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { STATUS_KEYS } from "../../lib/ui.ts";
+import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { ENV_ROOT } from "../../lib/env.ts";
 import { loadConfig, type WorktreeConfig } from "./config.ts";
 import type { WorktreeState } from "./state.ts";

package/lib/README.md

@@ -24,7 +24,7 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`interaction.ts`](./interaction.ts) | Turn-affinity prompt contract: the channel a remote adapter installs on `ctx.ui` under a string key, the `InteractionChannel` interface (`request` / `post` / `postFile`), and `remoteChannel` / `isRemoteTurn` / `supportsCustomUI` / `askHuman` (with an optional file/text preface) plus the shared “Other” label. |
 | [`git/`](./git/) | Shared git plumbing. [`git/runner.ts`](./git/runner.ts) is the `RunGit` seam (`createExecRunner` with timeout/env handling, `runGitOrThrow`, `GitError`); [`git/read.ts`](./git/read.ts) holds the read helpers (`repoRoot`, `repoRootFor`, `gitDir`, `revParse`, `hasCommits`, `currentBranch`); [`git/index.ts`](./git/index.ts) is the barrel. |
 | [`highlight.ts`](./highlight.ts) | First-party, escape-first syntax tokenizer (`detectLanguage`, `fenceLanguage`, `highlightLines`, `HighlightLanguage`, `TokenClass`) for js/ts, json, css, html, shell, python, java, yaml, and sql; shared by `file-browse` and plan's code blocks. |
-| [`list-cursor.ts`](./list-cursor.ts) | Scrollable-list behavior for the `/rewind`, `/bytefly`, `/todos`, and `/jobs` screens: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` state. |
+| [`tui/`](./tui/) | The Bytefly terminal design system shared by every interactive surface: [`tui/tokens.ts`](./tui/tokens.ts) (semantic role -> theme color, `paint`), [`tui/glyphs.ts`](./tui/glyphs.ts) (`GLYPHS`, `SEPARATORS`, `STATUS_KEYS`, `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, `BODY_INDENT` / `GLYPH_GAP` — the vocabulary both sides of a status must agree on), [`tui/chrome.ts`](./tui/chrome.ts) (`screenHint`, `dockListFrame` (the docked-list frame), `viewportRows`, `FULL_SCREEN_OVERLAY`, `reuseText`, `editorTheme`), [`tui/rules.ts`](./tui/rules.ts) (`plainRule` / `titleRule` / `centeredRule`), [`tui/rows.ts`](./tui/rows.ts) (`listRow`, `checkbox`, `chip`, `keyValueRow`, `emptyState`), [`tui/columns.ts`](./tui/columns.ts) (`splitRow`, `fitCells`, `flowCells`, `padTo`, `clip`), [`tui/gauge.ts`](./tui/gauge.ts) (`computeGauge`, `gaugeRole`, `gaugeBar`), [`tui/line-pane.ts`](./tui/line-pane.ts) (`LinePane`, the scrollable log/match pane), [`tui/status-controller.ts`](./tui/status-controller.ts) (`createStatusController`, the footer chips `job` and `watch` share), and [`tui/cursor.ts`](./tui/cursor.ts) (scroll and navigation: `fitRows`, `keepVisible`, `clampScroll`, `navIntent`, `navigateList`, `navigateScroll`, `wheelDelta`, `scrollList`, `isCloseKey`, `selectionMarker`, `formatRange`, and the `ListCursor` (by index) and `IdCursor` (by stable id) state). |
 | [`path.ts`](./path.ts) | `isInside` (string containment) plus `realPathOfNearest` / `isInsideReal` (symlink-aware): the containment predicates the file-browse, worktree, and doc guards share. |
 | [`pi-invocation.ts`](./pi-invocation.ts) | `getPiInvocation`: how to launch a nested `pi` process, shared by `subagent` and bytefly's doctor surface. |
 | [`policy.ts`](./policy.ts) | `createReadOnlyPolicy`: default-deny tool classification from `readOnlyHint` + explicit allow/deny. |
@@ -32,8 +32,6 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 | [`requirements.ts`](./requirements.ts) | Per-extension runtime prerequisite table plus a pure `probeExtension(seams)` over injected seams (exec, config reads, optional imports): bytefly's doctor surface reports on it and the extensions that own a dependency format their errors from it. |
 | [`shell.ts`](./shell.ts) | Shell escape rule shared by the worktree isolation guard and plan mode's read-only git guard: `SHELL_ESCAPABLE`, `isShellEscapable`, `hasShellEscape`. |
 | [`tool-names.ts`](./tool-names.ts) | Tool names and one parameter name that more than one extension must agree on, so an orchestrating `ctx.executeTool()` call or schema probe breaks the build on a rename. |
-| [`tui.ts`](./tui.ts) | Screen chrome: `screenHeader`, `screenHint`, `dockListFrame` (the shared docked-list assembly), `viewportRows`, and `FULL_SCREEN_OVERLAY`, plus `reuseText` (per-render `Text` reuse) and `editorTheme` (inline-editor theme). |
-| [`ui.ts`](./ui.ts) | Shared UI vocabulary: `GLYPHS`, `SEPARATORS`, `STATUS_KEYS` (`ctx.ui.setStatus` keys), `EXPAND_KEYBINDING` with `expandKey` / `expandHint`, and the transcript rail `BODY_INDENT` / `GLYPH_GAP`. |
 | [`web/`](./web/) | The Bytefly web brand system shared by the browser surfaces: [`web/tokens.ts`](./web/tokens.ts) (palette derived from the Bytefly terminal themes, scales, and the `tok-*` map), [`web/base.ts`](./web/base.ts), [`web/components.ts`](./web/components.ts), [`web/layout.ts`](./web/layout.ts), [`web/runtime.ts`](./web/runtime.ts) (`WEB_THEME_STORAGE_KEY`, `THEME_JS`, `THEME_TOGGLE_JS`), [`web/markup.ts`](./web/markup.ts), and the [`web/index.ts`](./web/index.ts) barrel. |
 
 ## Conventions
@@ -43,7 +41,12 @@ belongs in that extension instead — see `extensions/web-access/http.ts` and
 - **Inject the host seam.** Modules that need a host capability take a function
   (`RunGit`, `HttpRunner`) rather than the whole `ExtensionAPI`, so the logic is
   testable without a runtime.
-- **Constants that must agree across both sides live in `ui.ts`** — a glyph and
-  the `setStatus` key are one contract, not two literals. Tool names shared by
-  an orchestrating tool and the tool it calls — and parameter names one
-  extension probes on another — live in `tool-names.ts`.
+- **Constants that must agree across both sides live in `tui/glyphs.ts`** — a
+  glyph and the `setStatus` key are one contract, not two literals. Tool names
+  shared by an orchestrating tool and the tool it calls — and parameter names
+  one extension probes on another — live in `tool-names.ts`.
+- **A color is a role, not a token.** Draw through [`tui/tokens.ts`](./tui/tokens.ts)
+  (`paint(theme, role, text)`) so a theme swap re-skins every surface; the
+  primitives in `tui/` already do, and a new one should too. The one exception is
+  Pi's tool-rendering vocabulary (`toolOutput`, `toolTitle`), which stays direct:
+  those tokens style a tool block, and no role maps to them.

package/lib/requirements.ts

@@ -166,7 +166,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 		optional: [{ kind: "module", name: "unpdf", enables: "PDF text extraction in `web_fetch`", hint: pdfGuidance() }],
 	},
 	"file-browse": {
-		optional: [gitCheck("the branch chip")],
+		optional: [gitCheck("the branch chip and the diff view")],
 		notes: ["The default-browser opener (`open` / `xdg-open` / `cmd`) is best-effort; the URL is printed either way."],
 	},
 	document: {},
@@ -194,7 +194,7 @@ export const REQUIREMENTS: Readonly<Record<string, ExtensionRequirements>> = {
 	bytefly: {
 		configFiles: [SHARED_CONFIG_FILE],
 		notes: [
-			"TUI only for the header, footer, and turn rule; `/bytefly` (and the `/extensions` and `/doctor` aliases) prints a listing and report in RPC, JSON, and print modes.",
+			"TUI only for the header, footer, and turn rule; `/bytefly` prints a listing and `/bytefly doctor` the report in RPC, JSON, and print modes.",
 			"The panel writes extension enablement through Pi's own settings; project scope requires a trusted project.",
 			"`/bytefly`'s list screen and the proactive missing-prerequisite warning need an interactive UI.",
 		],

package/lib/{tui.ts → tui/chrome.ts}

@@ -18,7 +18,7 @@
 
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth, type EditorTheme, type OverlayOptions } from "@earendil-works/pi-tui";
-import { SEPARATORS } from "./ui.ts";
+import { SEPARATORS } from "./glyphs.ts";
 
 /**
  * `ctx.ui.custom` options that give a screen the whole terminal.
@@ -36,21 +36,6 @@ export const FULL_SCREEN_OVERLAY: { overlay: true; overlayOptions: OverlayOption
 	overlayOptions: { width: "100%", maxHeight: "100%", anchor: "top-left", margin: 0 },
 };
 
-/**
- * Top border with `label` centered-left, exactly `width` columns wide. When the
- * terminal is too narrow for the title and a border on each side, it degrades to
- * a plain rule rather than truncating the title into an ellipsis.
- */
-export function screenHeader(theme: Theme, width: number, label: string): string {
-	const text = ` ${label} `;
-	const prefix = "───";
-	if (width < visibleWidth(prefix) + visibleWidth(text) + 1) {
-		return theme.fg("borderMuted", "─".repeat(Math.max(0, width)));
-	}
-	const remaining = width - visibleWidth(prefix) - visibleWidth(text);
-	return theme.fg("borderMuted", prefix) + theme.fg("accent", text) + theme.fg("borderMuted", "─".repeat(remaining));
-}
-
 /** A row count, or a live getter so a screen re-sizes with the terminal. */
 export type ViewportRowsSource = number | (() => number | undefined);
 
@@ -105,12 +90,8 @@ export function screenHint(theme: Theme, width: number, hints: ScreenHint[]): st
  * the frame only places them.
  */
 export interface DockListFrame {
-	/** Semantic theme for the header rule and the hint row. */
-	theme: Theme;
-	/** Body width in columns. */
-	width: number;
-	/** The header label, e.g. `Extensions`. */
-	title: string;
+	/** The pre-rendered header line, usually `titleRule(theme, width, title)`. */
+	header: string;
 	/** A summary line under the header; a blank line follows it. */
 	summary?: string;
 	/** The list rows, or the screen's single empty-state line. */
@@ -124,18 +105,16 @@ export interface DockListFrame {
 }
 
 /**
- * Assemble a docked list screen: the `─` header rule, an optional summary and
- * its blank line, the body, an optional range row, optional detail rows, and
+ * Assemble a docked list screen: the caller's header rule, an optional summary
+ * and its blank line, the body, an optional range row, optional detail rows, and
  * the blank-line-padded key-hint footer.
  *
- * This is the convention the bytefly panel (`/bytefly`, and the `/extensions`
- * and `/doctor` aliases) shares with `/jobs` and `/todos`. `/rewind` (a blank
- * after the header and no blank before the hint) places its blanks differently,
- * so it stays hand-rolled rather than changing its output to fit this helper.
+ * This is the convention every docked list screen shares — the bytefly panel,
+ * `/jobs`, `/watch`, `/todos`, `/memory`, and `/rewind`. The header line is built
+ * by the caller (usually `titleRule`), so the frame never picks a rule style.
  */
 export function dockListFrame(frame: DockListFrame): string[] {
-	const width = Math.max(1, frame.width);
-	const lines: string[] = [screenHeader(frame.theme, width, frame.title)];
+	const lines: string[] = [frame.header];
 	if (frame.summary !== undefined) lines.push(frame.summary, "");
 	lines.push(...frame.body);
 	if (frame.range !== undefined) lines.push(frame.range);

package/lib/tui/columns.ts

@@ -0,0 +1,96 @@
+/**
+ * Width arithmetic for the terminal: justify, fit, pad, and clip lines.
+ *
+ * Every function works in terminal columns via `visibleWidth` /
+ * `truncateToWidth`, never string length, and every result fits the width it
+ * was given. Themed strings pass through unchanged except where a cell has to
+ * be clipped, so a color survives every cell that fits.
+ *
+ * Value-only: pure functions over their arguments.
+ */
+
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** A usable origin: terminal arithmetic starts from one column, never zero. */
+function columns(width: number): number {
+	return Math.max(1, Math.floor(width));
+}
+
+/** Clip a possibly-themed string to `width` columns, marking a cut with `ellipsis`. */
+export function clip(text: string, width: number, ellipsis = "…"): string {
+	return truncateToWidth(text, columns(width), ellipsis);
+}
+
+/** Pad `text` on the right to exactly `width` columns. Never truncates. */
+export function padTo(text: string, width: number): string {
+	const missing = columns(width) - visibleWidth(text);
+	return missing > 0 ? text + " ".repeat(missing) : text;
+}
+
+/**
+ * Left/right justify on one line: the left cell sits at the margin, the right
+ * cell at the edge, and at least `minGap` columns separate them.
+ *
+ * The right cell is the anchor — it is clipped only after the left cell has
+ * been clipped away — so a value at the end of a line (a model name, a metric)
+ * survives a tight terminal instead of vanishing. An empty right cell means a
+ * plain left-aligned line with no trailing spaces.
+ */
+export function splitRow(left: string, right: string, width: number, minGap = 1): string {
+	const w = columns(width);
+	if (!right) return clip(left, w);
+	const gap = Math.max(0, Math.floor(minGap));
+	const rightCell = clip(right, w);
+	const rightWidth = visibleWidth(rightCell);
+	const leftBudget = w - rightWidth - gap;
+	if (leftBudget <= 0) return rightCell;
+	return padTo(clip(left, leftBudget), w - rightWidth) + rightCell;
+}
+
+/**
+ * Join as many whole cells as fit, dropping trailing cells rather than
+ * clipping one in half. The first cell is always kept, so an over-wide line
+ * degrades to a clipped first cell instead of an empty one.
+ */
+export function fitCells(cells: readonly string[], width: number, separator = " "): string {
+	const w = columns(width);
+	const kept: string[] = [];
+	for (const cell of cells) {
+		const candidate = [...kept, cell].join(separator);
+		if (kept.length > 0 && visibleWidth(candidate) > w) break;
+		kept.push(cell);
+	}
+	return clip(kept.join(separator), w);
+}
+
+/**
+ * Lay atomic, already-themed cells onto lines no wider than `width`.
+ *
+ * Cells are never split: one that would not fit moves to the next line, and one
+ * wider than the whole width is clipped. Use this for a row of independent
+ * tokens (tabs, tags) where `fitCells`' single-line drop would lose one; unlike
+ * {@link fitCells} it may return several lines, and always returns one.
+ */
+export function flowCells(cells: readonly string[], width: number): string[] {
+	const w = columns(width);
+	const lines: string[] = [];
+	let current = "";
+	let currentWidth = 0;
+	for (const cell of cells) {
+		let text = cell;
+		let cellWidth = visibleWidth(cell);
+		if (cellWidth > w) {
+			text = truncateToWidth(cell, w);
+			cellWidth = visibleWidth(text);
+		}
+		if (currentWidth > 0 && currentWidth + cellWidth > w) {
+			lines.push(current);
+			current = "";
+			currentWidth = 0;
+		}
+		current += text;
+		currentWidth += cellWidth;
+	}
+	lines.push(current);
+	return lines;
+}