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

package/src/hotkeys-markdown.ts

@@ -1,24 +1,67 @@
-import {
-	type AppKeybinding,
-	formatKeyHint,
-	formatKeyHints,
-	type KeybindingsManager,
-	keyHintPlatform,
-} from "./app-keybindings";
+import type { TspSpan } from "@oh-my-pi/pi-wire";
+import { type AppKeybinding, formatKeyHint, type KeybindingsManager, keyHintPlatform } from "./app-keybindings";
+import { Markdown } from "./components/markdown";
+import { matchesSelectCancel } from "./keybinding-matchers";
+import type { KeyName } from "./key-hint-format";
 import { canonicalKeyId } from "./keybindings";
+import { col, node, span } from "./native/describe";
+import type { NativeNode, NativeUiEvent } from "./native/node";
+import { actionBar, actionButton } from "./native/overlay";
+import { getMarkdownTheme } from "./theme/theme";
+import type { Component } from "./tui";
 
 /** Effective keybinding operations used to render the hotkey reference. */
 export interface HotkeysMarkdownBindings {
 	keybindings: Pick<KeybindingsManager, "getDisplayString" | "getKeys" | "matchesCanonical">;
 }
 
-function hotkeyLabel(bindings: HotkeysMarkdownBindings, action: AppKeybinding): string {
-	return bindings.keybindings.getDisplayString(action) || "Disabled";
+/**
+ * One piece of a shortcut cell: formatted key hints (alternatives, one keycap
+ * each), a literal typed token (`#<number>`, `!!`), or connecting prose.
+ */
+type HotkeyPart =
+	| {
+			/** Formatted for the markdown table (`⌃R`); `Disabled` when unbound. */
+			keys: readonly string[];
+			/** Key ids (`ctrl+r`) for native keycaps, which the terminal draws with platform glyphs. */
+			ids: readonly KeyName[];
+			action?: AppKeybinding;
+	  }
+	| { token: string }
+	| { text: string };
+
+interface HotkeyRow {
+	readonly keys: readonly HotkeyPart[];
+	readonly action: string;
 }
 
-/** Build the platform-aware Markdown reference for effective application hotkeys. */
-export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string {
+interface HotkeyGroup {
+	readonly title: string;
+	readonly rows: readonly HotkeyRow[];
+}
+
+/** Formatted hints for key ids. */
+function hints(keys: readonly KeyName[]): HotkeyPart {
+	return { keys: keys.map(formatKeyHint), ids: keys };
+}
+
+/** The markdown cell text of a part; key alternatives join with `/` as `formatKeyHints` does. */
+function markdownPart(bindings: HotkeysMarkdownBindings, part: HotkeyPart): string {
+	if ("text" in part) return part.text;
+	if ("token" in part) return `\`${part.token}\``;
+	const label = part.action ? bindings.keybindings.getDisplayString(part.action) || "Disabled" : part.keys.join("/");
+	return `\`${label}\``;
+}
+
+/** The shortcut groups, built from the effective bindings. */
+function hotkeyGroups(bindings: HotkeysMarkdownBindings): HotkeyGroup[] {
 	const isMac = keyHintPlatform() === "darwin";
+	// An action's effective keys, one keycap each; `Disabled` when unbound.
+	const act = (action: AppKeybinding): HotkeyPart => {
+		const keys = bindings.keybindings.getKeys(action);
+		if (keys.length > 0) return { keys: keys.map(formatKeyHint), ids: keys, action };
+		return { keys: [bindings.keybindings.getDisplayString(action) || "Disabled"], ids: [], action };
+	};
 	// CustomEditor tests the chord that was actually pressed, so exit keys split by role: a key
 	// that also carries tui.editor.deleteCharForward (the readline `^D` overlap) forward-deletes
 	// while the prompt holds a draft, any other exit key quits immediately. Mixed bindings such as
@@ -31,67 +74,206 @@ export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string
 	const quittingExitKeys = exitKeys.filter(
 		key => !bindings.keybindings.matchesCanonical(canonicalKeyId(key), "tui.editor.deleteCharForward"),
 	);
-	const exitRows: string[] = [];
+	const exitRows: HotkeyRow[] = [];
 	if (deletingExitKeys.length > 0) {
-		exitRows.push(
-			`| \`${formatKeyHints(deletingExitKeys)}\` | Delete char forward (with draft) / exit (empty prompt) |`,
-		);
+		exitRows.push({
+			keys: [hints(deletingExitKeys)],
+			action: "Delete char forward (with draft) / exit (empty prompt)",
+		});
 	}
 	// An unbound exit action still gets its row, mirroring the `Disabled` hint every other row uses.
 	if (quittingExitKeys.length > 0 || deletingExitKeys.length === 0) {
-		exitRows.push(`| \`${formatKeyHints(quittingExitKeys) || "Disabled"}\` | Exit |`);
+		exitRows.push({
+			keys: [quittingExitKeys.length > 0 ? hints(quittingExitKeys) : { keys: ["Disabled"], ids: [] }],
+			action: "Exit",
+		});
+	}
+	const groups: HotkeyGroup[] = [
+		{
+			title: "Navigation",
+			rows: [
+				{
+					keys: [hints(["up", "down", "left", "right"])],
+					action: `Move cursor / browse history (${formatKeyHint("up")} when empty)`,
+				},
+				{ keys: [hints(["alt+left", "alt+right"])], action: "Move by word" },
+				{
+					keys: [hints(isMac ? ["ctrl+a", "home", "super+left"] : ["ctrl+a", "home"])],
+					action: "Start of line",
+				},
+				{ keys: [hints(isMac ? ["ctrl+e", "end", "super+right"] : ["ctrl+e", "end"])], action: "End of line" },
+			],
+		},
+		{
+			title: "Editing",
+			rows: [
+				{ keys: [hints(["enter"])], action: "Send message" },
+				{ keys: [hints(["shift+enter", "alt+enter"])], action: "New line" },
+				{ keys: [hints(["ctrl+w", "alt+backspace"])], action: "Delete word backwards" },
+				{ keys: [hints(["ctrl+u"])], action: "Delete to start of line" },
+				{ keys: [hints(["ctrl+k"])], action: "Delete to end of line" },
+				{ keys: [act("app.clipboard.copyLine")], action: "Copy current line" },
+				{ keys: [act("app.clipboard.copyPrompt")], action: "Copy whole prompt" },
+			],
+		},
+		{
+			title: "Other",
+			rows: [
+				{ keys: [hints(["tab"])], action: "Path completion / accept autocomplete" },
+				{ keys: [act("app.interrupt")], action: "Cancel autocomplete / interrupt active work" },
+				{ keys: [act("app.clear")], action: "Clear editor (first) / exit (second)" },
+				...exitRows,
+				{ keys: [act("app.suspend")], action: "Suspend to background" },
+				{ keys: [act("app.display.reset")], action: "Reset terminal display" },
+				{ keys: [act("app.thinking.cycle")], action: "Cycle thinking level" },
+				{ keys: [act("app.model.cycleForward")], action: "Cycle role models (slow/default/smol)" },
+				{ keys: [act("app.model.cycleBackward")], action: "Cycle role models (backward)" },
+				{ keys: [act("app.model.selectTemporary")], action: "Select model (temporary)" },
+				{ keys: [act("app.model.select")], action: "Select model (set roles)" },
+				{ keys: [act("app.plan.toggle")], action: "Toggle plan mode" },
+				{ keys: [act("app.history.search")], action: "Search prompt history" },
+				{ keys: [act("app.tools.expand")], action: "Toggle tool output expansion" },
+				{ keys: [act("app.tools.toggleVisibility")], action: "Toggle tool activity visibility" },
+				{ keys: [act("app.thinking.toggle")], action: "Toggle thinking block visibility" },
+				{ keys: [act("app.editor.external")], action: "Edit message in external editor" },
+				{ keys: [act("app.retry")], action: "Retry last failed assistant turn" },
+				{ keys: [act("app.clipboard.pasteImage")], action: "Paste image or text from clipboard" },
+				{
+					keys: [{ text: "Hold " }, hints(["space"])],
+					action: "Speech-to-text (push-to-talk): hold to record, release to transcribe",
+				},
+				{ keys: [act("app.live.toggle")], action: "Start/stop live voice mode (/live)" },
+				{
+					keys: [
+						act("app.agents.hub"),
+						{ text: " / " },
+						act("app.session.observe"),
+						{ text: " / double-tap " },
+						hints(["left"]),
+						{ text: " (empty editor)" },
+					],
+					action: "Open the agent hub",
+				},
+				{ keys: [{ token: "#<number>" }], action: "GitHub issue/PR reference (e.g. `#3164` → `pr://`/`issue://`)" },
+				{
+					keys: [{ token: "#" }, { text: " / " }, { token: "#<text>" }],
+					action: "Prompt actions (copy / undo / move cursor)",
+				},
+				{ keys: [{ token: "/" }], action: "Slash commands" },
+				{ keys: [{ token: "!" }], action: "Run bash command" },
+				{ keys: [{ token: "!!" }], action: "Run bash command (excluded from context)" },
+				{ keys: [{ token: "$" }], action: "Run Python in shared kernel" },
+				{ keys: [{ token: "$$" }], action: "Run Python (excluded from context)" },
+			],
+		},
+	];
+	return groups;
+}
+
+/** Build the platform-aware Markdown reference for effective application hotkeys. */
+export function buildHotkeysMarkdown(bindings: HotkeysMarkdownBindings): string {
+	const lines: string[] = [];
+	for (const [index, group] of hotkeyGroups(bindings).entries()) {
+		if (index > 0) lines.push("");
+		lines.push(`**${group.title}**`, "| Key | Action |", "|-----|--------|");
+		for (const row of group.rows) {
+			const keys = row.keys.map(part => markdownPart(bindings, part)).join("");
+			lines.push(`| ${keys} | ${row.action} |`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * A shortcut cell as spans: each key alternative a `key` span holding its key
+ * id (`ctrl+r`, drawn as a keycap like `kbd`), literal tokens as code, prose dim.
+ */
+function keySpans(parts: readonly HotkeyPart[]): TspSpan[] {
+	const spans: TspSpan[] = [];
+	for (const part of parts) {
+		if ("text" in part) spans.push(span(part.text, "dim"));
+		else if ("token" in part) spans.push(span(part.token, "code"));
+		else if (part.ids.length === 0) spans.push(span(part.keys.join("/"), "dim"));
+		else {
+			for (const [index, id] of part.ids.entries()) {
+				if (index > 0) spans.push(span(" ", "dim"));
+				spans.push(span(id, "key"));
+			}
+		}
+	}
+	return spans;
+}
+
+/** Inline markdown (backticks) of an action description as spans: code runs mono, the rest plain. */
+function actionSpans(action: string): TspSpan[] {
+	return action.split(/(`[^`]+`)/).flatMap(piece => {
+		if (piece === "") return [];
+		return piece.startsWith("`") && piece.endsWith("`") ? [span(piece.slice(1, -1), "code")] : [span(piece)];
+	});
+}
+
+/**
+ * `/hotkeys` under a native terminal: a large sheet "Keyboard shortcuts" with
+ * one section per group, each a two-column table whose key cells carry `key`
+ * spans (Tern draws them as keycaps). Esc (or Close) dismisses it. Terminals
+ * without the native surface get the transcript markdown panel instead.
+ */
+export class HotkeysSheetComponent implements Component {
+	readonly nativeOverlay = { role: "omp.overlay.hotkeys", size: "lg", head: "Keyboard shortcuts" } as const;
+	readonly #bindings: HotkeysMarkdownBindings;
+	readonly #onClose: () => void;
+	#native: NativeNode | undefined;
+	#markdown: Markdown | undefined;
+
+	constructor(bindings: HotkeysMarkdownBindings, onClose: () => void) {
+		this.#bindings = bindings;
+		this.#onClose = onClose;
+	}
+
+	describe(): NativeNode {
+		if (this.#native) return this.#native;
+		const sections = hotkeyGroups(this.#bindings).map((group, index) =>
+			node(
+				"section",
+				{ head: group.title, role: "omp.hotkeys.group" },
+				[
+					node("table", {
+						role: "omp.hotkeys.table",
+						cols: [
+							{ id: "keys", head: "Key" },
+							{ id: "action", head: "Action", grow: 1 },
+						],
+						rows: group.rows.map((row, rowIndex) => ({
+							id: String(rowIndex),
+							cells: { keys: keySpans(row.keys), action: actionSpans(row.action) },
+						})),
+					}),
+				],
+				`g${index}`,
+			),
+		);
+		const close = actionButton("Close", "close", { keys: "escape" });
+		this.#native = col([...sections, actionBar([null, close])], { gap: "lg" });
+		return this.#native;
+	}
+
+	/** The markdown reference, for a terminal that falls back to rows. */
+	render(width: number): readonly string[] {
+		this.#markdown ??= new Markdown(buildHotkeysMarkdown(this.#bindings), 1, 1, getMarkdownTheme());
+		return this.#markdown.render(width);
+	}
+
+	invalidate(): void {
+		this.#native = undefined;
+		this.#markdown = undefined;
+	}
+
+	handleInput(data: string): void {
+		if (matchesSelectCancel(data)) this.#onClose();
+	}
+
+	/** Close runs what Esc runs. */
+	handleNativeEvent(event: NativeUiEvent): void {
+		if (event.type === "action" && event.act === "close") this.#onClose();
 	}
-	return [
-		"**Navigation**",
-		"| Key | Action |",
-		"|-----|--------|",
-		`| \`${formatKeyHints(["up", "down", "left", "right"])}\` | Move cursor / browse history (${formatKeyHint("up")} when empty) |`,
-		`| \`${formatKeyHints(["alt+left", "alt+right"])}\` | Move by word |`,
-		`| \`${formatKeyHints(isMac ? ["ctrl+a", "home", "super+left"] : ["ctrl+a", "home"])}\` | Start of line |`,
-		`| \`${formatKeyHints(isMac ? ["ctrl+e", "end", "super+right"] : ["ctrl+e", "end"])}\` | End of line |`,
-		"",
-		"**Editing**",
-		"| Key | Action |",
-		"|-----|--------|",
-		`| \`${formatKeyHint("enter")}\` | Send message |`,
-		`| \`${formatKeyHints(["shift+enter", "alt+enter"])}\` | New line |`,
-		`| \`${formatKeyHints(["ctrl+w", "alt+backspace"])}\` | Delete word backwards |`,
-		`| \`${formatKeyHint("ctrl+u")}\` | Delete to start of line |`,
-		`| \`${formatKeyHint("ctrl+k")}\` | Delete to end of line |`,
-		`| \`${hotkeyLabel(bindings, "app.clipboard.copyLine")}\` | Copy current line |`,
-		`| \`${hotkeyLabel(bindings, "app.clipboard.copyPrompt")}\` | Copy whole prompt |`,
-		"",
-		"**Other**",
-		"| Key | Action |",
-		"|-----|--------|",
-		`| \`${formatKeyHint("tab")}\` | Path completion / accept autocomplete |`,
-		`| \`${hotkeyLabel(bindings, "app.interrupt")}\` | Cancel autocomplete / interrupt active work |`,
-		`| \`${hotkeyLabel(bindings, "app.clear")}\` | Clear editor (first) / exit (second) |`,
-		...exitRows,
-		`| \`${hotkeyLabel(bindings, "app.suspend")}\` | Suspend to background |`,
-		`| \`${hotkeyLabel(bindings, "app.display.reset")}\` | Reset terminal display |`,
-		`| \`${hotkeyLabel(bindings, "app.thinking.cycle")}\` | Cycle thinking level |`,
-		`| \`${hotkeyLabel(bindings, "app.model.cycleForward")}\` | Cycle role models (slow/default/smol) |`,
-		`| \`${hotkeyLabel(bindings, "app.model.cycleBackward")}\` | Cycle role models (backward) |`,
-		`| \`${hotkeyLabel(bindings, "app.model.selectTemporary")}\` | Select model (temporary) |`,
-		`| \`${hotkeyLabel(bindings, "app.model.select")}\` | Select model (set roles) |`,
-		`| \`${hotkeyLabel(bindings, "app.plan.toggle")}\` | Toggle plan mode |`,
-		`| \`${hotkeyLabel(bindings, "app.history.search")}\` | Search prompt history |`,
-		`| \`${hotkeyLabel(bindings, "app.tools.expand")}\` | Toggle tool output expansion |`,
-		`| \`${hotkeyLabel(bindings, "app.tools.toggleVisibility")}\` | Toggle tool activity visibility |`,
-		`| \`${hotkeyLabel(bindings, "app.thinking.toggle")}\` | Toggle thinking block visibility |`,
-		`| \`${hotkeyLabel(bindings, "app.editor.external")}\` | Edit message in external editor |`,
-		`| \`${hotkeyLabel(bindings, "app.retry")}\` | Retry last failed assistant turn |`,
-		`| \`${hotkeyLabel(bindings, "app.clipboard.pasteImage")}\` | Paste image or text from clipboard |`,
-		`| Hold \`${formatKeyHint("space")}\` | Speech-to-text (push-to-talk): hold to record, release to transcribe |`,
-		`| \`${hotkeyLabel(bindings, "app.live.toggle")}\` | Start/stop live voice mode (/live) |`,
-		`| \`${hotkeyLabel(bindings, "app.agents.hub")}\` / \`${hotkeyLabel(bindings, "app.session.observe")}\` / double-tap \`${formatKeyHint("left")}\` (empty editor) | Open the agent hub |`,
-		"| `#<number>` | GitHub issue/PR reference (e.g. `#3164` → `pr://`/`issue://`) |",
-		"| `#` / `#<text>` | Prompt actions (copy / undo / move cursor) |",
-		"| `/` | Slash commands |",
-		"| `!` | Run bash command |",
-		"| `!!` | Run bash command (excluded from context) |",
-		"| `$` | Run Python in shared kernel |",
-		"| `$$` | Run Python (excluded from context) |",
-	].join("\n");
 }

package/src/index.ts

@@ -57,6 +57,12 @@ export * from "./latex-block";
 export * from "./latex-to-unicode";
 // SGR mouse report parsing
 export * from "./mouse";
+// Tern Surface Protocol: describe contract, builders, blobs, settling, render state
+export * from "./native/blobs";
+export * from "./native/describe";
+export type * from "./native/node";
+export * from "./native/settle";
+export * from "./native/state";
 // Mermaid diagram support
 // Input buffering for batch splitting
 export * from "./stdin-buffer";

package/src/latex-block.ts

@@ -23,6 +23,8 @@
 // scratch here on this module's ANSI-aware Box model.
 
 import { latexColorScope, latexToUnicode, MATH_FONT_COMMANDS } from "./latex-to-unicode";
+import { node } from "./native/describe";
+import type { NativeNode } from "./native/node";
 import { visibleWidth } from "./utils";
 
 /**
@@ -1428,6 +1430,15 @@ function splitLines(src: string): string[] {
 	return lines;
 }
 
+/**
+ * The native form of {@link latexToBlock}: the TeX source as a `math` node
+ * the terminal typesets (display style by default, `display: false` for
+ * inline `$…$` math).
+ */
+export function describeLatex(src: string, display = true): NativeNode {
+	return node("math", { text: src, display });
+}
+
 /**
  * Render a display LaTeX math fragment to lines with full 2-D layout: stacked
  * fractions, stretchy delimiters, matrix grids, operator limits, drawn

package/src/native/apply.ts

@@ -0,0 +1,275 @@
+/**
+ * Reference document applier: applies TSP frames to a node tree the way the
+ * spec says the terminal does (§5.1). Ops are validated and applied one by
+ * one; a rejected op is reported and skipped without affecting the rest of
+ * the frame. `settle` is recorded as a hint and never restricts later ops.
+ *
+ * Used by tests, the debug server's `doc` op, and the TSP test harness.
+ */
+import { TSP_KINDS, TSP_TEXT_KINDS, type TspFrame, type TspKind, type TspNode, type TspOp } from "@oh-my-pi/pi-wire";
+
+/** One rejected op. */
+export interface TspApplyError {
+	/** Frame sequence number. */
+	s: number;
+	/** Op index inside the frame. */
+	op: number;
+	msg: string;
+}
+
+interface DocNode {
+	id: string;
+	k: TspKind;
+	p: Record<string, unknown>;
+	c: DocNode[];
+	parent: DocNode | null;
+}
+
+const KINDS: ReadonlySet<string> = new Set(TSP_KINDS);
+const TEXT_KINDS: ReadonlySet<string> = new Set(TSP_TEXT_KINDS);
+
+class OpError extends Error {}
+
+function fail(msg: string): never {
+	throw new OpError(msg);
+}
+
+/** A surface document: the root (id = surface id) plus an id index. */
+export class TspDocument {
+	readonly surface: string;
+	#root: DocNode;
+	#index = new Map<string, DocNode>();
+	#settled = new Set<string>();
+	#focus: string | null = null;
+	#suspended = false;
+
+	constructor(surface: string) {
+		this.surface = surface;
+		this.#root = { id: surface, k: "col", p: {}, c: [], parent: null };
+		this.#index.set(surface, this.#root);
+	}
+
+	/** Currently focused node id. */
+	get focus(): string | null {
+		return this.#focus;
+	}
+
+	get suspended(): boolean {
+		return this.#suspended;
+	}
+
+	/** Ids that received a `settle` hint and no later op. */
+	get settled(): ReadonlySet<string> {
+		return this.#settled;
+	}
+
+	/** Number of nodes, including the root. */
+	get size(): number {
+		return this.#index.size;
+	}
+
+	has(id: string): boolean {
+		return this.#index.has(id);
+	}
+
+	/** `x keep:true`: drop the live-only regions (`dock`, `layer`) and focus; `main` stays. */
+	close(): void {
+		for (const region of ["dock", "layer"]) {
+			const node = this.#index.get(region);
+			if (!node || node.parent !== this.#root) continue;
+			this.#root.c.splice(this.#root.c.indexOf(node), 1);
+			this.#unregister(node);
+		}
+		this.#focus = null;
+	}
+
+	/** Apply a frame op by op; returns the rejected ops. */
+	applyFrame(frame: TspFrame): TspApplyError[] {
+		const errors: TspApplyError[] = [];
+		for (let i = 0; i < frame.ops.length; i++) {
+			try {
+				this.#apply(frame.ops[i]!);
+			} catch (error) {
+				if (!(error instanceof OpError)) throw error;
+				errors.push({ s: frame.s, op: i, msg: error.message });
+			}
+		}
+		return errors;
+	}
+
+	/** Snapshot of the whole document (root included) as wire nodes. */
+	snapshot(): TspNode {
+		return this.#export(this.#root);
+	}
+
+	/** Snapshot of one subtree, or undefined for an unknown id. */
+	get(id: string): TspNode | undefined {
+		const found = this.#index.get(id);
+		return found ? this.#export(found) : undefined;
+	}
+
+	#export(node: DocNode): TspNode {
+		const out: { id: string; k: TspKind; p?: Record<string, unknown>; c?: TspNode[] } = { id: node.id, k: node.k };
+		if (Object.keys(node.p).length > 0) out.p = { ...node.p };
+		if (node.c.length > 0) out.c = node.c.map(child => this.#export(child));
+		return out as TspNode;
+	}
+
+	#node(id: string): DocNode {
+		return this.#index.get(id) ?? fail(`unknown id ${id}`);
+	}
+
+	#unsettle(node: DocNode): void {
+		if (this.#settled.size === 0) return;
+		for (let at: DocNode | null = node; at; at = at.parent) this.#settled.delete(at.id);
+	}
+
+	#apply(op: TspOp): void {
+		switch (op[0]) {
+			case "add": {
+				const [, id, parentId, before, wire] = op;
+				if (wire.id !== id) fail(`add id ${id} does not match node id ${wire.id}`);
+				const parent = this.#node(parentId);
+				const index = this.#insertIndex(parent, before);
+				const built = this.#build(wire, parent, new Set());
+				parent.c.splice(index, 0, built);
+				this.#register(built);
+				this.#unsettle(parent);
+				return;
+			}
+			case "set": {
+				const [, id, props] = op;
+				const node = this.#node(id);
+				if (typeof props !== "object" || props === null || Array.isArray(props))
+					fail("set props must be an object");
+				for (const key in props) {
+					const value = props[key];
+					if (value === null) delete node.p[key];
+					else if (value !== undefined) node.p[key] = value;
+				}
+				this.#unsettle(node);
+				return;
+			}
+			case "text": {
+				const [, id, mode, text] = op;
+				const node = this.#textNode(id);
+				if (typeof text !== "string") fail("text must be a string");
+				if (mode === "append") node.p.text = this.#text(node) + text;
+				else if (mode === "replace") node.p.text = text;
+				else fail(`unknown text mode ${String(mode)}`);
+				this.#unsettle(node);
+				return;
+			}
+			case "splice": {
+				const [, id, at, del, text] = op;
+				const node = this.#textNode(id);
+				const current = this.#text(node);
+				if (!Number.isInteger(at) || !Number.isInteger(del) || at < 0 || del < 0 || at + del > current.length)
+					fail(`splice range ${at}+${del} outside text of length ${current.length}`);
+				node.p.text = current.slice(0, at) + text + current.slice(at + del);
+				this.#unsettle(node);
+				return;
+			}
+			case "move": {
+				const [, id, parentId, before] = op;
+				const node = this.#node(id);
+				if (node === this.#root) fail("cannot move the root");
+				const parent = this.#node(parentId);
+				for (let at: DocNode | null = parent; at; at = at.parent) {
+					if (at === node) fail(`cannot move ${id} into its own subtree`);
+				}
+				if (before === id) fail("move before itself");
+				const oldParent = node.parent!;
+				// Validate `before` before detaching so a rejected move leaves the tree intact.
+				if (before !== null && this.#index.get(before)?.parent !== parent)
+					fail(`${before} is not a child of ${parentId}`);
+				oldParent.c.splice(oldParent.c.indexOf(node), 1);
+				parent.c.splice(this.#insertIndex(parent, before), 0, node);
+				node.parent = parent;
+				this.#unsettle(oldParent);
+				this.#unsettle(node);
+				return;
+			}
+			case "del": {
+				const [, id] = op;
+				const node = this.#node(id);
+				if (node === this.#root) fail("cannot delete the root");
+				const parent = node.parent!;
+				parent.c.splice(parent.c.indexOf(node), 1);
+				this.#unregister(node);
+				this.#unsettle(parent);
+				return;
+			}
+			case "settle": {
+				const [, id] = op;
+				this.#node(id);
+				this.#settled.add(id);
+				return;
+			}
+			case "focus": {
+				const [, id] = op;
+				if (id !== null) this.#node(id);
+				this.#focus = id;
+				return;
+			}
+			case "reveal": {
+				const [, id] = op;
+				this.#node(id);
+				return;
+			}
+			case "suspend":
+				this.#suspended = true;
+				return;
+			case "resume":
+				this.#suspended = false;
+				return;
+			default:
+				fail(`unknown op ${String((op as readonly unknown[])[0])}`);
+		}
+	}
+
+	#textNode(id: string): DocNode {
+		const node = this.#node(id);
+		if (!TEXT_KINDS.has(node.k)) fail(`${id} (${node.k}) has no primary text`);
+		return node;
+	}
+
+	#text(node: DocNode): string {
+		return typeof node.p.text === "string" ? node.p.text : "";
+	}
+
+	#insertIndex(parent: DocNode, before: string | null): number {
+		if (before === null) return parent.c.length;
+		const sibling = this.#index.get(before);
+		if (!sibling || sibling.parent !== parent) fail(`${before} is not a child of ${parent.id}`);
+		return parent.c.indexOf(sibling);
+	}
+
+	#build(wire: TspNode, parent: DocNode, seen: Set<string>): DocNode {
+		if (typeof wire.id !== "string" || wire.id.length === 0) fail("node without id");
+		if (!KINDS.has(wire.k)) fail(`unknown kind ${String(wire.k)}`);
+		if (this.#index.has(wire.id) || seen.has(wire.id)) fail(`duplicate id ${wire.id}`);
+		seen.add(wire.id);
+		const node: DocNode = { id: wire.id, k: wire.k, p: {}, c: [], parent };
+		if (wire.p) {
+			for (const key in wire.p) {
+				const value = (wire.p as Record<string, unknown>)[key];
+				if (value !== undefined && value !== null) node.p[key] = value;
+			}
+		}
+		if (wire.c) for (const child of wire.c) node.c.push(this.#build(child, node, seen));
+		return node;
+	}
+
+	#register(node: DocNode): void {
+		this.#index.set(node.id, node);
+		for (const child of node.c) this.#register(child);
+	}
+
+	#unregister(node: DocNode): void {
+		this.#index.delete(node.id);
+		this.#settled.delete(node.id);
+		if (this.#focus === node.id) this.#focus = null;
+		for (const child of node.c) this.#unregister(child);
+	}
+}