@oh-my-pi/pi-tui 18.4.3 → 18.4.4

package/src/components/tab-bar.ts

@@ -10,6 +10,9 @@
  */
 import { formatKeyHint } from "../app-keybindings";
 import { matchesKey } from "../keys";
+import { compactText, styledSpans, styleSpans } from "../native/spans";
+import { node, row } from "../native/describe";
+import type { DescribeContext, NativeNode, NativeUiEvent } from "../native/node";
 import type { Component } from "../tui";
 import { truncateToWidth, visibleWidth } from "../utils";
 
@@ -60,6 +63,7 @@ export class TabBar implements Component {
 	#theme: TabBarTheme;
 	#label: string;
 	#hoverTabId: string | null = null;
+	#native?: { signature: string; node: NativeNode };
 	/** Per-render tab hit zones: 0-based line + [start, end) columns. */
 	#hitZones: { line: number; start: number; end: number; index: number }[] = [];
 
@@ -161,6 +165,44 @@ export class TabBar implements Component {
 		// No cached state to invalidate
 	}
 
+	/**
+	 * A native `tabs` strip (muted tabs keep the muted token), preceded by the
+	 * bar label and followed by the cycle hint when present. Shrinking to
+	 * `short` labels and wrapping are the terminal's.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		// Tabs are a caller-owned mutable array (render keeps no cache either), so key on content.
+		let signature = `${this.#activeIndex}\0${this.#label}\0${this.showHint}`;
+		for (const tab of this.#tabs) signature += `\0${tab.id}\x01${tab.label}\x01${tab.muted === true}`;
+		if (this.#native?.signature === signature) return this.#native.node;
+		const tabs = node("tabs", {
+			items: this.#tabs.map(tab => {
+				const label = styledSpans(tab.label);
+				return {
+					id: tab.id,
+					label: tab.muted
+						? label.map(part => ({ ...part, s: part.s ? `${part.s} muted` : "muted" }))
+						: compactText(label),
+				};
+			}),
+			active: this.#tabs[this.#activeIndex]?.id,
+		});
+		const parts: NativeNode[] = [];
+		if (this.#label) parts.push(node("text", { spans: styleSpans(`${this.#label}:`, this.#theme.label) }));
+		parts.push(tabs);
+		if (this.showHint) {
+			parts.push(node("text", { spans: styleSpans(`(${formatKeyHint("tab")} to cycle)`, this.#theme.hint) }));
+		}
+		const described = parts.length === 1 ? tabs : row(parts, { gap: "md", align: "center" });
+		this.#native = { signature, node: described };
+		return described;
+	}
+
+	/** A click on a tab activates it (muted tabs stay inert). */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "select" || event.type === "activate") this.selectTab(event.item);
+	}
+
 	/**
 	 * Handle keyboard input for tab navigation.
 	 * @returns true if the input was handled, false otherwise

package/src/components/table.ts

@@ -1,3 +1,7 @@
+import type { TspTableColumn, TspText } from "@oh-my-pi/pi-wire";
+import { compactText, styleSpans } from "../native/spans";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, getWidthConfigEpoch, replaceTabs, truncateToWidth, visibleWidth } from "../utils";
 
@@ -92,6 +96,7 @@ export class Table implements Component {
 	readonly #columns: readonly TableColumn[];
 	readonly #options: TableOptions;
 	#cache: { width: number; epoch: number; lines: readonly string[] } | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(rows: readonly (readonly TableCell[])[], columns: readonly TableColumn[], options: TableOptions = {}) {
 		this.#rows = rows;
@@ -103,11 +108,40 @@ export class Table implements Component {
 		if (this.#rows === rows) return false;
 		this.#rows = rows;
 		this.#cache = undefined;
+		this.#native = undefined;
 		return true;
 	}
 
 	invalidate(): void {
 		this.#cache = undefined;
+		this.#native = undefined;
+	}
+
+	/**
+	 * A native `table`. Column priorities carry over unchanged (lower gives
+	 * way first); truncating columns truncate at the end, the rest keep
+	 * their content. Widths are the terminal's.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		const columns = this.#columns;
+		const cols: TspTableColumn[] = columns.map((column, index) => ({
+			id: `c${index}`,
+			align: column.align === "right" ? "end" : "start",
+			truncate: column.overflow === "truncate" ? "end" : undefined,
+			priority: column.priority ?? 0,
+		}));
+		const rows = this.#rows.map((row, rowIndex) => {
+			const cells: Record<string, TspText> = {};
+			const count = Math.min(row.length, columns.length);
+			for (let index = 0; index < count; index++) {
+				const cell = row[index]!;
+				cells[`c${index}`] = compactText(styleSpans(singleLine(cell.text), cell.style ?? columns[index]!.style));
+			}
+			return { id: `r${rowIndex}`, cells };
+		});
+		this.#native = node("table", { cols, rows });
+		return this.#native;
 	}
 
 	render(width: number): readonly string[] {

package/src/components/text.ts

@@ -1,3 +1,7 @@
+import { styledSpans } from "../native/spans";
+import { backgroundChrome, sampleBackground } from "../native/tone";
+import { node, text } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import {
 	applyBackgroundToLine,
@@ -39,6 +43,7 @@ export class Text implements Component {
 	#cachedWidth?: number;
 	#cachedWidthConfigEpoch?: number;
 	#cachedLines?: string[];
+	#native?: { source: string; bg: string | undefined; node: NativeNode };
 
 	constructor(text: string = "", paddingX: number = 1, paddingY: number = 1, customBgFn?: (text: string) => string) {
 		this.#text = text;
@@ -104,6 +109,24 @@ export class Text implements Component {
 		this.#cachedLines = undefined;
 	}
 
+	/**
+	 * Wrapped text; styling re-derived from the styled source so a theme swap
+	 * re-resolves tokens. A background fill becomes the node's tone.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const source = this.#styleFn ? this.#styleFn(this.#text) : this.#text;
+		const bg = sampleBackground(this.#customBgFn);
+		const cached = this.#native;
+		if (cached?.source === source && cached.bg === bg) return cached.node;
+		const spans = source.trim() === "" ? [] : styledSpans(source);
+		const described =
+			spans.length === 0
+				? node("col", { hidden: true })
+				: text(spans, { wrap: "word", tone: backgroundChrome(bg).tone });
+		this.#native = { source, bg, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		// Check cache
 		if (

package/src/components/tree-view.ts

@@ -1,3 +1,7 @@
+import type { TspSpan, TspTreeNode } from "@oh-my-pi/pi-wire";
+import { styledSpans } from "../native/spans";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Theme } from "../theme/theme";
 import type { Component } from "../tui";
 import { replaceTabs, truncateToWidth, visibleWidth } from "../utils";
@@ -191,6 +195,11 @@ export interface TreeViewOptions<T, K extends TreeKey> extends FlattenTreeOption
 	scrollbarTheme?: ScrollViewTheme;
 }
 
+/** A tree node under construction; frozen into the wire shape once described. */
+type MutableTreeNode = {
+	-readonly [P in keyof TspTreeNode]: P extends "children" ? MutableTreeNode[] : TspTreeNode[P];
+};
+
 /** Result of a tree render, including whether a row or line budget omitted content. */
 export interface TreeViewRenderResult {
 	lines: readonly string[];
@@ -219,6 +228,7 @@ export class TreeView<T, K extends TreeKey = string> implements Component {
 	#version = 0;
 	#cache?: { width: number; version: number; result: TreeViewRenderResult };
 	#childByKey = new Map<K, Component>();
+	#native?: { version: number; node: NativeNode | null };
 
 	constructor(options: TreeViewOptions<T, K>) {
 		this.#options = options;
@@ -327,6 +337,61 @@ export class TreeView<T, K extends TreeKey = string> implements Component {
 		return this.renderWithState(width).lines;
 	}
 
+	/**
+	 * A native disclosure `tree` over the filtered rows, nested by hierarchy
+	 * (a filtered-out ancestor lifts its visible descendants to the nearest
+	 * visible one). Gutters, windowing and the scrollbar are the terminal's;
+	 * the selected row is marked with the `mark` token. Rows whose body is a
+	 * component can't be tree labels, so such a tree stays on `rows`.
+	 */
+	describe(_cx: DescribeContext): NativeNode | null {
+		this.#ensureRows();
+		if (this.#native?.version === this.#version) return this.#native.node;
+		const rows = this.#rows;
+		const byKey = new Map<K, MutableTreeNode>();
+		const roots: MutableTreeNode[] = [];
+		let described: NativeNode | null = null;
+		let componentRow = false;
+		for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+			const row = rows[rowIndex]!;
+			const selected = row.key === this.#selectedKey;
+			const rendered = this.#options.renderRow(row.item, {
+				row,
+				selected,
+				rowIndex,
+				windowStart: 0,
+				windowEnd: rows.length,
+				windowRows: rows,
+				width: Number.POSITIVE_INFINITY,
+				contentWidth: Number.POSITIVE_INFINITY,
+				prefix: { first: "", continuation: "" },
+			});
+			if (typeof rendered !== "string" && "render" in rendered) {
+				this.#replaceChild(row.key, rendered);
+				componentRow = true;
+				continue;
+			}
+			this.#replaceChild(row.key, undefined);
+			let label: TspSpan[] = styledSpans(typeof rendered === "string" ? rendered : rendered.join("\n"));
+			if (selected) label = label.map(part => ({ ...part, s: part.s ? `${part.s} mark` : "mark" }));
+			const treeNode: MutableTreeNode = { id: String(row.key), label };
+			byKey.set(row.key, treeNode);
+			let parentKey = row.parentKey;
+			while (parentKey !== undefined && !byKey.has(parentKey)) parentKey = this.#rowByKey.get(parentKey)?.parentKey;
+			const parent = parentKey === undefined ? undefined : byKey.get(parentKey);
+			if (parent) {
+				parent.children ??= [];
+				parent.open = true;
+				parent.children.push(treeNode);
+			} else {
+				roots.push(treeNode);
+			}
+		}
+		if (!componentRow) described = node("tree", { nodes: roots });
+		this.#native = { version: this.#version, node: described };
+		return described;
+	}
+
 	/** Render lines plus budget/window metadata for adapters that append an ellipsis. */
 	renderWithState(width: number): TreeViewRenderResult {
 		this.#ensureRows();

package/src/components/truncated-text.ts

@@ -1,3 +1,6 @@
+import { styledSpans } from "../native/spans";
+import { text } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 import { padding, truncateToWidth, visibleWidth } from "../utils";
 
@@ -10,6 +13,7 @@ export class TruncatedText implements Component {
 	#paddingY: number;
 	#cachedWidth = -1;
 	#cachedLines: string[] | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(text: string, paddingX: number = 0, paddingY: number = 0) {
 		this.#text = text;
@@ -32,10 +36,20 @@ export class TruncatedText implements Component {
 	}
 
 	invalidate(): void {
+		this.#native = undefined;
 		this.#cachedWidth = -1;
 		this.#cachedLines = undefined;
 	}
 
+	/** First line only, clamped to one visual line with an end ellipsis. */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		const newlineIndex = this.#text.indexOf("\n");
+		const firstLine = newlineIndex === -1 ? this.#text : this.#text.slice(0, newlineIndex);
+		this.#native = text(styledSpans(firstLine), { wrap: "none", truncate: "end", lines: 1 });
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		if (this.#cachedLines && this.#cachedWidth === width) {
 			return this.#cachedLines;

package/src/components/wizard-step.ts

@@ -1,5 +1,9 @@
 import type { MouseRoutable, SgrMouseEvent } from "../mouse";
+import { col } from "../native/describe";
+import { sameItems } from "../native/memo";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
+import { spaceForRows } from "./spacer";
 
 /** Semantic role of a wizard step's primary interactive content. */
 export type WizardStepKind = "input" | "choice" | "confirm" | "async" | "custom";
@@ -37,14 +41,6 @@ function isMouseRoutable(component: Component): component is Component & MouseRo
 	return "routeMouse" in component && typeof component.routeMouse === "function";
 }
 
-function sameLines(left: readonly string[], right: readonly string[]): boolean {
-	if (left.length !== right.length) return false;
-	for (let i = 0; i < left.length; i++) {
-		if (left[i] !== right[i]) return false;
-	}
-	return true;
-}
-
 /**
  * Reusable presentation for input, choice, confirmation, and asynchronous
  * wizard steps. Controllers retain state transitions; this component owns the
@@ -68,6 +64,7 @@ export class WizardStep implements Component, MouseRoutable {
 	#contentRowStart = -1;
 	#contentRowCount = 0;
 	#cachedLines: readonly string[] | undefined;
+	#native: { slots: readonly Component[]; node: NativeNode } | undefined;
 
 	constructor(options: WizardStepOptions) {
 		this.#kind = options.kind;
@@ -163,6 +160,18 @@ export class WizardStep implements Component, MouseRoutable {
 		content.routeMouse(event, line - this.#contentRowStart, col);
 	}
 
+	/**
+	 * The slots in order as a spaced `col`; the height budget and optional
+	 * preview collapse are the terminal's (it scrolls instead of clipping).
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const slots = this.debugChildren;
+		if (sameItems(this.#native?.slots, slots)) return this.#native!.node;
+		const described = col(slots, { gap: spaceForRows(this.#gap) });
+		this.#native = { slots, node: described };
+		return described;
+	}
+
 	render(width: number): readonly string[] {
 		const safeWidth = Math.max(1, width);
 		const gap = this.#gap;
@@ -217,7 +226,7 @@ export class WizardStep implements Component, MouseRoutable {
 			lines.push(...slot.lines);
 		}
 		const bounded = maxHeight === undefined || lines.length <= maxHeight ? lines : lines.slice(0, maxHeight);
-		if (this.#cachedLines && sameLines(this.#cachedLines, bounded)) return this.#cachedLines;
+		if (this.#cachedLines && sameItems(this.#cachedLines, bounded)) return this.#cachedLines;
 		this.#cachedLines = bounded;
 		return bounded;
 	}

package/src/debug-server.ts

@@ -1,7 +1,7 @@
 import { existsSync, unlinkSync } from "node:fs";
 import { createServer, type Server, type Socket } from "node:net";
 import { type Component, isFocusable, type OverlayOptions, type TUI } from "./tui";
-import { replaceTabs } from "./utils";
+import { plainText } from "./native/spans";
 
 export interface TuiDebugTreeNode {
 	kind: string;
@@ -63,10 +63,6 @@ const SPECIAL_KEYS: Readonly<Record<string, string>> = {
 	f12: "\x1b[24~",
 };
 
-function plainLine(line: string): string {
-	return replaceTabs(Bun.stripANSI(line)).replace(/[\x00-\x1f\x7f-\x9f]/g, "");
-}
-
 function errorMessage(error: unknown): string {
 	try {
 		return error instanceof Error ? error.message : String(error);
@@ -326,14 +322,25 @@ export class TuiDebugServer {
 				if (paint === undefined) return { ok: false, error: "no frame painted yet" };
 				return {
 					ok: true,
-					lines: paint.lines.map(plainLine),
+					lines: paint.lines.map(plainText),
 					window_top: paint.windowTop,
 					alt_screen: paint.altScreen,
 					...(paint.cursor === undefined ? {} : { cursor: paint.cursor }),
 				};
 			}
 			case "frame":
-				return { ok: true, lines: this.#tui.getDebugDocument().map(plainLine) };
+				return { ok: true, lines: this.#tui.getDebugDocument().map(plainText) };
+			case "doc": {
+				// The document a Tern Surface Protocol terminal should hold: every sent
+				// frame applied by the reference applier.
+				const doc = this.#tui.getNativeDocument();
+				if (doc === undefined) return { ok: false, error: "no native surface" };
+				return { ok: true, doc, rows: this.#tui.nativeFallbackCount };
+			}
+			case "tsp": {
+				const count = typeof request.n === "number" && request.n > 0 ? Math.trunc(request.n) : undefined;
+				return { ok: true, native: this.#tui.nativeRendering, frames: this.#tui.getNativeFrames(count) };
+			}
 			case "tree":
 				return { ok: true, tree: this.#tree() };
 			case "values":