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

package/lib/{list-cursor.ts → tui/cursor.ts}

@@ -3,18 +3,22 @@
  * it (`/rewind`, `/todos`, `/jobs`).
  *
  * Each screen keeps its own layout, rows, and selection model — rewind uses an
- * index, jobs use a stable id, todos have no cursor at all — but
+ * index, jobs and watchers use a stable id, todos have no cursor at all — but
  * they all need the same arithmetic: how many rows fit, how to keep the focus
  * in view, which keys navigate, and how to render the "showing X–Y of N" row.
  * That shared part lives here so a fix or a rebinding happens once.
  *
- * No runtime dependencies beyond `lib/tui.ts` and `@earendil-works/pi-tui`; the
+ * `ListCursor` tracks an index, which is right for a list whose shape is the
+ * screen's own. `IdCursor` tracks a stable id, which is right for a list that
+ * is re-sorted from live state on every render.
+ *
+ * No runtime dependencies beyond `lib/tui/chrome.ts` and `@earendil-works/pi-tui`; the
  * theme is passed in and there is no cross-extension state.
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
-import { viewportRows, type ViewportRowsSource } from "./tui.ts";
+import { viewportRows, type ViewportRowsSource } from "./chrome.ts";
 
 /**
  * Rows that fit for a list of `itemCount`, reserving one extra line when the
@@ -147,6 +151,55 @@ export class ListCursor {
 	}
 }
 
+/**
+ * Cursor and scroll for a list whose order changes under it.
+ *
+ * A live list (jobs, watchers) is re-read and re-sorted on every render, so an
+ * index would silently point at a different row. This cursor remembers the id
+ * of the focused row and re-derives its index against the current items, falling
+ * back to the first row when that id is gone. It is pure state: the screen owns
+ * `requestRender`, and assigns `visible` from {@link fitRows} each render.
+ */
+export class IdCursor {
+	/** Id of the focused row, or `undefined` before the first paint. */
+	id: string | undefined;
+	/** First visible row. */
+	scroll = 0;
+	/** Rows shown at once; the screen sets this before use. */
+	visible = 1;
+
+	/** Index of the focused row, or `0` when its id is gone or the list is empty. */
+	indexOf<T>(items: readonly T[], key: (item: T) => string): number {
+		if (items.length === 0) return 0;
+		const index = this.id === undefined ? -1 : items.findIndex((item) => key(item) === this.id);
+		return index >= 0 ? index : 0;
+	}
+
+	/** Re-anchor the id against the current items; never repaints. */
+	clamp<T>(items: readonly T[], key: (item: T) => string): void {
+		if (items.length === 0) {
+			this.id = undefined;
+			this.scroll = 0;
+			return;
+		}
+		this.id = key(items[this.indexOf(items, key)]);
+		this.scroll = clampScroll(this.scroll, items.length, this.visible);
+	}
+
+	/** Focus the row at `index` (clamped) and scroll it into view. */
+	select<T>(items: readonly T[], key: (item: T) => string, index: number): void {
+		if (items.length === 0) return;
+		const clamped = Math.min(Math.max(0, index), items.length - 1);
+		this.id = key(items[clamped]);
+		this.ensureVisible(clamped);
+	}
+
+	/** Scroll `index` into view without moving the focus. */
+	ensureVisible(index: number): void {
+		this.scroll = Math.max(0, keepVisible(this.scroll, index, this.visible));
+	}
+}
+
 /**
  * Apply a standard navigation key to `cursor`, reporting whether it handled it.
  *

package/lib/tui/gauge.ts

@@ -0,0 +1,78 @@
+/**
+ * The gauge: filled and empty blocks, and the tone they carry.
+ *
+ * One implementation for every bar in the package — the footer's context
+ * meter, a plan's scroll position — so the block glyphs, the floor, and the
+ * tone thresholds cannot drift between surfaces.
+ *
+ * Value-only: pure functions, theme passed in.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { GLYPHS } from "./glyphs.ts";
+import { paint, type TuiRole } from "./tokens.ts";
+
+/** The percentages at which a gauge changes tone. */
+export interface GaugeThresholds {
+	/** Above this (exclusive), the gauge warns. */
+	warn: number;
+	/** Above this (exclusive), the gauge is in error. */
+	danger: number;
+}
+
+/** The package default: warn past 70%, error past 90%. */
+export const DEFAULT_GAUGE_THRESHOLDS: GaugeThresholds = { warn: 70, danger: 90 };
+
+/**
+ * Filled and empty block counts for a percentage across `blocks` cells.
+ *
+ * The fill floors so the bar reads full only at 100%, and forces one block for
+ * any non-zero usage so a small percentage is still visible. A `null` percent
+ * (unknown) fills nothing, leaving the caller to decide whether to draw the
+ * empty track; a known `0` draws it.
+ */
+export function computeGauge(percent: number | null, blocks: number): { filled: number; empty: number } {
+	if (blocks <= 0) return { filled: 0, empty: 0 };
+	if (percent === null) return { filled: 0, empty: blocks };
+	const clamped = Math.max(0, Math.min(100, percent));
+	const filled = Math.max(clamped > 0 ? 1 : 0, Math.floor((clamped / 100) * blocks));
+	return { filled, empty: blocks - filled };
+}
+
+/** The role a context percentage is drawn in. Neutral until it crosses a threshold. */
+export function gaugeRole(percent: number | null, thresholds: GaugeThresholds = DEFAULT_GAUGE_THRESHOLDS): TuiRole {
+	if (percent === null) return "meta";
+	if (percent > thresholds.danger) return "bad";
+	if (percent > thresholds.warn) return "warn";
+	return "meta";
+}
+
+/** A gauge bar's content. */
+export interface GaugeBarOptions {
+	/** The percentage, or `null` when it is unknown. */
+	percent: number | null;
+	/** Cells the track occupies. */
+	blocks: number;
+	/** Override the role instead of deriving it from the thresholds. */
+	role?: TuiRole;
+	/** Role for the empty track. Defaults to the filled role. */
+	emptyRole?: TuiRole;
+	thresholds?: GaugeThresholds;
+}
+
+/**
+ * The colored bar, or `""` when the percentage is unknown.
+ *
+ * Unknown and zero stay distinct: a known `0%` still draws the empty track so
+ * the column does not jump, while an unknown value draws nothing and leaves the
+ * caller to print a muted `?` instead.
+ */
+export function gaugeBar(theme: Theme, options: GaugeBarOptions): string {
+	if (options.percent === null) return "";
+	const { filled, empty } = computeGauge(options.percent, options.blocks);
+	const role = options.role ?? gaugeRole(options.percent, options.thresholds);
+	const emptyRole = options.emptyRole ?? role;
+	const track = filled > 0 ? paint(theme, role, GLYPHS.gaugeFull.repeat(filled)) : "";
+	const rest = empty > 0 ? paint(theme, emptyRole, GLYPHS.gaugeEmpty.repeat(empty)) : "";
+	return track + rest;
+}

package/lib/tui/index.ts

@@ -0,0 +1,25 @@
+/**
+ * The Bytefly terminal design system: one kit for every interactive surface.
+ *
+ * Import from `lib/tui/index.ts` rather than a leaf module so the surface reads
+ * as one system. The leaves: `tokens.ts` (semantic role -> theme token),
+ * `glyphs.ts` (the shared glyph, separator, and status-key vocabulary),
+ * `chrome.ts` (screen frame, hints, viewport, overlay), `cursor.ts` (list
+ * scroll and navigation), `columns.ts` (width math), `rules.ts` (the rule
+ * grammar), `rows.ts` (list rows, checkboxes, chips, empty states), `gauge.ts`
+ * (the context gauge), and `line-pane.ts` (the scrollable log/match pane).
+ *
+ * Value-only, like every `lib/` module: pure functions, constants, and classes,
+ * with no module-level state.
+ */
+
+export * from "./chrome.ts";
+export * from "./columns.ts";
+export * from "./cursor.ts";
+export * from "./gauge.ts";
+export * from "./glyphs.ts";
+export * from "./line-pane.ts";
+export * from "./rows.ts";
+export * from "./rules.ts";
+export * from "./status-controller.ts";
+export * from "./tokens.ts";

package/lib/tui/line-pane.ts

@@ -0,0 +1,173 @@
+/**
+ * A scrollable text pane: the log tail a job screen opens, the match list a
+ * watcher screen opens.
+ *
+ * Both screens embed the same pane — an open row's id, a buffer of already
+ * sanitized lines, a scroll offset that follows the tail until the user scrolls
+ * away from it, a "showing last N" subtitle, and one dim range row — so the
+ * state machine lives here once. The screen owns rendering, the visible row
+ * budget, and `requestRender`; the pane owns only the state and the keys that
+ * move it.
+ *
+ * Value-only: a class with instance state, no module-level state.
+ */
+
+import { clampScroll, navigateScroll } from "./cursor.ts";
+
+/** A patch for the pane's contents; each field given replaces that field. */
+export interface PaneSource {
+	/** Title shown after the pane's prefix, e.g. `j1 build`. */
+	title?: string;
+	/** The lines, newest last. */
+	lines?: string[];
+	/** The dim subtitle line, e.g. the log file path. Already sanitized. */
+	subtitle?: string;
+	/** Whether earlier lines exist beyond the loaded window. */
+	more?: boolean;
+}
+
+/** Whether two line buffers are identical. */
+function sameLines(a: readonly string[], b: readonly string[]): boolean {
+	if (a.length !== b.length) return false;
+	for (let index = 0; index < a.length; index++) {
+		if (a[index] !== b[index]) return false;
+	}
+	return true;
+}
+
+/** The scrollable text pane both the job and watch screens embed. */
+export class LinePane {
+	/** Id of the row whose pane is open; `""` when the pane is closed. */
+	id = "";
+	/** First visible line. */
+	scroll = 0;
+	/** Rows shown at once; the screen sets this from `fitRows` each render. */
+	visible = 1;
+	/** Whether the view is parked at the tail; set false once the user scrolls up. */
+	follow = true;
+
+	private buffer: string[] = [];
+	private label = "";
+	private subtitle: string | undefined;
+	private more = false;
+
+	/** Lines loaded into the pane, oldest first. */
+	get lines(): readonly string[] {
+		return this.buffer;
+	}
+
+	/** Loaded line count. */
+	get count(): number {
+		return this.buffer.length;
+	}
+
+	/** The furthest the view can scroll while keeping a full window. */
+	get maxScroll(): number {
+		return Math.max(0, this.buffer.length - this.visible);
+	}
+
+	/** Open the pane on a row, reset to the tail. */
+	open(id: string, source: PaneSource): void {
+		this.id = id;
+		this.buffer = [];
+		this.label = "";
+		this.subtitle = undefined;
+		this.more = false;
+		this.scroll = 0;
+		this.follow = true;
+		this.update(source);
+	}
+
+	/** Close the pane and drop its buffer. */
+	close(): void {
+		this.id = "";
+		this.buffer = [];
+		this.label = "";
+		this.subtitle = undefined;
+		this.more = false;
+		this.scroll = 0;
+		this.follow = true;
+	}
+
+	/**
+	 * Replace the given fields.
+	 *
+	 * Returns whether anything visible changed, so a caller polling the pane
+	 * every 500ms can skip a repaint — and leave the user's scroll alone — when
+	 * the buffer is byte-identical.
+	 */
+	update(source: PaneSource): boolean {
+		const titleChanged = source.title !== undefined && source.title !== this.label;
+		const linesChanged = source.lines !== undefined && !sameLines(source.lines, this.buffer);
+		const moreChanged = source.more !== undefined && source.more !== this.more;
+		const subtitleChanged = source.subtitle !== undefined && source.subtitle !== this.subtitle;
+
+		if (source.title !== undefined) this.label = source.title;
+		if (source.lines !== undefined) this.buffer = source.lines;
+		if (source.more !== undefined) this.more = source.more;
+		if (source.subtitle !== undefined) this.subtitle = source.subtitle;
+
+		// Follow the tail; a paused view keeps its place but never past the end.
+		if (this.follow) this.scroll = this.maxScroll;
+		else this.scroll = Math.min(this.scroll, this.maxScroll);
+
+		return titleChanged || linesChanged || moreChanged || subtitleChanged;
+	}
+
+	/** The header label: the pane prefix, and the row's title when it has one. */
+	title(prefix: string): string {
+		return this.label ? `${prefix} · ${this.label}` : prefix;
+	}
+
+	/**
+	 * The dim subtitle: the source (a log path), the loaded-window note, and
+	 * whether the view is following. Empty when there is nothing to say.
+	 */
+	subtitleLine(): string {
+		const parts: string[] = [];
+		if (this.subtitle) parts.push(this.subtitle);
+		if (this.more && this.buffer.length > 0) parts.push(`showing last ${this.buffer.length} lines`);
+		if (this.buffer.length > 0) parts.push(this.follow ? "following" : "paused");
+		return parts.join(" · ");
+	}
+
+	/** The visible half-open line range, clamped to the buffer. */
+	window(): { start: number; end: number } {
+		const start = Math.min(Math.max(0, this.scroll), this.maxScroll);
+		return { start, end: Math.min(this.buffer.length, start + this.visible) };
+	}
+
+	/** Scroll to `next`, clamped; leaving the tail clears `follow`. */
+	setScroll(next: number): void {
+		this.scroll = clampScroll(next, this.buffer.length, this.visible);
+		this.follow = this.scroll >= this.maxScroll;
+	}
+
+	/**
+	 * Adopt a new visible height for the coming render: clamp the scroll into
+	 * range, and re-park a following view at the tail. Does not touch `follow`.
+	 */
+	fit(visible: number): void {
+		this.visible = visible;
+		this.scroll = clampScroll(this.scroll, this.buffer.length, this.visible);
+		if (this.follow) this.scroll = this.maxScroll;
+	}
+
+	/** Apply a scroll key; `false` when the key is not one the pane consumes. */
+	handleKey(data: string): boolean {
+		const next = navigateScroll(data, this.scroll, this.buffer.length, this.visible);
+		if (next !== undefined) {
+			this.setScroll(next);
+			return true;
+		}
+		if (data === "g") {
+			this.setScroll(0);
+			return true;
+		}
+		if (data === "G") {
+			this.setScroll(this.maxScroll);
+			return true;
+		}
+		return false;
+	}
+}

package/lib/tui/rows.ts

@@ -0,0 +1,109 @@
+/**
+ * The row grammar: a list row, a checkbox, a status chip, a key/value row, and
+ * an empty state.
+ *
+ * Every row is one line (an empty state is its two), built from the shared
+ * token roles and the shared selection marker, and clipped with `columns.ts` so
+ * it fits the width it was given. The point is that a list row looks the same
+ * whether it is the extension screen, the job list, or the rewind timeline:
+ *
+ *   ❯ ◼ extensions  7 enabled
+ *
+ * Value-only: pure functions, theme passed in.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { clip, padTo, splitRow } from "./columns.ts";
+import { selectionMarker } from "./cursor.ts";
+import { BODY_INDENT, GLYPHS } from "./glyphs.ts";
+import { paint, type TuiRole } from "./tokens.ts";
+
+/** One selectable list row. */
+export interface ListRow {
+	/** Draw the `❯` marker in the accent role. A blank marker column is reserved either way. */
+	selected?: boolean;
+	/**
+	 * A pre-themed cell between the marker and the glyph, e.g. a `checkbox`.
+	 * Reserved by the caller (pass a blank when the row has none) so a column of
+	 * rows stays aligned.
+	 */
+	leading?: string;
+	/** A leading status or type glyph, painted in `glyphRole`. */
+	glyph?: string;
+	glyphRole?: TuiRole;
+	/** The row's text. */
+	label: string;
+	labelRole?: TuiRole;
+	/** Right-aligned meta (a count, a time, a state). */
+	trailing?: string;
+	trailingRole?: TuiRole;
+	/** Extra columns before the marker, for a nested row. */
+	indent?: number;
+}
+
+/**
+ * One list row: an optional indent, the selection marker, an optional glyph,
+ * the label, and right-aligned trailing meta.
+ *
+ * The marker column is always reserved, so selected and unselected rows align.
+ * The trailing meta is the anchor when the terminal is narrow (see
+ * `splitRow`), so a value at the end of the row survives.
+ */
+export function listRow(theme: Theme, width: number, row: ListRow): string {
+	const indent = " ".repeat(Math.max(0, Math.floor(row.indent ?? 0)));
+	const marker = selectionMarker(theme, row.selected === true);
+	const leading = row.leading ? `${row.leading} ` : "";
+	const glyph = row.glyph ? `${paint(theme, row.glyphRole ?? "info", row.glyph)} ` : "";
+	const label = paint(theme, row.labelRole ?? "label", row.label);
+	const trailing = row.trailing ? paint(theme, row.trailingRole ?? "meta", row.trailing) : "";
+	return splitRow(`${indent}${marker}${leading}${glyph}${label}`, trailing, width);
+}
+
+/** The on/off checkbox glyph, in one role per state. */
+export function checkbox(theme: Theme, on: boolean, roles: { on?: TuiRole; off?: TuiRole } = {}): string {
+	return on ? paint(theme, roles.on ?? "ok", GLYPHS.boxOn) : paint(theme, roles.off ?? "faint", GLYPHS.boxOff);
+}
+
+/** A glyph and a short label in one color: the vocabulary of a status chip. */
+export function chip(theme: Theme, glyph: string, label: string, role: TuiRole = "meta"): string {
+	const head = paint(theme, role, glyph);
+	return label ? `${head} ${paint(theme, role, label)}` : head;
+}
+
+/** A fixed-width label column followed by its value. */
+export interface KeyValueRow {
+	label: string;
+	value: string;
+	/** Columns the label column occupies. Default 12. */
+	labelWidth?: number;
+	labelRole?: TuiRole;
+	valueRole?: TuiRole;
+}
+
+/**
+ * One body-indented `label   value` row, the label padded to a fixed column.
+ * The `BODY_INDENT` prefix matches `emptyState`, so a screen's body rows and its
+ * empty state share one indent.
+ */
+export function keyValueRow(theme: Theme, width: number, row: KeyValueRow): string {
+	const labelWidth = Math.max(1, Math.floor(row.labelWidth ?? 12));
+	const label = paint(theme, row.labelRole ?? "meta", padTo(row.label, labelWidth));
+	const value = paint(theme, row.valueRole ?? "label", row.value);
+	return clip(`${" ".repeat(BODY_INDENT)}${label}${value}`, width);
+}
+
+/** A screen's empty state: what is missing, and the next action. */
+export interface EmptyState {
+	/** One line naming what is absent, e.g. `No notes yet.`. */
+	label: string;
+	/** An optional line naming the next action. */
+	hint?: string;
+}
+
+/** The empty-state lines: a body-indented label, then its hint. */
+export function emptyState(theme: Theme, width: number, state: EmptyState): string[] {
+	const indent = " ".repeat(BODY_INDENT);
+	const lines = [clip(`${indent}${paint(theme, "faint", state.label)}`, width)];
+	if (state.hint) lines.push(clip(`${indent}${paint(theme, "faint", state.hint)}`, width));
+	return lines;
+}

package/lib/tui/rules.ts

@@ -0,0 +1,88 @@
+/**
+ * The rule grammar: how a surface draws a horizontal divider.
+ *
+ * Two shapes, built from one idea — a run of a single-column glyph, with an
+ * optional label — so a screen title and a centered rule read as one family:
+ *
+ *   title     Extensions ──────────────────   (label first, accent)
+ *   centered       ╌╌╌╌╌╌ turn 3 ╌╌╌╌╌╌       (label centered)
+ *
+ * A rule degrades to a plain fill rather than truncating a label into an
+ * ellipsis, matching Pi's built-in header.
+ *
+ * Value-only: pure functions, theme passed in.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { paint, type TuiRole } from "./tokens.ts";
+
+/** The glyph and colors a rule is drawn with. */
+export interface RuleStyle {
+	/** Single-column fill glyph. Default `─` (a centered rule defaults to `─` too). */
+	glyph?: string;
+	/** The label's role. */
+	labelRole?: TuiRole;
+	/** The fill's role. */
+	fillRole?: TuiRole;
+}
+
+/** A centered rule's style adds the padding around the label. */
+export interface CenteredRuleStyle extends RuleStyle {
+	/** Spaces on each side of the label. Default 1. */
+	pad?: number;
+}
+
+/** A usable origin: terminal arithmetic starts from one column, never zero. */
+function widthOf(width: number): number {
+	return Math.max(1, Math.floor(width));
+}
+
+/** A full-width divider in one color. */
+export function plainRule(theme: Theme, width: number, style: RuleStyle = {}): string {
+	const w = widthOf(width);
+	return paint(theme, style.fillRole ?? "rule", (style.glyph ?? "─").repeat(w));
+}
+
+/** The label-first shape a screen or panel title uses. */
+export function titleRule(theme: Theme, width: number, label: string, style: RuleStyle = {}): string {
+	return labelRule(theme, width, label, "title", "rule", style);
+}
+
+/** A label-first rule: the label at the margin, a fill to the edge. */
+function labelRule(
+	theme: Theme,
+	width: number,
+	label: string,
+	labelRole: TuiRole,
+	fillRole: TuiRole,
+	style: RuleStyle,
+): string {
+	const w = widthOf(width);
+	const text = label.trim();
+	if (!text) return plainRule(theme, w, style);
+	const labelWidth = visibleWidth(text);
+	if (labelWidth + 1 >= w) return plainRule(theme, w, style);
+	const fill = (style.glyph ?? "─").repeat(w - labelWidth - 1);
+	return paint(theme, style.labelRole ?? labelRole, text) + " " + paint(theme, style.fillRole ?? fillRole, fill);
+}
+
+/** A centered rule: fill, label, and the rest of the fill. */
+export function centeredRule(theme: Theme, width: number, label: string, style: CenteredRuleStyle = {}): string {
+	const w = widthOf(width);
+	const glyph = style.glyph ?? "─";
+	const fillRole = style.fillRole ?? "ruleStrong";
+	if (!label.trim()) return paint(theme, fillRole, glyph.repeat(w));
+	const pad = " ".repeat(Math.max(0, Math.floor(style.pad ?? 1)));
+	const text = `${pad}${label}${pad}`;
+	const labelWidth = visibleWidth(text);
+	if (labelWidth >= w) return paint(theme, fillRole, glyph.repeat(w));
+	const remaining = w - labelWidth;
+	const left = Math.floor(remaining / 2);
+	const right = remaining - left;
+	return (
+		paint(theme, fillRole, glyph.repeat(left)) +
+		paint(theme, style.labelRole ?? "meta", text) +
+		paint(theme, fillRole, glyph.repeat(right))
+	);
+}

package/lib/tui/status-controller.ts

@@ -0,0 +1,107 @@
+/**
+ * The footer status chips two extensions publish the same way.
+ *
+ * A controller remembers the last context it was attached to, repaints the keys
+ * it owns, clears them when its feature is disabled, and never throws: a
+ * non-interactive mode has no UI, so every method no-ops or falls back to plain
+ * text instead.
+ *
+ * The chips themselves are the caller's: it supplies the keys, the counts, and
+ * the roles, so `job` and `watch` share the controller but not their vocabulary.
+ * Value-only: the per-caller state lives in this closure, never in the module.
+ */
+
+import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { paint, type TuiRole } from "./tokens.ts";
+
+/** One chip a controller publishes. */
+export interface StatusChip {
+	/** The `ctx.ui.setStatus` key. */
+	key: string;
+	/** Glyph shown before the count. */
+	glyph: string;
+	/** Count; `0` clears the key. */
+	count: number;
+	/** The design role the chip is drawn in. */
+	role: TuiRole;
+}
+
+/** What a controller publishes, read fresh on every paint. */
+export interface StatusControllerOptions {
+	/** The keys this controller owns, cleared together when it is disabled. */
+	keys: readonly string[];
+	/** Whether the chips should be published at all. */
+	enabled(): boolean;
+	/** The chips for the current state. */
+	chips(): readonly StatusChip[];
+}
+
+/** An attach/paint/clear surface for one extension's footer chips. */
+export interface StatusController {
+	/** Remember the live context; later calls use it when none is passed. */
+	attach(ctx: ExtensionContext): void;
+	/** Forget the context, for example on shutdown or reload. */
+	detach(): void;
+	/** Republish using the attached context. */
+	paint(): void;
+	/** Publish the chips (and attach `ctx` when given). */
+	setStatus(ctx?: ExtensionContext): void;
+}
+
+/** A context's theme, or `undefined` when the UI is unavailable. */
+function themeOf(target: ExtensionContext): Theme | undefined {
+	try {
+		return target.ui.theme;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Paint in role, falling back to plain text when the theme cannot. */
+function safePaint(theme: Theme | undefined, role: TuiRole, text: string): string {
+	if (!theme) return text;
+	try {
+		return paint(theme, role, text);
+	} catch {
+		return text;
+	}
+}
+
+/** Build a controller for one extension's pair of chips. */
+export function createStatusController(options: StatusControllerOptions): StatusController {
+	let ctx: ExtensionContext | undefined;
+
+	const setStatus = (next?: ExtensionContext): void => {
+		if (next) ctx = next;
+		const target = ctx;
+		if (!target) return;
+		try {
+			if (!options.enabled()) {
+				for (const key of options.keys) target.ui.setStatus(key, undefined);
+				return;
+			}
+			const theme = themeOf(target);
+			for (const chip of options.chips()) {
+				// A space before the count keeps the compact chrome form (`▸2`),
+				// while the two chips stay separate segments in the full form.
+				const text = `${chip.glyph} ${chip.count}`;
+				target.ui.setStatus(chip.key, chip.count > 0 ? safePaint(theme, chip.role, text) : undefined);
+			}
+		} catch {
+			// UI may be unavailable in non-interactive modes.
+		}
+	};
+
+	return {
+		attach: (next) => {
+			ctx = next;
+		},
+		detach: () => {
+			ctx = undefined;
+		},
+		paint: () => {
+			setStatus();
+		},
+		setStatus,
+	};
+}