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

package/src/native/blobs.ts

@@ -0,0 +1,70 @@
+/**
+ * Content-addressed binary blobs (images) for `image` nodes.
+ *
+ * `describe()` registers the bytes and puts the returned id in `image.p.blob`;
+ * the native backend uploads each referenced blob once per surface with verb
+ * `b` before the frame that first references it.
+ */
+import type { TspProps } from "@oh-my-pi/pi-wire";
+import { getImageDimensions } from "../terminal-capabilities";
+import { node } from "./describe";
+import type { NativeNode } from "./node";
+
+export interface NativeBlob {
+	readonly id: string;
+	readonly mime: string;
+	readonly bytes: Uint8Array;
+}
+
+const blobs = new Map<string, NativeBlob>();
+// Registration usually repeats with the same bytes object on every describe;
+// the tag skips rehashing it.
+const kBlobId = Symbol("native.blobId");
+
+interface BlobTagged {
+	[kBlobId]?: string;
+}
+
+/** Register `bytes` and return their content address (sha256 hex) for `image.p.blob`. */
+export function registerNativeBlob(bytes: Uint8Array, mime: string): string {
+	const known = (bytes as BlobTagged)[kBlobId];
+	if (known !== undefined) return known;
+	const id = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+	(bytes as BlobTagged)[kBlobId] = id;
+	if (!blobs.has(id)) blobs.set(id, { id, mime, bytes });
+	return id;
+}
+
+/** A registered blob by id. */
+export function getNativeBlob(id: string): NativeBlob | undefined {
+	return blobs.get(id);
+}
+
+/**
+ * An `image` node for a base64 payload: the bytes are registered as a blob and
+ * the pixel size probed from the header. Decoding and hashing cost real time,
+ * so callers cache the node per payload ({@link NativeImageCache}).
+ */
+export function base64ImageNode(
+	data: string,
+	mimeType: string,
+	p?: Omit<TspProps<"image">, "blob" | "w" | "h">,
+	key?: string,
+): NativeNode {
+	const blob = registerNativeBlob(Buffer.from(data, "base64"), mimeType);
+	const size = getImageDimensions(data, mimeType);
+	return node("image", size ? { ...p, blob, w: size.widthPx, h: size.heightPx } : { ...p, blob }, undefined, key);
+}
+
+/** `image` nodes for base64 payloads, one per slot key, rebuilt only when the slot's payload changes. */
+export class NativeImageCache {
+	#entries = new Map<string, { data: string; node: NativeNode }>();
+
+	get(key: string, data: string, mimeType: string): NativeNode {
+		const cached = this.#entries.get(key);
+		if (cached?.data === data) return cached.node;
+		const image = base64ImageNode(data, mimeType, { alt: mimeType }, key);
+		this.#entries.set(key, { data, node: image });
+		return image;
+	}
+}

package/src/native/describe.ts

@@ -0,0 +1,124 @@
+/**
+ * Builders for {@link NativeNode}s, so `describe()` implementations read as
+ * a tree instead of object literals.
+ *
+ * @example
+ * describe() {
+ *   return card({ role: "omp.tool.bash", status: "running", head: [span("Bash", "toolTitle")] }, [
+ *     ansi(this.#output, { follow: true, preview: { lines: 10 } }),
+ *   ]);
+ * }
+ */
+import type { TspKind, TspProps, TspSpan, TspText } from "@oh-my-pi/pi-wire";
+import type { NativeChild, NativeNode } from "./node";
+
+/** A node of any kind. */
+export function node<K extends TspKind>(k: K, p?: TspProps<K>, c?: readonly NativeChild[], key?: string): NativeNode {
+	return { k, p, c, key } as NativeNode;
+}
+
+/** One styled span; `s` is a space-separated list of semantic or theme tokens. */
+export function span(t: string, s?: string, extra?: Omit<TspSpan, "t" | "s">): TspSpan {
+	return s === undefined && extra === undefined ? { t } : { t, s, ...extra };
+}
+
+/** Plain or styled text. */
+export function text(content: TspText, p?: Omit<TspProps<"text">, "text" | "spans">): NativeNode {
+	return typeof content === "string" ? node("text", { ...p, text: content }) : node("text", { ...p, spans: content });
+}
+
+/** Vertical stack. */
+export function col(c: readonly NativeChild[], p?: TspProps<"col">): NativeNode {
+	return node("col", p, c);
+}
+
+/** Horizontal flex row. */
+export function row(c: readonly NativeChild[], p?: TspProps<"row">): NativeNode {
+	return node("row", p, c);
+}
+
+/** Card with an optional header, status and collapsible body. */
+export function card(p: TspProps<"card">, c: readonly NativeChild[]): NativeNode {
+	return node("card", p, c);
+}
+
+/** Markdown source in omp's dialect. */
+export function md(source: string, p?: Omit<TspProps<"md">, "text">): NativeNode {
+	return node("md", { ...p, text: source });
+}
+
+/** Highlighted code. */
+export function code(source: string, p?: Omit<TspProps<"code">, "text">): NativeNode {
+	return node("code", { ...p, text: source });
+}
+
+/** Raw terminal output rendered as a mini terminal. */
+export function ansi(output: string, p?: Omit<TspProps<"ansi">, "text">): NativeNode {
+	return node("ansi", { ...p, text: output });
+}
+
+/** Unified diff. */
+export function diff(unified: string, p?: Omit<TspProps<"diff">, "text">): NativeNode {
+	return node("diff", { ...p, text: unified });
+}
+
+/** A mounted, empty, invisible node for components that describe nothing. */
+export const EMPTY_NODE: NativeNode = node("col", { hidden: true });
+
+/** `described` with a sibling identity key (the layout builders only take props). */
+export function keyed(described: NativeNode, key: string): NativeNode {
+	return { ...described, key };
+}
+
+/** `described` mounted but not laid out when `hidden` (cheap visibility toggles keep ids and view state). */
+export function withHidden(described: NativeNode, hidden: boolean): NativeNode {
+	if (!hidden) return described;
+	return node(described.k, { ...described.p, hidden: true } as TspProps, described.c, described.key);
+}
+
+/** Stable node key for an arbitrary identity string; keys join into `/` keypaths, so identities are hashed. */
+export function stableKey(identity: string): string {
+	return Bun.hash(identity).toString(36);
+}
+
+/** Drop absent entries (`undefined`, `null`, `false`) from a child list. */
+export function compact<T>(items: readonly (T | undefined | null | false)[]): T[] {
+	const out: T[] = [];
+	for (const entry of items) if (entry !== undefined && entry !== null && entry !== false) out.push(entry);
+	return out;
+}
+
+/** A `kv` grid from label/value pairs with muted labels, skipping empty values; undefined when nothing is left. */
+export function kv(pairs: readonly (readonly [string, TspText | undefined])[]): NativeNode | undefined {
+	const items: { k: TspText; v: TspText }[] = [];
+	for (const [label, value] of pairs) {
+		if (value === undefined || value === "" || (Array.isArray(value) && value.length === 0)) continue;
+		items.push({ k: [span(label, "muted")], v: value });
+	}
+	return items.length > 0 ? node("kv", { items }) : undefined;
+}
+
+/** One list `item`, keyed by the value select/activate events report back. */
+export function item(key: string, p: TspProps<"item">): NativeNode {
+	return node("item", p, undefined, key);
+}
+
+/** A `list` of items. */
+export function list(items: readonly NativeChild[], p?: TspProps<"list">, key?: string): NativeNode {
+	return node("list", p, items, key);
+}
+
+/** Terminal-clocked elapsed counter: `age` ms already elapsed; `stopped` freezes it there. */
+export function elapsed(age: number, stopped?: boolean): NativeNode {
+	const ms = Math.max(0, Math.round(age));
+	return node("elapsed", stopped ? { age: ms, stopped: ms, format: "short" } : { age: ms, format: "short" });
+}
+
+/**
+ * Keycap for one key id (`"ctrl+o"` → keys `["ctrl", "o"]`); the terminal
+ * draws platform glyphs. A literal `+` key survives (`"+"`, `"ctrl++"`).
+ */
+export function kbd(key: string, nodeKey?: string): NativeNode {
+	const keys = key === "+" ? ["+"] : key.endsWith("++") ? [...key.slice(0, -2).split("+"), "+"] : key.split("+");
+	return node("kbd", { keys: keys.filter(part => part.length > 0) }, undefined, nodeKey);
+}

package/src/native/encode.ts

@@ -0,0 +1,233 @@
+/**
+ * Tern Surface Protocol framing: `ESC _ tsp ; <verb> [; k=v]* ; <body> ESC \`.
+ *
+ * Bodies are UTF-8 JSON (JSON escapes every control character, so a body can
+ * never contain ESC or BEL) or base64 for blob chunks. A body larger than the
+ * negotiated `apc` limit is split across messages with the same verb, tagged
+ * `c=<chunk-id>`, with `m=1` on every chunk but the last; the receiver joins
+ * the bodies byte-wise. Chunks split on code-point boundaries, so every chunk
+ * is valid UTF-8 on its own and the joined bytes equal the original body.
+ */
+import { isRecord } from "@oh-my-pi/pi-utils/type-guards";
+import {
+	TSP_APC_ID,
+	TSP_DEFAULT_APC_LIMIT,
+	TSP_VERSION,
+	type TspEvent,
+	type TspReply,
+	type TspVerb,
+} from "@oh-my-pi/pi-wire";
+
+const APC = "\x1b_";
+const ST = "\x1b\\";
+/** Every TSP message starts with this. */
+export const TSP_PREFIX = `${APC}${TSP_APC_ID};`;
+
+/** The terminal's hello reply. */
+export type TspHello = Extract<TspReply, { r: "hello" }>;
+
+/** A decoded terminal → program message. */
+export type TspIncoming = { verb: "r"; reply: TspReply } | { verb: "e"; event: TspEvent };
+
+/** Message parameters (`k=v`, ASCII, never containing `;`). */
+export type TspParams = Readonly<Record<string, string | number>>;
+
+let nextChunkId = 1;
+
+/** UTF-8 byte length of one UTF-16 code unit sequence starting at `i`, and its unit count. */
+function codePointBytes(text: string, i: number): { bytes: number; units: number } {
+	const c = text.charCodeAt(i);
+	if (c < 0x80) return { bytes: 1, units: 1 };
+	if (c < 0x800) return { bytes: 2, units: 1 };
+	if (c >= 0xd800 && c <= 0xdbff && i + 1 < text.length) {
+		const next = text.charCodeAt(i + 1);
+		if (next >= 0xdc00 && next <= 0xdfff) return { bytes: 4, units: 2 };
+	}
+	return { bytes: 3, units: 1 };
+}
+
+/** Split `body` into pieces of at most `limit` UTF-8 bytes, never inside a code point. */
+export function splitUtf8(body: string, limit: number): string[] {
+	const max = Math.max(4, Math.trunc(limit));
+	const pieces: string[] = [];
+	let start = 0;
+	let bytes = 0;
+	let i = 0;
+	while (i < body.length) {
+		const step = codePointBytes(body, i);
+		if (bytes + step.bytes > max) {
+			pieces.push(body.slice(start, i));
+			start = i;
+			bytes = 0;
+		}
+		bytes += step.bytes;
+		i += step.units;
+	}
+	pieces.push(body.slice(start));
+	return pieces;
+}
+
+function frame(verb: TspVerb, params: string, body: string): string {
+	return `${TSP_PREFIX}${verb}${params};${body}${ST}`;
+}
+
+function encodeParams(params: TspParams | undefined): string {
+	if (!params) return "";
+	let out = "";
+	for (const key in params) out += `;${key}=${params[key]}`;
+	return out;
+}
+
+/**
+ * Encode one logical message, chunked when `body` exceeds `limit` UTF-8 bytes.
+ * Returns the complete byte string to write (all chunks, in order).
+ */
+export function encodeTspMessage(
+	verb: TspVerb,
+	body: string,
+	params?: TspParams,
+	limit: number = TSP_DEFAULT_APC_LIMIT,
+): string {
+	const base = encodeParams(params);
+	// Fast path: ASCII-length bound first, exact byte count only near the limit.
+	if (body.length * 3 <= limit || Buffer.byteLength(body, "utf8") <= limit) return frame(verb, base, body);
+	const chunkId = (nextChunkId++).toString(36);
+	const pieces = splitUtf8(body, limit);
+	let out = "";
+	for (let i = 0; i < pieces.length; i++) {
+		const more = i < pieces.length - 1 ? ";m=1" : "";
+		out += frame(verb, `${base};c=${chunkId}${more}`, pieces[i]!);
+	}
+	return out;
+}
+
+/** Encode a JSON message body. */
+export function encodeTspJson(verb: TspVerb, value: unknown, params?: TspParams, limit?: number): string {
+	return encodeTspMessage(verb, JSON.stringify(value), params, limit);
+}
+
+/** The `hello` query; callers follow it with a DA1 sentinel. */
+export function encodeTspHelloQuery(version?: string): string {
+	return encodeTspJson("q", { q: "hello", v: [TSP_VERSION], app: "omp", ver: version });
+}
+
+/** One decoded APC message: verb, parameters and raw body. */
+export interface TspRawMessage {
+	verb: string;
+	params: Record<string, string>;
+	body: string;
+}
+
+const PARAM_PATTERN = /^[A-Za-z0-9_-]+=[\x21-\x3a\x3c-\x7e]*$/;
+
+/** Split a complete `ESC _ tsp;… ESC \` string into verb, parameters and body; null when it isn't one. */
+export function splitTspMessage(sequence: string): TspRawMessage | null {
+	if (!sequence.startsWith(TSP_PREFIX) || !sequence.endsWith(ST)) return null;
+	const inner = sequence.slice(TSP_PREFIX.length, -ST.length);
+	let semi = inner.indexOf(";");
+	if (semi <= 0) return semi === -1 && inner.length > 0 ? { verb: inner, params: {}, body: "" } : null;
+	const verb = inner.slice(0, semi);
+	const params: Record<string, string> = {};
+	let pos = semi + 1;
+	// A segment is a parameter only when another `;` follows it; the body is the rest.
+	for (;;) {
+		semi = inner.indexOf(";", pos);
+		if (semi === -1) break;
+		const segment = inner.slice(pos, semi);
+		if (!PARAM_PATTERN.test(segment)) break;
+		const eq = segment.indexOf("=");
+		params[segment.slice(0, eq)] = segment.slice(eq + 1);
+		pos = semi + 1;
+	}
+	return { verb, params, body: inner.slice(pos) };
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+
+function decodeReply(value: Record<string, unknown>): TspReply | null {
+	if (value.r === "hello") {
+		if (typeof value.v !== "number" || typeof value.term !== "string" || !isStringArray(value.kinds)) return null;
+		return value as TspHello;
+	}
+	if (value.r === "blobs") return isStringArray(value.have) ? (value as TspReply) : null;
+	return null;
+}
+
+const EVENT_REQUIRED: Readonly<Record<string, Readonly<Record<string, "string" | "number" | "boolean" | "array">>>> = {
+	ack: { s: "number" },
+	resize: { cols: "number" },
+	theme: { dark: "boolean" },
+	motion: { reduce: "boolean" },
+	visible: { visible: "boolean" },
+	toggle: { id: "string", collapsed: "boolean" },
+	select: { id: "string", item: "string" },
+	activate: { id: "string", item: "string" },
+	action: { id: "string", act: "string" },
+	error: { msg: "string" },
+	gone: { ids: "array" },
+};
+
+function decodeEvent(value: Record<string, unknown>): TspEvent | null {
+	if (typeof value.ev !== "string") return null;
+	const required = EVENT_REQUIRED[value.ev];
+	if (!required) return null;
+	for (const key in required) {
+		const want = required[key];
+		const got = value[key];
+		if (want === "array" ? !isStringArray(got) : typeof got !== want) return null;
+	}
+	return value as TspEvent;
+}
+
+/**
+ * Reassembles chunked terminal → program messages and decodes replies and
+ * events. Unknown verbs, unknown events and unknown fields are tolerated
+ * (ignored or passed through); malformed input yields null.
+ */
+export class TspReader {
+	#chunks = new Map<string, string>();
+
+	/** Feed one complete APC string. Returns the decoded message once complete, else null. */
+	feed(sequence: string): TspIncoming | null {
+		const raw = splitTspMessage(sequence);
+		if (!raw) return null;
+		let body = raw.body;
+		const chunkId = raw.params.c;
+		if (chunkId !== undefined) {
+			const joined = (this.#chunks.get(chunkId) ?? "") + body;
+			if (raw.params.m === "1") {
+				this.#chunks.set(chunkId, joined);
+				return null;
+			}
+			this.#chunks.delete(chunkId);
+			body = joined;
+		}
+		return decodeTspBody(raw.verb, body);
+	}
+}
+
+/** Decode an unchunked reply/event body. Null for malformed JSON, missing fields or program → terminal verbs. */
+export function decodeTspBody(verb: string, body: string): TspIncoming | null {
+	if (verb !== "r" && verb !== "e") return null;
+	let value: unknown;
+	try {
+		value = JSON.parse(body);
+	} catch {
+		return null;
+	}
+	if (!isRecord(value)) return null;
+	if (verb === "r") {
+		const reply = decodeReply(value);
+		return reply ? { verb, reply } : null;
+	}
+	const event = decodeEvent(value);
+	return event ? { verb, event } : null;
+}
+
+/** Decode one complete, unchunked terminal → program message. */
+export function parseTspMessage(sequence: string): TspIncoming | null {
+	const raw = splitTspMessage(sequence);
+	return raw && raw.params.m !== "1" ? decodeTspBody(raw.verb, raw.body) : null;
+}

package/src/native/icons.ts

@@ -0,0 +1,184 @@
+/**
+ * Icon glyph normalization for native frames.
+ *
+ * Components style icons as Private Use Area codepoints (Nerd Font glyphs)
+ * baked into text with a padding space, e.g. `{t:"<glyph> Model", s:"statusLineModel"}`.
+ * The terminal draws icons and spaces them itself, so every PUA run becomes
+ * its own span carrying the `icon` token next to the original tokens (colour
+ * survives), and the single space that padded it from the neighbouring text
+ * is dropped. Applied once, centrally, to every `TspText` field of a node's
+ * props before they go on the wire.
+ */
+import type { TspKind, TspSpan, TspText } from "@oh-my-pi/pi-wire";
+
+const PUA = /[\u{E000}-\u{F8FF}\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]/u;
+const PUA_RUNS = /[\u{E000}-\u{F8FF}\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]+/gu;
+
+/** `TspText` props per kind (besides the structured ones handled below). */
+const TEXT_FIELDS: Partial<Record<TspKind, readonly string[]>> = {
+	text: ["spans"],
+	shimmer: ["spans"],
+	seg: ["spans"],
+	card: ["head"],
+	section: ["head"],
+	overlay: ["head"],
+	rule: ["label"],
+	spinner: ["label"],
+	progress: ["label"],
+	list: ["empty"],
+	item: ["label", "detail", "value"],
+	editor: ["prompt"],
+	input: ["prompt"],
+};
+
+function withIcon(s: string | undefined): string {
+	if (s === undefined || s.length === 0) return "icon";
+	return s.split(" ").includes("icon") ? s : `${s} icon`;
+}
+
+/** Spans with every PUA run split into an `icon` span; the same array when there is none. */
+export function normalizeIconSpans(spans: readonly TspSpan[]): readonly TspSpan[] {
+	let found = false;
+	for (const span of spans) {
+		if (PUA.test(span.t)) {
+			found = true;
+			break;
+		}
+	}
+	if (!found) return spans;
+	const pieces: { span: TspSpan; icon: boolean }[] = [];
+	for (const span of spans) {
+		let at = 0;
+		for (const match of span.t.matchAll(PUA_RUNS)) {
+			if (match.index > at) pieces.push({ span: { ...span, t: span.t.slice(at, match.index) }, icon: false });
+			pieces.push({ span: { ...span, t: match[0], s: withIcon(span.s) }, icon: true });
+			at = match.index + match[0].length;
+		}
+		if (at < span.t.length) pieces.push({ span: at === 0 ? span : { ...span, t: span.t.slice(at) }, icon: false });
+	}
+	// The terminal spaces icons itself: drop the one space on each side that padded them.
+	for (let i = 0; i < pieces.length; i++) {
+		if (!pieces[i]!.icon) continue;
+		const prev = pieces[i - 1];
+		if (prev && !prev.icon && prev.span.t.endsWith(" ")) prev.span = { ...prev.span, t: prev.span.t.slice(0, -1) };
+		const next = pieces[i + 1];
+		if (next && !next.icon && next.span.t.startsWith(" ")) next.span = { ...next.span, t: next.span.t.slice(1) };
+	}
+	const out: TspSpan[] = [];
+	for (const piece of pieces) if (piece.span.t.length > 0) out.push(piece.span);
+	return out;
+}
+
+/** A `TspText` with icons normalized; plain strings with icons become spans. */
+export function normalizeIconText(text: TspText): TspText {
+	if (typeof text === "string") return PUA.test(text) ? normalizeIconSpans([{ t: text }]) : text;
+	return normalizeIconSpans(text);
+}
+
+function isText(value: unknown): value is TspText {
+	return typeof value === "string" || Array.isArray(value);
+}
+
+/** Map `fn` over `items`, returning the same array when nothing changed. */
+function mapSame<T>(items: readonly T[], fn: (item: T) => T): readonly T[] {
+	let out: T[] | undefined;
+	for (let i = 0; i < items.length; i++) {
+		const next = fn(items[i]!);
+		if (next !== items[i] && !out) out = items.slice(0, i);
+		out?.push(next);
+	}
+	return out ?? items;
+}
+
+interface TreeNodeLike {
+	label?: unknown;
+	children?: readonly TreeNodeLike[];
+}
+
+function normalizeTree(node: TreeNodeLike): TreeNodeLike {
+	const label = isText(node.label) ? normalizeIconText(node.label) : node.label;
+	const children = node.children ? mapSame(node.children, normalizeTree) : node.children;
+	return label === node.label && children === node.children ? node : { ...node, label, children };
+}
+
+/** Props with every `TspText` field's icons normalized; the same object when nothing changed. */
+export function normalizeIconProps(
+	kind: TspKind,
+	props: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> | undefined {
+	if (!props) return props;
+	let out: Record<string, unknown> | undefined;
+	const put = (key: string, value: unknown): void => {
+		if (value === props[key]) return;
+		out ??= { ...props };
+		out[key] = value;
+	};
+	// A plain `text` label holding an icon becomes spans.
+	if ((kind === "text" || kind === "shimmer") && typeof props.text === "string" && PUA.test(props.text)) {
+		put("text", undefined);
+		put("spans", normalizeIconSpans([{ t: props.text }]));
+	}
+	for (const key of TEXT_FIELDS[kind] ?? []) {
+		const value = (out ?? props)[key];
+		if (isText(value)) put(key, normalizeIconText(value));
+	}
+	switch (kind) {
+		case "tabs":
+		case "kv": {
+			const items = props.items;
+			if (!Array.isArray(items)) break;
+			put(
+				"items",
+				mapSame(items as readonly Record<string, unknown>[], item => {
+					let next = item;
+					for (const field of kind === "tabs" ? ["label"] : ["k", "v"]) {
+						const value = item[field];
+						if (!isText(value)) continue;
+						const normalized = normalizeIconText(value);
+						if (normalized !== value) next = { ...next, [field]: normalized };
+					}
+					return next;
+				}),
+			);
+			break;
+		}
+		case "table": {
+			const cols = props.cols;
+			if (Array.isArray(cols)) {
+				put(
+					"cols",
+					mapSame(cols as readonly Record<string, unknown>[], col => {
+						if (!isText(col.head)) return col;
+						const head = normalizeIconText(col.head);
+						return head === col.head ? col : { ...col, head };
+					}),
+				);
+			}
+			const rows = props.rows;
+			if (Array.isArray(rows)) {
+				put(
+					"rows",
+					mapSame(rows as readonly { cells?: Record<string, unknown> }[], row => {
+						const cells = row.cells;
+						if (!cells) return row;
+						let nextCells: Record<string, unknown> | undefined;
+						for (const col in cells) {
+							const value = cells[col];
+							if (!isText(value)) continue;
+							const normalized = normalizeIconText(value);
+							if (normalized !== value) (nextCells ??= { ...cells })[col] = normalized;
+						}
+						return nextCells ? { ...row, cells: nextCells } : row;
+					}),
+				);
+			}
+			break;
+		}
+		case "tree": {
+			const nodes = props.nodes;
+			if (Array.isArray(nodes)) put("nodes", mapSame(nodes as readonly TreeNodeLike[], normalizeTree));
+			break;
+		}
+	}
+	return out ?? props;
+}

package/src/native/memo.ts

@@ -0,0 +1,64 @@
+/**
+ * Memoization for `describe()`: an unchanged component must hand the
+ * reconciler the same node objects, so it can skip the subtree. {@link Memo}
+ * is the one primitive; {@link OwnerMemo} keys it by an object for stateless
+ * renderers (tool describe hooks) that re-describe the same args/result.
+ */
+import type { NativeNode } from "./node";
+
+/** Element-wise identity (`Object.is`) of two arrays; `undefined` never matches. */
+export function sameItems<T>(a: readonly T[] | undefined, b: readonly T[]): boolean {
+	if (a === b) return true;
+	if (a === undefined || a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (!Object.is(a[i], b[i])) return false;
+	return true;
+}
+
+/** Shallow equality of two flat prop bags built by successive describe calls. */
+export function sameProps<T extends object>(a: T | undefined, b: T): boolean {
+	if (a === undefined) return false;
+	for (const key in b) if (a[key] !== b[key]) return false;
+	for (const key in a) if (!(key in b)) return false;
+	return true;
+}
+
+/** Keeps the last built value while every dependency is unchanged (`Object.is` per slot). */
+export class Memo<T = NativeNode> {
+	#deps: readonly unknown[] | undefined;
+	#value: T | undefined;
+
+	get(deps: readonly unknown[], build: () => T): T {
+		if (this.#deps !== undefined && sameItems(this.#deps, deps)) return this.#value as T;
+		const value = build();
+		this.#deps = deps;
+		this.#value = value;
+		return value;
+	}
+
+	/** Forget the cached value (theme, glyph preset or keybindings changed). */
+	clear(): void {
+		this.#deps = undefined;
+		this.#value = undefined;
+	}
+}
+
+/**
+ * One {@link Memo} per owner object, kept in a symbol slot on the owner; each
+ * instance owns its own slot, so call and result views of one object don't
+ * collide. Builds uncached without an owner or when the owner is frozen.
+ */
+export class OwnerMemo<T> {
+	readonly #slot = Symbol("native.memo");
+
+	get(owner: object | undefined, deps: readonly unknown[], build: () => T): T {
+		if (!owner) return build();
+		const tagged = owner as { [slot: symbol]: Memo<T> | undefined };
+		let memo = tagged[this.#slot];
+		if (!memo) {
+			if (!Object.isExtensible(owner)) return build();
+			memo = new Memo<T>();
+			Object.defineProperty(owner, this.#slot, { value: memo, configurable: true });
+		}
+		return memo.get(deps, build);
+	}
+}