pi-soly 1.11.2 → 1.12.0

package/visual/format.ts

@@ -0,0 +1,73 @@
+// =============================================================================
+// visual/format.ts — pure formatting helpers for the soly chrome
+// =============================================================================
+//
+// Small, dependency-free, fully testable string helpers used by the footer,
+// top bar and working indicator. No ANSI, no pi imports — just text in / out.
+// Width-aware rendering (visibleWidth/truncateToWidth) lives in segments.ts.
+// =============================================================================
+
+import * as path from "node:path";
+
+/**
+ * Format a token count for compact display, mirroring pi's native footer:
+ * `<1000` exact, `<10k` one decimal, `<1M` rounded k, then M.
+ */
+export function formatTokens(count: number): string {
+	if (!Number.isFinite(count) || count <= 0) return "0";
+	if (count < 1000) return String(Math.round(count));
+	if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+	if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	return `${Math.round(count / 1_000_000)}M`;
+}
+
+/**
+ * Replace the home prefix with `~`. Mirrors pi's `formatCwdForFooter` so our
+ * footer matches the native one when the path is short.
+ */
+export function formatCwd(cwd: string, home: string | undefined): string {
+	if (!home) return cwd;
+	const rel = path.relative(path.resolve(home), path.resolve(cwd));
+	const insideHome = rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+	if (!insideHome) return cwd;
+	return rel === "" ? "~" : `~${path.sep}${rel}`;
+}
+
+/**
+ * Shrink a path to fit `maxWidth` visible columns through three tiers:
+ *   1. full          `~/src/stbl/pi-soly.framework`
+ *   2. elided middle `~/…/pi-soly.framework`
+ *   3. basename      `pi-soly.framework`
+ * Returns the widest tier that fits, or the basename truncated if even that
+ * is too wide. `maxWidth <= 0` returns an empty string (caller drops it).
+ */
+export function fitPath(cwd: string, home: string | undefined, maxWidth: number): string {
+	if (maxWidth <= 0) return "";
+	const full = formatCwd(cwd, home);
+	if (full.length <= maxWidth) return full;
+
+	const base = path.basename(cwd) || cwd;
+	const head = full.startsWith("~") ? "~" : path.parse(full).root.replace(/[\\/]+$/, "");
+	const elided = `${head}${path.sep}…${path.sep}${base}`;
+	if (elided.length <= maxWidth) return elided;
+
+	if (base.length <= maxWidth) return base;
+	return base.slice(0, Math.max(1, maxWidth - 1)) + "…";
+}
+
+/**
+ * Compact elapsed label: `8s` under a minute, `9m 50s` under an hour, `1h 02m`
+ * beyond. Components are space-separated so the digits don't run together.
+ * Seconds/minutes are zero-padded to two digits so the right edge doesn't
+ * jump each tick on a live-updating counter. Clamped at 0.
+ */
+export function formatElapsed(ms: number): string {
+	const total = Math.max(0, Math.floor(ms / 1000));
+	if (total < 60) return `${total}s`;
+	const h = Math.floor(total / 3600);
+	const m = Math.floor((total % 3600) / 60);
+	const s = total % 60;
+	if (h > 0) return `${h}h ${String(m).padStart(2, "0")}m`;
+	return `${m}m ${String(s).padStart(2, "0")}s`;
+}

package/visual/glyphs.ts

@@ -0,0 +1,35 @@
+// =============================================================================
+// visual/glyphs.ts — Nerd-Font glyphs with ASCII fallbacks
+// =============================================================================
+//
+// Each glyph has a Nerd-Font form and a plain-ASCII form. The chrome picks
+// per-glyph based on a single `ascii` flag (from soly config). Kept tiny and
+// pure so the components stay declarative.
+// =============================================================================
+
+export type GlyphName = "ctx" | "git" | "model" | "enter";
+
+const NERD: Record<GlyphName, string> = {
+	ctx: "◐",
+	git: "⎇",
+	model: "⊙",
+	enter: "↵",
+};
+
+const ASCII: Record<GlyphName, string> = {
+	ctx: "",
+	git: "git:",
+	model: "",
+	enter: "enter",
+};
+
+/** Return the glyph for `name`, using the ASCII form when `ascii` is true. */
+export function glyph(name: GlyphName, ascii: boolean): string {
+	return ascii ? ASCII[name] : NERD[name];
+}
+
+/** Prefix `text` with a glyph + space, omitting the space when the glyph is empty. */
+export function withGlyph(name: GlyphName, text: string, ascii: boolean): string {
+	const g = glyph(name, ascii);
+	return g ? `${g} ${text}` : text;
+}

package/visual/gradient.ts

@@ -0,0 +1,122 @@
+// =============================================================================
+// visual/gradient.ts — truecolor gradient helpers for the banner ("переливы")
+// =============================================================================
+//
+// Pure RGB math + ANSI emission, mode-aware:
+//   - truecolor → 24-bit `\x1b[38;2;r;g;bm`
+//   - 256color  → nearest xterm-256 `\x1b[38;5;Nm`
+//   - none      → no codes (plain text; used in tests / NO_COLOR / ASCII)
+//
+// Used by welcome.ts to paint the full-width wave band and the "soly" wordmark
+// with a multi-stop color sweep. No pi imports → trivially unit-testable.
+// =============================================================================
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+export type RGB = { r: number; g: number; b: number };
+export type ColorMode = "truecolor" | "256color" | "none";
+
+export const RESET = "\x1b[0m";
+
+/** Parse `#rgb` / `#rrggbb` → RGB, or null when malformed. */
+export function hexToRgb(hex: string): RGB | null {
+	const m = /^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.exec(hex.trim());
+	if (!m?.[1]) return null;
+	const h = m[1].length === 3 ? m[1].split("").map((c) => c + c).join("") : m[1];
+	return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16) };
+}
+
+const clamp255 = (n: number): number => Math.max(0, Math.min(255, Math.round(n)));
+
+/** Linear interpolate between two colors. `t` in [0,1]. */
+export function lerp(a: RGB, b: RGB, t: number): RGB {
+	return { r: clamp255(a.r + (b.r - a.r) * t), g: clamp255(a.g + (b.g - a.g) * t), b: clamp255(a.b + (b.b - a.b) * t) };
+}
+
+/** Produce `n` colors evenly sampled across a multi-stop gradient. */
+export function gradient(stops: RGB[], n: number): RGB[] {
+	if (n <= 0 || stops.length === 0) return [];
+	if (stops.length === 1 || n === 1) return Array.from({ length: n }, () => stops[0] as RGB);
+	const out: RGB[] = [];
+	for (let i = 0; i < n; i++) {
+		const pos = (i / (n - 1)) * (stops.length - 1);
+		const idx = Math.min(stops.length - 2, Math.floor(pos));
+		out.push(lerp(stops[idx] as RGB, stops[idx + 1] as RGB, pos - idx));
+	}
+	return out;
+}
+
+/** Nearest xterm-256 index for an RGB color (6×6×6 cube + grayscale ramp). */
+export function rgbTo256(c: RGB): number {
+	if (Math.abs(c.r - c.g) < 8 && Math.abs(c.g - c.b) < 8) {
+		if (c.r < 8) return 16;
+		if (c.r > 248) return 231;
+		return 232 + Math.round(((c.r - 8) / 247) * 24);
+	}
+	const q = (v: number): number => Math.round((v / 255) * 5);
+	return 16 + 36 * q(c.r) + 6 * q(c.g) + q(c.b);
+}
+
+const CUBE = [0, 95, 135, 175, 215, 255];
+const BASIC16: RGB[] = [
+	{ r: 0, g: 0, b: 0 }, { r: 128, g: 0, b: 0 }, { r: 0, g: 128, b: 0 }, { r: 128, g: 128, b: 0 },
+	{ r: 0, g: 0, b: 128 }, { r: 128, g: 0, b: 128 }, { r: 0, g: 128, b: 128 }, { r: 192, g: 192, b: 192 },
+	{ r: 128, g: 128, b: 128 }, { r: 255, g: 0, b: 0 }, { r: 0, g: 255, b: 0 }, { r: 255, g: 255, b: 0 },
+	{ r: 0, g: 0, b: 255 }, { r: 255, g: 0, b: 255 }, { r: 0, g: 255, b: 255 }, { r: 255, g: 255, b: 255 },
+];
+
+/** Convert an xterm-256 index back to approximate RGB (inverse of rgbTo256). */
+export function xterm256ToRgb(n: number): RGB {
+	if (n < 16) return BASIC16[n] ?? { r: 0, g: 0, b: 0 };
+	if (n >= 232) {
+		const v = clamp255(8 + (n - 232) * 10);
+		return { r: v, g: v, b: v };
+	}
+	const i = n - 16;
+	return {
+		r: CUBE[Math.floor(i / 36) % 6] ?? 0,
+		g: CUBE[Math.floor(i / 6) % 6] ?? 0,
+		b: CUBE[i % 6] ?? 0,
+	};
+}
+
+/** Extract an RGB from a theme fg ANSI string (`38;2;r;g;b` or `38;5;n`). */
+export function parseAnsiColor(ansi: string): RGB | null {
+	const tc = /38;2;(\d{1,3});(\d{1,3});(\d{1,3})/.exec(ansi);
+	if (tc) return { r: clamp255(+(tc[1] ?? 0)), g: clamp255(+(tc[2] ?? 0)), b: clamp255(+(tc[3] ?? 0)) };
+	const idx = /38;5;(\d{1,3})/.exec(ansi);
+	if (idx) return xterm256ToRgb(+(idx[1] ?? 0));
+	return null;
+}
+
+/** Variations around a base color: darker → base → lighter. Used for accent-derived banners. */
+export function variations(base: RGB): RGB[] {
+	return [lerp(base, { r: 0, g: 0, b: 0 }, 0.45), base, lerp(base, { r: 255, g: 255, b: 255 }, 0.5)];
+}
+
+/** Foreground ANSI for a color in the given mode (empty string when none). */
+export function fgAnsi(c: RGB, mode: ColorMode): string {
+	if (mode === "truecolor") return `\x1b[38;2;${c.r};${c.g};${c.b}m`;
+	if (mode === "256color") return `\x1b[38;5;${rgbTo256(c)}m`;
+	return "";
+}
+
+/**
+ * Color `text` column-by-column from `colors` (indexed by visible column).
+ * Spaces are left unstyled. Returns text unchanged when mode is "none".
+ */
+export function colorizeColumns(text: string, colors: RGB[], mode: ColorMode): string {
+	if (mode === "none" || colors.length === 0) return text;
+	let out = "";
+	let col = 0;
+	for (const ch of Array.from(text)) {
+		if (ch === " ") {
+			out += ch;
+		} else {
+			const color = colors[Math.min(colors.length - 1, col)] as RGB;
+			out += fgAnsi(color, mode) + ch;
+		}
+		col += visibleWidth(ch);
+	}
+	return out + RESET;
+}

package/visual/index.ts

@@ -0,0 +1,18 @@
+// =============================================================================
+// visual/index.ts — public surface of the soly chrome (Phase 2: visual)
+// =============================================================================
+//
+// A flexible, native, dependency-free status system for pi: two width-aware
+// "polosy" (a top bar above the editor + a custom footer) plus a configurable
+// working spinner with live telemetry. Built only on documented pi UI APIs
+// (setWidget / setFooter / setWorkingIndicator / setWorkingMessage).
+//
+// index.ts (the extension entry) creates one Chrome via createChrome(), keeps
+// its `data` snapshot up to date on lifecycle events, and calls poke() to
+// re-render. Everything else is internal.
+// =============================================================================
+
+export { createChrome, type Chrome, type ChromeConfig } from "./chrome.ts";
+export { type ChromeData, emptyChromeData } from "./data.ts";
+export { SPINNER_FRAMES, SPINNER_INTERVAL_MS } from "./working.ts";
+export { readWelcomeMeta, type WelcomeInput } from "./welcome.ts";

package/visual/list-panel.ts

@@ -0,0 +1,207 @@
+// =============================================================================
+// visual/list-panel.ts — generic focused list modal (rules / docs / …)
+// =============================================================================
+//
+// A reusable overlay panel (shown via ctx.ui.custom) on the same pattern as the
+// MCP panel: a fuzzy-filterable list with a live preview pane and key actions,
+// instead of dumping everything into the chat. Monochrome by default — dim
+// borders, muted rows, bold for the selected row (no decorative color).
+//
+// The caller supplies items (+ a `refresh` to re-read them after an action) and
+// optional actions (key → run). `/` enters search mode; Esc exits search, then
+// closes. Pure-ish: rendering uses only pi-tui width helpers + the theme.
+// =============================================================================
+
+import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { Component, TUI } from "@earendil-works/pi-tui";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { createPanelKeys, type PanelKeybindings, type PanelKeys } from "../mcp/panel-keys.ts";
+
+/** One row in the panel. `body` is shown in the preview pane when selected. */
+export type ListItem = { id: string; marker: string; label: string; meta?: string; body?: string };
+
+/** A key-triggered action over the selected item (e.g. enable/disable/reload). */
+export type ListAction = { key: string; hint: string; run: (item: ListItem) => void };
+
+export type ListPanelProps = {
+	tui: TUI;
+	theme: Theme;
+	keybindings?: PanelKeybindings;
+	done: () => void;
+	title: string;
+	/** Right-aligned header text (e.g. counts / token budget). */
+	headerRight?: string;
+	items: ListItem[];
+	actions?: ListAction[];
+	/** Re-read items after an action mutates state. */
+	refresh?: () => ListItem[];
+	/** Fired on Enter for the selected item; the panel then closes. When set,
+	 *  the footer shows an "⏎ open" hint. */
+	onSelect?: (item: ListItem) => void;
+};
+
+const MAX_ROWS = 12; // list window height (render() has no viewport height)
+const PREVIEW_LINES = 4;
+
+/** Subsequence fuzzy match: substring scores highest, then in-order chars. */
+function fuzzyScore(query: string, text: string): number {
+	const q = query.toLowerCase();
+	const t = text.toLowerCase();
+	if (!q) return 1;
+	if (t.includes(q)) return 100 + q.length / t.length;
+	let qi = 0;
+	for (let i = 0; i < t.length && qi < q.length; i++) if (t[i] === q[qi]) qi++;
+	return qi === q.length ? 1 : 0;
+}
+
+export class ListPanel implements Component {
+	private readonly p: ListPanelProps;
+	private readonly keys: PanelKeys;
+	private items: ListItem[];
+	private query = "";
+	private searching = false;
+	private selected = 0;
+
+	constructor(props: ListPanelProps) {
+		this.p = props;
+		this.items = props.items;
+		this.keys = createPanelKeys(props.keybindings);
+	}
+
+	invalidate(): void {
+		/* stateless cache */
+	}
+
+	private filtered(): ListItem[] {
+		if (!this.query) return this.items;
+		return this.items
+			.map((it) => ({ it, s: fuzzyScore(this.query, `${it.label} ${it.meta ?? ""}`) }))
+			.filter((x) => x.s > 0)
+			.sort((a, b) => b.s - a.s)
+			.map((x) => x.it);
+	}
+
+	private clamp(list: ListItem[]): void {
+		if (this.selected >= list.length) this.selected = Math.max(0, list.length - 1);
+		if (this.selected < 0) this.selected = 0;
+	}
+
+	handleInput(data: string): void {
+		const list = this.filtered();
+		this.clamp(list);
+
+		if (this.searching) {
+			if (matchesKey(data, "escape") || matchesKey(data, "return")) {
+				this.searching = false;
+			} else if (matchesKey(data, "backspace")) {
+				this.query = this.query.slice(0, -1);
+			} else if (data.length === 1 && data >= " ") {
+				this.query += data;
+				this.selected = 0;
+			}
+			this.p.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "escape")) {
+			this.p.done();
+			return;
+		}
+		if (this.keys.selectUp(data)) {
+			this.selected = Math.max(0, this.selected - 1);
+		} else if (this.keys.selectDown(data)) {
+			this.selected = Math.min(list.length - 1, this.selected + 1);
+		} else if (data === "/") {
+			this.searching = true;
+		} else if (matchesKey(data, "return")) {
+			const current = list[this.selected];
+			if (this.p.onSelect && current) {
+				this.p.onSelect(current);
+				this.p.done();
+				return;
+			}
+		} else {
+			const action = this.p.actions?.find((a) => a.key === data);
+			const current = list[this.selected];
+			if (action && current) {
+				action.run(current);
+				if (this.p.refresh) this.items = this.p.refresh();
+			}
+		}
+		this.p.tui.requestRender();
+	}
+
+	render(width: number): string[] {
+		const theme = this.p.theme;
+		const dim = (s: string) => theme.fg("dim", s);
+		const muted = (s: string) => theme.fg("muted", s);
+		const inner = Math.max(20, width - 4);
+		const list = this.filtered();
+		this.clamp(list);
+
+		const out: string[] = [];
+		out.push(this.headerLine(inner, dim, muted));
+		out.push(this.searchLine(inner, dim, muted));
+		out.push(this.frame("", inner, dim));
+
+		// Windowed list around the selection.
+		const start = Math.max(0, Math.min(this.selected - Math.floor(MAX_ROWS / 2), Math.max(0, list.length - MAX_ROWS)));
+		const window = list.slice(start, start + MAX_ROWS);
+		if (window.length === 0) out.push(this.frame(dim("  (no matches)"), inner, dim));
+		for (let i = 0; i < window.length; i++) out.push(this.rowLine(window[i] as ListItem, start + i === this.selected, inner, dim, muted));
+
+		out.push(this.ruleLine("preview", inner, dim));
+		for (const line of this.previewLines(list[this.selected], inner)) out.push(this.frame("  " + muted(line), inner, dim));
+
+		out.push(this.footerLine(inner, dim));
+		return out;
+	}
+
+	private frame(content: string, inner: number, dim: (s: string) => string): string {
+		const pad = Math.max(0, inner - visibleWidth(content));
+		return dim("│ ") + content + " ".repeat(pad) + dim(" │");
+	}
+
+	private headerLine(inner: number, dim: (s: string) => string, muted: (s: string) => string): string {
+		const left = ` ${this.p.title} `;
+		const right = this.p.headerRight ? ` ${this.p.headerRight} ` : "";
+		const fillN = Math.max(1, inner + 2 - visibleWidth(left) - visibleWidth(right));
+		return dim("┌") + muted(left) + dim("─".repeat(fillN)) + muted(right) + dim("┐");
+	}
+
+	private searchLine(inner: number, dim: (s: string) => string, muted: (s: string) => string): string {
+		const text = this.searching || this.query ? `/ ${this.query}${this.searching ? "▏" : ""}` : muted("/ to search");
+		return this.frame(text, inner, dim);
+	}
+
+	private rowLine(it: ListItem, selected: boolean, inner: number, dim: (s: string) => string, muted: (s: string) => string): string {
+		const cursor = selected ? muted("❯ ") : "  ";
+		const label = selected ? this.p.theme.bold(it.label) : muted(it.label);
+		const head = `${cursor}${dim(it.marker)} ${label}`;
+		const meta = it.meta ? dim(it.meta) : "";
+		const gap = Math.max(1, inner - visibleWidth(head) - visibleWidth(meta));
+		const line = head + " ".repeat(gap) + meta;
+		return this.frame(visibleWidth(line) > inner ? truncateToWidth(line, inner) : line, inner, dim);
+	}
+
+	/** A full-width "── label ───" rule inside the panel border. */
+	private ruleLine(label: string, inner: number, dim: (s: string) => string): string {
+		const head = `── ${label} `;
+		const dashes = Math.max(0, inner - visibleWidth(head));
+		return dim(`│ ${head}${"─".repeat(dashes)} │`);
+	}
+
+	private previewLines(it: ListItem | undefined, inner: number): string[] {
+		const body = (it?.body ?? "").replace(/\s+/g, " ").trim();
+		if (!body) return ["(no preview)"];
+		return wrapTextWithAnsi(body, inner - 2).slice(0, PREVIEW_LINES);
+	}
+
+	private footerLine(inner: number, dim: (s: string) => string): string {
+		const acts = (this.p.actions ?? []).map((a) => `${a.key} ${a.hint}`).join(" · ");
+		const open = this.p.onSelect ? "⏎ open · " : "";
+		const hint = ` ↑↓ move · ${open}/ search${acts ? " · " + acts : ""} · esc `;
+		const fillN = Math.max(1, inner + 2 - visibleWidth(hint));
+		return dim("└") + dim(hint) + dim("─".repeat(fillN)) + dim("┘");
+	}
+}

package/visual/segments.ts

@@ -0,0 +1,136 @@
+// =============================================================================
+// visual/segments.ts — width-aware segment composition for the soly chrome
+// =============================================================================
+//
+// A bar is two ordered lists of segments (left + right). Each segment carries
+// a `priority` (lower = dropped first when the terminal is too narrow). The
+// composer drops the lowest-priority segments until the bar fits, then joins
+// left/right with a separator and fills the gap with a rule (e.g. `─`).
+//
+// Segment `text` may already contain ANSI color codes; all width math uses
+// pi's `visibleWidth`/`truncateToWidth`, which ignore ANSI and handle wide
+// glyphs, so coloring never breaks the layout (same approach as pi's native
+// footer). The composer itself is pure: pass an identity `styleFill` in tests
+// to assert exact column widths.
+// =============================================================================
+
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** One unit of a bar. `text` is the final (possibly ANSI-styled) string. */
+export type Segment = {
+	/** Stable id (for debugging / future per-segment config). */
+	id: string;
+	/** Rendered text, may contain ANSI codes. */
+	text: string;
+	/** Lower priority is dropped first when space runs out. */
+	priority: number;
+};
+
+export type ComposeOptions = {
+	left: Segment[];
+	right: Segment[];
+	width: number;
+	/** Separator between segments on the same side. Default `" · "`. */
+	sep?: string;
+	/** Fill character for the gap between left and right. Default `"─"`. */
+	fillChar?: string;
+	/** Styles the gap fill (e.g. dim). Identity by default. */
+	styleFill?: (s: string) => string;
+};
+
+/** Sum of segment widths joined by `sep`. */
+function barWidth(segs: Segment[], sep: string): number {
+	if (segs.length === 0) return 0;
+	const sepW = visibleWidth(sep) * (segs.length - 1);
+	return segs.reduce((w, s) => w + visibleWidth(s.text), 0) + sepW;
+}
+
+/** Min columns between the left group and a non-empty right group. */
+const MIN_GAP = 2;
+
+function joinSide(segs: Segment[], sep: string): string {
+	return segs.map((s) => s.text).join(sep);
+}
+
+/**
+ * Drop the lowest-priority segments (from either side) until the bar fits
+ * `width`. Ties break toward dropping right-side segments first, so the
+ * left identity/context stays put longest. Returns the surviving lists.
+ */
+function dropToFit(left: Segment[], right: Segment[], width: number, sep: string): {
+	left: Segment[];
+	right: Segment[];
+} {
+	let l = [...left];
+	let r = [...right];
+	const fits = () => {
+		const gap = r.length > 0 ? MIN_GAP : 0;
+		return barWidth(l, sep) + barWidth(r, sep) + gap <= width;
+	};
+	while (!fits() && l.length + r.length > 0) {
+		const lowL = l.reduce<Segment | null>((m, s) => (m && m.priority <= s.priority ? m : s), null);
+		const lowR = r.reduce<Segment | null>((m, s) => (m && m.priority <= s.priority ? m : s), null);
+		// Prefer dropping the right side on ties (keep left identity).
+		if (lowR && (!lowL || lowR.priority <= lowL.priority)) {
+			r = r.filter((s) => s.id !== lowR.id);
+		} else if (lowL) {
+			l = l.filter((s) => s.id !== lowL.id);
+		} else {
+			break;
+		}
+	}
+	return { left: l, right: r };
+}
+
+/**
+ * Compose a single full-width bar line. Drops by priority to fit, joins each
+ * side with `sep`, and fills the middle gap with a styled rule. When the two
+ * sides still don't fit after dropping (single dominant segment), the right
+ * side is truncated, then the left, mirroring pi's native footer.
+ */
+export function composeBar(opts: ComposeOptions): string {
+	const sep = opts.sep ?? " · ";
+	const fillChar = opts.fillChar ?? "─";
+	const styleFill = opts.styleFill ?? ((s) => s);
+	const width = Math.max(0, opts.width);
+
+	const kept = dropToFit(opts.left, opts.right, width, sep);
+	let leftStr = joinSide(kept.left, sep);
+	let rightStr = joinSide(kept.right, sep);
+	let wl = visibleWidth(leftStr);
+	let wr = visibleWidth(rightStr);
+
+	if (rightStr.length === 0) {
+		return wl > width ? truncateToWidth(leftStr, width, "…") : leftStr;
+	}
+
+	if (wl + MIN_GAP + wr > width) {
+		// Truncate right, then left, to guarantee a single line.
+		const availRight = width - wl - MIN_GAP;
+		rightStr = availRight > 0 ? truncateToWidth(rightStr, availRight, "") : "";
+		if (rightStr.length === 0) return truncateToWidth(leftStr, width, "…");
+		wr = visibleWidth(rightStr);
+		const pad = Math.max(0, width - wl - wr);
+		return leftStr + " ".repeat(pad) + rightStr;
+	}
+
+	const gap = width - wl - wr;
+	const fill = gap >= MIN_GAP ? styleFill(` ${fillChar.repeat(gap - MIN_GAP)} `) : " ".repeat(gap);
+	return leftStr + fill + rightStr;
+}
+
+/**
+ * Join a flat list of prioritized parts into a single string no wider than
+ * `width`, dropping the lowest-priority parts first. Used for the working
+ * indicator message. Pure; no fill, no padding.
+ */
+export function fitParts(parts: Segment[], width: number, sep = " · "): string {
+	let kept = [...parts];
+	const total = () => barWidth(kept, sep);
+	while (total() > width && kept.length > 1) {
+		const low = kept.reduce((m, s) => (m.priority <= s.priority ? m : s));
+		kept = kept.filter((s) => s.id !== low.id);
+	}
+	const joined = joinSide(kept, sep);
+	return visibleWidth(joined) > width ? truncateToWidth(joined, width, "…") : joined;
+}

package/visual/style.ts

@@ -0,0 +1,34 @@
+// =============================================================================
+// visual/style.ts — styling indirection so render logic stays testable
+// =============================================================================
+//
+// Components style segment text through a ChromeStyler rather than touching a
+// pi Theme directly. Production wraps the real Theme; tests pass `identityStyler`
+// so assertions can compare exact, un-ANSI'd columns.
+// =============================================================================
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { ChromeColor } from "./colors.ts";
+
+/** Minimal styling surface used by the chrome. */
+export type ChromeStyler = {
+	fg(color: ChromeColor, text: string): string;
+	dim(text: string): string;
+	bold(text: string): string;
+};
+
+/** Wrap a real pi Theme. ChromeColor is a subset of ThemeColor, so this is sound. */
+export function themeStyler(theme: Theme): ChromeStyler {
+	return {
+		fg: (color, text) => theme.fg(color, text),
+		dim: (text) => theme.fg("dim", text),
+		bold: (text) => theme.bold(text),
+	};
+}
+
+/** No-op styler for tests — returns text unchanged so widths are predictable. */
+export const identityStyler: ChromeStyler = {
+	fg: (_color, text) => text,
+	dim: (text) => text,
+	bold: (text) => text,
+};