gentle-pi 2.4.0 → 2.5.0

package/lib/agents-widget.ts

@@ -0,0 +1,222 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { isFinished, TASK_STATUS, type TaskRecord, type TaskStatus } from "./agents-protocol.ts";
+import { formatTokens } from "./shell-bar.ts";
+import { CARD_TONE, cardInnerWidth, renderCard, type CardTheme, type CardTone } from "./shell-card.ts";
+
+// Gentle Agents widget: the card above the editor. Reads task records only
+// (status, prompt, counters, timestamps), so drawing it costs nothing per
+// event. One row per task: glyph, agent, task summary, then
+// model · tokens · cost · time right-aligned.
+
+export const AGENTS_GLYPH = "❀";
+
+export interface AgentsWidgetOptions {
+	collapsed: boolean;
+	collapseKey?: string;
+	// Rows the card may spend on tasks; beyond that the rest fold into one
+	// "… N more" line so the card never pushes the editor off the screen.
+	maxRows?: number;
+	viewKey?: string;
+}
+
+interface StatusLook {
+	glyph: string;
+	role: string;
+}
+
+interface Columns {
+	inner: number;
+	name: number;
+	task: number;
+	meta: number;
+	withModel: boolean;
+}
+
+const LOOK: Record<TaskStatus, StatusLook> = {
+	[TASK_STATUS.QUEUED]: { glyph: "○", role: "muted" },
+	[TASK_STATUS.RUNNING]: { glyph: "◐", role: "accent" },
+	[TASK_STATUS.WAITING]: { glyph: "?", role: "warning" },
+	[TASK_STATUS.COMPLETED]: { glyph: "✓", role: "success" },
+	[TASK_STATUS.FAILED]: { glyph: "✗", role: "error" },
+	[TASK_STATUS.CANCELLED]: { glyph: "–", role: "dim" },
+	[TASK_STATUS.TIMED_OUT]: { glyph: "✗", role: "error" },
+};
+const FINISHED_TTL_MS = 60_000;
+const MAX_FINISHED = 3;
+const ROWS_MIN = 3;
+const ROWS_MAX = 8;
+const ROWS_RATIO = 0.25;
+const SHOW_PRIORITY: Record<TaskStatus, number> = {
+	[TASK_STATUS.WAITING]: 0,
+	[TASK_STATUS.RUNNING]: 1,
+	[TASK_STATUS.QUEUED]: 2,
+	[TASK_STATUS.COMPLETED]: 3,
+	[TASK_STATUS.FAILED]: 3,
+	[TASK_STATUS.CANCELLED]: 3,
+	[TASK_STATUS.TIMED_OUT]: 3,
+};
+const NAME_MAX = 20;
+const TASK_MIN = 12;
+const GLYPH_GAP = "  ";
+const COLUMN_GAP = "  ";
+const NAME_ROLE = "text";
+const TASK_ROLE = "muted";
+const META_ROLE = "dim";
+const ELLIPSIS = "…";
+
+export function formatElapsed(ms: number): string {
+	const total = Math.max(0, Math.floor(ms / 1000));
+	if (total < 60) return `${total}s`;
+	const minutes = Math.floor(total / 60);
+	if (minutes < 60) return `${minutes}m${String(total % 60).padStart(2, "0")}s`;
+	return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+function clip(text: string, width: number): string {
+	if (visibleWidth(text) <= width) return text;
+	let out = "";
+	for (const char of text) {
+		if (visibleWidth(out + char) > width - 1) break;
+		out += char;
+	}
+	return `${out}${ELLIPSIS}`;
+}
+
+// Every active task plus the few that finished within the last minute, in
+// the order they started, so a batch reads top to bottom like a timeline.
+export function widgetTasks(tasks: readonly TaskRecord[], now: number): TaskRecord[] {
+	const active = tasks.filter((task) => !isFinished(task.status));
+	const finished = tasks
+		.filter((task) => isFinished(task.status) && task.endedAt !== null && now - task.endedAt < FINISHED_TTL_MS)
+		.sort((a, b) => (b.endedAt ?? 0) - (a.endedAt ?? 0))
+		.slice(0, MAX_FINISHED);
+	return [...active, ...finished].sort(startOrder);
+}
+
+// How long until the next finished row leaves the card, or undefined when no
+// shown row is waiting to expire. The host asks for exactly one frame at that
+// moment instead of ticking while the terminal is idle.
+export function widgetExpiryMs(tasks: readonly TaskRecord[], now: number): number | undefined {
+	const deadlines = widgetTasks(tasks, now)
+		.filter((task) => isFinished(task.status) && task.endedAt !== null)
+		.map((task) => (task.endedAt ?? now) + FINISHED_TTL_MS - now);
+	return deadlines.length === 0 ? undefined : Math.max(1, Math.min(...deadlines));
+}
+
+// A quarter of the terminal, never fewer than three rows nor more than eight.
+export function widgetRows(terminalRows: number | undefined): number {
+	if (terminalRows === undefined) return ROWS_MAX;
+	return Math.max(ROWS_MIN, Math.min(ROWS_MAX, Math.floor(terminalRows * ROWS_RATIO)));
+}
+
+function startOrder(a: TaskRecord, b: TaskRecord): number {
+	return (a.startedAt ?? a.createdAt) - (b.startedAt ?? b.createdAt);
+}
+
+// When the card overflows, questions and running work keep their rows first;
+// what stays visible is still drawn in start order.
+function visibleRows(shown: readonly TaskRecord[], maxRows: number | undefined): { listed: TaskRecord[]; hidden: number } {
+	if (maxRows === undefined || shown.length <= maxRows) return { listed: [...shown], hidden: 0 };
+	const kept = Math.max(1, maxRows - 1);
+	const listed = [...shown]
+		.sort((a, b) => SHOW_PRIORITY[a.status] - SHOW_PRIORITY[b.status] || startOrder(a, b))
+		.slice(0, kept)
+		.sort(startOrder);
+	return { listed, hidden: shown.length - listed.length };
+}
+
+function overflowRow(hidden: number, theme: CardTheme, viewKey: string | undefined): string {
+	const hint = viewKey ? ` · ${viewKey} to view` : "";
+	return theme.fg(META_ROLE, `${ELLIPSIS} ${hidden} more${hint}`);
+}
+
+function elapsed(task: TaskRecord, now: number): string {
+	return task.startedAt === null ? "" : formatElapsed((task.endedAt ?? now) - task.startedAt);
+}
+
+function modelLabel(task: TaskRecord): string {
+	const id = task.model.includes("/") ? task.model.slice(task.model.lastIndexOf("/") + 1) : task.model;
+	return id === "default" ? "" : id;
+}
+
+function meta(task: TaskRecord, now: number, withModel: boolean): string {
+	if (task.status === TASK_STATUS.QUEUED) return "queued";
+	const parts = [withModel ? modelLabel(task) : "", task.tokens > 0 ? formatTokens(task.tokens) : "", task.cost > 0 ? `$${task.cost.toFixed(2)}` : "", elapsed(task, now)];
+	return parts.filter((part) => part.length > 0).join(" · ");
+}
+
+function taskText(task: TaskRecord): string {
+	if (task.status === TASK_STATUS.WAITING) return task.lastStep;
+	if (task.error) return task.error;
+	return task.label;
+}
+
+// Narrow cards give up the task column first, then the model label.
+function columns(tasks: readonly TaskRecord[], inner: number, now: number): Columns {
+	const name = Math.min(NAME_MAX, Math.max(...tasks.map((task) => visibleWidth(task.agent))));
+	const fixed = 1 + GLYPH_GAP.length + name + COLUMN_GAP.length;
+	const metaWidth = (withModel: boolean) => Math.max(...tasks.map((task) => visibleWidth(meta(task, now, withModel))));
+	const full = metaWidth(true);
+	const task = inner - fixed - full - COLUMN_GAP.length;
+	if (task >= TASK_MIN) return { inner, name, meta: full, task, withModel: true };
+	return { inner, name, meta: metaWidth(false), task: 0, withModel: false };
+}
+
+function row(task: TaskRecord, theme: CardTheme, cols: Columns, now: number): string[] {
+	const look = LOOK[task.status];
+	const name = clip(task.agent, cols.name);
+	const head = `${theme.fg(look.role, look.glyph)}${GLYPH_GAP}${theme.fg(NAME_ROLE, name)}${" ".repeat(cols.name - visibleWidth(name))}`;
+	const tail = theme.fg(META_ROLE, meta(task, now, cols.withModel).padStart(cols.meta));
+	if (cols.task === 0) return [`${head}${" ".repeat(Math.max(COLUMN_GAP.length, cols.inner - visibleWidth(head) - visibleWidth(tail)))}${tail}`];
+	const text = clip(taskText(task), cols.task);
+	return [`${head}${COLUMN_GAP}${theme.fg(TASK_ROLE, text)}${" ".repeat(cols.task - visibleWidth(text))}${COLUMN_GAP}${tail}`];
+}
+
+function counts(tasks: readonly TaskRecord[]): string {
+	const labels: Array<[TaskStatus, string]> = [
+		[TASK_STATUS.RUNNING, "active"],
+		[TASK_STATUS.WAITING, "waiting"],
+		[TASK_STATUS.QUEUED, "queued"],
+		[TASK_STATUS.COMPLETED, "done"],
+		[TASK_STATUS.FAILED, "failed"],
+		[TASK_STATUS.TIMED_OUT, "timed out"],
+		[TASK_STATUS.CANCELLED, "cancelled"],
+	];
+	return labels
+		.map(([status, label]) => [tasks.filter((task) => task.status === status).length, label] as const)
+		.filter(([count]) => count > 0)
+		.map(([count, label]) => `${count} ${label}`)
+		.join(" · ");
+}
+
+function tone(tasks: readonly TaskRecord[]): CardTone {
+	if (tasks.some((task) => task.status === TASK_STATUS.WAITING)) return CARD_TONE.WARNING;
+	if (tasks.some((task) => task.status === TASK_STATUS.FAILED || task.status === TASK_STATUS.TIMED_OUT)) return CARD_TONE.ERROR;
+	return CARD_TONE.INFO;
+}
+
+// The batch clock: from the first start among the shown tasks until now, or
+// until the last one ended when nothing is running.
+function batchElapsed(tasks: readonly TaskRecord[], now: number): string | undefined {
+	const starts = tasks.map((task) => task.startedAt).filter((value): value is number => value !== null);
+	if (starts.length === 0) return undefined;
+	const active = tasks.some((task) => !isFinished(task.status));
+	const end = active ? now : Math.max(...tasks.map((task) => task.endedAt ?? now));
+	return formatElapsed(end - Math.min(...starts));
+}
+
+export function renderAgentsCard(tasks: readonly TaskRecord[], theme: CardTheme, width: number, now: number, options: AgentsWidgetOptions): string[] {
+	const shown = widgetTasks(tasks, now);
+	if (shown.length === 0) return [];
+	const cols = columns(shown, cardInnerWidth(width), now);
+	const { listed, hidden } = options.collapsed ? { listed: [shown[0]], hidden: 0 } : visibleRows(shown, options.maxRows);
+	const hint = options.collapsed && options.collapseKey ? `${options.collapseKey} expand` : batchElapsed(shown, now);
+	const body = listed.flatMap((task) => row(task, theme, cols, now));
+	if (hidden > 0) body.push(overflowRow(hidden, theme, options.viewKey));
+	return renderCard(
+		{ title: "Agents", subtitle: counts(shown), body, tone: tone(shown), glyph: AGENTS_GLYPH },
+		theme,
+		width,
+		{ expanded: true, hint },
+	);
+}

package/lib/gentle-ai-renderer.ts

@@ -1,16 +1,21 @@
 import { keyHint, type AgentToolResult } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { CARD_TONE, cardBottom, cardInnerWidth, cardLine, cardTop, type Card, type CardTheme, type CardTone } from "./shell-card.ts";
 import { sanitizeTerminalText } from "./terminal-theme.ts";
 
-type GentleAiLifecycleColor = "warning" | "success" | "error" | "dim";
+// Gentle AI tool cards: every call into the gentle-ai binary and every
+// gentle_review tool draws the same card as the other Gentle notices. The
+// call component owns the top rule; the result component closes the frame.
 
-export interface GentleAiRenderTheme {
-	bold(value: string): string;
-	fg(color: GentleAiLifecycleColor, value: string): string;
-}
+export type GentleAiRenderTheme = CardTheme;
 
 export interface GentleAiRenderState {
-	lifecycleComponent?: boolean; genericLocked?: boolean;
+	lifecycleComponent?: boolean;
+	genericLocked?: boolean;
+	/** Set by the result renderer once a final result exists, so a replayed
+	 * call (which pi never marks as started) still shows its outcome. */
+	finished?: boolean;
+	failed?: boolean;
 }
 
 export interface GentleAiRenderContext {
@@ -18,10 +23,35 @@ export interface GentleAiRenderContext {
 	executionStarted?: boolean;
 	isPartial?: boolean;
 	isError?: boolean;
+	expanded?: boolean;
 	lastComponent?: unknown;
 	state?: unknown;
+	invalidate?: () => void;
 }
 
+const LIFECYCLE_STATUS = {
+	PREPARING: "preparing",
+	RUNNING: "running",
+	COMPLETED: "completed",
+	FAILED: "failed",
+} as const;
+
+type LifecycleStatus = (typeof LIFECYCLE_STATUS)[keyof typeof LIFECYCLE_STATUS];
+
+const STATUS_TONE: Record<LifecycleStatus, CardTone> = {
+	[LIFECYCLE_STATUS.PREPARING]: CARD_TONE.WARNING,
+	[LIFECYCLE_STATUS.RUNNING]: CARD_TONE.WARNING,
+	[LIFECYCLE_STATUS.COMPLETED]: CARD_TONE.SUCCESS,
+	[LIFECYCLE_STATUS.FAILED]: CARD_TONE.ERROR,
+};
+
+const CARD_TITLE = "Gentle AI";
+// The binary keeps its rose; Gentle Shell notices keep the flower.
+const CARD_GLYPH = "\u{1F339}\uFE0E";
+const DETAIL_ROLE = "dim";
+const HIDDEN_ROLE = "dim";
+const passthroughTheme: CardTheme = { fg: (_color, text) => text };
+
 export function getGentleAiRenderState(state: unknown): GentleAiRenderState | undefined {
 	if (!state || typeof state !== "object" || Array.isArray(state)) return undefined;
 	const rowState = state as Record<string, unknown>, existing = rowState.gentleAiRender;
@@ -29,19 +59,103 @@ export function getGentleAiRenderState(state: unknown): GentleAiRenderState | un
 	return (rowState.gentleAiRender = {} as GentleAiRenderState);
 }
 
+// The call row: the top rule, with the expand key at its right end once the
+// tool finished, and the command when expanded. pi renders the result
+// component right below it, and that one closes the frame.
+// The call card owns the top rule. While the execution is still running it
+// also closes the frame, because no result row exists yet; once a final
+// result is in, the result card closes it instead.
+export class GentleAiCallCard {
+	private card: Card = { title: CARD_TITLE, body: [], tone: CARD_TONE.WARNING };
+	private theme: CardTheme = passthroughTheme;
+	private detail: string | undefined;
+	private hint: string | undefined;
+	private open = true;
+
+	update(status: LifecycleStatus, operationPath: string, theme: CardTheme, detail?: string, hint?: string): void {
+		this.card = { title: CARD_TITLE, subtitle: `${status} · ${operationPath}`, body: [], tone: STATUS_TONE[status], glyph: CARD_GLYPH };
+		this.theme = theme;
+		this.detail = detail;
+		this.hint = hint;
+		this.open = status === LIFECYCLE_STATUS.RUNNING || status === LIFECYCLE_STATUS.PREPARING;
+	}
+
+	render(width: number): string[] {
+		const lines = [cardTop(this.card, this.theme, width, this.hint)];
+		if (this.detail) lines.push(cardLine(this.theme.fg(DETAIL_ROLE, this.detail), this.card.tone, this.theme, width));
+		if (this.open) lines.push(cardBottom(this.card.tone, this.theme, width));
+		return lines;
+	}
+
+	invalidate(): void {}
+}
+
+// The result rows: the body when expanded, a count-only line when collapsed
+// (the call card carries the expand key and the text stays hidden), and
+// always the bottom rule that closes the frame. The rail follows the outcome:
+// amber while partial, green when done, red on error.
+export class GentleAiResultCard {
+	private readonly text: string;
+	private readonly expanded: boolean;
+	private readonly tone: CardTone;
+	private readonly theme: CardTheme;
+	private readonly partial: boolean;
+
+	constructor(text: string, expanded: boolean, tone: CardTone, theme: CardTheme, partial = false) {
+		this.text = text;
+		this.expanded = expanded;
+		this.tone = tone;
+		this.theme = theme;
+		this.partial = partial;
+	}
+
+	render(width: number): string[] {
+		const lines: string[] = [];
+		if (this.text.length > 0) {
+			if (this.expanded) {
+				const innerWidth = cardInnerWidth(width);
+				for (const raw of this.text.split("\n")) {
+					for (const line of raw === "" ? [""] : wrapTextWithAnsi(raw, innerWidth)) lines.push(cardLine(line, this.tone, this.theme, width));
+				}
+			} else {
+				const count = this.text.split("\n").length;
+				lines.push(cardLine(this.theme.fg(HIDDEN_ROLE, `${count} ${count === 1 ? "line" : "lines"}`), this.tone, this.theme, width));
+			}
+		}
+		// A partial result sits under a running call card, which still closes the frame.
+		if (!this.partial) lines.push(cardBottom(this.tone, this.theme, width));
+		return lines;
+	}
+
+	invalidate(): void {}
+}
+
 export interface GentleAiResultRenderOptions {
 	expanded?: boolean;
+	isPartial?: boolean;
+	isError?: boolean;
 }
 
 export function renderGentleAiResult(
 	result: AgentToolResult<unknown>,
 	options: GentleAiResultRenderOptions,
-): Text {
+	theme: CardTheme = passthroughTheme,
+	context?: GentleAiRenderContext,
+): GentleAiResultCard {
 	const textItems = result.content.flatMap((content) => (content.type === "text" ? [sanitizeTerminalText(content.text)] : []));
-	const text = textItems.join("\n");
-	const hasExpandableText = textItems.some((item) => item.length > 0);
-	const output = !hasExpandableText ? "" : options.expanded ? text : keyHint("app.tools.expand", "to expand");
-	return new Text(output, 0, 0);
+	const text = textItems.some((item) => item.length > 0) ? textItems.join("\n") : "";
+	const tone = options.isError ? CARD_TONE.ERROR : options.isPartial ? CARD_TONE.WARNING : CARD_TONE.SUCCESS;
+	const state = getGentleAiRenderState(context?.state);
+	if (state && options.isPartial !== true) {
+		const changed = state.finished !== true || state.failed !== (options.isError === true);
+		state.finished = true;
+		state.failed = options.isError === true;
+		// pi's invalidate re-runs the tool display synchronously; called from
+		// inside this render it would nest a second call+result pair into the
+		// same container. Deferring it keeps one frame per execution.
+		if (changed) queueMicrotask(() => context?.invalidate?.());
+	}
+	return new GentleAiResultCard(text, options.expanded === true, tone, theme, options.isPartial === true);
 }
 
 export function renderGentleAiLifecycleCall(
@@ -49,22 +163,24 @@ export function renderGentleAiLifecycleCall(
 	theme: GentleAiRenderTheme,
 	context?: GentleAiRenderContext,
 	detail?: string,
-): Text {
-	const status = context?.isError
-		? "failed"
-		: context?.argsComplete === false
-			? "preparing"
-			: !context?.executionStarted || context.isPartial
-				? "running"
-				: "completed";
-	const color = status === "preparing" || status === "running" ? "warning" : status === "completed" ? "success" : "error";
-	const lines = [theme.fg(color, theme.bold(`🌹︎ Gentle AI · ${status} · ${operationPath}`))];
-	if (detail) lines.push(theme.fg("dim", sanitizeTerminalText(detail)));
+): GentleAiCallCard {
+	// A finished execution is completed even when pi replays it without
+	// argsComplete (session reload); preparing only applies before it starts.
 	const state = getGentleAiRenderState(context?.state);
-	const component = context?.lastComponent instanceof Text && (!state || state.lifecycleComponent === true)
+	const finished = (context?.executionStarted === true && context.isPartial !== true) || state?.finished === true;
+	const failed = context?.isError === true || state?.failed === true;
+	const status: LifecycleStatus = failed
+		? LIFECYCLE_STATUS.FAILED
+		: finished
+			? LIFECYCLE_STATUS.COMPLETED
+			: context?.argsComplete === false
+				? LIFECYCLE_STATUS.PREPARING
+				: LIFECYCLE_STATUS.RUNNING;
+	const component = context?.lastComponent instanceof GentleAiCallCard && (!state || state.lifecycleComponent === true)
 		? context.lastComponent
-		: new Text("", 0, 0);
+		: new GentleAiCallCard();
 	if (state) state.lifecycleComponent = true;
-	component.setText(lines.join("\n"));
+	const hint = finished ? keyHint("app.tools.expand", context?.expanded ? "to collapse" : "to expand") : undefined;
+	component.update(status, operationPath, theme, detail ? sanitizeTerminalText(detail) : undefined, hint);
 	return component;
 }

package/lib/native-choice-list.ts

@@ -0,0 +1,194 @@
+import {
+	Box,
+	Container,
+	KeybindingsManager,
+	isKeyRelease,
+	matchesKey,
+	Text,
+	type TuiMouseEvent,
+	type TuiMouseEventResult,
+} from "@earendil-works/pi-tui";
+import { NativePointerScope } from "./native-pointer-region.ts";
+
+export interface NativeChoiceItem {
+	id: string;
+	label: string;
+	description?: string;
+}
+
+export interface NativeChoiceListTheme {
+	selectedPrefix(text: string): string;
+	selectedText(text: string): string;
+	description(text: string): string;
+	hoverBackground(text: string): string;
+}
+
+interface Row<T extends NativeChoiceItem> {
+	item: T;
+	text: Text;
+	box: Box;
+}
+
+export class NativeChoiceList<T extends NativeChoiceItem> extends Container {
+	onSelect?: (item: T) => void;
+	onCancel?: () => void;
+	private readonly rows: Row<T>[] = [];
+	private readonly items: readonly T[];
+	private readonly theme: NativeChoiceListTheme;
+	private readonly keybindings: KeybindingsManager | undefined;
+	private selected = 0;
+	private hovered: string | undefined;
+	private disabled = false;
+	private readonly pointerScope = new NativePointerScope();
+	private renderedWidth: number | undefined;
+
+	constructor(items: readonly T[], theme: NativeChoiceListTheme, keybindings?: KeybindingsManager) {
+		super();
+		this.items = items;
+		this.theme = theme;
+		this.keybindings = keybindings;
+		for (const item of items) this.addRow(item);
+		this.refreshRows();
+	}
+
+	getSelectedItem(): T | undefined {
+		return this.items[this.selected];
+	}
+
+	setSelectedIndex(index: number): void {
+		const next = Math.max(0, Math.min(this.items.length - 1, index));
+		if (next === this.selected) return;
+		this.selected = next;
+		this.refreshRows();
+	}
+
+	clearHover(): boolean {
+		if (!this.hovered) return false;
+		this.hovered = undefined;
+		this.refreshRows();
+		return true;
+	}
+
+	setDisabled(disabled: boolean): void {
+		this.disabled = disabled;
+		this.pointerScope.setDisabled(disabled);
+		if (disabled) this.clearHover();
+	}
+
+	createMouseObserver(requestRender: () => void) {
+		return this.pointerScope.createMouseObserver(requestRender);
+	}
+
+	override handleMouse(event: TuiMouseEvent) {
+		const result = super.handleMouse(event);
+		if (result || this.disabled || event.type !== "wheel" || !event.wheelDelta) return result;
+		const before = this.selected;
+		this.setSelectedIndex(this.selected + (event.wheelDelta < 0 ? -1 : 1));
+		return {
+			handled: true as const,
+			render: before !== this.selected,
+			target: {
+				component: this,
+				originX: event.screenX - event.x,
+				originY: event.screenY - event.y,
+				width: event.width,
+				height: event.height,
+			},
+		};
+	}
+
+	handleInput(data: string): void {
+		if (this.disabled || isKeyRelease(data)) return;
+		if (this.matches(data, "tui.select.up")) this.setSelectedIndex(this.selected - 1);
+		else if (this.matches(data, "tui.select.down")) this.setSelectedIndex(this.selected + 1);
+		else if (this.matches(data, "tui.select.confirm")) {
+			const item = this.getSelectedItem();
+			if (item) this.onSelect?.(item);
+		}
+		else if (this.matches(data, "tui.select.cancel")) this.onCancel?.();
+	}
+
+	override render(width: number): string[] {
+		if (this.renderedWidth !== width) {
+			this.renderedWidth = width;
+			this.pointerScope.invalidate();
+		}
+		return super.render(width);
+	}
+
+	override invalidate(): void {
+		this.renderedWidth = undefined;
+		this.pointerScope.invalidate();
+		super.invalidate();
+	}
+
+	private addRow(item: T): void {
+		const text = new Text("", 1, 0);
+		const box = new Box(0, 0, (value) => this.hovered === item.id ? this.theme.hoverBackground(value) : value);
+		box.addChild(text);
+		this.rows.push({ item, text, box });
+		this.addChild(this.pointerScope.wrap(box, {
+			onHover: (event) => this.handleRowMouse(item, event),
+			onLeave: () => this.clearHover(),
+			onPress: (event) => this.handleRowMouse(item, event),
+			onClick: (event) => this.handleRowMouse(item, event),
+		}));
+	}
+
+	private handleRowMouse(item: T, event: TuiMouseEvent): TuiMouseEventResult | undefined {
+		if (this.disabled) return undefined;
+		if (event.type === "move" && event.button === "none") {
+			const changed = this.setHover(item.id);
+			return { handled: true, render: changed };
+		}
+		if (event.button !== "left") return undefined;
+		if (event.type === "press") {
+			const changed = this.selectItem(item.id);
+			return { handled: true, focus: true, render: changed };
+		}
+		if (event.type === "click") {
+			this.selectItem(item.id);
+			this.onSelect?.(item);
+			return { handled: true };
+		}
+		return undefined;
+	}
+
+	private matches(
+		data: string,
+		binding: "tui.select.up" | "tui.select.down" | "tui.select.confirm" | "tui.select.cancel",
+	): boolean {
+		if (this.keybindings?.matches) return this.keybindings.matches(data, binding);
+		const key = binding === "tui.select.up" ? "up"
+			: binding === "tui.select.down" ? "down"
+				: binding === "tui.select.confirm" ? "enter" : "escape";
+		return matchesKey(data, key);
+	}
+
+	private selectItem(id: string): boolean {
+		const index = this.items.findIndex((item) => item.id === id);
+		if (index === -1 || index === this.selected) return false;
+		this.selected = index;
+		this.refreshRows();
+		return true;
+	}
+
+	private setHover(id: string): boolean {
+		if (this.hovered === id) return false;
+		this.hovered = id;
+		this.refreshRows();
+		return true;
+	}
+
+	private refreshRows(): void {
+		for (const [index, row] of this.rows.entries()) {
+			const prefix = index === this.selected ? this.theme.selectedPrefix("→ ") : "  ";
+			const label = index === this.selected ? this.theme.selectedText(row.item.label) : row.item.label;
+			const text = row.item.description
+				? `${prefix}${label}\n   ${this.theme.description(row.item.description)}`
+				: `${prefix}${label}`;
+			row.text.setText(text);
+			row.box.invalidate();
+		}
+	}
+}

package/lib/native-fullscreen-interaction.ts

@@ -0,0 +1,47 @@
+import { Container, type Component, type TuiMouseEvent } from "@earendil-works/pi-tui";
+
+export interface NativeFullscreenMouseObserver {
+	beforeMouse(event: TuiMouseEvent): void;
+	afterMouse(event: TuiMouseEvent): void;
+}
+
+export interface NativeFullscreenInteractionOptions {
+	keyboardTarget: Component;
+	requestRender(): void;
+	mouseObserver?: NativeFullscreenMouseObserver;
+}
+
+export class NativeFullscreenInteraction extends Container {
+	private readonly options: NativeFullscreenInteractionOptions;
+
+	constructor(options: NativeFullscreenInteractionOptions) {
+		super();
+		this.options = options;
+	}
+
+	handleInput(data: string): void {
+		if (!this.options.keyboardTarget.handleInput) return;
+		this.options.keyboardTarget.handleInput(data);
+		this.options.requestRender();
+	}
+
+	override handleMouse(event: TuiMouseEvent) {
+		this.options.mouseObserver?.beforeMouse(event);
+		try {
+			return super.handleMouse(event);
+		} finally {
+			this.options.mouseObserver?.afterMouse(event);
+		}
+	}
+}
+
+/**
+ * Compose native Container mouse dispatch with one keyboard-owning control.
+ * Optional observers run around native delegation without rewriting its result,
+ * so native layout, targeting, focus, wheel, and click semantics stay intact.
+ */
+export function createNativeFullscreenInteraction(
+	options: NativeFullscreenInteractionOptions,
+): NativeFullscreenInteraction {
+	return new NativeFullscreenInteraction(options);
+}