@zaly/tui 0.0.4

package/dist/renderer-CxL4xbkl.mjs

@@ -0,0 +1,2644 @@
+import { C as useActiveOwner, E as withOwner, S as unwrap, _ as peek, d as createSuspenseBoundary, h as memo, l as createRoot, n as SuspenseContext, o as createNode, v as provideContext, x as untrack, y as signal } from "./reactive-f7NpAi69.mjs";
+import { t as defaultTheme } from "./registry-U654j61Y.mjs";
+import { s as stripAnsiBg } from "./ansi-Clq0ozyA.mjs";
+import { t as styleBuilder } from "./builder-D49ECBEf.mjs";
+import { n as box } from "./box-DyaByEiG.mjs";
+import { r as createCtx, t as RenderContext } from "./render-DxVLqqB9.mjs";
+import { TuiReporter } from "./services/logger.mjs";
+import { o as bumpPlacements } from "./kitty-JbCJC0iQ.mjs";
+import { TerminalQueries, canonical } from "./index.mjs";
+import { Emitter } from "@zaly/shared";
+import { sliceAnsi, stringWidth, stripAnsi } from "@zaly/shared/ansi";
+import { inspect, isDeepStrictEqual } from "node:util";
+import { Logger } from "@zaly/shared/logger";
+import { throttle } from "@zaly/shared/throttle";
+//#region src/input/actions.ts
+function filterAction(action, filter) {
+	if (!action) return false;
+	if (!filter) return true;
+	if (filter.cmd && filter.cmd !== action.cmd) return false;
+	if (filter.id) {
+		if (typeof filter.id === "string" && filter.id !== action.id) return false;
+		if (filter.id instanceof RegExp && !filter.id.test(action.id)) return false;
+	}
+	if (filter.hidden !== void 0 && filter.hidden !== (action.hidden ?? false)) return false;
+	if (filter.filter && !filter.filter(action)) return false;
+	if (filter.source && filter.source !== action.source) return false;
+	return true;
+}
+/**
+* Runtime registry of action metadata + impls.
+*
+* `register(entries)` merges new `ActionInfo` objects into the catalog
+* by id — passing `{ "x": { keys: [...] } }` updates only the `keys`
+* field of `x`, preserving existing `fn`/`desc`. That lets docs,
+* bindings, and impls be registered in separate calls / from different
+* layers (bundled defaults, app-level overrides, plugin contributions).
+*
+* `dispatch(id, ctx)` runs the action:
+*   - If the catalog entry has `fn`, it's called directly (global
+*     actions).
+*   - Otherwise, the focus chain is walked from `ctx.target` (default:
+*     the router's focused node) up to the root, and the first node
+*     with `actions[id]` handles it.
+*
+* `list()` returns the catalog for command palette / help enumeration.
+*/
+var Actions = class extends Emitter {
+	#catalog = /* @__PURE__ */ new Map();
+	/** Optional focus-chain walker. Supplied by the Renderer so Actions
+	*  doesn't have to know about the router directly. Returns the
+	*  starting node (focused by default) so dispatch can walk up. */
+	#getTarget = () => void 0;
+	#logger;
+	#keymap = /* @__PURE__ */ new Map();
+	constructor(logger) {
+		super();
+		this.#logger = logger ?? new Logger();
+		this.on("change", () => this.#updateKeymap());
+	}
+	/** Internal — the Renderer wires this after construction. */
+	setTargetResolver(fn) {
+		this.#getTarget = fn;
+	}
+	bind(binding) {
+		const { id, keys, ...info } = binding;
+		return this.register({ [id]: {
+			...info,
+			keys: (Array.isArray(keys) ? keys : [keys]).map((k) => canonical(k))
+		} });
+	}
+	/**
+	* Register or merge catalog entries. Values are shallow-merged into
+	* existing entries by id.
+	*
+	* When `opts.default` is `true`, the new entry is merged *before* the
+	* existing one, so it provides defaults.
+	*
+	* When `opts.default` is `false` (the default), the new entry is merged
+	* *after* the existing one, so it overrides prior values.
+	*
+	* Returns an unregister function that rolls this call back.
+	*/
+	register(actions, opts = {}) {
+		const entries = Array.isArray(actions) ? Object.fromEntries(actions.map((a) => [a.id, a])) : actions;
+		const isDefault = opts.default ?? false;
+		const ids = Object.keys(entries);
+		const prior = /* @__PURE__ */ new Map();
+		for (const id of ids) prior.set(id, this.#catalog.get(id));
+		for (const [id, info] of Object.entries(entries)) {
+			info.keys = info.keys?.map((k) => canonical(k));
+			const existing = this.#catalog.get(id);
+			this.#catalog.set(id, isDefault ? {
+				...info,
+				...existing,
+				id
+			} : {
+				...existing,
+				...info,
+				id
+			});
+		}
+		this.emit("change");
+		return () => {
+			for (const id of ids) {
+				const before = prior.get(id);
+				if (before === void 0) this.#catalog.delete(id);
+				else this.#catalog.set(id, before);
+			}
+			this.emit("change");
+		};
+	}
+	/** Remove entries by id. */
+	delete(filter) {
+		const ids = Array.isArray(filter) ? filter : this.list(filter).map((a) => a.id);
+		let changed = false;
+		for (const id of ids) if (this.#catalog.delete(id)) changed = true;
+		if (changed) this.emit("change");
+	}
+	get(id) {
+		return this.#catalog.get(id);
+	}
+	list(opts) {
+		return [...this.#catalog.values()].filter((action) => opts ? filterAction(action, opts) : true);
+	}
+	find(opts) {
+		return this.list(opts)[0];
+	}
+	dispatch(idOrAction, partial = {}) {
+		const id = typeof idOrAction === "string" ? idOrAction : idOrAction.id;
+		const action = typeof idOrAction === "string" ? this.#catalog.get(id) : idOrAction;
+		const target = partial.target ?? this.#getTarget();
+		const source = partial.source ?? "programmatic";
+		if (action?.fn) {
+			const ctx = {
+				id,
+				source,
+				target,
+				...partial
+			};
+			const fn = action.fn;
+			this.#logger.try(() => fn(ctx), {
+				id,
+				name: "dispatch",
+				source
+			});
+			return true;
+		}
+		for (let node = target; node !== void 0; node = node.parent) {
+			if (!node.isVisible() || !node.mounted) continue;
+			const entry = node.actions?.[id];
+			const fn = typeof entry === "function" ? entry : entry?.fn;
+			if (typeof fn === "function") {
+				const ctx = {
+					id,
+					node,
+					source,
+					target,
+					...partial
+				};
+				this.#logger.try(() => fn(ctx), {
+					id,
+					name: "dispatch",
+					source
+				});
+				return true;
+			}
+		}
+		return false;
+	}
+	dispatchKey(routed, opts = {}) {
+		const actions = (this.#keymap.get(canonical(routed.pattern)) ?? []).map((id) => this.get(id)).filter((a) => filterAction(a)).toSorted((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+		if (!actions.length) return false;
+		const nodeActions = opts.node ?? true ? actions.filter((a) => !a.fn) : [];
+		const globalActions = opts.global ?? true ? actions.filter((a) => a.fn) : [];
+		const target = this.#getTarget();
+		if (nodeActions.length) {
+			for (const t of target ? [...target.actionTargets, target] : []) for (const a of nodeActions) if (this.dispatch(a, {
+				key: routed,
+				source: "key",
+				target: t
+			})) return true;
+		}
+		for (const a of globalActions) if (this.dispatch(a, {
+			key: routed,
+			source: "key"
+		})) return true;
+		return false;
+	}
+	/**
+	* Build a `canonical-key → action-id[]` keymap from every catalog
+	* entry's `keys` field. Multiple actions can share the same default
+	* binding (e.g. both `input.submit` and `menu.select` default to
+	* `enter`) — the router's dispatch tries each candidate in order
+	* and the first whose handler is reachable on the focus chain
+	* wins. Registration order defines priority; later wins.
+	*/
+	#updateKeymap() {
+		const out = /* @__PURE__ */ new Map();
+		for (const [id, info] of this.#catalog) {
+			if (!info.keys) continue;
+			for (const pattern of info.keys) {
+				const c = canonical(pattern);
+				const list = out.get(c) ?? [];
+				list.push(id);
+				out.set(c, list);
+			}
+		}
+		this.#keymap = out;
+	}
+	whichKey(node, opts = {}) {
+		const ret = [];
+		const actions = Object.keys(node.actions ?? {}).map((id) => this.get(id)).filter((a) => filterAction(a, opts.filter)).toSorted((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+		const used = /* @__PURE__ */ new Set();
+		for (const action of actions) {
+			const keys = (action.keys ?? []).map((k) => canonical(k)).filter((k) => !used.has(k));
+			if (keys.length === 0) continue;
+			keys.forEach((k) => used.add(k));
+			ret.push({
+				...action,
+				keys
+			});
+		}
+		return ret;
+	}
+};
+//#endregion
+//#region src/input/decoder.ts
+var Decoder = class {
+	#pending = "";
+	#paste;
+	feed(chunk) {
+		const out = [];
+		let buf = this.#pending + chunk;
+		this.#pending = "";
+		while (buf.length > 0) {
+			if (this.#paste !== void 0) {
+				const end = buf.indexOf(PASTE_END);
+				if (end === -1) {
+					this.#paste += buf;
+					buf = "";
+					continue;
+				}
+				this.#paste += buf.slice(0, end);
+				out.push({
+					text: this.#paste,
+					type: "paste"
+				});
+				this.#paste = void 0;
+				buf = buf.slice(end + PASTE_END.length);
+				continue;
+			}
+			if (buf[0] === "\x1B") {
+				const consumed = parseEsc(buf, out, () => {
+					this.#paste = "";
+				});
+				if (consumed === 0) {
+					this.#pending = buf;
+					return out;
+				}
+				buf = buf.slice(consumed);
+				continue;
+			}
+			const step = decodeChar(buf, out, { alt: false });
+			buf = buf.slice(step);
+		}
+		return out;
+	}
+	/**
+	* Force-emit any state we've been holding. Currently only the bare-ESC
+	* case: if `feed` ended on a lone `\x1b` we hold it in case `a` follows
+	* (alt+a); call `flush` after a short idle timeout to commit it as an
+	* `esc` key press.
+	*/
+	flush() {
+		if (this.#pending === "\x1B") {
+			this.#pending = "";
+			return [key({ name: "esc" })];
+		}
+		return [];
+	}
+};
+const PASTE_END = "\x1B[201~";
+function parseEsc(buf, out, onPasteStart) {
+	if (buf.length === 1) return 0;
+	const second = buf[1];
+	if (second === "[") return parseCsi(buf, out, onPasteStart);
+	if (second === "O") return parseSs3(buf, out);
+	if (second === "]") return parseStringControl(buf, out, "osc");
+	if (second === "P") return parseStringControl(buf, out, "dcs");
+	if (second === "_") return parseStringControl(buf, out, "apc");
+	return 1 + decodeChar(buf.slice(1), out, { alt: true });
+}
+function parseCsi(buf, out, onPasteStart) {
+	let i = 2;
+	while (i < buf.length) {
+		const code = buf.charCodeAt(i);
+		if (code >= 64 && code <= 126) {
+			const params = buf.slice(2, i);
+			const final = buf[i];
+			const consumed = i + 1;
+			if (params === "200" && final === "~") {
+				onPasteStart();
+				return consumed;
+			}
+			if (params === "" && final === "I") {
+				out.push({
+					gained: true,
+					type: "focus"
+				});
+				return consumed;
+			}
+			if (params === "" && final === "O") {
+				out.push({
+					gained: false,
+					type: "focus"
+				});
+				return consumed;
+			}
+			if (isTerminalCsiResponse(params, final)) {
+				out.push({
+					final,
+					kind: "csi",
+					params,
+					sequence: buf.slice(0, consumed),
+					type: "term-response"
+				});
+				return consumed;
+			}
+			handleCsi(params, final, out);
+			return consumed;
+		}
+		i++;
+	}
+	return 0;
+}
+function parseStringControl(buf, out, kind) {
+	const payloadStart = 2;
+	const st = buf.indexOf("\x1B\\", payloadStart);
+	const bel = kind === "osc" ? buf.indexOf("\x07", payloadStart) : -1;
+	const useBel = bel !== -1 && (st === -1 || bel < st);
+	const end = useBel ? bel : st;
+	if (end === -1) return 0;
+	const consumed = end + (useBel ? 1 : 2);
+	out.push({
+		kind,
+		payload: buf.slice(payloadStart, end),
+		sequence: buf.slice(0, consumed),
+		type: "term-response"
+	});
+	return consumed;
+}
+function parseSs3(buf, out) {
+	if (buf.length < 3) return 0;
+	const final = buf[2];
+	const name = SS3_NAMES[final];
+	if (name !== void 0) out.push(key({ name }));
+	return 3;
+}
+const ARROW_NAMES = {
+	A: "up",
+	B: "down",
+	C: "right",
+	D: "left",
+	F: "end",
+	H: "home"
+};
+const TILDE_NAMES = {
+	"1": "home",
+	"11": "f1",
+	"12": "f2",
+	"13": "f3",
+	"14": "f4",
+	"15": "f5",
+	"17": "f6",
+	"18": "f7",
+	"19": "f8",
+	"2": "insert",
+	"20": "f9",
+	"21": "f10",
+	"23": "f11",
+	"24": "f12",
+	"3": "delete",
+	"4": "end",
+	"5": "pageup",
+	"6": "pagedown",
+	"7": "home",
+	"8": "end"
+};
+const SS3_NAMES = {
+	P: "f1",
+	Q: "f2",
+	R: "f3",
+	S: "f4"
+};
+function isTerminalCsiResponse(params, final) {
+	return final === "c" && (params.startsWith("?") || params.startsWith(">"));
+}
+function handleCsi(params, final, out) {
+	if ((final === "M" || final === "m") && params.startsWith("<")) {
+		handleMouse(params, final, out);
+		return;
+	}
+	const parts = params.length === 0 ? [] : params.split(";");
+	const arrow = ARROW_NAMES[final];
+	if (arrow !== void 0) {
+		const mod = parts.length === 2 ? Number.parseInt(parts[1], 10) : 1;
+		out.push(key({
+			name: arrow,
+			...modBits(mod)
+		}));
+		return;
+	}
+	if (final === "~") {
+		const code = parts[0] ?? "";
+		const name = TILDE_NAMES[code];
+		if (name === void 0) return;
+		const mod = parts.length === 2 ? Number.parseInt(parts[1], 10) : 1;
+		out.push(key({
+			name,
+			...modBits(mod)
+		}));
+		return;
+	}
+}
+function handleMouse(params, final, out) {
+	const [button, x, y] = params.slice(1).split(";").map((p) => Number.parseInt(p, 10));
+	if (!Number.isFinite(button) || !Number.isFinite(x) || !Number.isFinite(y)) return;
+	const code = button & 3;
+	const scroll = (button & 64) !== 0;
+	const mods = mouseModBits(button);
+	if (scroll) {
+		out.push({
+			...mods,
+			deltaY: code === 0 ? -1 : 1,
+			kind: "scroll",
+			type: "mouse",
+			x,
+			y
+		});
+		return;
+	}
+	const mouseButton = buttonName(code);
+	if (!mouseButton) return;
+	const kind = mouseKind(button, final);
+	out.push({
+		...mods,
+		button: mouseButton,
+		kind,
+		type: "mouse",
+		x,
+		y
+	});
+}
+function mouseKind(button, final) {
+	if (final === "m") return "up";
+	if ((button & 32) !== 0) return "drag";
+	return "down";
+}
+function buttonName(code) {
+	if (code === 0) return "left";
+	if (code === 1) return "middle";
+	if (code === 2) return "right";
+}
+function mouseModBits(button) {
+	return {
+		alt: (button & 8) !== 0,
+		ctrl: (button & 16) !== 0,
+		meta: false,
+		shift: (button & 4) !== 0
+	};
+}
+function modBits(m) {
+	const v = Number.isFinite(m) ? m - 1 : 0;
+	return {
+		alt: (v & 2) !== 0,
+		ctrl: (v & 4) !== 0,
+		meta: (v & 8) !== 0,
+		shift: (v & 1) !== 0
+	};
+}
+function decodeChar(buf, out, opts) {
+	const alt = opts.alt;
+	const code = buf.charCodeAt(0);
+	if (code === 9) {
+		out.push(key({
+			alt,
+			name: "tab"
+		}));
+		return 1;
+	}
+	if (code === 10 || code === 13) {
+		out.push(key({
+			alt,
+			name: "enter"
+		}));
+		return 1;
+	}
+	if (code === 8 || code === 127) {
+		out.push(key({
+			alt,
+			name: "backspace"
+		}));
+		return 1;
+	}
+	if (code === 32) {
+		out.push(key({
+			alt,
+			name: "space",
+			text: " "
+		}));
+		return 1;
+	}
+	if (code >= 1 && code <= 26) {
+		const letter = String.fromCharCode(code + 96);
+		out.push(key({
+			alt,
+			ctrl: true,
+			name: letter
+		}));
+		return 1;
+	}
+	const cp = buf.codePointAt(0) ?? 0;
+	const ch = String.fromCodePoint(cp);
+	const isUpper = ch.length === 1 && ch >= "A" && ch <= "Z";
+	out.push(key({
+		alt,
+		name: ch,
+		shift: isUpper,
+		text: ch
+	}));
+	return ch.length;
+}
+function key(partial) {
+	return {
+		event: {
+			alt: partial.alt ?? false,
+			ctrl: partial.ctrl ?? false,
+			meta: partial.meta ?? false,
+			name: partial.name,
+			shift: partial.shift ?? false,
+			...partial.text !== void 0 ? { text: partial.text } : {}
+		},
+		type: "key"
+	};
+}
+//#endregion
+//#region src/input/defaults.ts
+/**
+* Catalog of built-in actions with descriptions and default bindings.
+* Typed as `Record<BuiltinAction, ActionInfo>` so missing entries are a
+* compile error — add an action to a widget and you'll be nudged to
+* document it here.
+*
+* The Renderer registers this into its `actions` registry at
+* construction; apps compose further catalogs via
+* `renderer.actions.register(...)`.
+*/
+const defaultActions = {
+	"global.quit": {
+		cmd: "quit",
+		desc: "quit",
+		keys: ["ctrl-c"]
+	},
+	"input.cursorDown": {
+		desc: "move cursor down one line",
+		hidden: true,
+		keys: ["down"]
+	},
+	"input.cursorLeft": {
+		desc: "move cursor left",
+		hidden: true,
+		keys: ["left"]
+	},
+	"input.cursorLineEnd": {
+		desc: "jump to end of current line",
+		hidden: true,
+		keys: ["end", "ctrl-e"]
+	},
+	"input.cursorLineStart": {
+		desc: "jump to start of current line",
+		hidden: true,
+		keys: ["home", "ctrl-a"]
+	},
+	"input.cursorRight": {
+		desc: "move cursor right",
+		hidden: true,
+		keys: ["right"]
+	},
+	"input.cursorUp": {
+		desc: "move cursor up one line",
+		hidden: true,
+		keys: ["up"]
+	},
+	"input.deleteCharBack": {
+		desc: "delete the character before the cursor",
+		hidden: true,
+		keys: ["backspace"]
+	},
+	"input.deleteCharForward": {
+		desc: "delete the character at the cursor",
+		hidden: true,
+		keys: ["delete"]
+	},
+	"input.deleteWordBack": {
+		desc: "delete the word before the cursor",
+		hidden: true,
+		keys: ["ctrl-w"]
+	},
+	"input.insertNewline": {
+		desc: "insert a newline at the cursor (copies leading indent)",
+		hidden: true,
+		keys: ["shift-enter", "alt-enter"]
+	},
+	"input.insertTab": {
+		desc: "insert an indent (two spaces) at the cursor",
+		hidden: true,
+		keys: ["tab"]
+	},
+	"input.paste": {
+		desc: "paste text from the system clipboard, or attach a pasted image",
+		hidden: true,
+		keys: ["ctrl-v"]
+	},
+	"input.submit": {
+		desc: "submit the current value",
+		hidden: true,
+		keys: ["enter"]
+	},
+	"picker.next": {
+		desc: "move to the next item that matches the query",
+		hidden: true,
+		keys: ["ctrl-n"]
+	},
+	"picker.prev": {
+		desc: "move to the previous item that matches the query",
+		hidden: true,
+		keys: ["ctrl-p"]
+	},
+	"select.accept": {
+		desc: "select the active item",
+		hidden: true,
+		keys: ["enter"]
+	},
+	"select.close": {
+		desc: "close",
+		keys: ["esc"]
+	},
+	"select.complete": {
+		desc: "complete the active item",
+		hidden: true,
+		keys: ["tab"]
+	},
+	"select.first": {
+		desc: "jump to the first item",
+		hidden: true,
+		keys: ["home"]
+	},
+	"select.last": {
+		desc: "jump to the last item",
+		hidden: true,
+		keys: ["end"]
+	},
+	"select.next": {
+		desc: "move to the next item",
+		hidden: true,
+		keys: ["down"]
+	},
+	"select.page-down": {
+		desc: "move down one page",
+		hidden: true,
+		keys: ["pagedown", "ctrl-d"]
+	},
+	"select.page-up": {
+		desc: "move up one page",
+		hidden: true,
+		keys: ["pageup", "ctrl-u"]
+	},
+	"select.prev": {
+		desc: "move to the previous item",
+		hidden: true,
+		keys: ["up"]
+	}
+};
+//#endregion
+//#region src/input/router.ts
+/**
+* Routes decoder events to the right node and/or action.
+*
+* Dispatch priority for a key event (most-specific-first):
+*
+*   1. **Per-node `"key"` bubble** — focused node up to root. Each
+*      node's `on("key")` / `bind()` handlers fire. Calling `.stop()`
+*      ends dispatch. This is where local overrides live.
+*   2. **Keymap lookup** — a single table built by the `Actions`
+*      registry (`canonical pattern → action id | direct handler`).
+*      Action ids are dispatched through `Actions.dispatch(id)`,
+*      which walks the focus chain for `node.actions[id]` — or
+*      calls a catalog-level `fn` if the action has one.
+*   3. **Global `bind()` handlers** — a last-resort fallback for
+*      ad-hoc app-level bindings registered via `router.bind(...)`.
+*
+* Paste events follow a simple emit-and-bubble path — no keymap.
+*/
+var InputRouter = class extends Emitter {
+	#focused = [];
+	/** Set by the Renderer so keymap-matched action ids can be
+	*  dispatched through the catalog. */
+	#actions;
+	#logger;
+	#mouseClick;
+	#terminalFocus = true;
+	constructor(logger) {
+		super();
+		this.#logger = logger ?? new Logger();
+	}
+	/** Internal — wired by the Renderer at construction. */
+	setActions(actions) {
+		this.#actions = actions;
+	}
+	/** Currently-focused node, or `undefined` when none. */
+	get focused() {
+		this.#focused = this.#focused.filter((n) => n.mounted);
+		return this.#focused.at(-1);
+	}
+	/**
+	* Move focus to `node`. Emits `blur`
+	* on the previously-focused node and `focus` on the new one.
+	* Focusing the already-focused node is a no-op.
+	*/
+	focus(node) {
+		if (!node.mounted || this.focused === node) return;
+		const prev = this.focused;
+		this.#focused = this.#focused.filter((n) => n !== node);
+		this.#focused.push(node);
+		if (prev !== void 0) {
+			prev.emit("blur");
+			this.emit("blur", { node: prev });
+		}
+		node.emit("focus");
+		this.emit("focus", { node });
+	}
+	/** Clear focus from `node`. Emits `blur` on the node and `focus`
+	* on the next-most-recently-focused node, if any. */
+	blur(node) {
+		const top = this.focused;
+		this.#focused = this.#focused.filter((n) => n !== node);
+		if (top !== node) return;
+		const next = this.focused;
+		node.emit("blur");
+		this.emit("blur", { node });
+		if (next !== void 0) {
+			next.emit("focus");
+			this.emit("focus", { node: next });
+		}
+	}
+	get terminalFocus() {
+		return this.#terminalFocus;
+	}
+	/**
+	* Dispatch a decoder event. Returns `true` if consumed.
+	*/
+	dispatch(ev) {
+		return this.#logger.try(() => this.#dispatch(ev), "dispatch") ?? false;
+	}
+	#dispatch(ev) {
+		if (ev.type === "key") return this.#dispatchKey(ev.event);
+		if (ev.type === "paste") return this.#dispatchPaste(ev.text);
+		if (ev.type === "term-response") {
+			this.emit("term-response", { event: ev });
+			return false;
+		}
+		if (ev.type === "mouse") {
+			this.emit("mouse", { event: this.#routeMouse(ev) });
+			return false;
+		} else {
+			this.#terminalFocus = ev.gained;
+			this.emit("terminal-focus", { gained: ev.gained });
+		}
+		return false;
+	}
+	#routeMouse(event) {
+		if (event.kind !== "down") return event;
+		const now = Date.now();
+		const prev = this.#mouseClick;
+		const count = prev !== void 0 && prev.button === event.button && prev.x === event.x && prev.y === event.y && now - prev.time <= 500 ? prev.count % 3 + 1 : 1;
+		this.#mouseClick = {
+			button: event.button,
+			count,
+			time: now,
+			x: event.x,
+			y: event.y
+		};
+		return {
+			...event,
+			click: count
+		};
+	}
+	#dispatchKey(event) {
+		this.emit("key", { event });
+		const routed = makeRoutedKey(event);
+		if (this.#actions?.dispatchKey(routed, {
+			global: false,
+			node: true
+		})) return true;
+		for (let node = this.focused; node !== void 0; node = node.parent) {
+			node.emit("key", { key: routed });
+			if (routed.stopped) return true;
+		}
+		return this.#actions?.dispatchKey(routed, {
+			global: true,
+			node: false
+		}) ?? false;
+	}
+	#dispatchPaste(text) {
+		const routed = makeRoutedPaste(text);
+		let node = this.focused;
+		while (node !== void 0) {
+			node.emit("paste", { paste: routed });
+			if (routed.stopped) return true;
+			node = node.parent;
+		}
+		return false;
+	}
+};
+function makeRoutedKey(ev) {
+	const r = {
+		alt: ev.alt,
+		ctrl: ev.ctrl,
+		meta: ev.meta,
+		name: ev.name,
+		pattern: canonical(ev),
+		shift: ev.shift,
+		stop: () => {
+			r.stopped = true;
+		},
+		stopped: false
+	};
+	if (ev.text !== void 0) r.text = ev.text;
+	return r;
+}
+function makeRoutedPaste(text) {
+	const r = {
+		stop: () => {
+			r.stopped = true;
+		},
+		stopped: false,
+		text
+	};
+	return r;
+}
+//#endregion
+//#region src/renderer/frame.ts
+function sliceLine(line, from, to, width) {
+	const start = from ? Math.max(0, from - 1) : 0;
+	const end = to ? Math.max(start, to - 1) : width;
+	if (end <= start) return;
+	const lineWidth = stringWidth(line);
+	if (start >= lineWidth) return;
+	const clampedEnd = Math.min(end, lineWidth);
+	return {
+		from: start + 1,
+		line,
+		to: clampedEnd + 1
+	};
+}
+var Frame = class {
+	terminal;
+	#base = [];
+	#current = [];
+	constructor(terminal) {
+		this.terminal = terminal;
+	}
+	reset(rows = this.terminal.rows) {
+		this.#base = Array(rows).fill(void 0);
+		this.#current = Array(rows).fill(void 0);
+	}
+	begin() {
+		const rows = this.terminal.rows;
+		if (this.#current.length !== rows || this.#base.length !== rows) this.reset(rows);
+		return new RenderFrame(this.terminal, this.#current, this.#base);
+	}
+	slice(row, from, to, width = this.terminal.cols) {
+		return sliceLine(this.#current[row - 1] ?? "", from, to, width);
+	}
+};
+var RenderFrame = class {
+	terminal;
+	current;
+	base;
+	#ops = [];
+	#next;
+	constructor(terminal, current, base) {
+		this.terminal = terminal;
+		this.current = current;
+		this.base = base;
+		this.#next = base.map((row) => row ?? "");
+	}
+	get(row) {
+		return this.#next[row - 1] ?? "";
+	}
+	set(row, content) {
+		if (row < 1 || row > this.#next.length) return;
+		this.#next[row - 1] = content;
+	}
+	clear(row) {
+		this.set(row, "");
+	}
+	overlay(row, col, content) {
+		if (row < 1 || row > this.#next.length) return;
+		const base = this.get(row);
+		const start = Math.max(0, col - 1);
+		const width = stringWidth(content);
+		const prefix = sliceAnsi(base, 0, start);
+		const pad = " ".repeat(Math.max(0, start - stringWidth(prefix)));
+		this.set(row, `${prefix}${pad}${content}${sliceAnsi(base, start + width)}`);
+	}
+	slice(row, from, to, width = this.terminal.cols) {
+		if (row < 1 || row > this.#next.length) return;
+		return sliceLine(this.get(row), from, to, width);
+	}
+	highlight(row, from, to, ctx) {
+		const ret = this.slice(row, from, to, ctx.width);
+		if (!ret) return;
+		const start = ret.from - 1;
+		const end = (ret.to ?? ctx.width + 1) - 1;
+		const text = sliceAnsi(ret.line, start, end);
+		const highlighted = ctx.style.selection(stripAnsiBg(text));
+		this.set(row, `${sliceAnsi(ret.line, 0, start)}${highlighted}${sliceAnsi(ret.line, end)}`);
+		return ret;
+	}
+	queue(op) {
+		this.#ops.push(op);
+	}
+	commitBase() {
+		for (let i = 0; i < this.#next.length; i++) this.base[i] = this.#next[i];
+	}
+	flush() {
+		for (let i = 0; i < this.#next.length; i++) {
+			const next = this.#next[i];
+			if (this.current[i] === next) continue;
+			const row = i + 1;
+			this.queue((terminal) => {
+				terminal.write(terminal.moveTo(row, 1) + terminal.clearLine() + next.trimEnd());
+			});
+			this.current[i] = next;
+		}
+	}
+	scrollUp(top, bottom, lines, op) {
+		if (lines <= 0 || top > bottom) return;
+		this.flush();
+		this.queue(op);
+		const from = Math.max(1, top);
+		const to = Math.min(this.#next.length, bottom);
+		const amount = Math.min(lines, to - from + 1);
+		for (let i = from - 1; i < to; i++) {
+			const source = i + amount;
+			const value = source < to ? this.current[source] ?? "" : "";
+			this.current[i] = value;
+			this.#next[i] = value;
+		}
+	}
+	scrollDown(top, bottom, lines, op) {
+		if (lines <= 0 || top > bottom) return;
+		this.flush();
+		this.queue(op);
+		const from = Math.max(1, top);
+		const to = Math.min(this.#next.length, bottom);
+		const amount = Math.min(lines, to - from + 1);
+		for (let i = to - 1; i >= from - 1; i--) {
+			const source = i - amount;
+			const value = source >= from - 1 ? this.current[source] ?? "" : "";
+			this.current[i] = value;
+			this.#next[i] = value;
+		}
+	}
+	paint() {
+		const ops = this.#ops.length;
+		this.flush();
+		const rows = this.#ops.length - ops;
+		for (const op of this.#ops) op(this.terminal);
+		this.#ops.length = 0;
+		return {
+			ops,
+			rows
+		};
+	}
+};
+//#endregion
+//#region src/renderer/surface.ts
+/**
+* Shared base for the three renderer surfaces (`Stream`, `UI`,
+* `OverlaySurface`). Owns the common lifecycle and paint bookkeeping:
+*
+*   - `#running` flag and `#mountCtx` reference, driven by the Renderer
+*     `start` / `stop` events. Subclasses read `mountCtx` to mount nodes
+*     appended while the renderer is running.
+*   - `#dirty`, set by `invalidate()`, means this surface has content or
+*     state changes and schedules a frame.
+* Concrete surfaces override `mountAll` / `unmountAll` to walk whichever
+* node set they track, and `_render()` to compute rows and enqueue a paint
+* closure into the renderer's atomic terminal sync.
+*
+* @internal
+*/
+var Surface = class extends Emitter {
+	#running = false;
+	#mountCtx;
+	#rendering;
+	$r;
+	#dirty = false;
+	constructor(renderer) {
+		super();
+		this.$r = renderer.on("start", () => {
+			if (this.#running) return;
+			this.#running = true;
+			this.#mountCtx = this.$r.mountCtx(this.type);
+			this.mountAll(this.#mountCtx);
+		}).on("stop", () => {
+			if (!this.#running) return;
+			this.#running = false;
+			this.unmountAll();
+			this.#mountCtx = void 0;
+		});
+	}
+	/** Check if this surface contains the given screen position */
+	contains(point) {
+		const { top, bottom } = this.bounds;
+		return point.row >= top && point.row <= bottom;
+	}
+	get dirty() {
+		return this.#dirty;
+	}
+	track(ev, inc = 1) {
+		this.$r.stats.inc(ev, inc);
+	}
+	/** Mark this surface as changed and schedule a renderer frame. */
+	invalidate = () => {
+		this.#dirty = true;
+		this.track(`${this.type}.dirty`);
+		untrack(() => void this.$r.emit("dirty"));
+	};
+	/** `true` between `onStart()` and `onStop()`. Subclasses read this
+	*  to decide whether an append should mount immediately or wait. */
+	get running() {
+		return this.#running;
+	}
+	/** The MountCtx handed in by the Renderer on `start()`. Undefined
+	*  when the surface isn't running. Subclasses read this to mount
+	*  nodes appended while the renderer is up. */
+	get mountCtx() {
+		return this.#mountCtx;
+	}
+	async render(frame) {
+		const ownFrame = frame ?? this.$r.frame.begin();
+		return this.#rendering ??= (async () => {
+			this.#dirty = false;
+			await this._render(ownFrame);
+			if (frame === void 0) this.$r.terminal.sync(() => ownFrame.paint());
+		})().finally(() => {
+			this.#rendering = void 0;
+		});
+	}
+};
+//#endregion
+//#region src/renderer/overlay.ts
+/**
+* Overlay surface — paints absolute-positioned `Overlay` nodes on top
+* of the stream and UI surfaces after each tick.
+*
+* Open/close is explicit. While an overlay is open, mutations on its
+* state (or its subtree) bubble through `invalidate` → this surface's
+* `dirty` → Renderer's scheduler, same as the other surfaces. On
+* close, the covered area is overdrawn by asking the stream and UI
+* to invalidate so the next flush repaints them in full.
+*
+* v1 is intentionally minimal:
+*   - Overlays are painted top-to-bottom in z-order on every flush; we
+*     don't track per-overlay dirty flags, just paint all active ones.
+*   - No clipping against the viewport — callers are responsible for
+*     sizing / positioning sensibly. The stream lives inside DECSTBM,
+*     so overlays that touch row 0 can disrupt scrollback.
+*/
+var OverlaySurface = class extends Surface {
+	type = "overlay";
+	#overlays = [];
+	/** Cached render state for each active overlay, in z-order (low -> high). */
+	#state = [];
+	get state() {
+		return [...this.#state];
+	}
+	get bounds() {
+		return {
+			bottom: this.$r.terminal.rows,
+			top: 1
+		};
+	}
+	get dirty() {
+		return this.active.length > 0 || super.dirty;
+	}
+	/** Active overlays in paint order (low → high z-index). */
+	get active() {
+		return this.#overlays.filter((o) => o.visible && o.ctx !== void 0);
+	}
+	/** Return the topmost overlay at the given `(row, col)`, if any. */
+	at({ row, col }) {
+		return this.#state.findLast((s) => {
+			if (row < s.y || row >= s.y + s.height) return false;
+			if (col < s.x || col >= s.x + s.width) return false;
+			return true;
+		});
+	}
+	contains(point) {
+		return this.at(point) !== void 0;
+	}
+	/** Register an overlay with the surface. Function form runs `fn`
+	*  inside a fresh Owner scope and adopts the returned Overlay. */
+	add(overlay) {
+		const resolved = withOwner(this.$r.rootOwner, () => createNode(overlay));
+		if (this.#overlays.includes(resolved)) return resolved;
+		this.#overlays.push(resolved);
+		this.#overlays.sort((a, b) => (a.state.zIndex ?? 0) - (b.state.zIndex ?? 0));
+		resolved.on("invalidate", this.invalidate);
+		resolved.on("unmount", () => this.remove(resolved));
+		const ctx = this.mountCtx;
+		if (this.running && ctx) resolved.mount(ctx);
+		if (resolved.visible) this.invalidate();
+		return resolved;
+	}
+	remove(overlay) {
+		const i = this.#overlays.indexOf(overlay);
+		if (i === -1) return this;
+		this.#overlays.splice(i, 1);
+		overlay.emit("close");
+		if (overlay.mounted) overlay.unmount();
+		overlay.off("invalidate", this.invalidate);
+		this.invalidate();
+		return this;
+	}
+	open(overlay) {
+		return this.add(overlay).show();
+	}
+	close(overlay) {
+		overlay.hide();
+		this.remove(overlay);
+		return this;
+	}
+	/** Every currently-open overlay node, for renderer traversals. */
+	get nodes() {
+		return this.#overlays;
+	}
+	mountAll(ctx) {
+		for (const o of this.#overlays) if (!o.mounted) o.mount(ctx);
+	}
+	unmountAll() {
+		for (const o of this.#overlays) if (o.mounted) o.unmount();
+	}
+	/**
+	* Render pass: compute rows for each active overlay, then paint them
+	* at their absolute `(y, x)` inside the outer sync block. Matches the
+	* `render(sync?)` shape used by Stream and UI so the Renderer can
+	* capture all three paints and emit them in one atomic frame.
+	*/
+	async _render(frame) {
+		const painted = [];
+		const ctx = this.$r.ctx;
+		this.#state = await Promise.all(this.active.map(async (node) => {
+			const rows = await node.render(ctx);
+			const height = rows.length;
+			const width = Math.max(...rows.map((r) => stringWidth(r)));
+			let x = node.state.x;
+			let y = node.state.y;
+			if (x < 1 && x > 0) x = Math.floor(this.$r.terminal.cols * x);
+			if (x < 0) x = this.$r.terminal.cols + x;
+			let refY = 1;
+			let refHeight = this.$r.terminal.rows;
+			if (node.state.relative === "ui") {
+				refHeight = this.$r.ui.height;
+				refY = this.$r.terminal.footerTop;
+			} else if (node.state.relative === "stream") refHeight = this.$r.stream.liveHeight;
+			if (y < 1 && y > 0) y = Math.floor(refHeight * y);
+			const anchorY = y < 0 ? refY + refHeight + y : refY + y - 1;
+			const va = node.state.verticalAnchor ?? "top";
+			if (va === "bottom") y = anchorY - height + 1;
+			else if (va === "center") y = anchorY - Math.floor(height / 2);
+			else y = anchorY;
+			const ha = node.state.horizontalAnchor ?? "left";
+			if (ha === "right") x = x - width + 1;
+			else if (ha === "center") x -= Math.floor(width / 2);
+			painted.push({
+				rows,
+				x,
+				y
+			});
+			const s = {
+				height,
+				node,
+				width,
+				x,
+				y,
+				zIndex: node.state.zIndex ?? 0
+			};
+			this.emit("render-node", s);
+			return s;
+		}));
+		for (const { rows, x, y } of painted) for (let r = 0; r < rows.length; r++) frame.overlay(y + r, x, rows[r]);
+	}
+};
+//#endregion
+//#region src/renderer/selection.ts
+var SelectionLayer = class extends Emitter {
+	#selection;
+	#text = "";
+	#dirty = false;
+	#emitted;
+	$r;
+	constructor(renderer) {
+		super();
+		this.$r = renderer;
+	}
+	get selection() {
+		return this.#selection;
+	}
+	set selection(value) {
+		const prev = this.#selection;
+		if (isDeepStrictEqual(prev, value)) return;
+		this.#selection = value;
+		this.#dirty = true;
+		this.#emitted = void 0;
+		if (!value) {
+			this.#text = "";
+			this.#dirty = false;
+		}
+		this.invalidate();
+		this.emit("change", {
+			prev,
+			selection: value
+		});
+	}
+	get text() {
+		return this.#selection ? this.#text : void 0;
+	}
+	set text(value) {
+		if (this.#text === value && !this.#dirty) return;
+		this.#text = value;
+		const selection = this.#selection;
+		if (!selection || selection.dragging || this.#emitted === selection) return;
+		this.#dirty = false;
+		setImmediate(() => {
+			if (selection !== this.#selection || value !== this.#text) return;
+			this.#emitted = selection;
+			this.emit("selection", {
+				selection,
+				text: value
+			});
+		});
+	}
+	invalidate() {
+		this.$r.overlay.invalidate();
+		untrack(() => void this.$r.emit("dirty"));
+	}
+	mouse(event) {
+		if (event.kind === "scroll") return false;
+		if (event.button !== "left") return false;
+		const point = this.#hit(event);
+		if (event.kind === "down") {
+			if (event.click === 2) {
+				this.select(point.screen, "word");
+				return true;
+			}
+			if (event.click === 3) {
+				this.select(point.screen, "line");
+				return true;
+			}
+			this.selection = point.stream ? {
+				dragging: true,
+				from: point.stream,
+				surface: "stream",
+				to: point.stream
+			} : {
+				dragging: true,
+				from: point.screen,
+				surface: "screen",
+				to: point.screen
+			};
+			return true;
+		}
+		const selection = this.#selection;
+		if (!selection?.dragging) return false;
+		if (event.kind === "drag") {
+			this.selection = this.#update(selection, point, true);
+			return true;
+		}
+		const next = this.#update(selection, point, false);
+		this.selection = samePoint(next.from, next.to) ? void 0 : next;
+		return true;
+	}
+	clear() {
+		if (!this.#selection) return;
+		this.selection = void 0;
+	}
+	select(screen, what) {
+		const point = this.#hitPoint(screen);
+		const line = this.$r.frame.slice(screen.row, 1, void 0);
+		if (!line) return;
+		const slice = what === "line" ? lineRange(line.line) : wordRange(line.line, screen.col);
+		if (!slice) return;
+		const row = point.stream?.row ?? screen.row;
+		this.selection = {
+			dragging: false,
+			from: {
+				col: slice.from,
+				row
+			},
+			surface: point.stream ? "stream" : "screen",
+			to: {
+				col: slice.to,
+				row
+			}
+		};
+	}
+	renderStream(frame, ctx) {
+		if (this.#selection?.surface === "stream") this.render(frame, ctx);
+	}
+	renderScreen(frame, ctx) {
+		if (this.#selection?.surface === "screen") this.render(frame, ctx);
+	}
+	render(frame, ctx) {
+		const selection = this.#selection;
+		if (!selection) return;
+		const from = this.#toScreen(selection.surface, selection.from);
+		const to = this.#toScreen(selection.surface, selection.to);
+		const start = before(from, to) ? from : to;
+		const end = start === from ? to : from;
+		const bounds = selection.surface === "stream" ? this.$r.stream.bounds : void 0;
+		const highlighted = renderRange({
+			bounds,
+			ctx,
+			end,
+			frame,
+			start
+		});
+		this.text = normalizeText(selection.surface === "stream" ? this.#streamSlices(start, end, bounds) : highlighted);
+	}
+	#hit(event) {
+		return this.#hitPoint({
+			col: event.x,
+			row: event.y
+		});
+	}
+	#hitPoint(screen) {
+		if (this.$r.overlay.contains(screen)) return { screen };
+		if (this.$r.ui.contains(screen)) return { screen };
+		return {
+			screen,
+			stream: this.$r.stream.contains(screen) ? this.$r.stream.fromScreen(screen) : void 0
+		};
+	}
+	#update(selection, point, dragging) {
+		if (selection.surface === "stream" && point.stream) return {
+			...selection,
+			dragging,
+			to: point.stream
+		};
+		return {
+			dragging,
+			from: selection.surface === "stream" ? this.$r.stream.toScreen(selection.from) : selection.from,
+			surface: "screen",
+			to: point.screen
+		};
+	}
+	#toScreen(surface, point) {
+		return surface === "stream" ? this.$r.stream.toScreen(point) : point;
+	}
+	#streamSlices(start, end, bounds) {
+		const ret = [];
+		const firstRow = Math.max(start.row, bounds.top);
+		const lastRow = Math.min(end.row, bounds.bottom);
+		if (lastRow < firstRow) return ret;
+		for (let row = firstRow; row <= lastRow; row++) {
+			const streamPoint = this.$r.stream.fromScreen({
+				col: 1,
+				row
+			});
+			if (!streamPoint) continue;
+			const line = this.$r.stream.getRow(streamPoint.row);
+			if (line === void 0) continue;
+			ret.push({
+				from: row === start.row ? start.col : 1,
+				line,
+				to: row === end.row ? end.col : void 0
+			});
+		}
+		return ret;
+	}
+};
+const WORD = /^[\w\-/\\@]$/;
+function lineRange(line) {
+	const text = stripAnsi(line);
+	const start = text.search(/\S/);
+	if (start === -1) return;
+	let end = text.length;
+	while (end > start && /\s/.test(text[end - 1])) end--;
+	return {
+		from: start + 1,
+		to: end + 1
+	};
+}
+function wordRange(line, col) {
+	const text = stripAnsi(line);
+	const index = col - 1;
+	if (index < 0 || index >= text.length) return;
+	const match = charClass(text[index]);
+	let start = index;
+	while (start > 0 && charClass(text[start - 1]) === match) start--;
+	let end = index + 1;
+	while (end < text.length && charClass(text[end]) === match) end++;
+	return {
+		from: start + 1,
+		to: end + 1
+	};
+}
+function charClass(char) {
+	if (/\s/.test(char)) return "space";
+	if (WORD.test(char)) return "word";
+	return "punct";
+}
+function samePoint(a, b) {
+	return a.row === b.row && a.col === b.col;
+}
+function before(a, b) {
+	return a.row < b.row || a.row === b.row && a.col <= b.col;
+}
+function normalizeText(slices) {
+	const lines = slices.map((slice) => {
+		const full = stripAnsi(slice.line).trimEnd();
+		const text = stripAnsi(sliceAnsi(slice.line, slice.from - 1, slice.to ? slice.to - 1 : void 0)).trimEnd();
+		return {
+			from: slice.from,
+			full,
+			text
+		};
+	});
+	const indent = commonIndent(lines.map((line) => line.full));
+	return lines.map((line) => stripIndent(line.text, line.from, indent)).join("\n");
+}
+function commonIndent(lines) {
+	const nonEmpty = lines.filter((line) => line.trim() !== "");
+	if (nonEmpty.length === 0) return 0;
+	return Math.min(...nonEmpty.map((line) => line.match(/^[ \t]*/)?.[0].length ?? 0));
+}
+function stripIndent(line, from, indent) {
+	if (indent === 0 || line.trim() === "") return line;
+	const visibleBeforeSelection = from - 1;
+	const remove = Math.max(0, indent - visibleBeforeSelection);
+	return remove === 0 ? line : line.slice(remove);
+}
+function renderRange({ bounds, ctx, end, frame, start }) {
+	const lines = [];
+	const firstRow = bounds ? Math.max(start.row, bounds.top) : start.row;
+	const lastRow = bounds ? Math.min(end.row, bounds.bottom) : end.row;
+	if (lastRow < firstRow) return lines;
+	if (firstRow === lastRow) {
+		const from = firstRow === start.row ? start.col : 1;
+		const to = firstRow === end.row ? end.col : void 0;
+		const text = frame.highlight(firstRow, from, to, ctx);
+		if (text !== void 0) lines.push(text);
+		return lines;
+	}
+	const first = frame.highlight(firstRow, firstRow === start.row ? start.col : 1, void 0, ctx);
+	if (first !== void 0) lines.push(first);
+	for (let row = firstRow + 1; row < lastRow; row++) {
+		const text = frame.highlight(row, 1, void 0, ctx);
+		if (text !== void 0) lines.push(text);
+	}
+	const last = frame.highlight(lastRow, 1, lastRow === end.row ? end.col : void 0, ctx);
+	if (last !== void 0) lines.push(last);
+	return lines;
+}
+//#endregion
+//#region src/renderer/stream.ts
+/**
+* Stream surface — append-only list of nodes that render into the bottom
+* of the terminal's scroll region and commit to scrollback as newer
+* content arrives.
+*
+* We keep previously-appended nodes in `#state` as long as any of their
+* rows are still on-screen, so `rows` (the getter) can report the full
+* visible slice, and so the overlay surface can reconstruct what was
+* underneath it. Only the current tail is `live` — committed nodes are
+* frozen.
+*
+* Scrollback commits happen via `\n` at `scrollBottom`: the only
+* guaranteed-portable way to move a row into scrollback (xterm.js and
+* ghostty-web's WASM parser both ignore `CSI S` for scrollback
+* promotion). So growth of the stream always flows through the bottom
+* row with a `\n`-prefix write per new row.
+*/
+function findFrozenPrefixEnd(rendered, frozen) {
+	if (frozen.length === 0) return 0;
+	for (let start = 0; start <= rendered.length - frozen.length; start++) {
+		let match = true;
+		for (let i = 0; i < frozen.length; i++) if (rendered[start + i] !== frozen[i]) {
+			match = false;
+			break;
+		}
+		if (match) return start + frozen.length;
+	}
+	return frozen.length;
+}
+const SCROLL_DURATION = 120;
+var Stream = class extends Surface {
+	type = "stream";
+	#state = [];
+	#snapshot = {
+		bottom: 0,
+		historyLength: 0,
+		rows: [],
+		scrollTop: 0,
+		top: 1,
+		virtual: false,
+		visible: []
+	};
+	#opts;
+	#scrollback = [];
+	/** 0 = follow live bottom; otherwise 1-based top row inside history. */
+	#scrollTop = 0;
+	#scrollAnim;
+	constructor(renderer, opts = {}) {
+		super(renderer);
+		this.#opts = {
+			fixedFooterHeight: opts.fixedFooterHeight ?? 0,
+			maxLive: opts.maxLive ?? 3
+		};
+		this.emitScroll = throttle(this.emitScroll.bind(this), 1e3 / 60);
+	}
+	get bounds() {
+		return {
+			bottom: this.terminal.scrollBottom,
+			top: 1
+		};
+	}
+	get terminal() {
+		return this.$r.terminal;
+	}
+	/**
+	* Append `node` as the new live tail. The previous tail is frozen —
+	* it stops receiving re-renders even if its state mutates.
+	*
+	* Function form: `append(() => node)` runs the function inside a
+	* fresh Owner scope (so `signal` / `effect` / `onCleanup` /
+	* `provideContext` inside `fn` attach to that scope) and appends the
+	* returned Node. The Owner disposes when the Node unmounts.
+	*/
+	append(node) {
+		const boundary = createSuspenseBoundary();
+		const resolved = withOwner(this.$r.rootOwner, () => createNode(() => {
+			provideContext(SuspenseContext, boundary);
+			return node();
+		}));
+		const invalidate = () => {
+			state.dirty = true;
+			this.invalidate();
+		};
+		const state = {
+			boundary,
+			commit: 0,
+			dirty: true,
+			freeze: () => {
+				if (state.node.mounted) state.node.unmount();
+				state.node.off("invalidate", invalidate);
+			},
+			get live() {
+				return this.boundary.active() || this.dirty || !!this.node.state.sticky;
+			},
+			node: resolved
+		};
+		this.#state.push(state);
+		const ctx = this.mountCtx;
+		if (this.running && ctx) resolved.mount(ctx);
+		resolved.on("invalidate", invalidate);
+		this.invalidate();
+		return resolved;
+	}
+	/** How many rows the live region may occupy. */
+	get liveHeight() {
+		return this.terminal.scrollBottom;
+	}
+	/** Tracked nodes (oldest first). Used by renderer traversals. */
+	get nodes() {
+		return this.#state.map((s) => s.node);
+	}
+	async waitIdle() {
+		if (!this.pending) return;
+		await new Promise((resolve) => this.once("idle", resolve));
+	}
+	/**
+	* Rows currently painted in the live region, top-to-bottom. Bottom
+	* of the returned array aligns with `terminal.scrollBottom`. Exposed
+	* so the overlay surface can restore what it drew over.
+	*/
+	get rows() {
+		return this.#snapshot.visible;
+	}
+	getRow(row) {
+		return this.#snapshot.rows[row - 1];
+	}
+	fromScreen(point) {
+		const { top, visible, scrollTop } = this.#snapshot;
+		if (point.row < top || point.row >= top + visible.length) return;
+		return {
+			col: point.col,
+			row: scrollTop + point.row - top
+		};
+	}
+	toScreen(point) {
+		const { top, scrollTop } = this.#snapshot;
+		const offset = point.row - scrollTop;
+		return {
+			col: point.col,
+			row: top + offset
+		};
+	}
+	get #historyLength() {
+		return this.#snapshot.historyLength;
+	}
+	emitScroll() {
+		setImmediate(() => {
+			this.emit("scroll", {
+				below: this.#scrollTop === 0 ? 0 : this.#historyLength - this.#scrollTop - this.liveHeight + 1,
+				offset: this.#scrollTop === 0 ? this.#historyLength : this.#scrollTop,
+				total: this.#historyLength
+			});
+		});
+	}
+	scroll(lines = .5) {
+		const amount = Math.trunc(Math.abs(lines) < 1 ? lines * this.liveHeight : lines);
+		if (amount === 0) return Promise.resolve();
+		const total = this.#historyLength;
+		const maxTop = Math.max(1, total - this.liveHeight + 1);
+		const current = this.#scrollTop === 0 ? maxTop : this.#scrollTop;
+		const target = Math.max(1, Math.min(maxTop, current + amount));
+		if (target === current) return Promise.resolve();
+		this.#scrollAnim?.cancel();
+		const ret = Promise.withResolvers();
+		const delta = Math.abs(target - current);
+		const dir = Math.sign(target - current);
+		const stepTime = Math.max(8, Math.min(16, SCROLL_DURATION / delta));
+		const stepAmount = Math.max(1, Math.ceil(delta / Math.ceil(SCROLL_DURATION / stepTime)));
+		const tick = () => {
+			const lastTop = Math.max(1, this.#historyLength - this.liveHeight + 1);
+			const top = this.#scrollTop === 0 ? lastTop : this.#scrollTop;
+			const remaining = Math.abs(target - top);
+			if (remaining === 0) {
+				this.#scrollTop = target >= lastTop ? 0 : target;
+				this.emitScroll();
+				ret.resolve();
+				this.#scrollAnim = void 0;
+				return;
+			}
+			const next = top + dir * Math.min(stepAmount, remaining);
+			this.#scrollTop = next >= lastTop ? 0 : next;
+			this.emitScroll();
+			this.invalidate();
+			const t = setTimeout(tick, stepTime);
+			t.unref();
+			this.#scrollAnim = { cancel: () => {
+				clearTimeout(t);
+				ret.resolve();
+				this.#scrollAnim = void 0;
+			} };
+		};
+		tick();
+		return ret.promise;
+	}
+	async scrollBottom() {
+		if (this.#scrollTop === 0) return;
+		await this.scroll(Math.max(1, this.#historyLength - this.liveHeight + 1));
+		if (this.#scrollTop === 0) return;
+		if (this.#scrollAnim) return;
+		this.#scrollTop = 0;
+		this.emitScroll();
+		this.invalidate();
+	}
+	scrollTop() {
+		return this.scroll(-this.#historyLength + 1);
+	}
+	scrollUp(lines = .5) {
+		return this.scroll(-lines);
+	}
+	scrollDown(lines = .5) {
+		return this.scroll(lines);
+	}
+	async #render() {
+		const ctx = this.$r.ctx;
+		await Promise.all(this.#state.map(async (s) => {
+			const prev = s.rows ?? [];
+			const len = prev.length;
+			const frozen = prev.slice(0, s.commit);
+			s.dirty = false;
+			const rendered = await s.node.render(ctx);
+			const mutableStart = s.commit === 0 ? 0 : findFrozenPrefixEnd(rendered, frozen);
+			s.rows = [...frozen, ...rendered.slice(mutableStart)];
+			if (s.rows.length < len) s.rows.push(...Array(len - s.rows.length).fill(""));
+		}));
+		await Promise.resolve();
+		const states = [];
+		const sticky = [];
+		for (const s of this.#state) if (s.node.state.sticky) sticky.push(s);
+		else states.push(s);
+		states.push(...sticky);
+		this.#state = [...states];
+		const rows = [];
+		let commitLimit;
+		for (const s of this.#state) {
+			if (commitLimit === void 0 && s.live) commitLimit = rows.length;
+			if (s.rows) rows.push(...s.rows);
+		}
+		return {
+			commitLimit: commitLimit ?? rows.length,
+			rows
+		};
+	}
+	async _render(frame) {
+		const { commitLimit, rows: allRows } = await this.#render();
+		const old = this.#snapshot;
+		const liveHeight = this.liveHeight;
+		const committed = this.#committedRows();
+		const commitThreshold = Math.max(1, this.terminal.rows - this.#opts.fixedFooterHeight);
+		const liveStart = Math.min(commitLimit, Math.max(committed, allRows.length - commitThreshold));
+		const commit = allRows.slice(committed, liveStart);
+		this.#scrollback.push(...commit);
+		const liveRows = allRows.slice(liveStart);
+		const historyLength = this.#scrollback.length + liveRows.length;
+		const maxTop = Math.max(1, historyLength - liveHeight + 1);
+		if (this.#scrollTop > maxTop) this.#scrollTop = 0;
+		let newVisible = liveRows.slice(-liveHeight);
+		const historyChanged = this.#historyLength !== historyLength;
+		let deleteImages;
+		if (this.#scrollTop > 0) {
+			if (historyChanged) this.emitScroll();
+			const start = this.#scrollTop - 1;
+			const sbl = this.#scrollback.length;
+			if (start >= sbl) newVisible = liveRows.slice(start - sbl, start - sbl + liveHeight);
+			else {
+				newVisible = this.#scrollback.slice(start, start + liveHeight);
+				if (newVisible.length < liveHeight) newVisible.push(...liveRows.slice(0, liveHeight - newVisible.length));
+			}
+		}
+		if (this.#scrollTop > 0 || this.terminal.altScreen) {
+			const kittyPlacements = bumpPlacements(newVisible);
+			if (kittyPlacements) {
+				newVisible = kittyPlacements.rows;
+				deleteImages = kittyPlacements.delete;
+			}
+		}
+		const next = {
+			bottom: liveHeight,
+			deleteVirtualPlacements: deleteImages,
+			historyLength,
+			rows: [...this.#scrollback, ...liveRows],
+			scrollTop: this.#scrollTop === 0 ? maxTop : this.#scrollTop,
+			top: liveHeight - newVisible.length + 1,
+			virtual: this.#scrollTop > 0,
+			visible: newVisible
+		};
+		const plan = {
+			commit,
+			frame,
+			next,
+			old
+		};
+		this.#paint(plan);
+		this.#snapshot = next;
+		this.#advanceCommits(commit.length);
+		this.#dropCommittedStates();
+		if (!this.pending) this.emit("idle");
+	}
+	#paint(plan) {
+		if (plan.old.deleteVirtualPlacements) plan.frame.queue((terminal) => terminal.write(plan.old.deleteVirtualPlacements()));
+		if (!this.terminal.altScreen) this.#commitToScrollback(plan);
+		this.#clearAboveVisible(plan);
+		this.#paintVirtualScroll(plan);
+		this.#paintVisible(plan);
+	}
+	#commitToScrollback(plan) {
+		let i = 0;
+		while (i < plan.commit.length) {
+			const batch = Math.min(plan.commit.length - i, plan.next.bottom);
+			for (let j = 0; j < batch; j++) {
+				const row = 1 + j;
+				const content = plan.commit[i + j];
+				plan.frame.set(row, content);
+			}
+			plan.frame.scrollUp(1, plan.next.bottom, batch, (terminal) => {
+				terminal.write(terminal.moveTo(plan.next.bottom, 1));
+				for (let j = 0; j < batch; j++) terminal.write("\n");
+			});
+			i += batch;
+		}
+	}
+	#clearAboveVisible(plan) {
+		const clearTop = plan.old.bottom !== plan.next.bottom ? Math.max(1, Math.min(plan.old.top, plan.next.top)) : 1;
+		for (let r = clearTop; r < plan.next.top; r++) {
+			if (r < 1 || r > plan.next.bottom) continue;
+			plan.frame.clear(r);
+		}
+	}
+	#paintVirtualScroll(plan) {
+		if (plan.commit.length > 0) return;
+		if (!plan.old.virtual || !plan.next.virtual) return;
+		if (plan.old.bottom !== plan.next.bottom) return;
+		if (plan.old.visible.length !== plan.next.visible.length) return;
+		if (plan.next.visible.length === 0) return;
+		const delta = plan.next.scrollTop - plan.old.scrollTop;
+		const lines = Math.abs(delta);
+		if (lines === 0 || lines >= plan.next.visible.length) return;
+		if (delta > 0) plan.frame.scrollUp(1, plan.next.bottom, lines, (terminal) => {
+			terminal.write(terminal.scrollUp(lines));
+		});
+		else plan.frame.scrollDown(1, plan.next.bottom, lines, (terminal) => {
+			terminal.write(terminal.scrollDown(lines));
+		});
+	}
+	#paintVisible(plan) {
+		for (let k = 0; k < plan.next.visible.length; k++) {
+			const row = plan.next.top + k;
+			plan.frame.set(row, plan.next.visible[k]);
+		}
+	}
+	#advanceCommits(commitCount) {
+		let remaining = commitCount;
+		for (const s of this.#state) {
+			if (remaining <= 0) break;
+			const len = s.rows?.length ?? 0;
+			const n = Math.min(remaining, Math.max(0, len - s.commit));
+			s.commit += n;
+			remaining -= n;
+		}
+	}
+	#dropCommittedStates() {
+		while (this.#state.length > 0) {
+			const first = this.#state[0];
+			const len = first.rows?.length ?? 0;
+			if (first.live || first.commit < len) break;
+			this.#state.shift();
+			first.freeze();
+		}
+	}
+	#committedRows() {
+		return this.#state.reduce((sum, s) => sum + s.commit, 0);
+	}
+	get pending() {
+		return this.active;
+	}
+	get active() {
+		return this.#state.some((s) => s.boundary.active());
+	}
+	/**
+	* Terminal was resized. Forget only the paint mirror that mapped stream
+	* rows onto the old screen geometry. App scrollback and per-state commit
+	* boundaries are preserved; retained nodes re-render at the new width
+	* through Node.render()'s cache key.
+	*
+	* Paired with a screen-clear in the Renderer's resize handler — this
+	* method only resets our mirror of what's on screen; the actual wipe
+	* and re-establishment of DECSTBM lives in the terminal-level handler.
+	*/
+	onResize() {
+		this.resetPaint();
+	}
+	resetPaint() {
+		this.#snapshot = {
+			...this.#snapshot,
+			bottom: this.terminal.scrollBottom,
+			rows: [],
+			scrollTop: 0,
+			top: 1,
+			virtual: false,
+			visible: []
+		};
+		this.#scrollAnim?.cancel();
+		this.invalidate();
+	}
+	reset(opts = {}) {
+		this.resetPaint();
+		this.#scrollback = [];
+		this.#snapshot.historyLength = 0;
+		this.#scrollTop = 0;
+		for (const s of this.#state) s.commit = 0;
+		if (!opts.keepNodes) {
+			for (const s of this.#state) s.freeze();
+			this.#state = [];
+		}
+	}
+	mountAll(ctx) {
+		for (const s of this.#state) if (!s.node.mounted) s.node.mount(ctx);
+	}
+	unmountAll() {
+		for (const s of this.#state) if (s.node.mounted) s.node.unmount();
+	}
+};
+//#endregion
+//#region src/renderer/terminal.ts
+/**
+* Terminal primitive — owns stdin raw mode, stdout writes, and the
+* standard set of control modes we flip for a direct-mode renderer:
+* hide cursor, DECAWM off, DECSTBM scroll region, synchronized output.
+*
+* No rendering logic lives here; upstream surfaces (stream, ui) push
+* escape sequences through the helpers exposed below.
+*/
+const progressStates = {
+	inactive: 0,
+	progress: 1,
+	error: 2,
+	loading: 3,
+	paused: 4
+};
+const CSI = "\x1B[";
+const ST = "\x1B\\";
+/** @internal */
+var Terminal = class {
+	#stdout;
+	#stdin;
+	#altScreen;
+	#hookSignals;
+	#started = false;
+	#reserveBottom;
+	#mouse = false;
+	#progress = { type: "inactive" };
+	#progressInterval;
+	#prevRawMode;
+	#resizeListeners = /* @__PURE__ */ new Set();
+	#signalCleanup;
+	#onResize = () => {
+		for (const l of this.#resizeListeners) l(this.cols, this.rows);
+	};
+	constructor(opts = {}) {
+		this.#stdout = opts.stdout ?? process.stdout;
+		this.#stdin = opts.stdin ?? process.stdin;
+		this.#reserveBottom = opts.reserveBottom ?? 0;
+		this.#altScreen = opts.altScreen ?? false;
+		this.#hookSignals = opts.hookSignals ?? true;
+		this.#mouse = opts.mouse ?? false;
+	}
+	/** Current terminal columns (number of cells wide). */
+	get cols() {
+		return this.#stdout.columns || 80;
+	}
+	/** Current terminal rows (number of cells tall). */
+	get rows() {
+		return this.#stdout.rows || 24;
+	}
+	/** Rows reserved at the bottom for the footer. */
+	get reserveBottom() {
+		return this.#reserveBottom;
+	}
+	/** Bottom row of the scroll region (1-based, inclusive). */
+	get scrollBottom() {
+		return Math.max(1, this.rows - this.#reserveBottom);
+	}
+	/** Top row of the footer (1-based, inclusive). 0 when no footer. */
+	get footerTop() {
+		return this.#reserveBottom > 0 ? this.rows - this.#reserveBottom + 1 : 0;
+	}
+	get altScreen() {
+		return this.#altScreen;
+	}
+	get mouse() {
+		return this.#mouse;
+	}
+	set mouse(mouse) {
+		if (this.#mouse === mouse) return;
+		this.#mouse = mouse;
+		if (!this.#started) return;
+		this.write(mouse ? `${CSI}?1002h${CSI}?1006h${CSI}?1007h` : `${CSI}?1007l${CSI}?1006l${CSI}?1002l`);
+	}
+	/**
+	* Install control-mode state: hide cursor, DECAWM off, DECSTBM scroll
+	* region, stdin raw mode, SIGWINCH + SIGINT/SIGTERM hooks.
+	*/
+	start() {
+		if (this.#started) return;
+		this.#started = true;
+		this.#writeProgress("progress", 0);
+		this.#writeProgress("inactive");
+		if (this.#altScreen) this.write(`${CSI}?1049h`);
+		this.write(`${CSI}?25l${CSI}?7l${CSI}?2004h${CSI}?1004h`);
+		if (this.#mouse) this.write(`${CSI}?1002h${CSI}?1006h${CSI}?1007h`);
+		this.#writeProgress();
+		if (this.#reserveBottom > 0) this.setScrollRegion(1, this.scrollBottom);
+		if (this.#stdin?.isTTY && typeof this.#stdin.setRawMode === "function") {
+			this.#prevRawMode = Boolean(this.#stdin.isRaw);
+			this.#stdin.setRawMode(true);
+		}
+		process.on("SIGWINCH", this.#onResize);
+		if (this.#hookSignals) {
+			const bye = () => {
+				this.stop();
+				process.exit(0);
+			};
+			const onCrash = (err) => {
+				this.stop();
+				const insp = process.versions.bun ? Bun.inspect : inspect;
+				process.stdout.write("", () => {
+					process.stdout.write(insp(err, { colors: true }));
+				});
+			};
+			process.once("uncaughtException", onCrash);
+			process.once("SIGINT", bye);
+			process.once("SIGTERM", bye);
+			const onExit = () => this.stop();
+			process.once("exit", onExit);
+			this.#signalCleanup = () => {
+				process.off("SIGINT", bye);
+				process.off("SIGTERM", bye);
+				process.off("exit", onExit);
+				process.off("uncaughtException", onCrash);
+			};
+		}
+	}
+	deleteImages(opts = {}) {
+		if (!this.#started) return;
+		this.write(`\x1b_Ga=d,d=${opts.data ?? true ? "A" : "a"},q=2\x1b\\`);
+	}
+	/** Restore terminal modes, detach listeners. Idempotent. */
+	stop() {
+		if (!this.#started) return;
+		try {
+			this.deleteImages();
+			this.setProgress();
+			if (this.#reserveBottom > 0) this.clearScrollRegion();
+			this.write(`${CSI}?1007l${CSI}?1006l${CSI}?1002l${CSI}?1000l${CSI}?1004l${CSI}?2004l${CSI}?7h${CSI}?25h`);
+			if (this.#altScreen) this.write(`${CSI}?1049l`);
+		} finally {
+			this.#started = false;
+		}
+		if (this.#stdin?.isTTY && typeof this.#stdin.setRawMode === "function") {
+			this.#stdin.setRawMode(this.#prevRawMode ?? false);
+			this.#stdin.pause?.();
+		}
+		process.off("SIGWINCH", this.#onResize);
+		this.#signalCleanup?.();
+		this.#signalCleanup = void 0;
+	}
+	setProgress(state, value) {
+		state ??= "inactive";
+		const resetError = () => {
+			this.#writeProgress("progress", 50);
+			this.#writeProgress("loading");
+		};
+		if (this.#progress.type === "error" && state !== "error") resetError();
+		if (state === "progress") this.#progress = {
+			type: "progress",
+			value: value ?? 0
+		};
+		else if (state === "error" || state === "paused") this.#progress = {
+			type: state,
+			value: value ?? this.#progress.value
+		};
+		else this.#progress = { type: state };
+		this.#writeProgress();
+		if (state === "inactive") {
+			if (this.#progressInterval) clearInterval(this.#progressInterval);
+			this.#progressInterval = void 0;
+		} else if (!this.#progressInterval) {
+			this.#progressInterval = setInterval(() => this.#writeProgress(), 100);
+			this.#progressInterval.unref();
+		}
+	}
+	#writeProgress(state, value) {
+		if (!this.#started) return;
+		value ??= this.#progress.value === void 0 ? void 0 : Math.max(0, Math.min(100, Math.round(this.#progress.value)));
+		const seq = `\x1b]9;4;${progressStates[state ?? this.#progress.type]}${typeof value === "number" ? `;${value}` : ""}${ST}`;
+		this.write(seq);
+	}
+	/** Change the bottom reservation and re-apply the scroll region. */
+	setReserveBottom(rows) {
+		const next = Math.max(0, Math.min(rows, this.rows - 1));
+		if (next === this.#reserveBottom) return;
+		this.#reserveBottom = next;
+		if (!this.#started) return;
+		if (next > 0) this.setScrollRegion(1, this.scrollBottom);
+		else this.clearScrollRegion();
+	}
+	/** Low-level write. Use escape helpers + this to emit sequences. */
+	write(s) {
+		if (!this.#started) return;
+		this.#stdout.write(s);
+	}
+	#write(s) {
+		this.#stdout.write(s);
+	}
+	#pendingTransmits = [];
+	/** Queue a side-channel ANSI payload (KGP transmit, etc.) for the
+	*  next `flushTransmits()`. No-op for empty strings. */
+	enqueueTransmit(seq) {
+		if (seq) this.#pendingTransmits.push(seq);
+	}
+	/** Drain the transmit queue. Called by the renderer at the start of
+	*  each paint, before frame composition. Idempotent when empty. */
+	flushTransmits() {
+		if (this.#pendingTransmits.length === 0) return;
+		this.#stdout.write(this.#pendingTransmits.join(""));
+		this.#pendingTransmits.length = 0;
+	}
+	/** Absolute cursor move (1-based). */
+	moveTo(row, col = 1) {
+		return `${CSI}${row};${col}H`;
+	}
+	/** Erase the entire line the cursor is on. */
+	clearLine() {
+		return `${CSI}2K`;
+	}
+	/** Clear from cursor to end of screen. */
+	clearBelow() {
+		return `${CSI}0J`;
+	}
+	/** Scroll the scroll region up by `n` rows (SU). Top rows enter scrollback. */
+	scrollUp(n) {
+		return n > 0 ? `${CSI}${n}S` : "";
+	}
+	/**
+	* Scroll the scroll region down by `n` rows (SD). Top `n` rows become
+	* blank, existing content shifts down, bottom `n` rows fall off the
+	* region (they don't move to scrollback — scrollback is a top-side
+	* concept; SD's displaced rows are simply lost).
+	*/
+	scrollDown(n) {
+		return n > 0 ? `${CSI}${n}T` : "";
+	}
+	/** Delete `n` lines at the cursor, pulling content below upward (DL). */
+	deleteLines(n) {
+		return n > 0 ? `${CSI}${n}M` : "";
+	}
+	/** Set the scroll region (DECSTBM), 1-based inclusive. */
+	setScrollRegion(top, bottom) {
+		this.write(`${CSI}${top};${bottom}r`);
+	}
+	/** Reset to the full-viewport scroll region. */
+	clearScrollRegion() {
+		this.write(`${CSI}r`);
+	}
+	/**
+	* Wrap a block of writes in begin/end-synchronized-update. Supporting
+	* terminals buffer the enclosed bytes and paint atomically — eliminates
+	* flicker on multi-row diff rewrites. Unsupported terminals ignore
+	* both escapes, so there's no downside.
+	*/
+	sync(fn) {
+		if (!this.#started) return;
+		this.write(`${CSI}?2026h`);
+		try {
+			fn();
+		} finally {
+			this.#write(`${CSI}?2026l`);
+		}
+	}
+	onResize(fn) {
+		this.#resizeListeners.add(fn);
+		return () => this.#resizeListeners.delete(fn);
+	}
+};
+//#endregion
+//#region src/renderer/ui.ts
+/**
+* UI surface — the sticky footer. Renders a single Box tree at the
+* bottom of the terminal, inside the rows reserved by `Terminal`'s
+* scroll region. Row-diff redraws: only changed rows are rewritten on
+* each flush, so an input widget re-rendering every keystroke doesn't
+* repaint the entire footer.
+*
+* Height is determined by the root's rendered row count, capped to a
+* sensible upper bound so a runaway render can't take over the screen.
+* When the height changes the terminal's reserved bottom gets updated,
+* which rewrites `DECSTBM`; the stream surface then has less/more room
+* and its next flush naturally fills the new geometry.
+*/
+var UI = class extends Surface {
+	type = "ui";
+	#root = box({ flexDirection: "column" });
+	#rows = [];
+	constructor(renderer) {
+		super(renderer);
+		this.#root.on("invalidate", this.invalidate);
+	}
+	/** The footer's root Box. Add children via `ui.root.add(child)`. */
+	get root() {
+		return this.#root;
+	}
+	get terminal() {
+		return this.$r.terminal;
+	}
+	/** Shortcut: add a child to the footer root. Same semantics as
+	*  `ui.root.add(child)`; returns `this` for chaining.
+	*
+	*  Function form: `add(() => box(…))` runs the function inside a
+	*  fresh Owner scope (so `signal` / `effect` / `onCleanup` /
+	*  `provideContext` inside `fn` attach to that scope) and adds the
+	*  returned Node. The Owner disposes when the Node unmounts. */
+	add(child) {
+		const ret = withOwner(this.$r.rootOwner, () => createNode(child));
+		this.#root.add(ret);
+		return ret;
+	}
+	/** Current rendered height (rows). */
+	get height() {
+		return this.#rows.length;
+	}
+	/**
+	* The rows currently painted into the footer region, in order from the
+	* top of the reserved area downward. Exposed so the overlay surface
+	* can re-emit this content after it tears down, without re-rendering
+	* the tree.
+	*/
+	get rows() {
+		return this.#rows;
+	}
+	/**
+	* Render the footer tree and paint the diff against the last paint.
+	* Updates the terminal's reservation whenever the height changes so
+	* the scroll region stays correctly sized.
+	*
+	* When called from `Renderer.render()`, a capture-style `sync` is
+	* provided so all surfaces paint inside one atomic sync frame. Direct
+	* callers (tests) omit it and get an immediate `terminal.sync`.
+	*/
+	async _render(frame) {
+		const ctx = this.$r.ctx;
+		const rendered = await this.#root.render({
+			...ctx,
+			width: this.terminal.cols
+		});
+		const visible = Math.max(0, this.terminal.rows - 1);
+		const rows = rendered.length > visible ? rendered.slice(-visible) : rendered;
+		const prevHeight = this.#rows.length;
+		const nextHeight = rows.length;
+		if (nextHeight !== this.terminal.reserveBottom) {
+			frame.flush();
+			frame.queue((terminal) => terminal.setReserveBottom(nextHeight));
+			this.$r.stream.invalidate();
+		}
+		const top = this.terminal.rows - nextHeight + 1;
+		const prevTop = this.terminal.rows - prevHeight + 1;
+		for (let row = prevTop; row < top; row++) frame.clear(row);
+		for (let i = 0; i < nextHeight; i++) frame.set(top + i, rows[i]);
+		this.#rows = rows;
+	}
+	/**
+	* Terminal was resized. Drop the painted-rows mirror so the next
+	* render's grow/shrink math treats the footer as if it's just
+	* appearing — correct after a screen clear, when the terminal no
+	* longer holds any footer bytes. The scroll region gets re-established
+	* through the normal `setReserveBottom` path inside `render()`.
+	*/
+	onResize() {
+		this.#rows = [];
+		this.invalidate();
+	}
+	/** UI's tracked node set is just the footer root. */
+	get nodes() {
+		return [this.#root];
+	}
+	mountAll(ctx) {
+		if (!this.#root.mounted) this.#root.mount(ctx);
+	}
+	unmountAll() {
+		if (this.#root.mounted) this.#root.unmount();
+	}
+	get bounds() {
+		const top = this.terminal.footerTop || this.terminal.rows + 1;
+		return {
+			bottom: this.terminal.rows,
+			top
+		};
+	}
+};
+//#endregion
+//#region src/renderer/renderer.ts
+var RenderStats = class {
+	#stats = {};
+	/** Increment a stat by `delta` (default: `1`). */
+	inc(stat, delta = 1) {
+		this.#stats[stat] = (this.#stats[stat] ?? 0) + delta;
+	}
+	set(stat, value) {
+		this.#stats[stat] = value;
+	}
+	get() {
+		return { ...this.#stats };
+	}
+};
+/**
+* Wires a `Terminal` primitive with the `Stream` and `UI` surfaces.
+* Doesn't render anything until you either append to `renderer.stream`
+* or add children to `renderer.ui.root`.
+*
+* ```ts
+* const renderer = new Renderer()
+* renderer.start()
+* renderer.stream.append(text("hello"))
+* renderer.ui.root.add(input({ placeholder: "> " }))
+* // ... later
+* renderer.stop()
+* ```
+*/
+var Renderer = class extends Emitter {
+	stream;
+	ui;
+	overlay;
+	selection;
+	terminal;
+	input;
+	frame;
+	/** Always-on logger, auto-attached to `this.stream`. Calling
+	*  `renderer.log("msg")` logs at `"log"` level; level methods
+	*  (`renderer.log.error(...)` etc.) are also available. */
+	logger;
+	#decoder = new Decoder();
+	#stdin;
+	#theme = signal(void 0);
+	/** Root Owner — every surface's function-shape `add` / `append` runs
+	*  its child under this Owner via `withOwner(#rootOwner, …)`, so
+	*  context values provided here (`RenderContext`, future global
+	*  scopes) are visible to every widget body in the tree. */
+	#rootOwner;
+	#running = false;
+	#escTimer;
+	#rendering;
+	#dirty = false;
+	#debug = false;
+	/** Monotonic cache-key for `RenderCtx`. Bumped on any event that
+	*  invalidates every node cache in the tree (resize, theme swap). */
+	#ctxVersion = 0;
+	#ctx;
+	queries;
+	/** Runtime action registry (catalog + dispatcher). Populated with
+	*  `defaultActions` + `globalActions` at construction; apps extend
+	*  via `renderer.actions.register({ "app.foo": { ... } })`. */
+	actions;
+	stats = new RenderStats();
+	/** Global action impls. Merged into the `actions` catalog on
+	*  construction so the ids declared here gain their keys and desc
+	*  from `defaultActions`. Using `satisfies` (rather than an explicit
+	*  type annotation) keeps the literal keys so `BuiltinAction` can
+	*  pull them out. */
+	globalActions = { "global.quit": { fn: () => {
+		this.stop();
+		process.exit(0);
+	} } };
+	constructor(opts = {}) {
+		super();
+		this.terminal = new Terminal({
+			altScreen: opts.altScreen,
+			hookSignals: opts.hookSignals,
+			mouse: opts.mouse,
+			stdin: opts.stdin,
+			stdout: opts.stdout
+		});
+		this.frame = new Frame(this.terminal);
+		if (opts.theme) this.#theme.set(opts.theme);
+		this.ui = new UI(this);
+		this.stream = new Stream(this, { fixedFooterHeight: opts.fixedFooterHeight });
+		this.overlay = new OverlaySurface(this);
+		this.selection = new SelectionLayer(this);
+		this.logger = opts.logger ?? new Logger({ name: "renderer" });
+		this.input = new InputRouter(this.logger.child({ name: "input" }));
+		this.queries = new TerminalQueries(this.input, this.terminal);
+		this.actions = new Actions(this.logger.child({ name: "actions" }));
+		this.#rootOwner = createRoot(() => {
+			provideContext(RenderContext, {
+				images: memo(() => unwrap(opts.images) ?? true),
+				queries: this.queries,
+				style: memo(() => styleBuilder(this.#theme.get())),
+				theme: this.#theme.get
+			});
+			return useActiveOwner();
+		});
+		const reporter = new TuiReporter(opts.reporter);
+		reporter.attach({ append: (node) => this.stream.append(node) });
+		this.logger.attach("tui", reporter);
+		this.actions.setTargetResolver(() => this.input.focused);
+		this.input.setActions(this.actions);
+		this.input.on("mouse", ({ event }) => {
+			if (event.kind === "scroll") this.stream.scroll(event.deltaY);
+			else this.selection.mouse(event);
+		});
+		this.input.on("key", ({ event }) => {
+			if (event.name === "esc") this.selection.clear();
+		});
+		this.actions.register(defaultActions, { default: true });
+		this.actions.register(this.globalActions, { default: true });
+		this.on("dirty", () => untrack(() => this.#schedule()));
+		this.terminal.onResize(() => {
+			this.#ctxVersion++;
+			this.#ctx = void 0;
+			this.terminal.sync(() => {
+				this.terminal.clearScrollRegion();
+				this.terminal.write(`${this.terminal.moveTo(1, 1)}\x1b[2J`);
+				if (this.terminal.reserveBottom > 0) this.terminal.setScrollRegion(1, this.terminal.scrollBottom);
+			});
+			this.frame.reset();
+			this.stream.onResize();
+			this.ui.onResize();
+		});
+		this.#stdin = opts.stdin ?? process.stdin;
+	}
+	/**
+	* Shared `RenderCtx` for the current tick. Built on demand and
+	* reused across every `Node.render(ctx)` call until the version
+	* bumps (resize, theme swap). Nodes compare `ctx.version` against
+	* their cached row's version — simple integer check, no hashing.
+	*/
+	get ctx() {
+		if (this.#ctx === void 0 || this.#ctx.version !== this.#ctxVersion || this.#ctx.width !== this.terminal.cols) this.#ctx = createCtx({
+			theme: peek(this.#theme.get),
+			transmit: (seq) => this.terminal.enqueueTransmit(seq),
+			version: this.#ctxVersion,
+			width: this.terminal.cols
+		});
+		return this.#ctx;
+	}
+	get rootOwner() {
+		return this.#rootOwner;
+	}
+	get mouse() {
+		return this.terminal.mouse;
+	}
+	set mouse(mouse) {
+		this.terminal.mouse = mouse;
+	}
+	get debug() {
+		return this.#debug;
+	}
+	set debug(debug) {
+		if (this.#debug === debug) return;
+		this.#debug = debug;
+		this.#schedule();
+	}
+	/** Whether the renderer is currently running. Surfaces use this to
+	*  decide whether a fresh append/open should immediately mount the
+	*  node or just queue it for the next `start()`. */
+	get running() {
+		return this.#running;
+	}
+	/** Shortcut for `renderer.input.bind(pattern, handler)`. Returns an
+	*  unsubscribe function. Use for one-off app-level bindings where a
+	*  named action would be overkill. */
+	bind = (binding) => this.actions.bind(binding);
+	/** Swap the ambient theme. Widgets that read `theme()` / `style()`
+	*  from `useContext(RenderContext)` re-fire automatically; primitive
+	*  Nodes that compare cache against `ctx.version` need the version
+	*  bump that already happens elsewhere on theme-driven invalidation. */
+	set theme(theme) {
+		this.#theme.set(theme);
+		this.#ctxVersion++;
+		this.stream.invalidate();
+		this.ui.invalidate();
+		this.overlay.invalidate();
+		this.#schedule();
+	}
+	/** Get the current theme. (tracked) */
+	get theme() {
+		return this.#theme.get() ?? defaultTheme;
+	}
+	start() {
+		if (this.#running) return;
+		this.#running = true;
+		this.terminal.start();
+		this.#stdin.setEncoding?.("utf8");
+		this.#stdin.on("data", this.#onData);
+		this.#stdin.resume?.();
+		this.emit("start");
+		if (this.#dirty) this.#schedule();
+		process.on("unhandledRejection", (reason) => this.logger.child("unhandledRejection").error("Unhandled Rejection:", reason));
+	}
+	stop() {
+		if (!this.#running) return;
+		this.emit("stop");
+		this.#running = false;
+		this.#stdin.off("data", this.#onData);
+		this.#stdin.pause?.();
+		if (this.#escTimer !== void 0) {
+			clearTimeout(this.#escTimer);
+			this.#escTimer = void 0;
+		}
+		this.terminal.stop();
+	}
+	/** Look up a node by its `id`. Returns `undefined` if nothing matches. */
+	getNode(id) {
+		let found;
+		this.walk((n) => {
+			if (n.id() !== id) return void 0;
+			found = n;
+			return "stop";
+		});
+		return found;
+	}
+	/**
+	* Find every node matching a predicate. When passed a string, it's
+	* interpreted as `node.type === string` — the common "find all
+	* Inputs" case. For anything richer, pass a function.
+	*/
+	findNode(match) {
+		const pred = typeof match === "string" ? (n) => n.type === match : match;
+		const out = [];
+		this.walk((n) => {
+			if (pred(n)) out.push(n);
+		});
+		return out;
+	}
+	/**
+	* Walk every node in the combined stream + UI tree, depth-first,
+	* parents before children. Return `"stop"` from the visitor to halt.
+	*/
+	walk(visit) {
+		const stopped = { v: false };
+		const visitNode = (n) => {
+			if (stopped.v) return;
+			if (visit(n) === "stop") {
+				stopped.v = true;
+				return;
+			}
+			for (const c of n.children) visitNode(c);
+		};
+		visitNode(this.ui.root);
+		for (const n of this.stream.nodes) visitNode(n);
+		for (const n of this.overlay.nodes) visitNode(n);
+	}
+	/** Build a MountCtx for a given surface. Each call creates a fresh
+	*  object but closes over the same underlying services, so nodes
+	*  across surfaces share a single overlay surface, router, etc. */
+	mountCtx(surface) {
+		const logger = this.logger.child({
+			name: surface,
+			surface
+		});
+		const input = this.input;
+		return {
+			actions: this.actions,
+			findNode: (m) => this.findNode(m),
+			getNode: (id) => this.getNode(id),
+			input: {
+				bind: (binding) => this.actions.bind(binding),
+				blur: (node) => this.input.blur(node),
+				events: this.input,
+				focus: (node) => this.input.focus(node),
+				queries: this.queries,
+				get terminalFocus() {
+					return input.terminalFocus;
+				}
+			},
+			logger,
+			overlay: {
+				add: (o) => this.overlay.add(o),
+				remove: (o) => this.overlay.remove(o)
+			},
+			surface
+		};
+	}
+	/** Mark dirty and ensure the render loop is active. Cheap and
+	*  idempotent — synchronous invalidations within the same tick all
+	*  collapse into one paint via the microtask boundary at the top of
+	*  the loop. */
+	#schedule() {
+		this.#dirty = true;
+		if (!this.#running) return;
+		if (this.#rendering !== void 0) return;
+		this.#rendering = (async () => {
+			try {
+				await Promise.resolve();
+				while (this.#dirty && this.#running) {
+					this.#dirty = false;
+					try {
+						this.stats.inc("render");
+						await this.#render();
+					} catch (error) {
+						this.#running = false;
+						this.logger.child("render").error(error);
+						process.nextTick(() => {
+							throw error;
+						});
+						return;
+					}
+				}
+			} finally {
+				this.#rendering = void 0;
+			}
+		})();
+	}
+	/** Force a paint if dirty, and wait until the loop is idle. Useful
+	*  for tests and external "redraw and tell me when done" flows.
+	*  Concurrent callers share the same in-flight promise — no extra
+	*  paints are queued. */
+	async render() {
+		if (!this.#running) return;
+		this.#schedule();
+		if (this.#rendering !== void 0) await this.#rendering;
+	}
+	/** Render dirty surfaces into a shared full-viewport frame, then flush
+	* queued terminal ops and final row diffs in one atomic terminal sync. */
+	async #render() {
+		const frame = this.frame.begin();
+		const render = async (surface) => {
+			if (!surface.dirty) return;
+			await surface.render(frame);
+		};
+		await render(this.stream);
+		await render(this.ui);
+		frame.commitBase();
+		this.selection.renderStream(frame, this.ctx);
+		await render(this.overlay);
+		if (this.#debug) this.#renderDebug(frame);
+		this.selection.renderScreen(frame, this.ctx);
+		this.terminal.flushTransmits();
+		this.terminal.sync(() => {
+			const s = frame.paint();
+			this.stats.inc("paint-ops", s.ops);
+			this.stats.inc("paint-rows", s.rows);
+		});
+	}
+	#renderDebug(frame) {
+		const stats = this.stats.get();
+		const rows = Object.entries(stats).toSorted(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}: ${value}`);
+		rows.unshift(`debug: ${(/* @__PURE__ */ new Date()).toLocaleTimeString()}`);
+		const width = Math.min(this.terminal.cols, Math.max(...rows.map((row) => stringWidth(row)), 0));
+		const x = Math.max(1, this.terminal.cols - width + 1);
+		for (let i = 0; i < rows.length && i < this.terminal.rows; i++) frame.overlay(i + 1, x, rows[i]);
+	}
+	#onData = (chunk) => {
+		const text = typeof chunk === "string" ? chunk : String(chunk);
+		for (const ev of this.#decoder.feed(text)) this.input.dispatch(ev);
+		if (this.#escTimer !== void 0) clearTimeout(this.#escTimer);
+		this.#escTimer = setTimeout(() => {
+			this.#escTimer = void 0;
+			for (const ev of this.#decoder.flush()) this.input.dispatch(ev);
+		}, 25);
+		this.#escTimer.unref();
+	};
+};
+//#endregion
+export { Renderer };
+
+//# sourceMappingURL=renderer-CxL4xbkl.mjs.map