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

package/src/components/select-list.ts

@@ -1,8 +1,14 @@
 import { popLoopPhase, pushLoopPhase } from "@oh-my-pi/pi-utils";
+import { Input } from "./input";
 import { getMenuWindow, MenuSelection } from "./menu-selection";
 import { getKeybindings } from "../keybindings";
 import { extractPrintableText, matchesKey } from "../keys";
 import { type MouseRoutable, routeSelectListMouse, type SgrMouseEvent } from "../mouse";
+import { col, node, span } from "../native/describe";
+import { sameItems, sameProps } from "../native/memo";
+import { plainLine } from "../native/spans";
+import type { TspProps } from "@oh-my-pi/pi-wire";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
 import type { SymbolTheme } from "../symbols";
 import type { Component } from "../tui";
 import { Ellipsis, padding, replaceTabs, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "../utils";
@@ -23,12 +29,25 @@ function sanitizeSingleLine(text: string): string {
 
 const clamp = (value: number, min: number, max: number): number => Math.max(min, Math.min(value, max));
 
+/** Described `item` node cached on the item, rebuilt only when its visible fields change. */
+const kNativeItem = Symbol("selectList.nativeItem");
+
+interface NativeDescribedItem extends SelectItem {
+	[kNativeItem]?: { signature: string; node: NativeNode };
+}
+
 export interface SelectItem {
 	value: string;
 	label: string;
 	description?: string;
 	/** Optional type-indicator glyph rendered in an aligned column before the label */
 	icon?: string;
+	/** Named icon a TSP terminal draws from its own set (replaces the {@link icon} glyph natively). */
+	iconName?: string;
+	/** Native detail text when it differs from the ANSI {@link description} (which may embed {@link state}). */
+	nativeDetail?: string;
+	/** Live state drawn right-aligned natively ("demo/demo", "off"). */
+	state?: string;
 	/** Dim hint text shown inline after cursor when this item is selected */
 	hint?: string;
 	/** Disabled rows stay visible but are skipped by navigation and cannot activate. */
@@ -153,6 +172,12 @@ export class SelectList implements Component, MouseRoutable {
 	#hoveredIndex: number | null = null;
 	/** Per-render map of 0-based output line → filtered-item index. */
 	#hitRows: (number | undefined)[] = [];
+	#nativeList?: { props: TspProps<"list">; items: readonly NativeNode[]; node: NativeNode };
+	#nativeRoot?: { list: NativeNode; status: string; node: NativeNode };
+	/** Typed text marked at the start of native item labels (an autocomplete popup's query). */
+	#nativeMark: string | undefined;
+	/** The type-to-filter field; its value is pushed into the selection's query. */
+	readonly #search = new Input();
 
 	onSelect?: (item: SelectItem) => void;
 	onCancel?: () => void;
@@ -172,6 +197,7 @@ export class SelectList implements Component, MouseRoutable {
 			requiresConfirmation: item => item.confirmation !== undefined,
 			filter: layout.filterItems,
 		});
+		this.#search.prompt = "";
 	}
 	/** Return item, selection, and filter state for debug inspection. */
 	debugState(): Record<string, unknown> {
@@ -193,8 +219,10 @@ export class SelectList implements Component, MouseRoutable {
 		this.#maxVisible = Math.max(1, Math.trunc(rows));
 	}
 
+	/** Replace the filter text (caret to end) and refilter. */
 	setFilter(filter: string): void {
-		this.#setFilter(filter, true);
+		this.#search.setValue(filter);
+		this.#setFilter(this.#search.getValue(), true);
 	}
 
 	/** Replace controlled items while retaining the selected value when possible. */
@@ -215,6 +243,26 @@ export class SelectList implements Component, MouseRoutable {
 		return this.#selection.query;
 	}
 
+	/**
+	 * What a native `picker` shows: the filtered items in order, the selected
+	 * and pending values, the query and its caret (UTF-16 offset).
+	 */
+	pickerView(): {
+		readonly items: readonly SelectItem[];
+		readonly selected: string | null;
+		readonly pending: string | null;
+		readonly query: string;
+		readonly cursor: number;
+	} {
+		return {
+			items: this.#selection.visibleItems,
+			selected: this.#selection.selectedKey ?? null,
+			pending: this.#selection.pendingKey ?? null,
+			query: this.#selection.query,
+			cursor: this.#search.getCursor(),
+		};
+	}
+
 	/** Resolve a 0-based rendered-line index to a filtered-item index. */
 	hitTest(line: number): number | undefined {
 		return this.#hitRows[line];
@@ -242,6 +290,95 @@ export class SelectList implements Component, MouseRoutable {
 		routeSelectListMouse(this, event, line);
 	}
 
+	/**
+	 * A `list` of `item`s keyed by item value, with the selection, the search
+	 * query and the empty/no-match text, plus a status line (search query,
+	 * pending confirmation, host status) under it when one applies.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		const items: NativeNode[] = [];
+		for (const item of this.#selection.visibleItems) items.push(this.#describeItem(item));
+		const query = this.#selection.query;
+		const cachedMax = this.#nativeList?.props.max;
+		const props: TspProps<"list"> = {
+			selected: this.#selection.selectedKey ?? null,
+			filter: this.#nativeMark === undefined ? query.trim() || undefined : undefined,
+			empty:
+				query.trim().length > 0
+					? (this.layout.noMatchText ?? "No matching items")
+					: (this.layout.emptyText ?? "No items"),
+			max:
+				typeof cachedMax === "object" && cachedMax.lines === this.#maxVisible
+					? cachedMax
+					: { lines: this.#maxVisible },
+		};
+		const cachedList = this.#nativeList;
+		const list =
+			cachedList && sameProps(cachedList.props, props) && sameItems(cachedList.items, items)
+				? cachedList.node
+				: node("list", props, items, "list");
+		if (list !== cachedList?.node) this.#nativeList = { props, items, node: list };
+
+		const status = this.#shouldRenderSearchStatus() ? plainLine(this.#statusText()) : "";
+		const cachedRoot = this.#nativeRoot;
+		if (cachedRoot && cachedRoot.list === list && cachedRoot.status === status) return cachedRoot.node;
+		const children: NativeChild[] = [list];
+		if (status) children.push(node("text", { spans: [span(status, "muted")], wrap: "none" }, undefined, "status"));
+		const root = col(children, { role: "omp.select" });
+		this.#nativeRoot = { list, status, node: root };
+		return root;
+	}
+
+	/**
+	 * Mark `typed` where it leads a native item label (`{s:"mark"}`), for lists
+	 * whose items were matched against text outside the list (autocomplete).
+	 * The list then sends no `filter`: the marks already say what matched.
+	 */
+	setNativeMark(typed: string): void {
+		this.#nativeMark = typed;
+	}
+
+	/** Pointer select/activate on an item does what a click does today: select it and request activation. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type !== "select" && event.type !== "activate") return;
+		const index = this.#selection.visibleItems.findIndex(item => item.value === event.item);
+		if (index >= 0) this.clickItem(index);
+	}
+
+	#describeItem(item: NativeDescribedItem): NativeNode {
+		const pending = this.#selection.isPending(item);
+		const label = plainLine(this.#sanitizedLabel(item));
+		const description = plainLine((pending ? item.confirmation : this.#sanitizedDescription(item)) ?? "");
+		const detail = pending || item.nativeDetail === undefined ? description : plainLine(item.nativeDetail);
+		const icon = item.icon && item.iconName === undefined ? plainLine(item.icon) : "";
+		const state = item.state ? plainLine(item.state) : "";
+		const mark = this.#nativeMark ?? "";
+		const marked = mark.length > 0 && label.toLowerCase().startsWith(mark.toLowerCase()) ? mark.length : 0;
+		const signature =
+			`${label}\0${detail}\0${icon}\0${item.iconName}\0${state}\0${marked}\0` +
+			`${item.disabled === true}\0${pending}`;
+		const cached = item[kNativeItem];
+		if (cached?.signature === signature) return cached.node;
+		const name = marked === 0 ? [span(label)] : [span(label.slice(0, marked), "mark")];
+		if (marked > 0 && marked < label.length) name.push(span(label.slice(marked)));
+		const described = node(
+			"item",
+			{
+				// A named icon comes from the terminal's set; a bare glyph leads the label.
+				icon: item.iconName,
+				label: icon ? [span(`${icon} `, "muted"), ...name] : name,
+				detail: detail ? [span(detail, pending ? "warning" : "muted")] : undefined,
+				value: state ? [span(state, "muted")] : undefined,
+				disabled: item.disabled === true ? true : undefined,
+				tone: pending ? "warning" : undefined,
+			},
+			undefined,
+			item.value,
+		);
+		item[kNativeItem] = { signature, node: described };
+		return described;
+	}
+
 	invalidate(): void {
 		// No cached state to invalidate currently
 	}
@@ -356,14 +493,15 @@ export class SelectList implements Component, MouseRoutable {
 			return;
 		}
 
-		if (this.#handleSearchInput(keyData)) return;
-		if (this.#selection.visibleItems.length === 0) return;
-
+		// Typed text filters even when it collides with a navigation binding; then
+		// host navigation; every other key is the search field's.
+		if (extractPrintableText(keyData) !== undefined && this.#handleSearchInput(keyData)) return;
+		const wrap = this.layout.wrapNavigation !== false;
 		let selectionChanged = false;
 		if (kb.matches(keyData, "tui.select.up")) {
-			selectionChanged = this.#selection.move(-1, this.layout.wrapNavigation !== false);
+			selectionChanged = this.#selection.move(-1, wrap);
 		} else if (kb.matches(keyData, "tui.select.down")) {
-			selectionChanged = this.#selection.move(1, this.layout.wrapNavigation !== false);
+			selectionChanged = this.#selection.move(1, wrap);
 		} else if (kb.matches(keyData, "tui.select.pageUp")) {
 			selectionChanged = this.#selection.move(-this.#maxVisible);
 		} else if (kb.matches(keyData, "tui.select.pageDown")) {
@@ -373,7 +511,9 @@ export class SelectList implements Component, MouseRoutable {
 		} else if (matchesKey(keyData, "end")) {
 			selectionChanged = this.#selection.moveToBoundary("last");
 		} else if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n") {
-			this.#activateSelected();
+			if (this.#selection.visibleItems.length > 0) this.#activateSelected();
+		} else {
+			this.#handleSearchInput(keyData);
 		}
 		if (selectionChanged) this.#notifySelectionChange();
 	}
@@ -570,6 +710,21 @@ export class SelectList implements Component, MouseRoutable {
 	}
 
 	#renderStatusLine(width: number): string {
+		const avail = Math.max(1, width - 2);
+		if (
+			this.layout.statusText === undefined &&
+			this.#selection.pendingKey === undefined &&
+			this.#selection.query.length > 0
+		) {
+			const label = truncateToWidth("  Search: ", avail, Ellipsis.Omit);
+			const fieldWidth = avail - visibleWidth(label);
+			const styled = this.theme.scrollInfo(label);
+			return fieldWidth > 0 ? styled + this.#search.render(fieldWidth)[0].trimEnd() : styled;
+		}
+		return this.theme.scrollInfo(truncateToWidth(this.#statusText(), avail, Ellipsis.Omit));
+	}
+
+	#statusText(): string {
 		const pendingItem =
 			this.#selection.pendingKey === undefined
 				? undefined
@@ -582,12 +737,10 @@ export class SelectList implements Component, MouseRoutable {
 			totalCount: this.#selection.items.length,
 			pendingItem,
 		});
-		const statusText =
-			this.layout.statusText !== undefined
-				? (custom ?? "")
-				: (pendingItem?.confirmation ??
+		return this.layout.statusText !== undefined
+			? (custom ?? "")
+			: (pendingItem?.confirmation ??
 					(query ? `  Search: ${query}` : this.#canEditSearch() ? "  Type to search" : ""));
-		return this.theme.scrollInfo(truncateToWidth(statusText, Math.max(1, width - 2), Ellipsis.Omit));
 	}
 
 	#shouldRenderSearchStatus(): boolean {
@@ -608,21 +761,17 @@ export class SelectList implements Component, MouseRoutable {
 	#handleSearchInput(keyData: string): boolean {
 		if (!this.#canEditSearch()) return false;
 
-		const kb = getKeybindings();
-		if (kb.matches(keyData, "tui.editor.deleteCharBackward")) {
-			if (this.#selection.query.length === 0) return false;
-			const chars = [...this.#selection.query];
-			chars.pop();
-			this.#setFilter(chars.join(""), true);
-			return true;
+		const before = this.#search.getValue();
+		if (before.length === 0) {
+			if (getKeybindings().matches(keyData, "tui.editor.deleteCharBackward")) return false;
+			const printableText = extractPrintableText(keyData);
+			if (printableText !== undefined && printableText.trim().length === 0) return false;
 		}
 
-		const printableText = extractPrintableText(keyData);
-		if (printableText === undefined) return false;
-		if (this.#selection.query.length === 0 && printableText.trim().length === 0) return false;
-
-		this.#setFilter(this.#selection.query + printableText, true);
-		return true;
+		const consumed = this.#search.handleInput(keyData);
+		const after = this.#search.getValue();
+		if (after !== before) this.#setFilter(after, true);
+		return consumed;
 	}
 
 	#setFilter(filter: string, notify: boolean): void {

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) {