@shanepadgett/tau-tui 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# @shanepadgett/tau-tui
+
+Shared terminal UI components and helpers for Tau Agent extensions.
+
+Use these when Pi built-ins (`ctx.ui.select`, `SelectList`, …) are not enough and you need custom panels, lists, tabs, markers, or key-hint footers that match Tau’s look.
+
+## Install
+
+```bash
+npm install @shanepadgett/tau-tui
+```
+
+Peer dependencies: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`.
+
+## Usage
+
+```ts
+import { ToolPanel, SelectableList, bindingHint } from "@shanepadgett/tau-tui";
+```
+
+Authoring guidance for Tau Agent lives in the agent package docs (`docs/tui.md`).

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@shanepadgett/tau-tui",
+	"version": "0.1.0",
+	"description": "Shared TUI components and helpers for Tau Agent",
+	"type": "module",
+	"license": "MIT",
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src/**/*",
+		"README.md"
+	],
+	"keywords": [
+		"tau",
+		"tui",
+		"terminal",
+		"pi"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/shanepadgett/tau-agent.git",
+		"directory": "packages/tui"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/src/editor-theme.ts

@@ -0,0 +1,15 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { EditorTheme } from "@earendil-works/pi-tui";
+
+export function editorTheme(theme: Theme): EditorTheme {
+	return {
+		borderColor: (text) => theme.fg("accent", text),
+		selectList: {
+			selectedPrefix: (text) => theme.fg("accent", text),
+			selectedText: (text) => theme.fg("accent", text),
+			description: (text) => theme.fg("muted", text),
+			scrollInfo: (text) => theme.fg("dim", text),
+			noMatch: (text) => theme.fg("warning", text),
+		},
+	};
+}

package/src/filter-row.ts

@@ -0,0 +1,11 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Input, truncateToWidth } from "@earendil-works/pi-tui";
+
+export function renderFilterRow(theme: Theme, input: Input, width: number, active: boolean): string {
+	if (!active) {
+		const value = input.getValue();
+		return truncateToWidth(theme.fg("muted", value ? `> ${value}` : ">"), width, "");
+	}
+	const body = input.render(Math.max(1, width))[0] ?? "";
+	return truncateToWidth(body, width, "");
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { editorTheme } from "./editor-theme.ts";
+export { bindingHint, bindingsHint, rawHint, type ToolKeyHint } from "./key-hints.ts";
+export { Marker, type MarkerState } from "./marker.ts";
+export {
+	SelectableList,
+	type SelectableListActionResult,
+	type SelectableListItem,
+	type SelectableListResult,
+} from "./selectable-list.ts";
+export { Tabs, type TabItem } from "./tabs.ts";
+export {
+	createTextRecordSelectPanel,
+	type TextRecordSelectPanelConfig,
+	type TextRecordSelectResult,
+} from "./text-record-select-panel.ts";
+export { formatAge, preview } from "./text.ts";
+export { ToolPanel, type ToolPanelConfig, type ToolPanelFooter } from "./tool-panel.ts";
+export { visibleWindow } from "./viewport.ts";

package/src/key-hints.ts

@@ -0,0 +1,68 @@
+import { keyHint, rawKeyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import { getKeybindings, type Keybinding } from "@earendil-works/pi-tui";
+
+export type ToolKeyHint =
+	| { kind: "binding"; binding: Keybinding; label: string }
+	| { kind: "bindings"; bindings: readonly Keybinding[]; label: string }
+	| { kind: "raw"; key: string; label: string };
+
+export function bindingHint(binding: Keybinding, label: string): ToolKeyHint {
+	return { kind: "binding", binding, label };
+}
+
+export function bindingsHint(bindings: readonly Keybinding[], label: string): ToolKeyHint {
+	return { kind: "bindings", bindings, label };
+}
+
+export function rawHint(key: string, label: string): ToolKeyHint {
+	return { kind: "raw", key, label };
+}
+
+export function renderToolKeyHints(theme: Theme, hints: readonly ToolKeyHint[]): string {
+	const separator = theme.fg("dim", " · ");
+	return hints.map(renderToolKeyHint).join(separator);
+}
+
+function renderToolKeyHint(hint: ToolKeyHint): string {
+	switch (hint.kind) {
+		case "binding":
+			return keyHint(hint.binding, hint.label);
+		case "bindings":
+			return rawKeyHint(formatBindingGroup(hint.bindings), hint.label);
+		case "raw":
+			return rawKeyHint(hint.key, hint.label);
+	}
+}
+
+function formatBindingGroup(bindings: readonly Keybinding[]): string {
+	const keys = bindings
+		.map((binding) => getKeybindings().getKeys(binding)[0])
+		.filter((key) => key !== undefined)
+		.map(formatGroupedKey);
+	return compactRawKeys(keys);
+}
+
+function formatGroupedKey(key: string): string {
+	return key
+		.replace(/\bpageUp\b/g, "pgup")
+		.replace(/\bpageDown\b/g, "pgdn")
+		.replace(/\bup\b/g, "↑")
+		.replace(/\bdown\b/g, "↓")
+		.replace(/\bleft\b/g, "←")
+		.replace(/\bright\b/g, "→");
+}
+
+function compactRawKeys(keys: readonly string[]): string {
+	if (keys.length === 1) return keys[0] ?? "";
+
+	const parts = keys.map((key) => {
+		const separatorIndex = key.lastIndexOf("+");
+		return separatorIndex === -1
+			? { prefix: "", suffix: key }
+			: { prefix: key.slice(0, separatorIndex + 1), suffix: key.slice(separatorIndex + 1) };
+	});
+	const prefix = parts[0]?.prefix ?? "";
+	return prefix && parts.every((part) => part.prefix === prefix)
+		? `${prefix}${parts.map((part) => part.suffix).join("/")}`
+		: keys.join("/");
+}

package/src/list-render.ts

@@ -0,0 +1,61 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { visibleWindow } from "./viewport.ts";
+
+export function renderWindowedList<T>(
+	theme: Theme,
+	items: readonly T[],
+	cursor: number,
+	maxVisible: number,
+	emptyMessage: string,
+	width: number,
+	renderHeader: (width: number) => readonly string[],
+	renderRow: (item: T, index: number, width: number) => string[],
+): string[] {
+	const renderWidth = Math.max(1, width);
+	return [
+		...renderHeader(renderWidth),
+		...renderWindowedRows(theme, items, cursor, maxVisible, emptyMessage, renderWidth, (item, index) =>
+			renderRow(item, index, renderWidth),
+		),
+	];
+}
+
+export function renderPrefixedRow<T, S>(
+	item: T,
+	state: S,
+	width: number,
+	prefix: string,
+	prefixWidthText: string,
+	renderItem: (item: T, state: S, width: number) => string[],
+): string[] {
+	const prefixWidth = visibleWidth(prefixWidthText);
+	const content = renderItem(item, state, Math.max(1, width - prefixWidth));
+	return renderPrefixedLines(prefix, prefixWidth, content, width);
+}
+
+function renderWindowedRows<T>(
+	theme: Theme,
+	items: readonly T[],
+	cursor: number,
+	maxVisible: number,
+	emptyMessage: string,
+	width: number,
+	renderRow: (item: T, index: number) => string[],
+): string[] {
+	if (items.length === 0) return wrapTextWithAnsi(theme.fg("muted", emptyMessage), width);
+
+	const lines: string[] = [];
+	const { start, end } = visibleWindow(cursor, items.length, maxVisible);
+	for (let index = start; index < end; index++) {
+		const item = items[index];
+		if (item !== undefined) lines.push(...renderRow(item, index));
+	}
+	if (start > 0 || end < items.length) lines.push(theme.fg("dim", `  (${cursor + 1}/${items.length})`));
+	return lines;
+}
+
+function renderPrefixedLines(prefix: string, prefixWidth: number, content: readonly string[], width: number): string[] {
+	const indent = " ".repeat(prefixWidth);
+	return content.map((line, index) => truncateToWidth(`${index === 0 ? prefix : indent}${line}`, width, ""));
+}

package/src/marker.ts

@@ -0,0 +1,49 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
+
+type ThemeColor = Parameters<Theme["fg"]>[0];
+
+export type MarkerState = "busy" | "complete" | "muted" | "warning" | "error";
+
+export interface MarkerOptions {
+	theme: Theme;
+	state: MarkerState;
+	label: string;
+	parts: readonly string[];
+}
+
+export class Marker implements Component {
+	private readonly theme: Theme;
+	private readonly state: MarkerState;
+	private readonly label: string;
+	private readonly parts: readonly string[];
+
+	constructor(options: MarkerOptions) {
+		this.theme = options.theme;
+		this.state = options.state;
+		this.label = options.label;
+		this.parts = options.parts;
+	}
+
+	render(width: number): string[] {
+		const color = colorForState(this.state);
+		const dot = this.state === "busy" && Math.floor(Date.now() / 500) % 2 === 1 ? " " : "●";
+		const text = [
+			` ${this.theme.fg(color, dot)}`,
+			this.theme.fg("text", this.theme.bold(this.label)),
+			...this.parts.map((part) => this.theme.fg("muted", part)),
+		]
+			.filter(Boolean)
+			.join(" ");
+
+		return [truncateToWidth(text, width)];
+	}
+
+	invalidate(): void {}
+}
+
+function colorForState(state: MarkerState): ThemeColor {
+	if (state === "warning") return "warning";
+	if (state === "error") return "error";
+	return "dim";
+}

package/src/selectable-list.ts

@@ -0,0 +1,420 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	type Focusable,
+	fuzzyFilter,
+	getKeybindings,
+	Input,
+	Key,
+	type KeyId,
+	matchesKey,
+} from "@earendil-works/pi-tui";
+import { renderFilterRow } from "./filter-row.ts";
+import { bindingHint, bindingsHint, rawHint, type ToolKeyHint } from "./key-hints.ts";
+import { renderPrefixedRow, renderWindowedList } from "./list-render.ts";
+import { clampIndex } from "./viewport.ts";
+
+const NON_PRINTABLE_KEYS = new Set<string>([
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageUp",
+	"pageDown",
+	"up",
+	"down",
+	"left",
+	"right",
+	"f1",
+	"f2",
+	"f3",
+	"f4",
+	"f5",
+	"f6",
+	"f7",
+	"f8",
+	"f9",
+	"f10",
+	"f11",
+	"f12",
+]);
+
+export interface SelectableListItem {
+	id: string;
+}
+
+export type SelectableListActionTarget = "current" | "currentOrSelection" | "visible" | "olderThanCursor";
+export type SelectableListResolvedTarget = "cursor" | "selection" | "visible" | "olderThanCursor";
+
+export interface SelectableListAction {
+	id: string;
+	key: KeyId;
+	hint: ToolKeyHint;
+	target?: SelectableListActionTarget;
+}
+
+export interface SelectableListActionResult<T extends SelectableListItem> {
+	actionId: string;
+	items: readonly T[];
+	target: SelectableListResolvedTarget;
+}
+
+export type SelectableListResult<T extends SelectableListItem> =
+	| { kind: "cancel" }
+	| { kind: "primary"; items: readonly T[]; target: SelectableListResolvedTarget }
+	| ({ kind: "action" } & SelectableListActionResult<T>);
+
+export interface SelectableListRowState {
+	active: boolean;
+	selected: boolean;
+	index: number;
+}
+
+export type SelectableListSelection =
+	| { kind: "single"; primaryLabel: string }
+	| { kind: "multi"; primaryLabel?: string };
+
+export interface SelectableListFilter<T extends SelectableListItem> {
+	searchText(item: T): string;
+}
+
+export interface SelectableListConfig<T extends SelectableListItem> {
+	items: readonly T[];
+	emptyMessage: string;
+	selection: SelectableListSelection;
+	filter?: SelectableListFilter<T>;
+	actions: readonly SelectableListAction[];
+	cancelLabel?: string;
+	maxVisible: number;
+	// Render row content only. SelectableList owns cursor, selection, and filter chrome.
+	renderItem(item: T, state: SelectableListRowState, width: number): string[];
+	onResult(result: SelectableListResult<T>): void;
+	onSelectionChange?: (items: readonly T[]) => void;
+}
+
+export class SelectableList<T extends SelectableListItem> implements Component, Focusable {
+	private readonly theme: Theme;
+	private readonly config: SelectableListConfig<T>;
+	private readonly filterInput = new Input();
+	private readonly selected = new Set<string>();
+	private items: readonly T[];
+	private cursor = 0;
+	private filterActive: boolean;
+	private _focused = false;
+
+	constructor(theme: Theme, config: SelectableListConfig<T>) {
+		this.theme = theme;
+		this.config = config;
+		this.items = config.items;
+		this.filterActive = config.filter !== undefined && config.selection.kind === "single";
+		this.filterInput.focused = this.filterActive;
+		assertFilterSafeActions(config.actions, config.filter !== undefined && config.selection.kind === "single");
+	}
+
+	get focused(): boolean {
+		return this._focused;
+	}
+
+	set focused(value: boolean) {
+		this._focused = value;
+		this.filterInput.focused = value && this.filterActive;
+	}
+
+	setItems(items: readonly T[], activeId?: string): void {
+		this.items = items;
+		const ids = new Set(items.map((item) => item.id));
+		for (const id of this.selected) {
+			if (!ids.has(id)) this.selected.delete(id);
+		}
+		if (activeId !== undefined) {
+			const index = this.filteredItems().findIndex((item) => item.id === activeId);
+			if (index >= 0) this.cursor = index;
+		}
+		this.clampCursor();
+		this.emitSelectionChange();
+	}
+
+	clearSelection(): void {
+		this.selected.clear();
+		this.emitSelectionChange();
+	}
+
+	setSelectedIds(ids: readonly string[]): void {
+		const validIds = new Set(this.items.map((item) => item.id));
+		this.selected.clear();
+		for (const id of ids) {
+			if (validIds.has(id)) this.selected.add(id);
+		}
+		this.emitSelectionChange();
+	}
+
+	getCurrentItem(): T | undefined {
+		return this.filteredItems()[this.cursor];
+	}
+
+	isFilterFocused(): boolean {
+		return this.config.selection.kind === "multi" && this.filterActive;
+	}
+
+	getKeyHints(): ToolKeyHint[] {
+		if (this.isFilterFocused()) {
+			return [
+				bindingsHint(["tui.select.up", "tui.select.down"], "move"),
+				rawHint("Enter", "apply filter"),
+				rawHint("Esc", "cancel filter"),
+				rawHint("ctrl+c", "clear filter"),
+			];
+		}
+
+		const primaryLabel = this.config.selection.primaryLabel;
+		return [
+			bindingsHint(["tui.select.up", "tui.select.down"], "move"),
+			...(primaryLabel ? [bindingHint("tui.select.confirm", primaryLabel)] : []),
+			...(this.config.selection.kind === "multi" ? this.multiSelectHints() : []),
+			...this.config.actions.map((action) => action.hint),
+			...(this.config.cancelLabel ? [bindingHint("tui.select.cancel", this.config.cancelLabel)] : []),
+		];
+	}
+
+	handleInput(data: string): void {
+		const keybindings = getKeybindings();
+		if (this.config.selection.kind === "multi" && this.filterActive && matchesKey(data, Key.ctrl("c"))) {
+			this.clearFilter();
+			return;
+		}
+		if (
+			this.config.selection.kind === "multi" &&
+			this.filterActive &&
+			keybindings.matches(data, "tui.select.cancel")
+		) {
+			this.clearFilterFocus();
+			return;
+		}
+		if (
+			this.config.selection.kind === "multi" &&
+			this.filterActive &&
+			keybindings.matches(data, "tui.select.confirm")
+		) {
+			this.blurFilter();
+			return;
+		}
+		if (keybindings.matches(data, "tui.select.cancel")) {
+			this.config.onResult({ kind: "cancel" });
+			return;
+		}
+
+		if (keybindings.matches(data, "tui.select.confirm")) {
+			this.primary();
+			return;
+		}
+
+		if (this.handleListKey(data)) return;
+		if (this.config.selection.kind === "multi" && this.handleMultiSelectKey(data)) return;
+		if (
+			this.config.selection.kind === "multi" &&
+			this.config.filter &&
+			!this.filterActive &&
+			matchesKey(data, Key.slash)
+		) {
+			this.activateFilter();
+			return;
+		}
+		if (this.config.selection.kind === "multi" && this.filterActive) {
+			this.handleFilterInput(data);
+			return;
+		}
+
+		for (const action of this.config.actions) {
+			if (matchesKey(data, action.key)) {
+				this.runAction(action);
+				return;
+			}
+		}
+
+		if (this.config.filter && this.config.selection.kind === "single") this.handleFilterInput(data);
+	}
+
+	render(width: number): string[] {
+		return renderWindowedList(
+			this.theme,
+			this.filteredItems(),
+			this.cursor,
+			this.config.maxVisible,
+			this.config.emptyMessage,
+			width,
+			(renderWidth) =>
+				this.config.filter
+					? [renderFilterRow(this.theme, this.filterInput, renderWidth, this.filterActive), ""]
+					: [],
+			(item, index, renderWidth) => this.renderRow(item, index, renderWidth),
+		);
+	}
+
+	invalidate(): void {}
+
+	private multiSelectHints(): ToolKeyHint[] {
+		if (!this.config.filter) return [rawHint("Space", "select"), rawHint("c", "clear")];
+		return this.filterActive
+			? [rawHint("Enter", "apply filter"), rawHint("Esc", "cancel filter"), rawHint("ctrl+c", "clear filter")]
+			: [rawHint("Space", "select"), rawHint("c", "clear"), rawHint("/", "filter")];
+	}
+
+	private primary(): void {
+		const filtered = this.filteredItems();
+		if (this.config.selection.kind === "multi") {
+			this.config.onResult({
+				kind: "primary",
+				items: this.items.filter((item) => this.selected.has(item.id)),
+				target: "selection",
+			});
+			return;
+		}
+
+		const current = filtered[this.cursor];
+		this.config.onResult({ kind: "primary", items: current ? [current] : [], target: "cursor" });
+	}
+
+	private handleListKey(data: string): boolean {
+		const keybindings = getKeybindings();
+		if (keybindings.matches(data, "tui.select.up")) {
+			const filtered = this.filteredItems();
+			this.cursor = filtered.length === 0 ? 0 : Math.max(0, this.cursor - 1);
+			return true;
+		}
+		if (keybindings.matches(data, "tui.select.down")) {
+			const filtered = this.filteredItems();
+			this.cursor = filtered.length === 0 ? 0 : Math.min(this.cursor + 1, filtered.length - 1);
+			return true;
+		}
+		return false;
+	}
+
+	private handleMultiSelectKey(data: string): boolean {
+		const filterCapturesText = this.config.filter && this.filterActive;
+		const toggleKey = Key.space;
+		const clearKey = filterCapturesText ? Key.ctrl("c") : "c";
+		if (filterCapturesText && matchesKey(data, clearKey)) {
+			this.clearFilter();
+			return true;
+		}
+		if (filterCapturesText) return false;
+		if (matchesKey(data, toggleKey) || (!filterCapturesText && data === " ")) {
+			const item = this.filteredItems()[this.cursor];
+			if (item && this.selected.has(item.id)) this.selected.delete(item.id);
+			else if (item) this.selected.add(item.id);
+			this.emitSelectionChange();
+			return true;
+		}
+		if (matchesKey(data, clearKey)) {
+			this.selected.clear();
+			this.emitSelectionChange();
+			return true;
+		}
+		return false;
+	}
+
+	private handleFilterInput(data: string): void {
+		const previous = this.filterInput.getValue();
+		this.filterInput.handleInput(data);
+		if (this.filterInput.getValue() !== previous) this.cursor = 0;
+		this.clampCursor();
+	}
+
+	private activateFilter(): void {
+		this.filterActive = true;
+		this.filterInput.focused = this._focused;
+		this.clampCursor();
+	}
+
+	private blurFilter(): void {
+		this.filterActive = false;
+		this.filterInput.focused = false;
+		this.clampCursor();
+	}
+
+	private clearFilter(): void {
+		this.filterInput.setValue("");
+		this.cursor = 0;
+		this.clampCursor();
+	}
+
+	private clearFilterFocus(): void {
+		this.clearFilter();
+		this.blurFilter();
+	}
+
+	private renderRow(item: T, index: number, width: number): string[] {
+		const state = { active: index === this.cursor, selected: this.selected.has(item.id), index };
+		const prefix = this.config.selection.kind === "multi" ? this.multiPrefix(state) : this.singlePrefix(state);
+		const placeholder = this.config.selection.kind === "multi" ? "› [ ] " : "› ";
+		return renderPrefixedRow(item, state, width, prefix, placeholder, this.config.renderItem);
+	}
+
+	private singlePrefix(state: SelectableListRowState): string {
+		return state.active ? this.theme.fg("accent", "› ") : "  ";
+	}
+
+	private multiPrefix(state: SelectableListRowState): string {
+		const marker = state.active ? this.theme.fg("accent", "› ") : "  ";
+		const box = state.selected ? this.theme.fg("success", "[x]") : this.theme.fg("dim", "[ ]");
+		return `${marker}${box} `;
+	}
+
+	private filteredItems(): readonly T[] {
+		const filter = this.config.filter;
+		if (!filter) return this.items;
+		const query = this.filterInput.getValue().trim();
+		if (!query) return this.items;
+		return fuzzyFilter([...this.items], query, filter.searchText);
+	}
+
+	private runAction(action: SelectableListAction): void {
+		const resolved = this.resolveTarget(action.target ?? "current");
+		this.config.onResult({ kind: "action", actionId: action.id, items: resolved.items, target: resolved.target });
+	}
+
+	private resolveTarget(target: SelectableListActionTarget): {
+		items: readonly T[];
+		target: SelectableListResolvedTarget;
+	} {
+		const filtered = this.filteredItems();
+		if (target === "visible") return { items: filtered, target: "visible" };
+		if (target === "olderThanCursor") return { items: filtered.slice(this.cursor + 1), target: "olderThanCursor" };
+		if (target === "currentOrSelection" && this.selected.size > 0) {
+			return { items: this.items.filter((item) => this.selected.has(item.id)), target: "selection" };
+		}
+		const current = filtered[this.cursor];
+		return { items: current ? [current] : [], target: "cursor" };
+	}
+
+	private clampCursor(): void {
+		this.cursor = clampIndex(this.cursor, this.filteredItems().length);
+	}
+
+	private emitSelectionChange(): void {
+		this.config.onSelectionChange?.(this.items.filter((item) => this.selected.has(item.id)));
+	}
+}
+
+function assertFilterSafeActions(actions: readonly SelectableListAction[], filtered: boolean): void {
+	if (!filtered) return;
+	for (const action of actions) assertFilterSafeKey(action.key, action.id);
+}
+
+function assertFilterSafeKey(key: KeyId, label: string): void {
+	if (isFilterSafeKey(key)) return;
+	throw new Error(`Filtered list action ${label} uses text key ${key}. Use ctrl, alt, super, or a non-printable key.`);
+}
+
+function isFilterSafeKey(key: KeyId): boolean {
+	if (key.includes("ctrl+") || key.includes("alt+") || key.includes("super+")) return true;
+	const base = key.split("+").at(-1) ?? key;
+	return NON_PRINTABLE_KEYS.has(base) && base !== "space";
+}

package/src/tabs.ts

@@ -0,0 +1,91 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { rawHint, type ToolKeyHint } from "./key-hints.ts";
+
+export interface TabItem {
+	id: string;
+	label: string;
+	count?: number;
+	body: Component;
+	getKeyHints?: () => readonly ToolKeyHint[];
+}
+
+export class Tabs implements Component {
+	private readonly theme: Theme;
+	private tabs: readonly TabItem[];
+	private activeId: string;
+
+	constructor(theme: Theme, tabs: readonly TabItem[], activeId: string) {
+		this.theme = theme;
+		this.tabs = tabs;
+		this.activeId = tabs.some((tab) => tab.id === activeId) ? activeId : (tabs[0]?.id ?? "");
+	}
+
+	getActiveId(): string {
+		return this.activeId;
+	}
+
+	setActiveId(id: string): void {
+		if (this.tabs.some((tab) => tab.id === id)) this.activeId = id;
+	}
+
+	setTabs(tabs: readonly TabItem[]): void {
+		this.tabs = tabs;
+		if (!tabs.some((tab) => tab.id === this.activeId)) this.activeId = tabs[0]?.id ?? "";
+	}
+
+	handleKey(data: string): boolean {
+		const direction =
+			matchesKey(data, Key.tab) || matchesKey(data, Key.right)
+				? 1
+				: matchesKey(data, Key.shift("tab")) || matchesKey(data, Key.left)
+					? -1
+					: 0;
+		if (direction === 0) return false;
+		if (this.tabs.length === 0) return true;
+		const currentIndex = this.tabs.findIndex((tab) => tab.id === this.activeId);
+		const start = currentIndex >= 0 ? currentIndex : 0;
+		const next = this.tabs[(start + direction + this.tabs.length) % this.tabs.length];
+		if (next) this.activeId = next.id;
+		return true;
+	}
+
+	handleInput(data: string): void {
+		if (this.handleKey(data)) return;
+		this.activeBody()?.handleInput?.(data);
+	}
+
+	getKeyHints(): ToolKeyHint[] {
+		return [rawHint("Tab/←/→", "switch tab"), ...(this.activeTab()?.getKeyHints?.() ?? [])];
+	}
+
+	render(width: number): string[] {
+		const renderWidth = Math.max(1, width);
+		const parts = this.tabs.map((tab) => {
+			const count = tab.count === undefined ? "" : ` ${this.theme.fg("dim", String(tab.count))}`;
+			const text = ` ${tab.label}${count} `;
+			return tab.id === this.activeId
+				? this.theme.bg("selectedBg", this.theme.fg("text", this.theme.bold(text)))
+				: this.theme.fg("muted", text);
+		});
+		const lines = wrapTextWithAnsi(parts.join(" "), renderWidth).map((line) =>
+			truncateToWidth(line, renderWidth, ""),
+		);
+		const activeBody = this.activeBody()?.render(renderWidth) ?? [];
+		if (activeBody.length > 0) lines.push("");
+		lines.push(...activeBody.map((line) => truncateToWidth(line, renderWidth, "")));
+		return lines;
+	}
+
+	invalidate(): void {
+		for (const tab of this.tabs) tab.body.invalidate();
+	}
+
+	private activeBody(): Component | undefined {
+		return this.activeTab()?.body;
+	}
+
+	private activeTab(): TabItem | undefined {
+		return this.tabs.find((tab) => tab.id === this.activeId);
+	}
+}

package/src/text-record-select-panel.ts

@@ -0,0 +1,92 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { formatAge, preview } from "./text.ts";
+import {
+	SelectableList,
+	type SelectableListAction,
+	type SelectableListItem,
+	type SelectableListRowState,
+} from "./selectable-list.ts";
+import { ToolPanel } from "./tool-panel.ts";
+
+export interface TextRecordSelectItem extends SelectableListItem {
+	text: string;
+	createdAt?: number;
+}
+
+export type TextRecordSelectResult<T extends TextRecordSelectItem> =
+	| { kind: "cancel" }
+	| { kind: "primary"; item: T }
+	| { kind: "action"; actionId: string; item: T };
+
+export interface TextRecordSelectPanelConfig {
+	title: string;
+	path: string;
+	emptyMessage: string;
+	primaryLabel: string;
+	actions: readonly SelectableListAction[];
+	expandActiveItem: boolean;
+}
+
+export function createTextRecordSelectPanel<T extends TextRecordSelectItem>(
+	theme: Theme,
+	items: readonly T[],
+	config: TextRecordSelectPanelConfig,
+	done: (result: TextRecordSelectResult<T>) => void,
+): Component {
+	const list = new SelectableList(theme, {
+		items,
+		emptyMessage: config.emptyMessage,
+		selection: { kind: "single", primaryLabel: config.primaryLabel },
+		filter: { searchText: (item) => item.text },
+		actions: config.actions,
+		cancelLabel: "cancel",
+		maxVisible: 12,
+		renderItem: (item, state, width) => renderTextRecord(theme, item, state, config.expandActiveItem, width),
+		onResult: (result) => {
+			if (result.kind === "cancel") {
+				done(result);
+				return;
+			}
+			const item = result.items[0];
+			if (!item) return;
+			done(
+				result.kind === "primary" ? { kind: "primary", item } : { kind: "action", actionId: result.actionId, item },
+			);
+		},
+	});
+	const panel = new ToolPanel(theme, {
+		title: config.title,
+		secondary: `${items.length} total · ${config.path}`,
+		body: list,
+		footer: { kind: "hints", hints: list.getKeyHints() },
+	});
+
+	return {
+		handleInput: (data) => list.handleInput(data),
+		render: (width) => panel.render(width),
+		invalidate: () => panel.invalidate(),
+	};
+}
+
+function renderTextRecord(
+	theme: Theme,
+	item: TextRecordSelectItem,
+	state: SelectableListRowState,
+	expandActiveItem: boolean,
+	width: number,
+): string[] {
+	const age = item.createdAt === undefined ? "" : theme.fg("dim", `  ${formatAge(item.createdAt)}`);
+	if (!state.active || !expandActiveItem) {
+		const label = theme.fg(state.active ? "accent" : "text", preview(item.text));
+		return [truncateToWidth(`${label}${age}`, width, "")];
+	}
+
+	const body = wrapTextWithAnsi(theme.fg("accent", item.text), width);
+	const lines = body.map((line) => truncateToWidth(line, width, ""));
+	const lastIndex = lines.length - 1;
+	if (age && lastIndex >= 0 && visibleWidth(lines[lastIndex] ?? "") + visibleWidth(age) <= width) {
+		lines[lastIndex] = `${lines[lastIndex]}${age}`;
+	}
+	return lines;
+}

package/src/text.ts

@@ -0,0 +1,18 @@
+// Display text helpers for TUI components.
+
+export function preview(text: string, max = 80): string {
+	const oneLine = text.replace(/\s+/g, " ").trim();
+	return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine;
+}
+
+export function formatAge(createdAt: number): string {
+	const seconds = Math.max(0, Math.round((Date.now() - createdAt) / 1000));
+	if (seconds < 60) return "just now";
+	const minutes = Math.round(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.round(minutes / 60);
+	if (hours < 48) return `${hours}h ago`;
+	const days = Math.round(hours / 24);
+	if (days < 30) return `${days}d ago`;
+	return new Date(createdAt).toISOString().slice(0, 10);
+}

package/src/tool-panel.ts

@@ -0,0 +1,90 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { renderToolKeyHints, type ToolKeyHint } from "./key-hints.ts";
+
+export type ToolPanelFooter =
+	| { kind: "hints"; hints: readonly ToolKeyHint[] }
+	| { kind: "destructiveAck"; message: string; hints: readonly ToolKeyHint[] }
+	| { kind: "infoAck"; message: string; hints: readonly ToolKeyHint[] };
+
+export interface ToolPanelConfig {
+	title: string;
+	secondary?: string;
+	header?: Component | readonly string[];
+	body: Component;
+	footer: ToolPanelFooter;
+}
+
+export class ToolPanel implements Component {
+	private readonly theme: Theme;
+	private config: ToolPanelConfig;
+
+	constructor(theme: Theme, config: ToolPanelConfig) {
+		this.theme = theme;
+		this.config = config;
+	}
+
+	render(width: number): string[] {
+		const renderWidth = Math.max(1, width);
+		const body = this.config.body.render(renderWidth).map((line) => truncateToWidth(line, renderWidth, ""));
+		const footer = this.renderFooter(renderWidth);
+		const lines: string[] = [];
+
+		lines.push(this.theme.fg("border", "─".repeat(renderWidth)));
+		lines.push(...this.renderTitle(renderWidth));
+		const header = this.renderHeader(renderWidth);
+		if (header.length > 0) lines.push("");
+		lines.push(...header);
+		if (body.length > 0) lines.push("");
+		lines.push(...body);
+		if (footer.length > 0) lines.push("");
+		lines.push(...footer);
+		lines.push(this.theme.fg("border", "─".repeat(renderWidth)));
+
+		return lines;
+	}
+
+	invalidate(): void {
+		const header = this.config.header;
+		if (header && "render" in header) header.invalidate();
+		this.config.body.invalidate();
+	}
+
+	private renderTitle(width: number): string[] {
+		const title = this.theme.fg("accent", this.theme.bold(this.config.title));
+		const lines = [truncateToWidth(title, width, "")];
+		if (this.config.secondary) {
+			lines.push(
+				...wrapTextWithAnsi(this.theme.fg("dim", this.config.secondary), width).map((line) =>
+					truncateToWidth(line, width, ""),
+				),
+			);
+		}
+		return lines;
+	}
+
+	private renderHeader(width: number): string[] {
+		const header = this.config.header;
+		if (!header) return [];
+
+		if ("render" in header) {
+			return header.render(width).map((line) => truncateToWidth(line, width, ""));
+		}
+
+		return header.flatMap((line) =>
+			wrapTextWithAnsi(line, width).map((wrapped) => truncateToWidth(wrapped, width, "")),
+		);
+	}
+
+	private renderFooter(width: number): string[] {
+		const footer = this.config.footer;
+		const hintText = renderToolKeyHints(this.theme, footer.hints);
+		const text =
+			footer.kind === "hints"
+				? hintText
+				: `${this.theme.fg(footer.kind === "destructiveAck" ? "error" : "accent", footer.message)}  ${hintText}`;
+
+		if (!text) return [];
+		return wrapTextWithAnsi(text, width).map((line) => truncateToWidth(line, width, ""));
+	}
+}

package/src/viewport.ts

@@ -0,0 +1,14 @@
+export interface VisibleWindow {
+	start: number;
+	end: number;
+}
+
+export function clampIndex(index: number, length: number): number {
+	return Math.min(Math.max(0, index), Math.max(0, length - 1));
+}
+
+export function visibleWindow(cursor: number, length: number, maxVisible: number): VisibleWindow {
+	const visible = Math.max(1, maxVisible);
+	const start = Math.max(0, Math.min(cursor - Math.floor(visible / 2), length - visible));
+	return { start, end: Math.min(length, start + visible) };
+}