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

package/src/components/settings-list.ts

@@ -4,10 +4,15 @@ import { fuzzyFilter } from "../fuzzy";
 import { getKeybindings } from "../keybindings";
 import { extractPrintableText } from "../keys";
 import type { MouseRoutable, SgrMouseEvent } from "../mouse";
+import type { TspPrefsControl, TspPrefsRow, TspPrefsSection, TspProps, TspSpan } from "@oh-my-pi/pi-wire";
+import { col, node, span } from "../native/describe";
+import { sameItems, sameProps } from "../native/memo";
+import { plainLine, plainText } from "../native/spans";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
 import { ScrollView } from "./scroll-view";
-import { FormField, type FormFieldOptions, type FormFieldTheme } from "./form";
+import { FormField, type FormFieldOptions, type FormFieldTheme, SelectFormField, TextFormField } from "./form";
 import { MenuSelection } from "./menu-selection";
 
 function sanitizeSingleLine(text: string): string {
@@ -17,6 +22,13 @@ function sanitizeSingleLine(text: string): string {
 		.trim();
 }
 
+/** Described `item` node cached on the setting, rebuilt when a visible field (e.g. `currentValue`) changes. */
+const kNativeItem = Symbol("settingsList.nativeItem");
+
+interface NativeDescribedSetting extends SettingItem {
+	[kNativeItem]?: { signature: string; node: NativeNode };
+}
+
 function hasMouseRouter(component: Component): component is Component & MouseRoutable {
 	return "routeMouse" in component && typeof component.routeMouse === "function";
 }
@@ -38,10 +50,59 @@ export interface SettingItem {
 	submenu?: (currentValue: string, done: (selectedValue?: string) => void) => Component;
 	/** True when the displayed setting differs from its default value. */
 	changed?: boolean;
+	/** The default, as a native settings page names it in the changed dot's title. */
+	defaultLabel?: string;
 	/** Render as a non-interactive section heading. Skipped by navigation and search. */
 	heading?: boolean;
 }
 
+/** A row's open editor as a native settings page shows it (`TspPrefsProps.editing`). */
+export interface PrefsEditing {
+	row: string;
+	draft?: string;
+	cursor?: number;
+	option?: string;
+}
+
+/** A submenu that reports the option it highlights (multiselect toggles) to a native settings page. */
+export interface PrefsOptionSource {
+	readonly prefsOption: string | undefined;
+}
+
+/** Where a setting row goes on a native settings page: its section and, for search results, its page. */
+export interface PrefsSectionRef {
+	id: string;
+	title: string;
+	page?: string;
+}
+
+/** The section id for a section title (`"Status Line"` → `"status-line"`). */
+export function prefsSectionId(title: string): string {
+	return title
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-|-$/g, "");
+}
+
+/** A setting as a native settings row, given its typed control; `undefined` for headings. */
+export function settingPrefsRow(item: SettingItem, control: TspPrefsControl): TspPrefsRow | undefined {
+	if (item.heading) return undefined;
+	const row: TspPrefsRow = {
+		id: item.id,
+		label: plainLine(item.label),
+		hint: item.description ? plainLine(item.description) : undefined,
+		warning: item.warning ? plainLine(item.warning) : undefined,
+		changed: item.changed === true ? true : undefined,
+		defaultLabel: item.changed && item.defaultLabel ? plainLine(item.defaultLabel) : undefined,
+		control,
+	};
+	return row;
+}
+
+function hasPrefsOption(component: Component): component is Component & PrefsOptionSource {
+	return "prefsOption" in component;
+}
+
 export interface SettingsListTheme {
 	label: (text: string, selected: boolean, changed: boolean) => string;
 	value: (text: string, selected: boolean, changed: boolean) => string;
@@ -133,6 +194,8 @@ export class SettingsList implements Component {
 	#hitRows: (string | undefined)[] = [];
 	#sidebarHitRows: (string | undefined)[] = [];
 	#sidebarHitCol = 0;
+	#nativeList?: { props: TspProps<"list">; items: readonly NativeNode[]; node: NativeNode };
+	#nativeRoot?: { body: NativeChild; hint: string; node: NativeNode };
 	constructor(
 		items: SettingItem[],
 		maxVisible: number,
@@ -222,6 +285,98 @@ export class SettingsList implements Component {
 		return this.#submenuComponent !== null;
 	}
 
+	/** The open submenu and the row that opened it, if any. */
+	get openSubmenu(): { id: string; component: Component } | undefined {
+		const component = this.#submenuComponent;
+		const id = this.#submenuItemId;
+		return component && id !== null ? { id, component } : undefined;
+	}
+
+	/**
+	 * The visible settings as native page sections: rows in list order, each
+	 * in the section `sectionOf` (given the row and the heading above it) names,
+	 * sections in order of their first row (ranked search results gather
+	 * under their section). Rows `control` has no typed control for are left
+	 * out.
+	 */
+	prefsSections(
+		sectionOf: (item: SettingItem, heading: SettingItem | undefined) => PrefsSectionRef,
+		control: (item: SettingItem) => TspPrefsControl | undefined,
+	): TspPrefsSection[] {
+		const sections: { ref: PrefsSectionRef; rows: TspPrefsRow[] }[] = [];
+		let heading: SettingItem | undefined;
+		for (const item of this.#filteredItems) {
+			if (item.heading) {
+				heading = item;
+				continue;
+			}
+			const typed = control(item);
+			const row = typed && settingPrefsRow(item, typed);
+			if (!row) continue;
+			const ref = sectionOf(item, heading);
+			const section = sections.find(candidate => candidate.ref.id === ref.id);
+			if (section) section.rows.push(row);
+			else sections.push({ ref, rows: [row] });
+		}
+		return sections.map(({ ref, rows }) => ({ ...ref, rows }));
+	}
+
+	/** The row with keyboard focus, or while the section rail has focus the focused section's heading label. */
+	prefsFocus(): { row?: string; section?: string } {
+		if (this.#sectionFocus) {
+			const sections = this.#sections();
+			return { section: sections[this.#activeSectionIndex(sections)]?.name };
+		}
+		return { row: this.getSelectedItem()?.id };
+	}
+
+	/**
+	 * The open editor as a native page draws it: a choice's highlighted option
+	 * (when `inlineMenu(id)` says the row's choices fit its popup menu), a text
+	 * field's draft and cursor (dots when masked), a multiselect's highlighted
+	 * option; `null` when nothing is open or the editor has no native control
+	 * (the host shows that one itself).
+	 */
+	prefsEditing(inlineMenu: (id: string) => boolean): PrefsEditing | null {
+		const open = this.openSubmenu;
+		if (!open) return null;
+		const { id, component } = open;
+		if (component instanceof SelectFormField) {
+			if (!inlineMenu(id)) return null;
+			return { row: id, option: component.selectList.getSelectedItem()?.value };
+		}
+		if (component instanceof TextFormField) {
+			const draft = component.getValue();
+			return {
+				row: id,
+				draft: component.input.mask ? "•".repeat(draft.length) : draft,
+				cursor: component.input.getCursor(),
+			};
+		}
+		if (hasPrefsOption(component)) return { row: id, option: component.prefsOption };
+		return null;
+	}
+
+	/** Applies `value` to a cycling (boolean/enum) row the way Enter does: the row shows it and `onChange` runs. */
+	applyValue(id: string, value: string): void {
+		const item = this.#items.find(candidate => !candidate.heading && candidate.id === id);
+		if (!item || item.submenu || !item.values?.includes(value)) return;
+		this.selectItem(id);
+		item.currentValue = value;
+		this.#onChange(item.id, value);
+	}
+
+	/** Opens row `id`'s submenu the way Enter does (leaving one already open for it); returns it. */
+	openSubmenuFor(id: string): Component | undefined {
+		const open = this.openSubmenu;
+		if (open?.id === id) return open.component;
+		if (open || !this.selectItem(id)) return undefined;
+		const item = this.getSelectedItem();
+		if (!item?.submenu) return undefined;
+		this.#activateItem();
+		return this.#submenuComponent ?? undefined;
+	}
+
 	#notifySelection(): void {
 		const item = this.getSelectedItem();
 		if (item?.id === this.#lastNotifiedSelectionId) return;
@@ -484,6 +639,113 @@ export class SettingsList implements Component {
 		return this.#padLines(this.#renderMainList(width));
 	}
 
+	/**
+	 * A `list` of setting `item`s (label, current value on the right, risk note
+	 * and description as detail; headings as disabled items) keyed by setting id,
+	 * with the selection and search query, plus the footer hint. An open submenu
+	 * replaces the list and describes itself.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		let body: NativeChild;
+		let hint = "";
+		if (this.#submenuComponent) {
+			body = this.#submenuComponent;
+		} else {
+			body = this.#describeList();
+			hint = this.#options.hint === "" ? "" : plainLine(this.#hintText());
+		}
+		const cached = this.#nativeRoot;
+		if (cached && cached.body === body && cached.hint === hint) return cached.node;
+		const children: NativeChild[] = [body];
+		if (hint) children.push(node("text", { spans: [span(hint, "muted")] }, undefined, "hint"));
+		const root = col(children, { role: "omp.settings", gap: "sm" });
+		this.#nativeRoot = { body, hint, node: root };
+		return root;
+	}
+
+	/**
+	 * Pointer actions do what a click does in the settings hosts: `select` moves
+	 * the selection to the row, or activates it (Enter) when it already is the
+	 * selection; `activate` selects and activates.
+	 */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (this.#submenuComponent || (event.type !== "select" && event.type !== "activate")) return;
+		const wasSelected = this.getSelectedItem()?.id === event.item;
+		if (!this.selectItem(event.item)) return;
+		if (event.type === "activate" || wasSelected) this.#activateItem();
+	}
+
+	#describeList(): NativeNode {
+		const items: NativeNode[] = [];
+		for (const item of this.#filteredItems) items.push(this.#describeItem(item));
+		const cachedMax = this.#nativeList?.props.max;
+		const props: TspProps<"list"> = {
+			selected: this.getSelectedItem()?.id ?? null,
+			filter: this.#filterQuery.trim() || undefined,
+			empty:
+				this.#items.length === 0 ? (this.#options.emptyText ?? "No settings available") : "No matching settings",
+			max:
+				typeof cachedMax === "object" && cachedMax.lines === this.#maxVisible
+					? cachedMax
+					: { lines: this.#maxVisible },
+		};
+		const cached = this.#nativeList;
+		if (cached && sameProps(cached.props, props) && sameItems(cached.items, items)) return cached.node;
+		const list = node("list", props, items, "list");
+		this.#nativeList = { props, items, node: list };
+		return list;
+	}
+
+	#describeItem(item: NativeDescribedSetting): NativeNode {
+		const value = plainLine(String(item.currentValue ?? ""));
+		const changed = item.changed === true;
+		const signature = `${item.heading === true}\0${item.label}\0${value}\0${changed}\0${item.warning ?? ""}\0${item.description ?? ""}`;
+		const cached = item[kNativeItem];
+		if (cached?.signature === signature) return cached.node;
+		let described: NativeNode;
+		if (item.heading) {
+			described = node(
+				"item",
+				{ label: [span(plainLine(item.label), "strong")], disabled: true, role: "omp.settings.heading" },
+				undefined,
+				item.id,
+			);
+		} else {
+			const label: TspSpan[] = [span(plainLine(item.label), changed ? "accent" : undefined)];
+			if (item.warning && this.#theme.warningMark)
+				label.push(span(` ${plainText(this.#theme.warningMark)}`, "warning"));
+			const detail: TspSpan[] = [];
+			if (item.warning) detail.push(span(plainLine(item.warning), "warning"));
+			if (item.description) {
+				if (detail.length > 0) detail.push(span(" "));
+				detail.push(span(plainLine(item.description), "muted"));
+			}
+			described = node(
+				"item",
+				{
+					label,
+					value: [span(value, changed ? "accent" : "muted")],
+					detail: detail.length > 0 ? detail : undefined,
+				},
+				undefined,
+				item.id,
+			);
+		}
+		item[kNativeItem] = { signature, node: described };
+		return described;
+	}
+
+	#hintText(): string {
+		const jumpHint =
+			this.#sections().length >= 2
+				? `${editorKeys("tui.select.pageUp", "tui.select.pageDown")} to jump sections · `
+				: "";
+		return (
+			this.#options.hint ??
+			`${editorKey("tui.select.confirm")}/${formatKeyHint("space")} to change · ${jumpHint}Type to search · ${editorKey("tui.select.cancel")} to cancel`
+		);
+	}
+
 	/** Warning glyph suffix for a row that carries a risk note, or "" when none applies. */
 	#warningMark(item: SettingItem): string {
 		return item.warning && this.#theme.warningMark ? ` ${this.#theme.warningMark}` : "";
@@ -642,12 +904,7 @@ export class SettingsList implements Component {
 		// Add hint (suppressed entirely when the host owns the footer)
 		if (this.#options.hint !== "") {
 			lines.push("");
-			const jumpHint =
-				sections.length >= 2 ? `${editorKeys("tui.select.pageUp", "tui.select.pageDown")} to jump sections · ` : "";
-			const hintText =
-				this.#options.hint ??
-				`${editorKey("tui.select.confirm")}/${formatKeyHint("space")} to change · ${jumpHint}Type to search · ${editorKey("tui.select.cancel")} to cancel`;
-			lines.push(truncateToWidth(this.#theme.hint(`  ${hintText}`), width));
+			lines.push(truncateToWidth(this.#theme.hint(`  ${this.#hintText()}`), width));
 		}
 
 		return lines;

package/src/components/spacer.ts

@@ -1,11 +1,22 @@
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 
+/** Terminal spacing step for a count of blank rows. */
+export function spaceForRows(rows: number): "none" | "sm" | "md" | "lg" {
+	if (!(rows > 0)) return "none";
+	if (rows <= 1) return "sm";
+	if (rows <= 2) return "md";
+	return "lg";
+}
+
 /**
  * Spacer component that renders empty lines
  */
 export class Spacer implements Component {
 	#lines: number;
 	#cached: string[] | undefined;
+	#native: NativeNode | undefined;
 
 	constructor(lines: number = 1) {
 		this.#lines = lines;
@@ -19,11 +30,17 @@ export class Spacer implements Component {
 		if (lines === this.#lines) return;
 		this.#lines = lines;
 		this.#cached = undefined;
+		this.#native = undefined;
 	}
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
 
+	describe(_cx: DescribeContext): NativeNode {
+		this.#native ??= node("spacer", { size: spaceForRows(this.#lines) });
+		return this.#native;
+	}
+
 	render(_width: number): readonly string[] {
 		let cached = this.#cached;
 		if (cached === undefined) {

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;