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

package/src/native/backend.ts

@@ -0,0 +1,682 @@
+/**
+ * Native (Tern Surface Protocol) backend: owns the surfaces a TSP terminal
+ * shows, sends reconciled frames under credit-based flow control, uploads
+ * blobs, and routes terminal events back to components.
+ *
+ * Surfaces. An inline surface (`mode:"inline"`) holds the session: its root
+ * (id = surface id) gets the fixed regions `main`, `dock` and `layer` on the
+ * first frame. While a fullscreen overlay is topmost, a `mode:"screen"`
+ * surface shows it instead and the inline surface pauses (the way the ANSI
+ * path borrows the alternate screen); closing the overlay closes that surface
+ * and the next inline frame catches up.
+ *
+ * Flow control. At most `credits` frames per surface are unacknowledged. A
+ * render while blocked only marks the surface dirty; the next `ack` reconciles
+ * once against the last sent state, so every intermediate change coalesces
+ * into one frame (`set`s merged, `text append`s joined).
+ */
+import * as fs from "node:fs";
+import * as logger from "@oh-my-pi/pi-utils/logger";
+import {
+	TSP_DEFAULT_APC_LIMIT,
+	TSP_DEFAULT_CREDITS,
+	TSP_KINDS,
+	TSP_VERSION,
+	type TspEvent,
+	type TspFrame,
+	type TspKind,
+	type TspNode,
+	type TspOp,
+} from "@oh-my-pi/pi-wire";
+import type { Terminal } from "../terminal";
+import {
+	bindTheme,
+	getCurrentThemeName,
+	getNativeThemePalette,
+	getNativeThemePaletteKey,
+	isLightTheme,
+	type NativeThemePalette,
+	setNativeSymbolPreset,
+} from "../theme/theme";
+import type { Component, OverlayOptions } from "../tui";
+import { TspDocument } from "./apply";
+import { getNativeBlob } from "./blobs";
+import { node } from "./describe";
+import { encodeTspJson, encodeTspMessage, type TspHello, TspReader, splitTspMessage } from "./encode";
+import type { DescribeContext, NativeChild, NativeNode, NativeSurface, NativeUiEvent } from "./node";
+import { nativeComponentId, Reconciler } from "./reconcile";
+import { setNativeRendering } from "./state";
+
+/** A visible TUI overlay, bottom to top. */
+export interface NativeOverlay {
+	readonly component: Component;
+	readonly options: OverlayOptions | undefined;
+	/** Keyboard focus is inside this overlay. */
+	readonly focused: boolean;
+}
+
+/** What the backend needs from the TUI. */
+export interface NativeHost {
+	readonly terminal: Terminal;
+	/** `main`/`dock` content: the frame provider's surface, or the TUI children. */
+	describeSurface(cx: DescribeContext): NativeSurface;
+	/** Visible overlays, bottom to top. */
+	overlays(): readonly NativeOverlay[];
+	/** Component receiving keyboard input. */
+	focused(): Component | null;
+	requestRender(): void;
+	/** The terminal switched appearance. */
+	appearanceChanged(dark: boolean): void;
+	/** Reduce Motion toggled. */
+	motionChanged(reduce: boolean): void;
+	/** Theme-derived output changed (symbol preset): drop render and describe caches. */
+	invalidate(): void;
+}
+
+export interface NativeBackendOptions {
+	/** Keep the reference document and recent frames for debugging. */
+	readonly mirror?: boolean;
+	/** Append every TSP message to this JSONL file. Defaults to `PI_TUI_TSP_RECORD`. */
+	readonly recordPath?: string;
+	/** Log the `rows` fallback count per frame. Defaults to `PI_TUI_NATIVE_STATS=1`. */
+	readonly stats?: boolean;
+	readonly now?: () => number;
+}
+
+/** Frames kept for the debug `tsp` op. */
+const RECENT_FRAMES = 64;
+/** An unanswered frame older than this no longer holds rendering back. */
+const STALLED_ACK_MS = 5000;
+
+class NativeContext implements DescribeContext {
+	cols: number;
+	reduceMotion: boolean;
+	dark: boolean;
+	#kinds: ReadonlySet<string>;
+	#features: ReadonlySet<string>;
+
+	constructor(hello: TspHello, cols: number) {
+		this.cols = cols;
+		this.reduceMotion = hello.reduceMotion === true;
+		this.dark = hello.dark !== false;
+		this.#kinds = new Set(hello.kinds);
+		this.#features = new Set(hello.features);
+	}
+
+	supports(kind: TspKind): boolean {
+		return this.#kinds.has(kind);
+	}
+
+	feature(name: string): boolean {
+		return this.#features.has(name);
+	}
+
+	/** Whether `other` advertises exactly the same kinds and features. */
+	sameVocabulary(other: NativeContext): boolean {
+		return sameSet(this.#kinds, other.#kinds) && sameSet(this.#features, other.#features);
+	}
+}
+
+/** Whether `a` and `b` hold the same strings. */
+function sameSet(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean {
+	if (a.size !== b.size) return false;
+	for (const item of a) if (!b.has(item)) return false;
+	return true;
+}
+
+/**
+ * The reply a v1 terminal is assumed to give before its real `hello` arrives
+ * (the `TERM_PROGRAM=tern` optimistic start): the whole vocabulary, the
+ * default APC limit and credits, the terminal's width, the appearance omp
+ * already detected, and full motion.
+ */
+export function assumedTspHello(terminal: Terminal): TspHello {
+	const appearance = terminal.appearance;
+	return {
+		r: "hello",
+		v: TSP_VERSION,
+		term: "tern",
+		kinds: TSP_KINDS,
+		apc: TSP_DEFAULT_APC_LIMIT,
+		credits: TSP_DEFAULT_CREDITS,
+		cols: terminal.columns,
+		dark: appearance === undefined ? !isLightTheme(getCurrentThemeName()) : appearance === "dark",
+		reduceMotion: false,
+	};
+}
+
+class Surface {
+	readonly id: string;
+	readonly mode: "inline" | "screen";
+	readonly reconciler: Reconciler;
+	readonly doc: TspDocument | null;
+	seq = 0;
+	acked = 0;
+	/** Send times of unacknowledged frames, oldest first. */
+	unacked: number[] = [];
+	uploaded = new Set<string>();
+	focus: string | null = null;
+	dirty = false;
+
+	constructor(id: string, mode: "inline" | "screen", mirror: boolean) {
+		this.id = id;
+		this.mode = mode;
+		this.reconciler = new Reconciler(id);
+		this.doc = mirror ? new TspDocument(id) : null;
+	}
+}
+
+function overlayAnchor(options: OverlayOptions | undefined): "center" | "top" | "bottom" {
+	const anchor = options?.anchor;
+	if (anchor?.startsWith("top")) return "top";
+	if (anchor?.startsWith("bottom")) return "bottom";
+	return "center";
+}
+
+function overlaySize(options: OverlayOptions | undefined, cols: number): "sm" | "md" | "lg" | "full" {
+	if (options?.fullscreen) return "full";
+	const width = options?.width;
+	if (width === undefined) return "md";
+	const fraction = typeof width === "number" ? width / Math.max(1, cols) : Number.parseFloat(width) / 100;
+	if (!Number.isFinite(fraction)) return "md";
+	if (fraction >= 0.75) return "lg";
+	if (fraction >= 0.45) return "md";
+	return "sm";
+}
+
+/** Blob ids referenced by `image` nodes an op adds or sets. */
+function collectBlobs(op: TspOp, out: Set<string>): void {
+	if (op[0] === "set") {
+		const blob = op[2].blob;
+		if (typeof blob === "string") out.add(blob);
+	} else if (op[0] === "add") {
+		const visit = (wire: TspNode): void => {
+			if (wire.k === "image" && typeof wire.p?.blob === "string") out.add(wire.p.blob);
+			if (wire.c) for (const child of wire.c) visit(child);
+		};
+		visit(op[4]);
+	}
+}
+
+export class NativeBackend {
+	#host: NativeHost;
+	#hello: TspHello;
+	#cx: NativeContext;
+	#limit: number;
+	#credits: number;
+	#reader = new TspReader();
+	#inline: Surface;
+	#screen: Surface | null = null;
+	#nextSurface = 1;
+	#mirror: boolean;
+	#recordPath: string | undefined;
+	#stats: boolean;
+	#now: () => number;
+	#recent: TspFrame[] = [];
+	#sawResize = false;
+	#live = false;
+	#overlayNodes = new Map<Component, { key: string; node: NativeNode }>();
+	#unbindTheme: (() => void) | undefined;
+	#palette: NativeThemePalette | undefined;
+	#paletteKey: string | undefined;
+	/** Serialized palette last sent, to skip resends of an unchanged theme. */
+	#paletteSent: string | undefined;
+
+	constructor(host: NativeHost, hello: TspHello, options: NativeBackendOptions = {}) {
+		this.#host = host;
+		this.#hello = hello;
+		this.#cx = new NativeContext(hello, hello.cols ?? host.terminal.columns);
+		this.#limit = TSP_DEFAULT_APC_LIMIT;
+		this.#credits = TSP_DEFAULT_CREDITS;
+		this.#applyHello(hello);
+		this.#mirror = options.mirror === true;
+		this.#recordPath = options.recordPath ?? (Bun.env.PI_TUI_TSP_RECORD || undefined);
+		this.#stats = options.stats ?? Bun.env.PI_TUI_NATIVE_STATS === "1";
+		this.#now = options.now ?? Date.now;
+		this.#inline = this.#newSurface("inline");
+	}
+
+	/** The terminal's hello reply. */
+	get hello(): TspHello {
+		return this.#hello;
+	}
+
+	/** Describe context shared by every surface. */
+	get context(): DescribeContext {
+		return this.#cx;
+	}
+
+	/** `rows` fallback nodes in the last frame. */
+	get fallbackCount(): number {
+		return (this.#screen ?? this.#inline).reconciler.fallbackCount;
+	}
+
+	/**
+	 * Open the inline surface and send the first frame. Native rendering is
+	 * announced only once the surface is open: Tern drops the shell's title
+	 * when a command's first surface opens, so the tab title set on the change
+	 * has to follow the `o`.
+	 */
+	start(): void {
+		if (this.#live) return;
+		this.#live = true;
+		this.#useNerdSymbols(true);
+		this.#watchTheme();
+		this.#open(this.#inline);
+		setNativeRendering(true);
+		this.render();
+	}
+
+	/**
+	 * Any theme swap (switch, selector preview, auto light/dark, file reload)
+	 * schedules a render; `render()` resends the palette when it changed, so
+	 * bursts coalesce into one `t` and no frame is needed for it.
+	 */
+	#watchTheme(): void {
+		this.#unbindTheme?.();
+		let initial = true;
+		this.#unbindTheme = bindTheme(() => {
+			if (initial) return;
+			this.#host.requestRender();
+		});
+		initial = false;
+	}
+
+	/** The current palette, recomputed only when its inputs changed. */
+	#currentPalette(): NativeThemePalette {
+		const key = getNativeThemePaletteKey();
+		if (this.#palette === undefined || key !== this.#paletteKey) {
+			this.#paletteKey = key;
+			this.#palette = getNativeThemePalette();
+		}
+		return this.#palette;
+	}
+
+	/** Send the palette to `surface` (right after its `o`, before any `f`). */
+	#sendPalette(surface: Surface): void {
+		const palette = this.#currentPalette();
+		if (!palette.dark && !palette.light) return;
+		this.#paletteSent = JSON.stringify(palette);
+		this.#write("t", { sf: surface.id, ...palette });
+	}
+
+	/** Resend the palette to every open surface when the theme changed since it was sent. */
+	#refreshPalette(): void {
+		const key = this.#paletteKey;
+		const palette = this.#currentPalette();
+		if (key === this.#paletteKey || JSON.stringify(palette) === this.#paletteSent) return;
+		this.#sendPalette(this.#inline);
+		if (this.#screen) this.#sendPalette(this.#screen);
+	}
+
+	/**
+	 * Tern's font carries every Nerd Font glyph, and it never answers the Glyph
+	 * Protocol, so icons come from the nerd preset (process-local, not the
+	 * user's saved setting) while a surface is live.
+	 */
+	#useNerdSymbols(on: boolean): void {
+		if (setNativeSymbolPreset(on ? "nerd" : undefined)) this.#host.invalidate();
+	}
+
+	/**
+	 * Close every surface. The inline transcript stays in scrollback unless
+	 * `keep` is false (a revoked optimistic start: rows repaint from scratch).
+	 */
+	stop(keep = true): void {
+		if (!this.#live) return;
+		this.#live = false;
+		if (this.#screen) this.#close(this.#screen, false);
+		this.#screen = null;
+		this.#close(this.#inline, keep);
+		this.#inline.doc?.close();
+		setNativeRendering(false);
+		this.#unbindTheme?.();
+		this.#unbindTheme = undefined;
+		this.#useNerdSymbols(false);
+	}
+
+	/**
+	 * After a stop/start cycle (external editor, suspend): adopt the closed
+	 * inline surface so the transcript continues in place instead of being
+	 * printed again. A `gone` reply for it opens a fresh surface.
+	 */
+	resume(hello: TspHello): void {
+		if (this.#live) return;
+		this.#hello = hello;
+		this.#applyHello(hello);
+		this.#live = true;
+		this.#useNerdSymbols(true);
+		this.#watchTheme();
+		const surface = this.#inline;
+		surface.reconciler.detachLive();
+		surface.unacked = [];
+		surface.acked = surface.seq;
+		surface.focus = null;
+		surface.dirty = false;
+		this.#write("o", { id: surface.id, mode: "inline", title: "omp", role: "omp.session", adopt: true });
+		this.#sendPalette(surface);
+		// After the `o`, as in `start()`.
+		setNativeRendering(true);
+		this.render();
+	}
+
+	/**
+	 * The terminal's real `hello` reply after an optimistic start: adopt its
+	 * APC limit, credits, cell size, kinds, appearance and motion preference.
+	 * A width the terminal already reported in a `resize` event wins over the
+	 * reply's. A different vocabulary or motion preference re-describes every
+	 * component, so kinds the terminal lacks fall back.
+	 */
+	confirm(hello: TspHello): void {
+		const before = this.#cx;
+		const sawResize = this.#sawResize;
+		this.#hello = hello;
+		this.#applyHello(hello);
+		if (sawResize) {
+			this.#cx.cols = before.cols;
+			this.#sawResize = true;
+		}
+		if (this.#cx.dark !== before.dark) this.#host.appearanceChanged(this.#cx.dark);
+		if (this.#cx.reduceMotion !== before.reduceMotion || !this.#cx.sameVocabulary(before)) this.#host.invalidate();
+		this.#host.requestRender();
+	}
+
+	/** SIGWINCH: refresh the width used for `rows` fallback until the terminal reports one. */
+	noteTerminalColumns(columns: number): void {
+		if (this.#sawResize || columns === this.#cx.cols) return;
+		this.#cx.cols = columns;
+		this.#host.requestRender();
+	}
+
+	/** Reconcile and send a frame, unless the target surface is out of credits. */
+	render(): void {
+		if (!this.#live) return;
+		this.#refreshPalette();
+		const overlays = this.#host.overlays();
+		let fullscreen = -1;
+		for (let i = overlays.length - 1; i >= 0; i--) {
+			// A picker/prefs sheet floats in `layer` over the transcript even
+			// when the TUI shows it fullscreen.
+			const o = overlays[i]!;
+			if (o.options?.fullscreen && !o.component.nativeSheet?.(this.#cx) && !o.component.nativeOverlay) {
+				fullscreen = i;
+				break;
+			}
+		}
+		let surface: Surface;
+		let main: readonly NativeChild[];
+		let dock: readonly NativeChild[];
+		let layer: NativeChild[];
+		if (fullscreen >= 0) {
+			if (!this.#screen) {
+				this.#screen = this.#newSurface("screen");
+				this.#open(this.#screen);
+			}
+			surface = this.#screen;
+			main = [overlays[fullscreen]!.component];
+			dock = [];
+			layer = overlays.slice(fullscreen + 1).map(overlay => this.#overlayNode(overlay));
+		} else {
+			if (this.#screen) {
+				this.#close(this.#screen, false);
+				this.#screen = null;
+			}
+			surface = this.#inline;
+			const described = this.#host.describeSurface(this.#cx);
+			main = described.main;
+			dock = described.dock;
+			layer = overlays.map(overlay => this.#overlayNode(overlay));
+		}
+		this.#pruneOverlayNodes(overlays);
+		if (!this.#hasCredit(surface)) {
+			surface.dirty = true;
+			return;
+		}
+		surface.dirty = false;
+		const ops = surface.reconciler.reconcile({ main, dock, layer }, this.#cx);
+		const focused = this.#host.focused();
+		const focus = focused ? surface.reconciler.focusTarget(focused) : null;
+		if (focus !== surface.focus) {
+			ops.push(["focus", focus]);
+			surface.focus = focus;
+		}
+		if (this.#stats) {
+			logger.debug("TSP frame", { sf: surface.id, ops: ops.length, rows: surface.reconciler.fallbackCount });
+		}
+		if (ops.length === 0) return;
+		this.#uploadBlobs(surface, ops);
+		this.#sendFrame(surface, ops);
+	}
+
+	/**
+	 * Handle one complete `ESC _ tsp;…` input string (events and late replies).
+	 * Returns false when `sequence` isn't TSP.
+	 */
+	handleInput(sequence: string): boolean {
+		const raw = splitTspMessage(sequence);
+		if (!raw) return false;
+		this.#record("in", raw.verb, raw.params, raw.body);
+		const message = this.#reader.feed(sequence);
+		if (message?.verb === "e") this.#handleEvent(message.event);
+		return true;
+	}
+
+	/** Reference document of the live surface (mirror mode only). */
+	document(): TspNode | undefined {
+		return (this.#screen ?? this.#inline).doc?.snapshot();
+	}
+
+	/** Last sent frames, oldest first (mirror mode only). */
+	recentFrames(count = RECENT_FRAMES): readonly TspFrame[] {
+		return this.#recent.slice(-count);
+	}
+
+	#applyHello(hello: TspHello): void {
+		this.#limit = hello.apc !== undefined && hello.apc > 0 ? hello.apc : TSP_DEFAULT_APC_LIMIT;
+		this.#credits = hello.credits !== undefined && hello.credits > 0 ? hello.credits : TSP_DEFAULT_CREDITS;
+		this.#cx = new NativeContext(hello, hello.cols ?? this.#cx.cols);
+		this.#sawResize = false;
+	}
+
+	#newSurface(mode: "inline" | "screen"): Surface {
+		return new Surface(`s:${this.#nextSurface++}`, mode, this.#mirror);
+	}
+
+	#open(surface: Surface): void {
+		this.#write("o", { id: surface.id, mode: surface.mode, title: "omp", role: "omp.session" });
+		this.#sendPalette(surface);
+	}
+
+	#close(surface: Surface, keep: boolean): void {
+		this.#write("x", { id: surface.id, keep });
+	}
+
+	#hasCredit(surface: Surface): boolean {
+		if (surface.unacked.length < this.#credits) return true;
+		const oldest = surface.unacked[0]!;
+		if (this.#now() - oldest < STALLED_ACK_MS) return false;
+		logger.warn("TSP: terminal stopped acknowledging frames; resuming without credits", {
+			sf: surface.id,
+			s: surface.seq,
+			acked: surface.acked,
+		});
+		surface.unacked = [];
+		surface.acked = surface.seq;
+		return true;
+	}
+
+	#sendFrame(surface: Surface, ops: readonly TspOp[]): void {
+		surface.seq++;
+		surface.unacked.push(this.#now());
+		const frame: TspFrame = { sf: surface.id, s: surface.seq, ops };
+		if (surface.doc) {
+			const errors = surface.doc.applyFrame(frame);
+			if (errors.length > 0) logger.warn("TSP: reference document rejected ops", { sf: surface.id, errors });
+			this.#recent.push(frame);
+			if (this.#recent.length > RECENT_FRAMES) this.#recent.splice(0, this.#recent.length - RECENT_FRAMES);
+		}
+		this.#write("f", frame);
+	}
+
+	#uploadBlobs(surface: Surface, ops: readonly TspOp[]): void {
+		const ids = new Set<string>();
+		for (const op of ops) collectBlobs(op, ids);
+		for (const id of ids) {
+			if (surface.uploaded.has(id)) continue;
+			const blob = getNativeBlob(id);
+			if (!blob) {
+				logger.warn("TSP: image references an unregistered blob", { id });
+				continue;
+			}
+			surface.uploaded.add(id);
+			const body = Buffer.from(blob.bytes.buffer, blob.bytes.byteOffset, blob.bytes.byteLength).toString("base64");
+			// The full body, so a replay (Tern's `surface-play`) shows the image.
+			this.#record("out", "b", { id, mime: blob.mime }, body);
+			this.#host.terminal.write(encodeTspMessage("b", body, { id, mime: blob.mime }, this.#limit));
+		}
+	}
+
+	#write(verb: "o" | "f" | "t" | "x", body: unknown): void {
+		this.#record("out", verb, undefined, body);
+		this.#host.terminal.write(encodeTspJson(verb, body, undefined, this.#limit));
+	}
+
+	#record(dir: "in" | "out", verb: string, params: Readonly<Record<string, string>> | undefined, body: unknown): void {
+		const path = this.#recordPath;
+		if (!path) return;
+		let payload = body;
+		if (dir === "in" && typeof body === "string") {
+			try {
+				payload = JSON.parse(body);
+			} catch {
+				payload = body;
+			}
+		}
+		try {
+			fs.appendFileSync(path, `${JSON.stringify({ t: this.#now(), dir, verb, params, body: payload })}\n`);
+		} catch (error) {
+			logger.warn("TSP: recording failed; disabling", { path, error: String(error) });
+			this.#recordPath = undefined;
+		}
+	}
+
+	#surfaceFor(sf: string | undefined): Surface | null {
+		if (sf === undefined || sf === this.#inline.id) return this.#inline;
+		return this.#screen?.id === sf ? this.#screen : null;
+	}
+
+	#handleEvent(event: TspEvent): void {
+		switch (event.ev) {
+			case "ack": {
+				const surface = this.#surfaceFor(event.sf);
+				if (!surface || event.s <= surface.acked) return;
+				const newly = Math.min(event.s, surface.seq) - surface.acked;
+				surface.acked = Math.min(event.s, surface.seq);
+				surface.unacked.splice(0, newly);
+				if (surface.dirty) this.#host.requestRender();
+				return;
+			}
+			case "resize": {
+				this.#sawResize = true;
+				if (event.cols === this.#cx.cols) return;
+				this.#cx.cols = event.cols;
+				this.#host.requestRender();
+				return;
+			}
+			case "theme":
+				this.#cx.dark = event.dark;
+				this.#host.appearanceChanged(event.dark);
+				return;
+			case "motion":
+				this.#cx.reduceMotion = event.reduce;
+				this.#host.motionChanged(event.reduce);
+				return;
+			case "visible":
+				return;
+			case "error":
+				logger.warn("TSP: terminal reported an error", event);
+				return;
+			case "gone":
+				if (event.ids.includes(this.#inline.id)) {
+					// Adopt found nothing (evicted, or another pane): start over.
+					this.#inline = this.#newSurface("inline");
+					if (this.#live) this.#open(this.#inline);
+					this.#host.requestRender();
+					return;
+				}
+				this.#surfaceFor(event.sf)?.reconciler.forget(event.ids);
+				return;
+			case "toggle":
+			case "select":
+			case "activate":
+			case "action":
+			case "change":
+				this.#routeUiEvent(event);
+				return;
+		}
+	}
+
+	#routeUiEvent(event: Extract<TspEvent, { ev: "toggle" | "select" | "activate" | "action" | "change" }>): void {
+		const reconciler = this.#surfaceFor(event.sf)?.reconciler;
+		const target = reconciler?.target(event.id);
+		if (!reconciler || !target?.component.handleNativeEvent) return;
+		// A list's items are nodes (`<list>/<key>`, or a component's root id) and
+		// map back to their described key. Data-first kinds (picker, prefs) send
+		// the program's own item ids (model ids, paths), which pass through.
+		const item = (id: string): string =>
+			id.startsWith(`${event.id}/`) || id.startsWith(`${event.id}.`) || !id.includes(".")
+				? reconciler.itemKey(id)
+				: id;
+		let ui: NativeUiEvent;
+		switch (event.ev) {
+			case "toggle":
+				ui = { type: "toggle", key: target.keypath, collapsed: event.collapsed };
+				break;
+			case "select":
+				ui = { type: "select", key: target.keypath, item: item(event.item) };
+				break;
+			case "activate":
+				ui = { type: "activate", key: target.keypath, item: item(event.item) };
+				break;
+			case "action":
+				ui = { type: "action", key: target.keypath, act: event.act, value: event.value, mods: event.mods ?? [] };
+				break;
+			case "change":
+				ui = { type: "change", key: target.keypath, item: event.item, value: event.value };
+				break;
+		}
+		target.component.handleNativeEvent(ui);
+		this.#host.requestRender();
+	}
+
+	/**
+	 * The `overlay` node wrapping a TUI overlay, memoized while its placement
+	 * is unchanged; a component describing its own sheet goes in unwrapped.
+	 */
+	#overlayNode(overlay: NativeOverlay): NativeChild {
+		if (overlay.component.nativeSheet?.(this.#cx)) return overlay.component;
+		const own = overlay.component.nativeOverlay;
+		const anchor = own?.anchor ?? overlayAnchor(overlay.options);
+		const size = own?.size ?? overlaySize(overlay.options, this.#cx.cols);
+		const modal = overlay.focused || overlay.options?.fullscreen === true;
+		const role = own?.role;
+		const head = own?.head;
+		const key = `${anchor}|${size}|${modal}|${role}|${JSON.stringify(head)}`;
+		const cached = this.#overlayNodes.get(overlay.component);
+		if (cached?.key === key) return cached.node;
+		const wrapper = node(
+			"overlay",
+			{ anchor, size, modal, ...(role ? { role } : {}), ...(head ? { head } : {}) },
+			[overlay.component],
+			`ov-${nativeComponentId(overlay.component)}`,
+		);
+		this.#overlayNodes.set(overlay.component, { key, node: wrapper });
+		return wrapper;
+	}
+
+	#pruneOverlayNodes(overlays: readonly NativeOverlay[]): void {
+		if (this.#overlayNodes.size <= overlays.length) return;
+		const live = new Set(overlays.map(overlay => overlay.component));
+		for (const component of this.#overlayNodes.keys()) if (!live.has(component)) this.#overlayNodes.delete(component);
+	}
+}