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

package/src/components/editor.ts

@@ -14,6 +14,11 @@ import { BracketedPasteHandler, decodeReencodedPasteControls } from "../brackete
 import { canonicalKeyId, getKeybindings, type KeybindingsManager } from "../keybindings";
 import { extractPrintableText, matchesKey, parseKey } from "../keys";
 import { KillRing } from "../kill-ring";
+import type { TspEditorDecoration, TspEditorProps, TspTone } from "@oh-my-pi/pi-wire";
+import { col, node } from "../native/describe";
+import { sameItems, sameProps } from "../native/memo";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeChild, NativeNode } from "../native/node";
 import type { SymbolTheme } from "../symbols";
 import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
 import {
@@ -52,7 +57,36 @@ export type { EditorBorderStyle, EditorTopBorder };
 
 import { type SelectItem, SelectList, type SelectListLayoutOptions, type SelectListTheme } from "./select-list";
 
+/** The TSP root an {@link Editor.describeLayout} hook builds around the `editor` node. */
+export interface NativeEditorLayout {
+	readonly role: string;
+	/** Tone of the root (`pending` while a turn runs). */
+	readonly tone?: TspTone;
+	readonly children: readonly NativeChild[];
+	/** Keypath of the `editor` node inside the root (the autocomplete's caret anchor). */
+	readonly caret: string;
+}
+
+/** Vim mode as the TSP `editor.mode` label. */
+const VIM_MODE_LABELS: Record<VimMode, string> = {
+	insert: "INSERT",
+	normal: "NORMAL",
+	visual: "VISUAL",
+	"visual-line": "VISUAL",
+};
+
 const PASSTHROUGH_COLOR = (text: string): string => text;
+
+/** Value equality of two decoration lists, so an unchanged set keeps its identity across text edits elsewhere. */
+function sameDecorations(a: readonly TspEditorDecoration[], b: readonly TspEditorDecoration[]): boolean {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		const x = a[i]!;
+		const y = b[i]!;
+		if (x.from !== y.from || x.to !== y.to || x.s !== y.s || x.fx !== y.fx) return false;
+	}
+	return true;
+}
 const MENTION_CONTEXT_RE = /(?:^|\s)\^[^\s]*$/;
 const AT_TOKEN_RE = /(?:^|\s)(@[^\s]*)$/;
 
@@ -63,12 +97,12 @@ const AUTOCOMPLETE_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
 /**
  * `@` file lists are narrowed in place (`setFilter(liveToken)`) while a fresh
  * search runs, so a slow walk never leaves entries that contradict the typed
- * token on screen. An emptied list means the refresh is still pending.
+ * token on screen. An emptied list means the refresh is still pending; the
+ * popup stays open but renders nothing until results arrive.
  */
 const AT_FILE_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
 	...AUTOCOMPLETE_SELECT_LIST_LAYOUT,
 	filterItems: (items, token) => items.filter(item => atCompletionMatches(token, item.value)),
-	noMatchText: "Searching…",
 };
 
 const SLASH_COMMAND_SELECT_LIST_LAYOUT: SelectListLayoutOptions = {
@@ -568,7 +602,30 @@ export class Editor implements Component, Focusable {
 	 *  Width-changing output is allowed on lines without the cursor; it is truncated
 	 *  to the content width rather than reflowed. Cursor glyphs and inline hints are excluded. */
 	decorateText: ((text: string, context: EditorTextDecorationContext) => string) | undefined;
+	/**
+	 * TSP counterpart of {@link decorateText}: styled ranges over the buffer
+	 * (UTF-16 offsets into the lines joined by `\n`). Called only when the text
+	 * changed or the editor was invalidated since the last description.
+	 */
+	describeDecorations: ((lines: readonly string[]) => readonly TspEditorDecoration[]) | undefined;
+	/** TSP code language of the buffer (`python`, `bash`): the terminal highlights it in the mono face. */
+	describeLanguage: (() => string | undefined) | undefined;
+	/**
+	 * TSP chrome around the `editor` node (the prompt composer's chips, mode
+	 * chip, send/stop): the root role, the children with `input` placed where
+	 * the layout wants it, and the input's keypath for the caret-anchored
+	 * autocomplete. Unset: a plain `omp.editor` column over the input.
+	 */
+	describeLayout: ((input: NativeNode, cx: DescribeContext) => NativeEditorLayout) | undefined;
+	/** TSP placeholder for the empty buffer; natively it replaces the rotating ANSI {@link placeholder} hints. */
+	nativePlaceholder: string | undefined;
 	#promptGutter: string | undefined;
+	/** Bumped by {@link invalidate}: host-side decoration inputs (spelling results, settings) changed. */
+	#nativeGeneration = 0;
+	#nativeDecor?: { text: string; generation: number; decor: readonly TspEditorDecoration[] | undefined };
+	#nativeEditor?: { props: TspEditorProps; node: NativeNode };
+	#nativeOverlay?: { list: SelectList; caret: string; node: NativeNode };
+	#nativeRoot?: { role: string; tone: TspTone | undefined; children: readonly NativeChild[]; node: NativeNode };
 
 	// Store last layout width for cursor navigation
 	#lastLayoutWidth: number = 80;
@@ -1032,7 +1089,7 @@ export class Editor implements Component, Focusable {
 	}
 
 	invalidate(): void {
-		// No cached state to invalidate currently
+		this.#nativeGeneration++;
 	}
 
 	/** Active chrome style; a hidden border collapses every shape to borderless. */
@@ -1539,20 +1596,139 @@ export class Editor implements Component, Focusable {
 		if (bottomRow !== undefined) result.push(bottomRow);
 
 		// Add autocomplete list if active
-		if (this.#autocompleteState && this.#autocompleteList) {
+		const autocompleteList = this.#visibleAutocompleteList();
+		if (autocompleteList) {
 			// Clamp the dropdown to the terminal viewport: the editor rows already
 			// rendered above plus a small reserve must stay visible.
 			const viewportRows = this.viewportRowsProvider?.() || process.stdout.rows || Number(Bun.env.LINES) || 24;
-			this.#autocompleteList.setMaxVisible(
+			autocompleteList.setMaxVisible(
 				Math.max(3, Math.min(this.#autocompleteMaxVisible, viewportRows - result.length - 2)),
 			);
-			const autocompleteResult = this.#autocompleteList.render(width);
-			result.push(...autocompleteResult);
+			result.push(...autocompleteList.render(width));
 		}
 
 		return result;
 	}
 
+	/**
+	 * An `editor` node (key `input`) carrying the buffer, caret, Vim selection
+	 * anchor and mode, decorations, ghost completion, placeholder, prompt and
+	 * height cap; the frame, wrapping, scrolling and caret are the terminal's,
+	 * so composer shapes play no part. An open autocomplete popup follows as an
+	 * `overlay` anchored to the caret around the completion list. Typing and
+	 * caret moves change only `text` and `cursor` on the same node.
+	 */
+	describe(cx: DescribeContext): NativeNode {
+		// Vertical caret motion walks visual rows; the terminal owns the real
+		// wrap, so the surface width is the closest available layout width.
+		this.#lastLayoutWidth = Math.max(1, cx.cols);
+		const { lines, cursorLine, cursorCol } = this.#state;
+		const text = lines.join("\n");
+		let offset = 0;
+		for (let i = 0; i < cursorLine; i++) offset += (lines[i]?.length ?? 0) + 1;
+		const cursor = offset + cursorCol;
+
+		let decor = this.#nativeDecor;
+		if (decor?.text !== text || decor.generation !== this.#nativeGeneration) {
+			const next = this.describeDecorations?.(lines);
+			decor = {
+				text,
+				generation: this.#nativeGeneration,
+				decor:
+					next && next.length > 0
+						? decor?.decor && sameDecorations(decor.decor, next)
+							? decor.decor
+							: next
+						: undefined,
+			};
+			this.#nativeDecor = decor;
+		}
+
+		const placeholder = this.#getPlaceholder();
+		const nativePlaceholder =
+			this.nativePlaceholder !== undefined && !this.#autocompleteState && this.#isEditorEmpty()
+				? this.nativePlaceholder
+				: placeholder && plainText(placeholder).trim();
+		const atLineEnd = cursorCol >= (lines[cursorLine]?.length ?? 0);
+		const ghost = nativePlaceholder || !atLineEnd ? null : this.#getInlineHint();
+		const vim = this.#vim;
+		let anchor: number | null = null;
+		if (vim?.visual && vim.anchor !== null) {
+			let anchorOffset = 0;
+			for (let i = 0; i < vim.anchor.line; i++) anchorOffset += (lines[i]?.length ?? 0) + 1;
+			if (vim.mode === "visual-line") {
+				// Linewise: stretch the anchor to the far edge of its line.
+				const before =
+					vim.anchor.line < cursorLine || (vim.anchor.line === cursorLine && vim.anchor.col <= cursorCol);
+				anchor = before ? anchorOffset : anchorOffset + (lines[vim.anchor.line]?.length ?? 0);
+			} else {
+				anchor = anchorOffset + vim.anchor.col;
+			}
+		}
+		const prompt = this.#promptGutter === undefined ? "" : plainText(this.#promptGutter);
+		const props: TspEditorProps = {
+			text,
+			cursor,
+			anchor: anchor ?? undefined,
+			decor: decor.decor,
+			ghost: ghost ? plainText(ghost) : undefined,
+			placeholder: nativePlaceholder || undefined,
+			prompt: prompt || undefined,
+			mode: vim ? VIM_MODE_LABELS[vim.mode] : undefined,
+			lang: this.describeLanguage?.(),
+			maxLines: this.#maxHeight,
+		};
+		let editor = this.#nativeEditor;
+		if (!editor || !sameProps(editor.props, props)) {
+			editor = { props, node: node("editor", props, undefined, "input") };
+			this.#nativeEditor = editor;
+		}
+
+		const layout = this.describeLayout?.(editor.node, cx) ?? {
+			role: "omp.editor",
+			children: [editor.node],
+			caret: "input",
+		};
+		const children: NativeChild[] = [...layout.children];
+		const list = this.#visibleAutocompleteList();
+		if (list) {
+			list.setNativeMark(this.#autocompleteMark());
+			const overlay = this.#nativeOverlay;
+			if (overlay?.list !== list || overlay.caret !== layout.caret) {
+				this.#nativeOverlay = {
+					list,
+					caret: layout.caret,
+					node: node("overlay", { anchor: { caret: layout.caret }, role: "omp.autocomplete" }, [list], "complete"),
+				};
+			}
+			children.push(this.#nativeOverlay!.node);
+		} else {
+			this.#nativeOverlay = undefined;
+		}
+		const root = this.#nativeRoot;
+		if (root && root.role === layout.role && root.tone === layout.tone && sameItems(root.children, children)) {
+			return root.node;
+		}
+		const described = col(children, layout.tone ? { role: layout.role, tone: layout.tone } : { role: layout.role });
+		this.#nativeRoot = { role: layout.role, tone: layout.tone, children, node: described };
+		return described;
+	}
+
+	/**
+	 * The typed text the open popup matches item labels against, for the TSP
+	 * `mark`: the completion prefix (the live `@` token while a file list
+	 * narrows in place) without its sigil, from its last path segment on.
+	 */
+	#autocompleteMark(): string {
+		let typed = this.#autocompletePrefix;
+		if (typed.startsWith("@")) {
+			const line = this.#state.lines[this.#state.cursorLine] ?? "";
+			typed = AT_TOKEN_RE.exec(line.slice(0, this.#state.cursorCol))?.[1] ?? typed;
+		}
+		typed = typed.replace(/^[/@:#$^]"?/, "");
+		return typed.slice(typed.lastIndexOf("/") + 1);
+	}
+
 	handleInput(data: string): void {
 		// Iterative, not recursive: the bytes trailing a completed bracketed
 		// paste (which may themselves contain further pastes) loop back here,
@@ -1651,10 +1827,13 @@ export class Editor implements Component, Focusable {
 
 		// Handle autocomplete special keys first (but don't block other input)
 		if (this.#autocompleteState && this.#autocompleteList) {
-			// Escape - cancel autocomplete
+			// Escape - cancel autocomplete. A hidden popup (empty narrowed `@` list) is
+			// dropped too, so its pending refresh cannot pop up afterward, but the key
+			// falls through: the user never saw anything to dismiss.
 			if (kb.matchesCanonical(canonical, "tui.select.cancel")) {
+				const visible = this.isShowingAutocomplete();
 				this.#cancelAutocomplete(true);
-				return;
+				if (visible) return;
 			}
 			// Right arrow at end of line accepts the selection like Tab (fish-style).
 			// Mid-line, right arrow keeps its cursor-movement role and falls through.
@@ -1720,31 +1899,8 @@ export class Editor implements Component, Focusable {
 						// arrow at end of line moves the cursor.
 						this.#cancelAutocomplete();
 						this.onAutocompleteUpdate?.();
-					} else if (this.#autocompleteProvider) {
-						const shouldChainAutocomplete =
-							this.#isSlashCommandNameAutocompleteSelection() || isDirectoryCompletionValue(selected.value);
-						const result = this.#autocompleteProvider.applyCompletion(
-							this.#state.lines,
-							this.#state.cursorLine,
-							this.#state.cursorCol,
-							selected,
-							this.#autocompletePrefix,
-						);
-
-						this.#state.lines = result.lines;
-						this.#state.cursorLine = result.cursorLine;
-						this.#setCursorCol(result.cursorCol);
-
-						this.#cancelAutocomplete();
-						this.onAutocompleteUpdate?.();
-
-						this.#notifyChange();
-
-						result.onApplied?.();
-
-						if (shouldChainAutocomplete) {
-							queueMicrotask(() => void this.#tryTriggerAutocomplete());
-						}
+					} else {
+						this.#acceptAutocompleteSelection(selected);
 					}
 					// Only an accepted candidate consumes the key; an empty list falls through.
 					if (selected) return;
@@ -4108,6 +4264,35 @@ export class Editor implements Component, Focusable {
 		}
 		await this.#queueAutocompleteRequest({ kind: "regular", explicitTab });
 	}
+	/** Apply `selected` the way Tab does: complete it in place and chain into directories/commands. */
+	#acceptAutocompleteSelection(selected: SelectItem): void {
+		if (!this.#autocompleteProvider) return;
+		const shouldChainAutocomplete =
+			this.#isSlashCommandNameAutocompleteSelection() || isDirectoryCompletionValue(selected.value);
+		const result = this.#autocompleteProvider.applyCompletion(
+			this.#state.lines,
+			this.#state.cursorLine,
+			this.#state.cursorCol,
+			selected,
+			this.#autocompletePrefix,
+		);
+
+		this.#state.lines = result.lines;
+		this.#state.cursorLine = result.cursorLine;
+		this.#setCursorCol(result.cursorCol);
+
+		this.#cancelAutocomplete();
+		this.onAutocompleteUpdate?.();
+
+		this.#notifyChange();
+
+		result.onApplied?.();
+
+		if (shouldChainAutocomplete) {
+			queueMicrotask(() => void this.#tryTriggerAutocomplete());
+		}
+	}
+
 	#createAutocompleteList(
 		prefix: string,
 		items: Array<{ value: string; label: string; description?: string }>,
@@ -4117,7 +4302,14 @@ export class Editor implements Component, Focusable {
 			: prefix.startsWith("@")
 				? AT_FILE_SELECT_LIST_LAYOUT
 				: AUTOCOMPLETE_SELECT_LIST_LAYOUT;
-		return new SelectList(items, this.#autocompleteMaxVisible, this.#theme.selectList, layout);
+		const list = new SelectList(items, this.#autocompleteMaxVisible, this.#theme.selectList, layout);
+		// A pointer pick on the popup (TSP `select`/`activate`) accepts it like Tab.
+		list.onSelect = item => {
+			if (this.#autocompleteList !== list) return;
+			if (this.#autocompleteState === "assist") this.#applySpellingSuggestion();
+			else this.#acceptAutocompleteSelection(item);
+		};
+		return list;
 	}
 
 	async #handleTabCompletion(): Promise<void> {
@@ -4246,8 +4438,19 @@ export class Editor implements Component, Focusable {
 		}
 	}
 
+	/**
+	 * Whether an autocomplete popup is on screen. An `@` list narrowed to no match
+	 * while its refresh is pending stays open internally but is hidden, so it does
+	 * not claim keys (Escape, Vim mode switches) meant for the editor or app.
+	 */
 	isShowingAutocomplete(): boolean {
-		return this.#autocompleteState !== null;
+		return this.#visibleAutocompleteList() !== undefined;
+	}
+
+	/** The open autocomplete list, unless it has no candidate to show. */
+	#visibleAutocompleteList(): SelectList | undefined {
+		if (this.#autocompleteState === null) return undefined;
+		return this.#autocompleteList?.getSelectedItem() ? this.#autocompleteList : undefined;
 	}
 
 	async #updateAutocomplete(): Promise<void> {

package/src/components/form.ts

@@ -1,6 +1,10 @@
 import { getKeybindings } from "../keybindings";
 import { matchesKey } from "../keys";
 import type { MouseRoutable, SgrMouseEvent } from "../mouse";
+import { col, node, span } from "../native/describe";
+import { plainText } from "../native/spans";
+import type { DescribeContext, NativeChild, NativeNode, NativeUiEvent } from "../native/node";
+import { type SelectPickerOptions, SelectListSheet } from "../native/picker";
 import { Container, type Component, type Focusable } from "../tui";
 import { replaceTabs, truncateToWidth } from "../utils";
 import { Input } from "./input";
@@ -48,10 +52,13 @@ function hasMouseRouter(component: FormControl): component is FormControl & Mous
 class StyledText implements Component {
 	readonly #text: Text;
 	#value: string;
+	#native: NativeNode | undefined;
 
 	constructor(
 		value: string,
 		private readonly style: (text: string) => string,
+		/** Span token standing in for `style` on a TSP terminal. */
+		private readonly token?: string,
 	) {
 		this.#value = value;
 		this.#text = new Text(this.style(value), 0, 0);
@@ -60,9 +67,15 @@ class StyledText implements Component {
 	setText(value: string): void {
 		if (value === this.#value) return;
 		this.#value = value;
+		this.#native = undefined;
 		this.#text.setText(this.style(value));
 	}
 
+	describe(_cx: DescribeContext): NativeNode {
+		this.#native ??= node("text", { spans: [span(plainText(this.#value), this.token)] });
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		return this.#text.render(width);
 	}
@@ -77,9 +90,14 @@ class OptionalText implements Component {
 	readonly #text: StyledText;
 	#value = "";
 	readonly #empty: readonly string[] = [];
+	readonly #hidden = node("text", { text: "", hidden: true });
 
-	constructor(style: (text: string) => string) {
-		this.#text = new StyledText("", style);
+	constructor(style: (text: string) => string, token?: string) {
+		this.#text = new StyledText("", style, token);
+	}
+
+	describe(cx: DescribeContext): NativeNode {
+		return this.#value ? this.#text.describe(cx) : this.#hidden;
 	}
 
 	setText(value: string): void {
@@ -114,37 +132,67 @@ export class FormField implements Component, Focusable, MouseRoutable {
 	#memoControl: readonly string[] | undefined;
 	#memoAfter: readonly string[] | undefined;
 	#memoLines: readonly string[] = [];
+	/** Fixed described structure: every child is a component or a static node, so it never changes. */
+	readonly #native: NativeNode;
 
 	constructor(control: FormControl, options: FormFieldOptions) {
 		this.control = control;
-		this.#error = new OptionalText(options.theme.error);
+		this.#error = new OptionalText(options.theme.error, "error");
+		// Spacing is the terminal's (`gap`); only content becomes native children.
+		const native: NativeChild[] = [];
 
 		if (options.leadingSpace) this.#beforeControl.addChild(new Spacer(1));
 		if (options.label) {
-			this.#beforeControl.addChild(new StyledText(options.label, options.theme.label));
+			const label = new StyledText(options.label, options.theme.label, "strong");
+			this.#beforeControl.addChild(label);
+			native.push(label);
 		}
 		if (options.description) {
 			if (options.label) this.#beforeControl.addChild(new Spacer(1));
-			this.#beforeControl.addChild(new StyledText(options.description, options.theme.description));
+			const description = new StyledText(options.description, options.theme.description, "muted");
+			this.#beforeControl.addChild(description);
+			native.push(description);
+		}
+		for (const detail of options.details ?? []) {
+			this.#beforeControl.addChild(detail);
+			native.push(detail);
 		}
-		for (const detail of options.details ?? []) this.#beforeControl.addChild(detail);
 		if (options.preview) {
 			this.#beforeControl.addChild(new Spacer(1));
 			if (options.previewLabel) {
-				this.#beforeControl.addChild(new StyledText(options.previewLabel, options.theme.description));
+				const previewLabel = new StyledText(options.previewLabel, options.theme.description, "muted");
+				this.#beforeControl.addChild(previewLabel);
+				native.push(previewLabel);
 			}
 			this.#beforeControl.addChild(options.preview);
+			native.push(options.preview);
 		}
 		if (options.spaceBeforeControl !== false) this.#beforeControl.addChild(new Spacer(1));
+		native.push(control);
 
 		if (options.spaceAfterControl !== false) this.#afterControl.addChild(new Spacer(1));
 		this.#afterControl.addChild(this.#error);
-		for (const summary of options.summary ?? []) this.#afterControl.addChild(summary);
-		if (options.hint) this.#afterControl.addChild(new StyledText(options.hint, options.theme.hint));
+		native.push(this.#error);
+		for (const summary of options.summary ?? []) {
+			this.#afterControl.addChild(summary);
+			native.push(summary);
+		}
+		if (options.hint) {
+			const hint = new StyledText(options.hint, options.theme.hint, "muted");
+			this.#afterControl.addChild(hint);
+			native.push(hint);
+		}
 		if (options.footer) {
 			this.#afterControl.addChild(new Spacer(1));
 			this.#afterControl.addChild(options.footer);
+			native.push(options.footer);
 		}
+		this.#native = col(native, { gap: "sm", role: "omp.form.field" });
+	}
+
+	/** Label, description, details, preview, the control, error, summary, hint and footer as one column. */
+	describe(_cx: DescribeContext): NativeNode {
+		return this.#native;
 	}
 
 	get focused(): boolean {
@@ -346,14 +394,22 @@ export interface SelectFormFieldOptions extends Omit<FormFieldOptions, "preview"
 	onCancel(): void;
 	/** Schedule a frame after an asynchronous preview update settles. */
 	requestRender?: () => void;
+	/** The picker sheet a long choice (> {@link PICKER_MIN_ITEMS} items) describes as; defaults to the label. */
+	picker?: SelectPickerOptions;
 }
 
+/** Choices longer than this describe as a `picker md` sheet where the terminal draws one (spec §5 controls). */
+const PICKER_MIN_ITEMS = 12;
+
 /** SelectList field that centralizes selection, cancellation, preview refresh, and mouse routing. */
 export class SelectFormField extends FormField {
 	readonly selectList: SelectList;
 	readonly #previewText: StyledText | undefined;
 	readonly #getPreview: (() => string) | undefined;
 	readonly #requestRender: (() => void) | undefined;
+	readonly #sheet: SelectListSheet;
+	/** Number of choices (before filtering). */
+	readonly itemCount: number;
 	#previewRequestId = 0;
 
 	constructor(options: SelectFormFieldOptions) {
@@ -375,6 +431,16 @@ export class SelectFormField extends FormField {
 		this.#previewText = previewText;
 		this.#getPreview = options.getPreview;
 		this.#requestRender = options.requestRender;
+		this.itemCount = options.items.length;
+		this.#sheet = new SelectListSheet(
+			selectList,
+			options.picker ?? {
+				title: options.label ?? "Select",
+				...(options.description ? { subtitle: options.description } : {}),
+				searchable: true,
+			},
+			{ docked: false },
+		);
 
 		selectList.onSelect = item => {
 			try {
@@ -420,9 +486,20 @@ export class SelectFormField extends FormField {
 
 	override invalidate(): void {
 		this.#updatePreview();
+		this.#sheet.invalidate();
 		super.invalidate();
 	}
 
+	/** Long choices describe as a picker sheet where supported; the host places it (layer or prefs editor). */
+	override describe(cx: DescribeContext): NativeNode {
+		return this.itemCount > PICKER_MIN_ITEMS && cx.supports("picker") ? this.#sheet.describe() : super.describe(cx);
+	}
+
+	/** Picker pointer events drive the list as its keys do (preview, pick, cancel). */
+	handleNativeEvent(event: NativeUiEvent): void {
+		this.#sheet.handle(event);
+	}
+
 	#finishPreview(requestId: number): void {
 		if (requestId !== this.#previewRequestId) return;
 		this.setError(undefined);
@@ -467,13 +544,20 @@ export class Form implements Component, Focusable, MouseRoutable {
 	#memoWidth = -1;
 	#memoFieldLines: (readonly string[])[] = [];
 	#memoLines: readonly string[] = [];
+	readonly #native: NativeNode;
 
 	constructor(options: FormOptions) {
 		this.#options = options;
 		this.#fields = options.fields;
+		this.#native = col(this.#fields, { gap: "md", role: "omp.form" });
 		this.#syncFocus();
 	}
 
+	/** The fields as one column; focus traversal stays keyboard-driven. */
+	describe(_cx: DescribeContext): NativeNode {
+		return this.#native;
+	}
+
 	get focused(): boolean {
 		return this.#focused;
 	}

package/src/components/image.ts

@@ -8,6 +8,9 @@ import {
 	renderImage,
 	TERMINAL,
 } from "../terminal-capabilities";
+import { registerNativeBlob } from "../native/blobs";
+import { node } from "../native/describe";
+import type { DescribeContext, NativeNode } from "../native/node";
 import type { Component } from "../tui";
 
 export interface ImageTheme {
@@ -731,6 +734,7 @@ export class Image implements Component {
 	// pads itself to this height so a budget demotion never shrinks the block
 	// (its rows may already be committed to native scrollback).
 	#renderedGraphicRows = 0;
+	#native?: NativeNode;
 
 	constructor(
 		base64Data: string,
@@ -764,6 +768,32 @@ export class Image implements Component {
 		this.#cachedWidth = undefined;
 	}
 
+	/**
+	 * A native `image` backed by a content-addressed blob; the terminal fits
+	 * it. Cell caps become `ch`/`lines` bounds. The inline-image budget and
+	 * graphics protocols do not apply.
+	 */
+	describe(_cx: DescribeContext): NativeNode {
+		if (this.#native) return this.#native;
+		const blob = registerNativeBlob(Buffer.from(this.#base64Data, "base64"), this.#mimeType);
+		const maxW = this.#options.maxWidthCells;
+		const maxH = this.#options.maxHeightCells;
+		this.#native = node("image", {
+			blob,
+			alt: imageFallback(this.#mimeType, this.#dimensions, this.#options.filename),
+			w: this.#dimensions.widthPx,
+			h: this.#dimensions.heightPx,
+			max:
+				(maxW ?? 0) > 0 || (maxH ?? 0) > 0
+					? {
+							w: maxW && maxW > 0 ? `${maxW}ch` : undefined,
+							h: maxH && maxH > 0 ? `${maxH}lines` : undefined,
+						}
+					: undefined,
+		});
+		return this.#native;
+	}
+
 	render(width: number): readonly string[] {
 		const imageProtocol = TERMINAL.imageProtocol;
 		const hasProtocol = imageProtocol != null;