pi-cliproxyapi 0.1.2 → 0.3.0

package/README.md

@@ -9,28 +9,44 @@ One `(endpoint, apiKey)` pair — every provider and model inherits it automatic
 
 ## Features
 
+- **Unified hub** — one `/cliproxy` overlay with **Models / Usage / Diagnostics** tabs (number hotkeys `1` `2` `3`) plus global actions: `r` refresh, `e` setup, `s` save
 - **Built-in provider routing** — whitelist which Anthropic / OpenAI / etc. models are available through the proxy
 - **Custom provider groups** — create named groups (e.g. `corp-glm`, `corp-gemini`) for proxy-only models with automatic metadata from [models.dev](https://models.dev)
-- **Exclusive model pool** — a model assigned to one group automatically disappears from others
-- **Per-account usage overlay** — colored quota bars, toggle disabled accounts, verbose errors — no LLM call
+- **Exclusive model pool** — a model assigned to one group automatically disappears from others, grouped by `owned_by` with type-to-filter (`/`)
+- **Live save state** — the header shows `● unsaved` while you edit and `✓ settings saved` after `s`, no console noise
+- **Per-account usage tab** — colored quota bars, toggle disabled accounts, verbose errors — no LLM call
 - **Setup wizard** — `/cliproxy-setup` configures endpoint, API key, provider prefix, and usage key interactively
 
 ## Commands
 
+Two commands; everything else lives inside the hub as tabs and actions.
+
 | Command | Description |
 | --- | --- |
-| `/cliproxy` | Interactive overlay — enable providers, toggle models, create custom groups |
+| `/cliproxy` | Hub overlay — **Models** / **Usage** / **Diagnostics** tabs plus global actions |
 | `/cliproxy-setup` | Configure endpoint, API key, provider prefix, usage key |
-| `/cliproxy-refresh` | Re-fetch upstream models, re-register providers |
-| `/cliproxy-list` | Read-only view of current configuration |
-| `/cliproxy-usage` | Per-account quota windows with progress bars (`d` = show disabled, `v` = verbose) |
-| `/cliproxy-doctor` | Connectivity, key resolution, discovery diagnostics |
+
+### The `/cliproxy` hub
+
+Global keys: `[` / `]` or `1` `2` `3` switch tabs · `r` refresh discovery + reapply · `e` setup · `s` save · `q` / `Esc` close.
+
+**Models tab** — three panels cycled with `Tab` / arrows:
+
+- **left** — every provider (built-in + custom). `+ new custom group…` is the last row.
+- **right top** — models assigned to the focused provider. `Enter` / `Space` removes one.
+- **right bottom** — available pool, grouped by upstream `owned_by`. `Enter` / `Space` attaches. Press `/` to filter the pool by id/name. A `⚠` marks an API mismatch (attach still allowed).
+
+Extra Models keys: `d` removes a custom group (with confirmation).
+
+**Usage tab** — per-account quota bars; `d` shows disabled accounts, `v` shows verbose errors.
+
+**Diagnostics tab** — connectivity, key resolution, and discovery shape.
 
 ## Prerequisites
 
 You need a running [CliProxyAPI](https://github.com/router-for-me/CLIProxyAPI) instance — this is the corporate LLM proxy that aggregates multiple providers behind a single OpenAI-compatible endpoint.
 
-For full functionality (`/cliproxy-usage`, enriched model metadata from [models.dev](https://models.dev)), also deploy the companion sidecar: **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)**. See [Deploying the sidecar](#deploying-the-sidecar-service) below.
+For full functionality (Usage tab, enriched model metadata from [models.dev](https://models.dev)), also deploy the companion sidecar: **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)**. See [Deploying the sidecar](#deploying-the-sidecar-service) below.
 
 ## Install
 
@@ -76,7 +92,7 @@ The plugin tries `GET <endpoint-origin>/.well-known/pi` first (requires the side
 The **[pi-cliproxyapi-wellknown](https://github.com/abix5/pi-cliproxyapi-wellknown)** sidecar runs alongside CliProxyAPI and provides:
 
 - `/.well-known/pi` — model discovery with metadata from [models.dev](https://models.dev) (context windows, costs, reasoning flags)
-- `/api/usage` — per-account quota windows used by `/cliproxy-usage`
+- `/api/usage` — per-account quota windows used by the hub Usage tab
 
 ```
 ┌──────────────┐     ┌───────────────────────────┐
@@ -134,16 +150,16 @@ Run `/cliproxy-setup` in Pi and enter:
 - **endpoint** — your public proxy URL ending with `/v1`
 - **apiKey** — CliProxyAPI bearer key
 - **providerPrefix** — short slug for custom provider names (e.g. `corp`, `myproxy`)
-- **usageKey** — same value as `PI_PLUGIN_USAGE_KEY` above (enables `/cliproxy-usage`)
+- **usageKey** — same value as `PI_PLUGIN_USAGE_KEY` above (enables the Usage tab)
 
 The sidecar is **optional for basic usage** — without it the plugin falls back to raw `/v1/models` with local heuristics. What changes:
 
 | | With sidecar | Without sidecar |
 | --- | --- | --- |
 | Model discovery | Enriched from [models.dev](https://models.dev) (real context windows, costs, reasoning) | Defaults: `contextWindow=128k`, `maxTokens=16k`, `cost=0`, `reasoning=false` |
-| `/cliproxy-usage` | Works — per-account quota bars | **Does not work** (no `/api/usage` endpoint) |
+| Usage tab | Works — per-account quota bars | **Does not work** (no `/api/usage` endpoint) |
 | Classification | Server-side, accurate | Local heuristics by `owned_by` |
-| `/cliproxy`, `/cliproxy-list`, `/cliproxy-doctor` | Work | Work |
+| `/cliproxy` hub | Works | Works (Usage tab shows an error) |
 
 ## Layout
 
@@ -151,15 +167,31 @@ The sidecar is **optional for basic usage** — without it the plugin falls back
 index.ts            ExtensionFactory entry point
 src/
   config.ts         ~/.config/pi-cliproxyapi/config.json
-  commands.ts       6 slash commands
+  commands.ts       2 slash commands (hub + setup)
   apply.ts          pi.registerProvider calls
   fetch-models.ts   well-known + /v1/models fallback
   fetch-usage.ts    /api/usage client with TTL cache
   compat.ts         baseUrl derivation, model classification
   conflicts.ts      read-only ~/.pi/{models,auth}.json scan
-  ui-picker.ts      overlay picker with collapsible provider groups
-  ui-usage.ts       ANSI-colored usage renderer
-  ui-overlay.ts     scrollable overlay shell with toggles
+  ui-frame.ts       single source of truth for overlay frames
   ui-setup.ts       setup wizard
+  ui-usage.ts       ANSI-coloured usage renderer
+  ui-hub/           the /cliproxy hub overlay
+    index.ts        public runHub entry
+    hub.ts          tabs, status header, global actions
+    types.ts        HubView contract
+    shell.ts        tab bar, status header, scroll/slice helpers
+    view-models.ts  three-panel picker (single pool ordering + filter)
+    view-usage.ts   usage tab (lazy fetch + d/v toggles)
+    view-diagnostics.ts  diagnostics tab
+  ui-picker/        picker building blocks reused by the Models view
+    types.ts        shared TS types
+    catalog.ts      build a model lookup from discovery
+    providers.ts    resolve the providers shown in the left panel
+    mutate.ts       attach / detach / claim + pool grouping + display order
+    render-text.ts  ANSI-aware pad / truncate
+    rows.ts         per-row renderers for left / right panels
+    prompt-confirm.ts    remove-group confirmation
+    prompt-name.ts       new-group name prompt
   log.ts            tagged logger
 ```

package/index.ts

@@ -6,8 +6,8 @@
  *   1. load ~/.config/pi-cliproxyapi/config.json (defaults if missing)
  *   2. fetch discovery (well-known → fall back to /v1/models)
  *   3. call pi.registerProvider for each enabled built-in + custom provider
- *   4. register slash commands /cliproxy /cliproxy-setup /cliproxy-refresh
- *      /cliproxy-list /cliproxy-usage /cliproxy-doctor
+ *   4. register slash commands /cliproxy and /cliproxy-setup
+ *      (refresh, usage, and diagnostics are tabs/actions inside the hub)
  *
  * All discovery + apply errors are logged but never abort extension load —
  * a missing/broken proxy must not prevent Pi from starting.
@@ -43,7 +43,7 @@ export default async function cliproxyapi(pi: ExtensionAPI): Promise<void> {
 		await applyAll(pi, cfg, discovery);
 	} catch (err) {
 		log.error("initial apply failed:", (err as Error).message);
-		// Commands stay registered; user can /cliproxy-doctor or /cliproxy-refresh.
+		// Commands stay registered; user can open /cliproxy and press r to refresh.
 	}
 
 	if (cfg.refreshIntervalMinutes > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cliproxyapi",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "type": "module",
   "description": "Pi extension for corporate management of model providers via a single CliProxyAPI endpoint",
   "license": "MIT",

package/src/apply.ts

@@ -37,6 +37,36 @@ export async function applyAll(
 	}
 
 	// -------- builtin providers (anthropic, openai, etc.)
+	const builtinByName = new Map<
+		string,
+		Array<{
+			id: string;
+			name: string;
+			reasoning: boolean;
+			contextWindow: number;
+			maxTokens: number;
+			cost: {
+				input: number;
+				output: number;
+				cacheRead: number;
+				cacheWrite: number;
+			};
+		}>
+	>();
+	for (const p of discovery.builtinProviders) {
+		builtinByName.set(
+			p.name,
+			p.models.map((m) => ({
+				id: m.id,
+				name: m.name,
+				reasoning: m.reasoning,
+				contextWindow: m.contextWindow,
+				maxTokens: m.maxTokens,
+				cost: m.cost,
+			})),
+		);
+	}
+
 	for (const [name, p] of Object.entries(cfg.builtinProviders)) {
 		if (!p?.enabled) {
 			report.skipped.push({ provider: name, reason: "disabled" });
@@ -46,7 +76,7 @@ export async function applyAll(
 			report.skipped.push({ provider: name, reason: "empty whitelist" });
 			continue;
 		}
-		let builtin: ReadonlyArray<{
+		let catalog: ReadonlyArray<{
 			id: string;
 			name: string;
 			api: Api;
@@ -56,19 +86,64 @@ export async function applyAll(
 			contextWindow: number;
 			maxTokens: number;
 			thinkingLevelMap?: any;
-		}>;
+		}> = [];
 		try {
-			builtin = getModels(name as any) as any;
+			catalog = getModels(name as any) as any;
 		} catch {
-			report.skipped.push({
-				provider: name,
-				reason: `pi-ai has no provider "${name}"`,
-			});
-			continue;
+			/* unknown provider in pi-ai catalog — keep going with proxy data */
 		}
-		const selected = builtin.filter(
-			(m) => p.models.includes(m.id) && proxyIds.has(m.id),
+		const catalogById = new Map(catalog.map((m) => [m.id, m]));
+		const proxyById = new Map(
+			(builtinByName.get(name) ?? []).map((m) => [m.id, m]),
 		);
+
+		interface MergedModel {
+			id: string;
+			name: string;
+			reasoning: boolean;
+			contextWindow: number;
+			maxTokens: number;
+			cost: any;
+			input: ("text" | "image")[];
+			api: Api;
+			thinkingLevelMap?: any;
+		}
+		const selected: MergedModel[] = [];
+		for (const id of p.models) {
+			if (!proxyIds.has(id)) continue;
+			const c = catalogById.get(id);
+			const px = proxyById.get(id);
+			if (c) {
+				selected.push({
+					id: c.id,
+					name: c.name,
+					reasoning: c.reasoning,
+					contextWindow: c.contextWindow,
+					maxTokens: c.maxTokens,
+					cost: c.cost,
+					input: c.input,
+					api: c.api,
+					thinkingLevelMap: c.thinkingLevelMap,
+				});
+				continue;
+			}
+			if (!px) continue;
+			// Catalog miss — fall back to proxy metadata. Pick API by provider name.
+			const api: Api =
+				name === "anthropic"
+					? "anthropic-messages"
+					: ((p.apiOverride as Api | undefined) ?? "openai-responses");
+			selected.push({
+				id: px.id,
+				name: px.name,
+				reasoning: px.reasoning,
+				contextWindow: px.contextWindow,
+				maxTokens: px.maxTokens,
+				cost: px.cost,
+				input: ["text"],
+				api,
+			});
+		}
 		if (selected.length === 0) {
 			report.skipped.push({
 				provider: name,

package/src/commands.ts

@@ -1,10 +1,8 @@
-// Slash commands.
-//   /cliproxy           — open the picker overlay
-//   /cliproxy-setup     — first-run / re-run setup wizard for endpoint+keys
-//   /cliproxy-refresh   — refetch discovery + re-apply
-//   /cliproxy-list      — show all upstream models in an overlay
-//   /cliproxy-usage     — fetch /api/usage and render in overlay
-//   /cliproxy-doctor    — connectivity + key-resolution diagnostics
+// Slash commands (2):
+//   /cliproxy         — open the hub (Models / Usage / Diagnostics + actions)
+//   /cliproxy-setup   — first-run / re-run wizard for endpoint+keys
+//
+// Refresh, usage, and diagnostics are now actions/tabs inside the hub.
 
 import type {
 	ExtensionAPI,
@@ -12,20 +10,16 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 
 import { applyAll } from "./apply.ts";
-import { loadConfig, resolveConfigValue, saveConfig } from "./config.ts";
-import { detectConflicts } from "./conflicts.ts";
-import { fetchDiscovery, PLUGIN_USER_AGENT } from "./fetch-models.ts";
-import { clearUsageCache, fetchUsage } from "./fetch-usage.ts";
-import { log } from "./log.ts";
-import { showOverlay } from "./ui-overlay.ts";
-import { runPicker } from "./ui-picker.ts";
+import { loadConfig, resolveConfigValue } from "./config.ts";
+import { fetchDiscovery } from "./fetch-models.ts";
+import { clearUsageCache } from "./fetch-usage.ts";
+import { runHub } from "./ui-hub/index.ts";
 import { runSetup } from "./ui-setup.ts";
-import { renderUsage } from "./ui-usage.ts";
 
 export function registerCommands(pi: ExtensionAPI): void {
 	pi.registerCommand("cliproxy", {
 		description:
-			"Pick which models to expose via the CliProxyAPI corporate proxy",
+			"Manage proxy models, usage, and diagnostics in one hub overlay",
 		handler: handleCliproxy.bind(null, pi),
 	});
 
@@ -34,27 +28,6 @@ export function registerCommands(pi: ExtensionAPI): void {
 			"Set endpoint, API key, and (optional) usage key for the proxy",
 		handler: handleSetup.bind(null, pi),
 	});
-
-	pi.registerCommand("cliproxy-refresh", {
-		description:
-			"Re-fetch upstream model list and re-apply provider registrations",
-		handler: handleRefresh.bind(null, pi),
-	});
-
-	pi.registerCommand("cliproxy-list", {
-		description: "Show every upstream model in a scrollable overlay",
-		handler: handleList,
-	});
-
-	pi.registerCommand("cliproxy-usage", {
-		description: "Show per-account quota windows from the upstream",
-		handler: handleUsage,
-	});
-
-	pi.registerCommand("cliproxy-doctor", {
-		description: "Check connectivity, key resolution, and discovery shape",
-		handler: handleDoctor,
-	});
 }
 
 // --------------------------------------------------------------------------- /cliproxy
@@ -67,7 +40,7 @@ async function handleCliproxy(
 	const cfg = loadConfig();
 	if (!cfg.proxy.endpoint || !resolveConfigValue(cfg.proxy.apiKey)) {
 		ctx.ui.notify(
-			"endpoint or API key not set \u2014 launching /cliproxy-setup first",
+			"endpoint or API key not set \u2014 launching setup first",
 			"info",
 		);
 		const ok = await runSetup(ctx, true);
@@ -82,17 +55,7 @@ async function handleCliproxy(
 		ctx.ui.notify(`discovery failed: ${(err as Error).message}`, "error");
 		return;
 	}
-	const updated = await runPicker(ctx, current, discovery);
-	if (!updated) {
-		ctx.ui.notify("changes discarded", "info");
-		return;
-	}
-	saveConfig(updated);
-	const rep = await applyAll(pi, updated, discovery);
-	ctx.ui.notify(
-		`saved \u00b7 ${rep.registered.length} providers registered, ${rep.skipped.length} skipped`,
-		"info",
-	);
+	await runHub(pi, ctx, current, discovery);
 }
 
 // --------------------------------------------------------------------------- /cliproxy-setup
@@ -124,124 +87,3 @@ async function handleSetup(
 		);
 	}
 }
-
-// --------------------------------------------------------------------------- /cliproxy-refresh
-
-async function handleRefresh(
-	pi: ExtensionAPI,
-	_args: string,
-	ctx: ExtensionCommandContext,
-): Promise<void> {
-	const cfg = loadConfig();
-	const resolvedKey = resolveConfigValue(cfg.proxy.apiKey);
-	try {
-		const discovery = await fetchDiscovery(cfg, resolvedKey);
-		const rep = await applyAll(pi, cfg, discovery);
-		clearUsageCache();
-		ctx.ui.notify(
-			`cliproxy: ${rep.registered.length} providers registered, ${rep.skipped.length} skipped (source=${discovery.source})`,
-			"info",
-		);
-	} catch (err) {
-		ctx.ui.notify(`refresh failed: ${(err as Error).message}`, "error");
-	}
-}
-
-// --------------------------------------------------------------------------- /cliproxy-list
-
-async function handleList(
-	_args: string,
-	ctx: ExtensionCommandContext,
-): Promise<void> {
-	const cfg = loadConfig();
-	const resolvedKey = resolveConfigValue(cfg.proxy.apiKey);
-	let discovery;
-	try {
-		discovery = await fetchDiscovery(cfg, resolvedKey);
-	} catch (err) {
-		ctx.ui.notify(`list failed: ${(err as Error).message}`, "error");
-		return;
-	}
-	await runPicker(ctx, cfg, discovery, {
-		readOnly: true,
-		title: " /cliproxy-list \u00b7 read-only ",
-	});
-}
-
-// --------------------------------------------------------------------------- /cliproxy-usage
-
-async function handleUsage(
-	args: string,
-	ctx: ExtensionCommandContext,
-): Promise<void> {
-	const force = /(^|\s)--refresh(\s|$)/.test(args);
-	const cfg = loadConfig();
-	const usageKey = resolveConfigValue(cfg.proxy.usageKey);
-	let doc;
-	try {
-		doc = await fetchUsage(cfg, usageKey, { force });
-	} catch (err) {
-		ctx.ui.notify(`usage failed: ${(err as Error).message}`, "error");
-		return;
-	}
-	await showOverlay(ctx, "cliproxy-usage", {
-		render: (state) =>
-			renderUsage(doc, {
-				showDisabled: state["d"] === true,
-				verbose: state["v"] === true,
-			}).join("\n"),
-		toggles: [
-			{ key: "d", hint: "d disabled" },
-			{ key: "v", hint: "v verbose" },
-		],
-	});
-}
-
-// --------------------------------------------------------------------------- /cliproxy-doctor
-
-async function handleDoctor(
-	_args: string,
-	ctx: ExtensionCommandContext,
-): Promise<void> {
-	const cfg = loadConfig();
-	const lines: string[] = [];
-	lines.push(`endpoint: ${cfg.proxy.endpoint}`);
-	lines.push(
-		`apiKey resolves: ${resolveConfigValue(cfg.proxy.apiKey) ? "yes" : "NO (empty after resolution)"}`,
-	);
-	lines.push(
-		`usageKey resolves: ${cfg.proxy.usageKey ? (resolveConfigValue(cfg.proxy.usageKey) ? "yes" : "NO") : "not configured"}`,
-	);
-	lines.push(`user-agent: ${PLUGIN_USER_AGENT}`);
-
-	try {
-		const discovery = await fetchDiscovery(
-			cfg,
-			resolveConfigValue(cfg.proxy.apiKey),
-		);
-		lines.push("");
-		lines.push(`discovery source: ${discovery.source}`);
-		lines.push(`upstream version: ${discovery.upstreamVersion ?? "(unknown)"}`);
-		lines.push(`upstream total ids: ${discovery.upstreamTotal}`);
-		lines.push(
-			`built-in providers seen: ${discovery.builtinProviders.map((p) => `${p.name}=${p.models.length}`).join(", ") || "(none)"}`,
-		);
-		lines.push(`custom pool size: ${discovery.customPool.length}`);
-	} catch (err) {
-		lines.push("");
-		lines.push(`discovery FAILED: ${(err as Error).message}`);
-	}
-
-	const conflicts = detectConflicts(cfg);
-	if (conflicts.length > 0) {
-		lines.push("");
-		lines.push("conflicts:");
-		for (const c of conflicts) lines.push(`  [${c.kind}] ${c.detail}`);
-	} else {
-		lines.push("");
-		lines.push("conflicts: none");
-	}
-
-	log.info("doctor:", lines.join(" | "));
-	await showOverlay(ctx, "cliproxy-doctor", lines.join("\n"));
-}

package/src/fetch-models.ts

@@ -20,7 +20,7 @@ import {
 import type { ProxyConfig } from "./config.ts";
 import { log } from "./log.ts";
 
-export const PLUGIN_USER_AGENT = "pi-cliproxyapi/0.1.0";
+export const PLUGIN_USER_AGENT = "pi-cliproxyapi/0.3.0";
 const REQUEST_TIMEOUT_MS = 5_000;
 
 export interface DiscoveryModelEntry {
@@ -215,10 +215,7 @@ async function fetchRawModels(
 		.filter((m) => m.id);
 }
 
-function classifyLocally(
-	raw: RawUpstreamModel[],
-	cfg: ProxyConfig,
-): Discovery {
+function classifyLocally(raw: RawUpstreamModel[], cfg: ProxyConfig): Discovery {
 	const excludes = cfg.discoveryExcludes;
 	const builtinByName = new Map<string, DiscoveryBuiltinProvider>();
 	const customPool: DiscoveryCustomEntry[] = [];

package/src/log.ts

@@ -1,19 +1,32 @@
 // Tiny logger that prefixes all messages with the extension tag.
 // Uses console.* directly — pi pipes stdout/stderr into its log sink.
+//
+// While an interactive overlay is open, console output corrupts the TUI (it
+// prints over the box and forces a redraw below it — stacking headers). The
+// overlay code wraps its lifetime in setLogQuiet(true) to mute us; user-facing
+// results are surfaced inside the overlay instead.
 
 const TAG = "[pi-cliproxyapi]";
 
+let quiet = false;
+
+/** Mute/unmute all console output (used around interactive overlays). */
+export function setLogQuiet(v: boolean): void {
+	quiet = v;
+}
+
 export const log = {
 	info(...args: unknown[]): void {
-		console.log(TAG, ...args);
+		if (!quiet) console.log(TAG, ...args);
 	},
 	warn(...args: unknown[]): void {
-		console.warn(TAG, ...args);
+		if (!quiet) console.warn(TAG, ...args);
 	},
 	error(...args: unknown[]): void {
-		console.error(TAG, ...args);
+		if (!quiet) console.error(TAG, ...args);
 	},
 	debug(...args: unknown[]): void {
-		if (process.env.PI_CLIPROXYAPI_DEBUG) console.log(TAG, "[debug]", ...args);
+		if (!quiet && process.env.PI_CLIPROXYAPI_DEBUG)
+			console.log(TAG, "[debug]", ...args);
 	},
 };

package/src/ui-frame.ts

@@ -0,0 +1,118 @@
+// Shared frame renderer for every /cliproxy overlay.
+//
+// Geometry contract:
+//   - frame() always returns lines that are EXACTLY `width` visible cells.
+//   - top    = \u256d\u2500 <title> <fill> \u256e
+//   - body i = \u2502 <line padded/truncated to width-2> \u2502
+//   - footer = \u2570\u2500 <hint> <fill> [badge] \u256f       (if footer provided)
+//     or       \u2570\u2500\u2500\u2500\u2026\u2500\u2500\u2500\u256f                          (otherwise)
+//
+// Callers stay simple:
+//
+//   return frame(theme, {
+//     width,
+//     title: " setup ",
+//     lines: [
+//       " hint goes here ",
+//       "",
+//       theme.fg("accent", "> input"),
+//     ],
+//     footer: { hint: "enter = save  \u00b7  esc = cancel" },
+//   });
+//
+// Anything inside `lines` may already contain ANSI escapes; pad() is ANSI-aware
+// (see render-text.ts). No caller should ever draw \u256d/\u256e/\u2502/\u2570/\u256f by hand again.
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+import { pad } from "./ui-picker/render-text.ts";
+import type { Theme } from "./ui-picker/types.ts";
+
+export interface FrameFooter {
+	/** Left-aligned hint text (dimmed). */
+	hint?: string;
+	/** Right-aligned focus/state badge (muted). */
+	badge?: string;
+}
+
+export interface FrameOpts {
+	width: number;
+	title?: string;
+	titleColor?: "accent" | "error" | "success" | "warning";
+	lines: string[];
+	footer?: FrameFooter;
+}
+
+const SIDE = "\u2502";
+const TL = "\u256d";
+const TR = "\u256e";
+const BL = "\u2570";
+const BR = "\u256f";
+const HR = "\u2500";
+
+export function frame(theme: Theme, opts: FrameOpts): string[] {
+	const w = Math.max(4, opts.width);
+	return [
+		drawTop(theme, opts.title, opts.titleColor ?? "accent", w),
+		...opts.lines.map((line) => drawBody(theme, line, w)),
+		drawBottom(theme, opts.footer, w),
+	];
+}
+
+function drawTop(
+	theme: Theme,
+	title: string | undefined,
+	color: "accent" | "error" | "success" | "warning",
+	width: number,
+): string {
+	// Layout: \u256d \u2500 <title> <fill> \u256e  \u2014 exactly `width` cells.
+	// Fixed cells = 2 (\u256d\u2500) + 1 (\u256e) = 3. The rest is title + fill.
+	const t = title ?? "";
+	const titleVis = visibleWidth(t);
+	const rest = Math.max(0, width - 3 - titleVis);
+	const titleColoured = t ? theme.bold(theme.fg(color, t)) : "";
+	const body = `${TL}${HR}${titleColoured}${HR.repeat(rest)}${TR}`;
+	return theme.fg("borderAccent", body);
+}
+
+function drawBody(theme: Theme, content: string, width: number): string {
+	// Layout: \u2502 <content padded to width-2> \u2502
+	const inner = Math.max(0, width - 2);
+	const side = theme.fg("borderAccent", SIDE);
+	return `${side}${pad(content, inner)}${side}`;
+}
+
+function drawBottom(
+	theme: Theme,
+	footer: FrameFooter | undefined,
+	width: number,
+): string {
+	const start = `${BL}${HR}`;
+	const end = `${BR}`;
+	const fixedCells = 3; // \u2570 + \u2500 + \u256f
+
+	if (!footer || (!footer.hint && !footer.badge)) {
+		const rest = Math.max(0, width - fixedCells);
+		return theme.fg("borderAccent", `${start}${HR.repeat(rest)}${end}`);
+	}
+
+	const hint = footer.hint ?? "";
+	const badge = footer.badge ?? "";
+	const hintVis = visibleWidth(hint);
+	const badgeVis = visibleWidth(badge);
+	const rest = Math.max(0, width - fixedCells - hintVis - badgeVis);
+
+	const left = theme.fg("dim", hint);
+	const right = badge ? theme.fg("muted", badge) : "";
+	const fill = HR.repeat(rest);
+
+	return `${theme.fg("borderAccent", start)}${left}${theme.fg("borderAccent", fill)}${right}${theme.fg("borderAccent", end)}`;
+}
+
+/**
+ * Convenience: number of usable content cells per body line for a given frame
+ * width. Use this when laying out children that need to know their width.
+ */
+export function frameInner(width: number): number {
+	return Math.max(0, width - 2);
+}