silvery 0.21.1 → 0.23.0

package/dist/test.mjs

@@ -0,0 +1,2829 @@
+import { f as processMouseEvent, g as updateKeyboardModifiers, s as createMouseEventProcessor, v as pointInRect } from "./mouse-events-WQ2h-uqG.mjs";
+import { r as findActiveCursorRect, t as commitLayoutSnapshot } from "./layout-signals-CGYbHmxy.mjs";
+import { Ct as CursorProvider, Nt as createFocusManager, wt as createCursorStore } from "./src-DbqcSrhy.mjs";
+import { D as buildMismatchContext, F as compareBuffers, I as formatMismatch, O as formatMismatchContext, a as CLS_STRICT_SLUG, c as ScopeProvider, i as CLS_STRICT_MIN_TIER, n as toChainAppContextValue, o as UnexpectedLayoutShiftError, r as createClsMonitor, s as isClsStrictEnabled, t as createChildApp } from "./chain-bridge-CkYcMxlq.mjs";
+import { $t as bufferToText, Ct as isStrictEnabled, H as createTerm, Jt as EMPTY_FRAME_CELL, N as stripAnsi, Qt as bufferToStyledText, Zt as bufferToHTML, _n as splitRawInput, en as cellEquals, gt as outputPhase, hn as parseKey, ln as keyToAnsi, mn as parseHotkey, on as CODE_TO_KEY, tn as cellToFrameCell, un as keyToKittyAnsi, ut as parseBracketedPaste, vt as IncrementalRenderMismatchError, xt as preloadStrictTerminalBackends } from "./unicode-CxyxVGmB.mjs";
+import { O as warnOnce, _ as kittyDeleteAllScrimPlacements, ct as deriveTheme, tt as isProtocolError } from "./src-B8lf1kiR.mjs";
+import { a as releaseContainer, b as getRenderEpoch, d as reportDisposeError, i as reconciler, l as setContainerNodeLifecycle, n as createFiberRoot, r as getContainerRoot, t as createContainer, u as createScope, x as isAnyDirty } from "./reconciler--_-biN23.mjs";
+import { i as isLayoutEngineInitialized, o as setLayoutEngine, t as ensureDefaultLayoutEngine } from "./layout-engine-BgR58vL0.mjs";
+import { c as INSTRUMENT, d as assertBoundedConvergence, f as beginConvergenceLoop, g as notePassCommit, h as logPass, l as MAX_CONVERGENCE_PASSES, n as createRenderPostState, o as FRESH_LAYOUT_STRICT_SLUG, p as beginPass, s as markLayoutTreeDirty, t as createAg, v as recordPassRing } from "./ag-q9lRlKlt.mjs";
+import { c as StdoutContext, i as FocusManagerContext, l as TermContext, o as RuntimeContext, r as ChainAppContext } from "./context-CEhuD1R_.mjs";
+import { createLogger } from "loggily";
+import React from "react";
+import { writeFile } from "node:fs/promises";
+import { is } from "css-select";
+import { EventEmitter } from "node:events";
+import { createGhosttyBackend } from "@termless/ghostty";
+import { createGhosttyNativeBackend } from "@termless/ghostty-native";
+import { createXtermBackend } from "@termless/xtermjs";
+//#region packages/test/src/auto-locator.ts
+/**
+* Create an AutoLocator from a container getter function.
+* The getter is called fresh on each resolution.
+*/
+function createAutoLocator(getContainer, opts) {
+	return new AutoLocatorImpl(getContainer, [], void 0, opts?.strict ?? false);
+}
+/**
+* AutoLocator implementation
+*/
+var AutoLocatorImpl = class AutoLocatorImpl {
+	constructor(getContainer, predicates, indexSelector, strict = false) {
+		this.getContainer = getContainer;
+		this.predicates = predicates;
+		this.indexSelector = indexSelector;
+		this.strict = strict;
+	}
+	getByText(text) {
+		const predicate = (node) => {
+			const content = getNodeTextContent(node);
+			if (!content) return false;
+			if (node.type !== "silvery-text") return false;
+			if (node.isRawText && node.parent?.type === "silvery-text") return false;
+			if (typeof text === "string") return content.includes(text);
+			return text.test(content);
+		};
+		return new AutoLocatorImpl(this.getContainer, [...this.predicates, predicate], void 0, this.strict);
+	}
+	getByTestId(id) {
+		const predicate = (node) => {
+			return getNodeProp(node, "testID") === id;
+		};
+		return new AutoLocatorImpl(this.getContainer, [...this.predicates, predicate], void 0, this.strict);
+	}
+	locator(selector) {
+		const predicate = (node) => {
+			try {
+				return is(node, selector, cssSelectOptions);
+			} catch {
+				return false;
+			}
+		};
+		return new AutoLocatorImpl(this.getContainer, [...this.predicates, predicate], void 0, this.strict);
+	}
+	filter(optionsOrPredicate) {
+		let predicate;
+		if (typeof optionsOrPredicate === "function") predicate = optionsOrPredicate;
+		else {
+			const opts = optionsOrPredicate;
+			predicate = (node) => {
+				if (opts.hasText !== void 0) {
+					const content = getNodeTextContent(node);
+					if (typeof opts.hasText === "string") {
+						if (!content.includes(opts.hasText)) return false;
+					} else if (!opts.hasText.test(content)) return false;
+				}
+				if (opts.hasTestId !== void 0) {
+					if (getNodeProp(node, "testID") !== opts.hasTestId) return false;
+				}
+				if (opts.has !== void 0) {
+					const value = getNodeProp(node, opts.has.attr);
+					if (opts.has.value !== void 0) {
+						if (value !== opts.has.value) return false;
+					} else if (value === void 0) return false;
+				}
+				return true;
+			};
+		}
+		return new AutoLocatorImpl(this.getContainer, [...this.predicates, predicate], void 0, this.strict);
+	}
+	first() {
+		return new AutoLocatorImpl(this.getContainer, this.predicates, { type: "first" }, this.strict);
+	}
+	last() {
+		return new AutoLocatorImpl(this.getContainer, this.predicates, { type: "last" }, this.strict);
+	}
+	nth(index) {
+		return new AutoLocatorImpl(this.getContainer, this.predicates, {
+			type: "nth",
+			index
+		}, this.strict);
+	}
+	resolve() {
+		const nodes = this.resolveAll();
+		if (this.indexSelector) switch (this.indexSelector.type) {
+			case "first": return nodes[0] ?? null;
+			case "last": return nodes[nodes.length - 1] ?? null;
+			case "nth": return nodes[this.indexSelector.index ?? 0] ?? null;
+		}
+		if (this.strict && nodes.length > 1) throw new Error(`Locator resolved to ${nodes.length} elements. Use .first(), .nth(n), or a more specific selector. Matched types: ${nodes.slice(0, 3).map((n) => n.type).join(", ")}${nodes.length > 3 ? "..." : ""}`);
+		return nodes[0] ?? null;
+	}
+	resolveAll() {
+		const container = this.getContainer();
+		if (this.predicates.length === 0) return [container];
+		const matches = [];
+		walkTree(container, (node) => {
+			if (this.predicates.every((p) => p(node))) matches.push(node);
+		});
+		return matches;
+	}
+	count() {
+		return this.resolveAll().length;
+	}
+	textContent() {
+		const node = this.resolve();
+		if (!node) return "";
+		return getNodeTextContent(node);
+	}
+	getAttribute(name) {
+		const node = this.resolve();
+		if (!node) return void 0;
+		return getNodeProp(node, name);
+	}
+	boundingBox() {
+		const node = this.resolve();
+		if (!node) return null;
+		return node.scrollRect ?? null;
+	}
+	isVisible() {
+		const box = this.boundingBox();
+		if (!box) return false;
+		return box.width > 0 && box.height > 0;
+	}
+};
+/**
+* Walk tree depth-first, calling visitor for each node
+*/
+function walkTree(node, visitor) {
+	visitor(node);
+	for (const child of node.children) walkTree(child, visitor);
+}
+/**
+* Get text content of a node (concatenated from all text descendants)
+*/
+function getNodeTextContent(node) {
+	if (node.textContent !== void 0) return node.textContent;
+	return node.children.map(getNodeTextContent).join("");
+}
+/**
+* Get a prop value from node
+*/
+function getNodeProp(node, name) {
+	const value = node.props[name];
+	if (value === void 0 || value === null) return void 0;
+	return String(value);
+}
+/** Shared css-select options — case-sensitive tags, no caching (tree changes between queries) */
+const cssSelectOptions = {
+	adapter: {
+		isTag: (node) => !node.isRawText,
+		getAttributeValue: (element, name) => getNodeProp(element, name),
+		getChildren: (node) => [...node.children],
+		getName: (element) => element.type ?? "unknown",
+		getParent: (node) => node.parent,
+		getSiblings: (node) => node.parent ? [...node.parent.children] : [node],
+		getText: (node) => getNodeTextContent(node),
+		hasAttrib: (element, name) => getNodeProp(element, name) !== void 0,
+		removeSubsets: (nodes) => {
+			return nodes.filter((node, i) => {
+				for (let j = 0; j < nodes.length; j++) if (i !== j) {
+					let ancestor = node.parent;
+					while (ancestor) {
+						if (ancestor === nodes[j]) return false;
+						ancestor = ancestor.parent;
+					}
+				}
+				return true;
+			});
+		},
+		prevElementSibling: (node) => {
+			if (!node.parent) return null;
+			const siblings = node.parent.children;
+			const index = siblings.indexOf(node);
+			for (let i = index - 1; i >= 0; i--) if (!siblings[i].isRawText) return siblings[i];
+			return null;
+		}
+	},
+	xmlMode: true,
+	cacheResults: false
+};
+//#endregion
+//#region packages/test/src/debug.ts
+/**
+* Pretty-print SilveryNode tree for debugging.
+*
+* @param node - Root node to inspect
+* @param options - Display options
+* @returns Formatted tree string
+*/
+function debugTree(node, options = {}) {
+	const { depth = Number.POSITIVE_INFINITY, showRects = true, showText = true } = options;
+	const lines = [];
+	function safeStringify(value) {
+		try {
+			return JSON.stringify(value);
+		} catch {
+			if (typeof value === "object" && value !== null) return "[object]";
+			return String(value);
+		}
+	}
+	function walk(n, indent, currentDepth) {
+		if (currentDepth > depth) return;
+		const props = Object.entries(n.props ?? {}).filter(([k]) => !["children"].includes(k)).filter(([, v]) => v !== void 0 && v !== null && v !== false).map(([k, v]) => {
+			if (typeof v === "string") return `${k}="${v}"`;
+			if (typeof v === "boolean") return k;
+			return `${k}=${safeStringify(v)}`;
+		}).join(" ");
+		let rect = "";
+		if (showRects && n.scrollRect) {
+			const { x, y, width, height } = n.scrollRect;
+			rect = ` [${x},${y} ${width}×${height}]`;
+		}
+		let text = "";
+		if (showText && n.textContent) text = ` "${n.textContent.length > 40 ? n.textContent.slice(0, 37) + "..." : n.textContent}"`;
+		const propsStr = props ? " " + props : "";
+		lines.push("  ".repeat(indent) + `<${n.type}${propsStr}${text}${rect}>`);
+		for (const child of n.children) walk(child, indent + 1, currentDepth + 1);
+	}
+	walk(node, 0, 0);
+	return lines.join("\n");
+}
+//#endregion
+//#region packages/test/src/diagnostic-theme.ts
+/**
+* Diagnostic theme for pipeline regression tests.
+*
+* Built so that **every distinct flat token resolves to a distinct, visible
+* color** — exposing pipeline bugs that would be invisible under themes where
+* tokens collapse to the canvas background.
+*
+* ## Why this exists
+*
+* The default `ansi16DarkTheme` uses Nord-derived hexes. In Nord:
+* - canvas `bg` = `#2e3440` = rgb(46, 52, 64)
+* - legacy `mutedbg` = blend(bg, fg, 0.04) ≈ rgb(52, 58, 70)
+*
+* When tests render at ansi16, the underlying RGBs from `mutedbg` and `bg`
+* differ by only a few units — and crucially, they look "the same" to
+* naive bg-vs-canvas detectors that compare against a fixed canvas color.
+*
+* One concrete consequence: the cyan-strip cold-start bug
+* (`@km/silvery/render-light-blue-bg-strip-residue`) emitted bg=$mutedbg paint
+* at cells past a clip boundary, but every test passed because the bg color
+* was indistinguishable from canvas in the test theme. Real users running at
+* Nord saw a visible strip; tests saw nothing.
+*
+* The diagnostic theme uses pure black canvas + saturated primaries so blends
+* preserve their step magnitude in every channel. Every Sterling/legacy token
+* resolves to a distinct RGB tuple. A test that asserts "no non-canvas bg in
+* region X" catches phantom bg paints regardless of which token emitted them.
+*
+* ## Usage
+*
+* ```ts
+* import { diagnosticTheme } from "@silvery/test"
+* import { createRenderer } from "@silvery/test"
+*
+* const r = createRenderer({ cols: 80, rows: 24, theme: diagnosticTheme })
+* ```
+*
+* Or via `testBoard` in km-tui:
+*
+* ```ts
+* const result = await testBoard(VAULT, { columns: 82, rows: 75, theme: diagnosticTheme })
+* // assert no cells past col 40 have non-canvas bg
+* for (let r = 0; r < 75; r++) {
+*   for (let c = 40; c < 82; c++) {
+*     const cell = result._result.cell(c, r)
+*     expect(cell.bg).toBeNull()  // canvas = null bg
+*   }
+* }
+* ```
+*
+* ## Distinctness invariant
+*
+* Pure black canvas (rgb 0,0,0) + pure white fg (rgb 255,255,255) means every
+* blend(bg, fg, t) for distinct `t` produces distinct RGBs. Sterling/legacy
+* derive uses these `t` values:
+*
+*   - `bg-surface-subtle`  = blend(0.03) ≈ rgb(8, 8, 8)
+*   - `bg-surface-hover`   = blend(0.10) ≈ rgb(26, 26, 26)
+*   - `bg-surface-raised`  = blend(0.10) ≈ rgb(26, 26, 26)
+*   - `bg-surface-overlay` = blend(0.12) ≈ rgb(31, 31, 31)
+*   - `bg-muted` (Sterling)= blend(0.08) ≈ rgb(20, 20, 20)
+*   - `mutedbg` (legacy)   = blend(0.04) ≈ rgb(10, 10, 10)
+*
+* All distinct from canvas (rgb 0,0,0) and from each other. The named ANSI
+* slots are saturated primaries so accentBg, redBg, etc. paint in vivid
+* unmistakable colors.
+*/
+/**
+* Maximally-distinct ColorScheme for diagnostic rendering tests.
+*
+* Pure black canvas, pure white fg, saturated ANSI primaries. Every derived
+* token gets a unique visible RGB.
+*/
+const diagnosticScheme = {
+	name: "diagnostic",
+	dark: true,
+	background: "#101828",
+	foreground: "#f0f8ff",
+	primary: "#ff00ff",
+	black: "#202830",
+	red: "#ff0000",
+	green: "#00ff00",
+	yellow: "#ffff00",
+	blue: "#4060ff",
+	magenta: "#ff00ff",
+	cyan: "#00ffff",
+	white: "#f0f8ff",
+	brightBlack: "#606870",
+	brightRed: "#ff8080",
+	brightGreen: "#80ff80",
+	brightYellow: "#ffff80",
+	brightBlue: "#8080ff",
+	brightMagenta: "#ff80ff",
+	brightCyan: "#80ffff",
+	brightWhite: "#ffffff",
+	cursorColor: "#ffaa00",
+	cursorText: "#101828",
+	selectionBackground: "#aa00ff",
+	selectionForeground: "#ffffff"
+};
+/**
+* Pre-derived diagnostic theme. Pass to `createRenderer({ theme })` or
+* `testBoard({ theme })` for pipeline regression coverage.
+*/
+const diagnosticTheme = deriveTheme(diagnosticScheme);
+//#endregion
+//#region packages/test/src/cell-inspector.ts
+function readCellSnapshot(buffer, x, y) {
+	return {
+		x,
+		y,
+		...buffer.getCell(x, y),
+		selectable: buffer.isCellSelectable(x, y)
+	};
+}
+function readCellRow(buffer, y) {
+	const cells = [];
+	for (let x = 0; x < buffer.width; x++) cells.push(readCellSnapshot(buffer, x, y));
+	return cells;
+}
+function formatSelectableCells(buffer) {
+	const lines = [];
+	for (let y = 0; y < buffer.height; y++) {
+		const chars = readCellRow(buffer, y).map((cell) => {
+			if (cell.char === "") return cell.selectable ? "^" : ",";
+			if (cell.char === " ") return cell.selectable ? "_" : ".";
+			return cell.selectable ? cell.char : cell.char.toLowerCase();
+		}).join("");
+		lines.push(chars);
+	}
+	return lines.join("\n");
+}
+//#endregion
+//#region packages/test/src/frame-recorder.ts
+const BLANK_CELL = Object.freeze({
+	char: " ",
+	fg: null,
+	bg: null,
+	bold: false,
+	dim: false,
+	italic: false,
+	underline: false,
+	underlineColor: null,
+	overline: false,
+	strikethrough: false,
+	inverse: false,
+	blink: false,
+	hidden: false,
+	wide: false,
+	continuation: false,
+	hyperlink: null
+});
+/**
+* Build an immutable TextFrame snapshot from a termless emulator. Cell values
+* must be copied eagerly: the emulator is mutable, so a lazy `cell()` read
+* would make every historical frame report the terminal's latest style.
+*/
+function snapshotEmulator(emu) {
+	const width = emu.cols;
+	const height = emu.rows;
+	const lines = emu.screen.getLines().slice(0, height);
+	while (lines.length < height) lines.push("");
+	const text = lines.join("\n");
+	const cells = [];
+	for (let row = 0; row < height; row++) for (let col = 0; col < width; col++) {
+		const view = emu.cell(row, col);
+		cells.push(Object.freeze({
+			char: view.char,
+			fg: view.fg,
+			bg: view.bg,
+			bold: view.bold,
+			dim: view.dim,
+			italic: view.italic,
+			underline: view.underline,
+			underlineColor: view.underlineColor,
+			overline: view.overline ?? false,
+			strikethrough: view.strikethrough,
+			inverse: view.inverse,
+			blink: view.blink,
+			hidden: view.hidden,
+			wide: view.wide,
+			continuation: view.continuation,
+			hyperlink: view.hyperlink
+		}));
+	}
+	return {
+		get text() {
+			return text;
+		},
+		get ansi() {
+			return text;
+		},
+		get lines() {
+			return lines;
+		},
+		width,
+		height,
+		cell(col, row) {
+			if (col < 0 || col >= width || row < 0 || row >= height) return BLANK_CELL;
+			return cells[row * width + col];
+		},
+		containsText(needle) {
+			return text.includes(needle);
+		}
+	};
+}
+function cellsEqual(a, b) {
+	if (a.char !== b.char) return false;
+	if (!rgbEqual(a.fg, b.fg)) return false;
+	if (!rgbEqual(a.bg, b.bg)) return false;
+	if (a.bold !== b.bold) return false;
+	if (a.dim !== b.dim) return false;
+	if (a.italic !== b.italic) return false;
+	if (a.underline !== b.underline) return false;
+	if (!rgbEqual(a.underlineColor, b.underlineColor)) return false;
+	if (a.overline !== b.overline) return false;
+	if (a.strikethrough !== b.strikethrough) return false;
+	if (a.inverse !== b.inverse) return false;
+	if (a.blink !== b.blink) return false;
+	if (a.hidden !== b.hidden) return false;
+	if (a.wide !== b.wide) return false;
+	if (a.continuation !== b.continuation) return false;
+	if (a.hyperlink !== b.hyperlink) return false;
+	return true;
+}
+function rgbEqual(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	return a.r === b.r && a.g === b.g && a.b === b.b;
+}
+function diffFrames(a, b) {
+	const width = Math.min(a.width, b.width);
+	const height = Math.min(a.height, b.height);
+	const changes = [];
+	for (let row = 0; row < height; row++) for (let col = 0; col < width; col++) {
+		const from = a.cell(col, row);
+		const to = b.cell(col, row);
+		if (!cellsEqual(from, to)) changes.push({
+			col,
+			row,
+			from,
+			to
+		});
+	}
+	return changes;
+}
+/**
+* Start recording frames from a Term (or any object exposing `.term`).
+*
+* The recorder observes the emulator's ANSI feed so that every render patch
+* triggers a fresh TextFrame snapshot. Only calls made AFTER `recordFrames()`
+* returns are captured — the initial render is not retroactively recorded.
+* Call `recording.stop()` to end recording early.
+*
+* For emulator-backed terms created via `createTermless()`, snapshots reflect
+* the real terminal state including resolved colors and wide characters. For
+* other Term types, this function throws — cell-level recording requires an
+* emulator.
+*/
+function recordFrames(target) {
+	const emulator = getEmulator(isFrameRecordable(target) ? target.term : target);
+	if (!emulator) throw new Error("recordFrames(): term has no emulator backend. Use createTermless() to create an emulator-backed Term for frame recording.");
+	const frames = [];
+	let stopped = false;
+	const originalFeed = emulator.feed;
+	const recordingFeed = function(data) {
+		originalFeed.call(this, data);
+		if (!stopped) frames.push(snapshotEmulator(emulator));
+	};
+	emulator.feed = recordingFeed;
+	return {
+		get frames() {
+			return frames;
+		},
+		get count() {
+			return frames.length;
+		},
+		diff(i, j) {
+			const a = frames[i];
+			const b = frames[j];
+			if (!a || !b) return [];
+			return diffFrames(a, b);
+		},
+		hasTransientChange(predicate) {
+			for (let i = 0; i + 2 < frames.length; i++) if (predicate(frames[i], frames[i + 1], frames[i + 2])) return true;
+			return false;
+		},
+		clear() {
+			frames.length = 0;
+		},
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			if (emulator.feed === recordingFeed) emulator.feed = originalFeed;
+		}
+	};
+}
+function isFrameRecordable(value) {
+	if (value === null || typeof value !== "object") return false;
+	const maybe = value;
+	if (maybe.term == null) return false;
+	const t = typeof maybe.term;
+	return t === "object" || t === "function";
+}
+function getEmulator(term) {
+	const emu = term._emulator;
+	if (emu == null) return null;
+	const t = typeof emu;
+	if (t !== "object" && t !== "function") return null;
+	const candidate = emu;
+	if (typeof candidate.cols !== "number") return null;
+	if (typeof candidate.rows !== "number") return null;
+	if (typeof candidate.cell !== "function") return null;
+	if (candidate.screen == null) return null;
+	return emu;
+}
+//#endregion
+//#region packages/ag-term/src/bound-term.ts
+/**
+* Create a BoundTerm from a buffer and root node getter
+*/
+function createBoundTerm(buffer, getRoot, getText) {
+	return {
+		cell(x, y) {
+			return buffer.getCell(x, y);
+		},
+		nodeAt(x, y) {
+			return findNodeAtScreenPosition(getRoot(), x, y);
+		},
+		get text() {
+			return getText();
+		},
+		get columns() {
+			return buffer.width;
+		},
+		get rows() {
+			return buffer.height;
+		},
+		get buffer() {
+			return buffer;
+		}
+	};
+}
+/**
+* Find the deepest node at the given screen coordinates
+*/
+function findNodeAtScreenPosition(node, x, y) {
+	const rect = node.scrollRect;
+	if (!rect) return null;
+	if (x < rect.x || x >= rect.x + rect.width || y < rect.y || y >= rect.y + rect.height) return null;
+	for (const child of node.children) {
+		const found = findNodeAtScreenPosition(child, x, y);
+		if (found) return found;
+	}
+	if (node.type === "silvery-text") for (let i = node.children.length - 1; i >= 0; i--) {
+		const child = node.children[i];
+		if (child.inlineRects) {
+			for (const inlineRect of child.inlineRects) if (x >= inlineRect.x && x < inlineRect.x + inlineRect.width && y >= inlineRect.y && y < inlineRect.y + inlineRect.height) return child;
+		}
+	}
+	return node;
+}
+//#endregion
+//#region packages/ag-term/src/screenshot.ts
+function createScreenshotter() {
+	let browser = null;
+	let page = null;
+	async function ensureBrowser() {
+		if (browser && page) return page;
+		const { chromium } = await import("playwright");
+		browser = await chromium.launch();
+		page = await (await browser.newContext()).newPage();
+		return page;
+	}
+	async function capture(html, outputPath) {
+		const p = await ensureBrowser();
+		await p.setContent(html, { waitUntil: "load" });
+		await p.waitForTimeout(50);
+		const buffer = await p.screenshot({ fullPage: true });
+		if (outputPath) await writeFile(outputPath, buffer);
+		return buffer;
+	}
+	async function close() {
+		if (browser) {
+			await browser.close();
+			browser = null;
+			page = null;
+		}
+	}
+	return {
+		capture,
+		close,
+		[Symbol.asyncDispose]: close
+	};
+}
+//#endregion
+//#region packages/ag-react/src/debug/render-path.ts
+function hostTypeLabel(type) {
+	if (type === "silvery-box") return "Box";
+	if (type === "silvery-text") return "Text";
+	return type;
+}
+/**
+* Resolve a node to its display name.
+* Mirrors `getDebugComponentName` in reconciler/host-config.ts (kept in
+* sync; if you change one, update the other).
+*/
+function getComponentName(node) {
+	const props = node.props;
+	const explicit = props["data-component"];
+	if (typeof explicit === "string" && explicit.length > 0) return explicit;
+	const base = hostTypeLabel(node.type);
+	const testID = props.testID;
+	if (typeof testID === "string" && testID.length > 0) return `${base}#${testID}`;
+	const id = props.id;
+	if (typeof id === "string" && id.length > 0) return `${base}#${id}`;
+	return base;
+}
+function summarize(node) {
+	const out = {
+		name: getComponentName(node),
+		type: node.type
+	};
+	if (node.boxRect) out.boxRect = {
+		x: node.boxRect.x,
+		y: node.boxRect.y,
+		width: node.boxRect.width,
+		height: node.boxRect.height
+	};
+	return out;
+}
+/**
+* Return the parent chain from `root` down to the first node matching
+* `componentName`. Each element is a `RenderPathNode` summary.
+*
+* Returns `[]` if no match is found.
+*
+* If multiple nodes match, returns the path to the FIRST in tree order.
+* Use `findNodesByComponentName` to inspect all matches.
+*/
+function getRenderPath(root, componentName) {
+	function walk(node, chain) {
+		const next = [...chain, node];
+		if (getComponentName(node) === componentName) return next;
+		for (const child of node.children) {
+			const hit = walk(child, next);
+			if (hit) return hit;
+		}
+		return null;
+	}
+	const hit = walk(root, []);
+	return hit ? hit.map(summarize) : [];
+}
+/**
+* Recursive JSON dump of the entire mount tree rooted at `root`.
+*
+* Useful for snapshot tests asserting on structural invariants —
+* e.g., "ToolBlock is always wrapped in a Content.Body[width=full]".
+*/
+function getMountTree(root) {
+	return {
+		...summarize(root),
+		children: root.children.map(getMountTree)
+	};
+}
+//#endregion
+//#region packages/ag-term/src/app.ts
+/**
+* Create an App instance
+*/
+function buildApp(options) {
+	const { getContainer, getBuffer, sendInput, rerender, unmount, waitUntilExit, clear, exitCalled = () => false, exitError = () => void 0, freshRender: freshRenderFn, debugFn, frames = [], columns, rows, kittyMode = false, actAndRender, resize: resizeFn, focusManager: fm, waitForLayoutStable: waitForLayoutStableFn, clsMonitor } = options;
+	const createLocator = () => createAutoLocator(getContainer);
+	const getText = () => {
+		const buffer = getBuffer();
+		return buffer ? bufferToText(buffer) : "";
+	};
+	let boundTerm = null;
+	const mouseState = createMouseEventProcessor();
+	let screenshotter = null;
+	const app = {
+		get text() {
+			return getText();
+		},
+		get ansi() {
+			const buffer = getBuffer();
+			return buffer ? bufferToStyledText(buffer) : "";
+		},
+		get lines() {
+			return getText().split("\n");
+		},
+		get width() {
+			return getBuffer()?.width ?? columns;
+		},
+		get height() {
+			return getBuffer()?.height ?? rows;
+		},
+		cell(col, row) {
+			const buffer = getBuffer();
+			if (!buffer) return EMPTY_FRAME_CELL;
+			return cellToFrameCell(buffer.getCell(col, row));
+		},
+		containsText(text) {
+			return getText().includes(text);
+		},
+		nodeAt(x, y) {
+			return findNodeAtContentPosition(getContainer(), x, y);
+		},
+		getByTestId(id) {
+			return createLocator().getByTestId(id);
+		},
+		getByText(text) {
+			return createLocator().getByText(text);
+		},
+		locator(selector) {
+			return createLocator().locator(selector);
+		},
+		press(key) {
+			return makeChain((async () => {
+				const hotkey = parseHotkey(key);
+				updateKeyboardModifiers(mouseState, {
+					super: hotkey.super,
+					hyper: hotkey.hyper,
+					eventType: "press"
+				});
+				sendInput(kittyMode ? keyToKittyAnsi(key) : keyToAnsi(key));
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		keyDown(key) {
+			return makeChain((async () => {
+				const hotkey = parseHotkey(key);
+				updateKeyboardModifiers(mouseState, {
+					super: hotkey.super || keyIsModifier(key, "Super"),
+					hyper: hotkey.hyper || keyIsModifier(key, "Hyper"),
+					eventType: "press"
+				});
+				sendInput(injectKittyEventType(kittyMode ? keyToKittyAnsi(key) : keyToAnsi(key), 1));
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		keyUp(key) {
+			return makeChain((async () => {
+				parseHotkey(key);
+				updateKeyboardModifiers(mouseState, {
+					super: false,
+					hyper: false,
+					eventType: "release"
+				});
+				sendInput(injectKittyEventType(kittyMode ? keyToKittyAnsi(key) : keyToAnsi(key), 3));
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		pressSequence(...keys) {
+			return makeChain((async () => {
+				for (const key of keys) await app.press(key);
+				return app;
+			})());
+		},
+		type(text) {
+			return makeChain((async () => {
+				for (const char of text) sendInput(char);
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		click(x, y, options) {
+			return makeChain((async () => {
+				const button = options?.button ?? 0;
+				if (options?.cmd) mouseState.keyboardModifiers.super = true;
+				const doClick = () => {
+					const parsed = {
+						button,
+						x,
+						y,
+						coordinateMode: "cell",
+						action: "down",
+						shift: options?.shift ?? false,
+						meta: options?.meta ?? false,
+						ctrl: options?.ctrl ?? false
+					};
+					processMouseEvent(mouseState, parsed, getContainer());
+					processMouseEvent(mouseState, {
+						...parsed,
+						action: "up"
+					}, getContainer());
+				};
+				if (actAndRender) actAndRender(doClick);
+				else doClick();
+				if (options?.cmd) mouseState.keyboardModifiers.super = false;
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		doubleClick(x, y, options) {
+			return makeChain((async () => {
+				const button = options?.button ?? 0;
+				if (options?.cmd) mouseState.keyboardModifiers.super = true;
+				const doDblClick = () => {
+					const baseParsed = {
+						button,
+						x,
+						y,
+						coordinateMode: "cell",
+						action: "down",
+						shift: options?.shift ?? false,
+						meta: options?.meta ?? false,
+						ctrl: options?.ctrl ?? false
+					};
+					processMouseEvent(mouseState, baseParsed, getContainer());
+					processMouseEvent(mouseState, {
+						...baseParsed,
+						action: "up"
+					}, getContainer());
+					processMouseEvent(mouseState, baseParsed, getContainer());
+					processMouseEvent(mouseState, {
+						...baseParsed,
+						action: "up"
+					}, getContainer());
+				};
+				if (actAndRender) actAndRender(doDblClick);
+				else doDblClick();
+				if (options?.cmd) mouseState.keyboardModifiers.super = false;
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		hover(x, y, options) {
+			return makeChain((async () => {
+				if (options?.cmd) mouseState.keyboardModifiers.super = true;
+				const doHover = () => {
+					processMouseEvent(mouseState, {
+						button: 0,
+						x,
+						y,
+						coordinateMode: "cell",
+						action: "move",
+						shift: options?.shift ?? false,
+						meta: options?.meta ?? false,
+						ctrl: options?.ctrl ?? false
+					}, getContainer());
+				};
+				if (actAndRender) actAndRender(doHover);
+				else doHover();
+				if (options?.cmd) mouseState.keyboardModifiers.super = false;
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		wheel(x, y, delta, options) {
+			return makeChain((async () => {
+				if (options?.cmd) mouseState.keyboardModifiers.super = true;
+				const doWheel = () => {
+					processMouseEvent(mouseState, {
+						button: 0,
+						x,
+						y,
+						coordinateMode: "cell",
+						action: "wheel",
+						delta,
+						shift: options?.shift ?? false,
+						meta: options?.meta ?? false,
+						ctrl: options?.ctrl ?? false
+					}, getContainer());
+				};
+				if (actAndRender) actAndRender(doWheel);
+				else doWheel();
+				if (options?.cmd) mouseState.keyboardModifiers.super = false;
+				await Promise.resolve();
+				return app;
+			})());
+		},
+		resize(cols, rows) {
+			if (!resizeFn) throw new Error("resize() is only available in test renderer");
+			resizeFn(cols, rows);
+		},
+		async run() {
+			return waitUntilExit();
+		},
+		get term() {
+			const buffer = getBuffer();
+			if (!buffer) return createBoundTerm({
+				width: columns,
+				height: rows,
+				getCell: () => ({
+					char: " ",
+					fg: null,
+					bg: null,
+					attrs: {},
+					wide: false,
+					continuation: false
+				}),
+				setCell: () => {},
+				clear: () => {},
+				inBounds: () => false
+			}, getContainer, getText);
+			if (!boundTerm || boundTerm.buffer !== buffer) boundTerm = createBoundTerm(buffer, getContainer, getText);
+			return boundTerm;
+		},
+		async screenshot(outputPath) {
+			const buffer = getBuffer();
+			if (!buffer) throw new Error("No buffer available for screenshot");
+			const html = bufferToHTML(buffer);
+			if (!screenshotter) screenshotter = createScreenshotter();
+			return screenshotter.capture(html, outputPath);
+		},
+		rerender,
+		unmount() {
+			if (screenshotter) {
+				screenshotter.close().catch(() => {});
+				screenshotter = null;
+			}
+			unmount();
+		},
+		[Symbol.dispose]() {
+			app.unmount();
+		},
+		waitUntilExit,
+		waitForLayoutStable(opts) {
+			if (!waitForLayoutStableFn) return Promise.reject(/* @__PURE__ */ new Error("waitForLayoutStable() is only available in the test renderer"));
+			return waitForLayoutStableFn(opts);
+		},
+		beginCLSCapture(classifier) {
+			if (!clsMonitor) throw new Error("beginCLSCapture: no ClsMonitor was provided to buildApp(). The render harness must instantiate `createClsMonitor()` and pass it via AppOptions.clsMonitor for CLS capture to work.");
+			clsMonitor.beginCapture(classifier);
+		},
+		endCLSCapture() {
+			if (!clsMonitor) throw new Error("endCLSCapture: no ClsMonitor was provided to buildApp().");
+			return clsMonitor.endCapture();
+		},
+		cancelCLSCapture() {
+			clsMonitor?.cancelCapture();
+		},
+		clear,
+		debug() {
+			if (debugFn) debugFn();
+			else console.log(app.text);
+		},
+		freshRender() {
+			if (!freshRenderFn) throw new Error("freshRender() is only available in test renderer");
+			return freshRenderFn();
+		},
+		exitCalled,
+		exitError,
+		stdin: { write: sendInput },
+		frames,
+		lastFrame() {
+			return frames[frames.length - 1];
+		},
+		lastBuffer() {
+			return getBuffer() ?? void 0;
+		},
+		lastFrameText() {
+			const buffer = getBuffer();
+			return buffer ? bufferToText(buffer) : void 0;
+		},
+		getContainer() {
+			return getContainer();
+		},
+		focus(testID) {
+			if (fm) {
+				const root = getContainer();
+				fm.focusById(testID, root, "programmatic");
+			}
+		},
+		getFocusPath() {
+			if (fm) {
+				const root = getContainer();
+				return fm.getFocusPath(root);
+			}
+			return [];
+		},
+		get focusManager() {
+			if (!fm) throw new Error("FocusManager not available — pass focusManager to buildApp()");
+			return fm;
+		},
+		getCursorState() {
+			const layoutCursor = findActiveCursorRect(getContainer());
+			if (layoutCursor) return {
+				x: layoutCursor.x,
+				y: layoutCursor.y,
+				visible: layoutCursor.visible,
+				shape: layoutCursor.shape
+			};
+			return options.getCursorState?.() ?? null;
+		},
+		renderPath(componentName) {
+			return getRenderPath(getContainer(), componentName);
+		},
+		mountTree() {
+			return getMountTree(getContainer());
+		}
+	};
+	return app;
+}
+/**
+* Wrap a `Promise<App>` in a `ChainableApp` — a thenable that exposes
+* the action methods so consumers can compose without explicit `await`
+* between every step:
+*
+*   await app.keyDown("Super").hover(x, y).keyUp("Super")
+*
+* Each chained method returns a new `ChainableApp` whose backing promise
+* `.then`s into the previous step + the new action. The terminal `await`
+* resolves the entire chain to the underlying `App`.
+*
+* Bead: @km/silvery/fluent-chain-actions.
+*/
+function makeChain(p) {
+	return {
+		press: (key) => makeChain(p.then((a) => a.press(key))),
+		keyDown: (key) => makeChain(p.then((a) => a.keyDown(key))),
+		keyUp: (key) => makeChain(p.then((a) => a.keyUp(key))),
+		pressSequence: (...keys) => makeChain(p.then((a) => a.pressSequence(...keys))),
+		type: (text) => makeChain(p.then((a) => a.type(text))),
+		click: (x, y, options) => makeChain(p.then((a) => a.click(x, y, options))),
+		doubleClick: (x, y, options) => makeChain(p.then((a) => a.doubleClick(x, y, options))),
+		hover: (x, y, options) => makeChain(p.then((a) => a.hover(x, y, options))),
+		wheel: (x, y, delta, options) => makeChain(p.then((a) => a.wheel(x, y, delta, options))),
+		then: (onFulfilled, onRejected) => p.then(onFulfilled, onRejected)
+	};
+}
+/**
+* Inject a Kitty CSI u event-type byte (`:1` press, `:2` repeat, `:3`
+* release) before the trailing terminator (`u`, `~`, or a CSI letter)
+* of a Kitty key sequence. Used by `keyDown`/`keyUp` to express held
+* vs. transient state — `keyToKittyAnsi` returns the bare-press shape
+* (no event-type byte), which the parser interprets as "press" by
+* default; explicit `:1`/`:3` lets tests drive paired down/up events.
+*
+* Examples:
+*
+*   `\x1b[57444;9u`   → `\x1b[57444;9:1u`   (left-super press)
+*   `\x1b[57444;9u`   → `\x1b[57444;9:3u`   (left-super release)
+*   `\x1b[1;5A`       → `\x1b[1;5:1A`       (Ctrl+ArrowUp press)
+*   `\x1b[3;5~`       → `\x1b[3;5:1~`       (Ctrl+Delete press)
+*
+* Sequences without a modifier byte (`\x1b[CPu`) get a `;1:eventType`
+* insert: `\x1b[57444u` → `\x1b[57444;1:1u`. The base modifier is `1`
+* (no modifiers + 1 base) per the Kitty spec.
+*
+* Bead: @km/silvery/keydown-keyup-test-primitives.
+*/
+function injectKittyEventType(seq, eventType) {
+	const withMod = seq.replace(/(;[0-9]+)([A-Za-z~])$/, `$1:${eventType}$2`);
+	if (withMod !== seq) return withMod;
+	return seq.replace(/^(\x1b\[[0-9]+)([A-Za-z~])$/, `$1;1:${eventType}$2`);
+}
+/**
+* Detect whether a key string represents a specific bare modifier
+* (e.g., `keyIsModifier("Super", "Super")` → true,
+* `keyIsModifier("leftsuper", "Super")` → true,
+* `keyIsModifier("a", "Super")` → false). Used by `keyDown`/`keyUp`
+* to update `mouseState.keyboardModifiers` even when the caller passes
+* a bare modifier name like "Super" rather than a chord like
+* "Super+a". `parseHotkey` only sets `.super` when the key is a chord
+* with Super as a modifier; it doesn't set it for the bare modifier
+* name itself.
+*
+* Bead: @km/silvery/keydown-keyup-test-primitives.
+*/
+function keyIsModifier(key, target) {
+	const parts = key.split("+");
+	const last = parts[parts.length - 1]?.toLowerCase() ?? "";
+	if (target === "Super") return last === "super" || last === "cmd" || last === "command" || last === "leftsuper" || last === "rightsuper";
+	return last === "hyper" || last === "lefthyper" || last === "righthyper";
+}
+/**
+* Find node at content coordinates (not screen coordinates)
+*/
+function findNodeAtContentPosition(node, x, y) {
+	const rect = node.boxRect;
+	if (!rect) return null;
+	if (!pointInRect(x, y, rect)) return null;
+	for (const child of node.children) {
+		const found = findNodeAtContentPosition(child, x, y);
+		if (found) return found;
+	}
+	return node;
+}
+const RESIDUE_SENTINEL_RGB = {
+	r: 254,
+	g: 0,
+	b: 254
+};
+/** SILVERY_STRICT slug for the residue check. Tier 2 by design. */
+const RESIDUE_STRICT_SLUG = "residue";
+/** Returns true when the residue check should fire. */
+function isResidueStrictEnabled() {
+	return isStrictEnabled(RESIDUE_STRICT_SLUG, 2);
+}
+/**
+* Fill every cell of `buffer` with the residue sentinel — a magenta-ish
+* RGB no theme uses + the thorn character "þ". This is a destructive
+* operation; callers must operate on a clone of the live prev buffer.
+*/
+function poisonBufferWithSentinel(buffer) {
+	buffer.fill(0, 0, buffer.width, buffer.height, {
+		char: "þ",
+		fg: RESIDUE_SENTINEL_RGB,
+		bg: RESIDUE_SENTINEL_RGB,
+		wide: false,
+		continuation: false
+	});
+}
+/**
+* Compare a sentinel-poison-prev incremental render to a fresh render,
+* accounting for the legitimate "cascade skipped this cell because prev
+* was already correct" pattern.
+*
+* The check semantic in detail:
+*
+*   1. Real prev buffer P captures the pre-frame state (the buffer the
+*      production incremental render correctly clones from).
+*   2. Poisoned prev P' = P with every cell replaced by sentinel.
+*   3. Incremental-with-poison buffer I' is what runPipeline produced
+*      against P'. Cells the cascade skipped retain sentinel; cells it
+*      repainted have fresh content.
+*   4. Fresh-from-zero buffer F is the all-paths-recomputed reference.
+*   5. INVARIANT: at every (x,y),
+*        I'[x,y] is sentinel ⇒ P[x,y] === F[x,y]
+*      (cascade skipped this cell ⇒ prev pixel was already what fresh
+*      paints; no stale carry-over).
+*   6. Equivalently: at any cell where P[x,y] ≠ F[x,y], the incremental
+*      cascade MUST repaint, and I'[x,y] ≠ sentinel.
+*
+* A violation = "the cascade decided this cell is clean, but the real
+* prev had different content from what fresh paints". That's exactly
+* the cyan-strip-residue class: prev had cyan bg at row 5; fresh paints
+* default bg; cascade skipped row 5; user sees cyan on a row that
+* should be default. Sentinel-poison reveals it because I' has the
+* sentinel where the cascade skipped, and F[x,y] ≠ P[x,y] at that cell.
+*
+* Pipeline-state contamination is detected as a side effect: if any
+* cross-pass state (postState / accumulators) leaks, I' diverges from
+* F at cells the sentinel doesn't cover, and `cellEquals` catches it.
+*
+* Throws on first divergence with a diagnostic identifying the verdict
+* (sentinel leak vs pipeline contamination), the cell coordinates, and
+* the value triple (P, I', F) for the offending cell.
+*/
+function verifyNoResidueLeak(realPrevBuffer, incrPoisonedBuffer, freshBuffer, frameCount) {
+	const w = Math.min(realPrevBuffer.width, incrPoisonedBuffer.width, freshBuffer.width);
+	const h = Math.min(realPrevBuffer.height, incrPoisonedBuffer.height, freshBuffer.height);
+	for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) {
+		const incr = incrPoisonedBuffer.getCell(x, y);
+		const fresh = freshBuffer.getCell(x, y);
+		if (cellEquals(incr, fresh)) continue;
+		if (isSentinelCell(incr)) {
+			const prev = realPrevBuffer.getCell(x, y);
+			if (cellEquals(prev, fresh)) continue;
+			throw new IncrementalRenderMismatchError(`STRICT residue check (frame ${frameCount}): SENTINEL LEAK at (${x},${y})\n  real prev:   char='${prev.char}' fg=${formatColor(prev.fg)} bg=${formatColor(prev.bg)}\n  incremental: char='${incr.char}' fg=${formatColor(incr.fg)} bg=${formatColor(incr.bg)} (sentinel — cascade skipped)\n  fresh:       char='${fresh.char}' fg=${formatColor(fresh.fg)} bg=${formatColor(fresh.bg)}\n  Real prev ≠ fresh at this cell, but the incremental cascade decided\n  not to repaint it. The user sees a stale prev pixel where fresh\n  would have painted differently — the cyan-strip-residue class.\n  Likely root cause: missing dirty flag propagation, a skipBgFill\n  that should have been bgRefillNeeded, or a transparent-Box\n  ancestorCleared cascade gap.\n  Slug: SILVERY_STRICT=${RESIDUE_STRICT_SLUG} (tier 2+).\n  Per-test opt-out: SILVERY_STRICT=2,!${RESIDUE_STRICT_SLUG}.`);
+		}
+		throw new IncrementalRenderMismatchError(`STRICT residue check (frame ${frameCount}): pipeline-state contamination at (${x},${y})\n  incremental: char='${incr.char}' fg=${formatColor(incr.fg)} bg=${formatColor(incr.bg)} (repainted)\n  fresh:       char='${fresh.char}' fg=${formatColor(fresh.fg)} bg=${formatColor(fresh.bg)}\n  Both passes painted this cell but disagreed. Cross-pass state\n  (postState / scrollOffset / outlineSnapshots) is leaking between\n  the sentinel-poisoned incremental render and the fresh baseline.\n  Slug: SILVERY_STRICT=${RESIDUE_STRICT_SLUG} (tier 2+).\n  Per-test opt-out: SILVERY_STRICT=2,!${RESIDUE_STRICT_SLUG}.`);
+	}
+}
+/** True when a cell still carries the residue sentinel. */
+function isSentinelCell(c) {
+	if (c.char !== "þ") return false;
+	const bg = c.bg;
+	if (typeof bg !== "object" || bg === null) return false;
+	const o = bg;
+	return o.r === RESIDUE_SENTINEL_RGB.r && o.g === RESIDUE_SENTINEL_RGB.g && o.b === RESIDUE_SENTINEL_RGB.b;
+}
+function formatColor(c) {
+	if (c === null || c === void 0) return "default";
+	if (typeof c === "number") return `${c}`;
+	if (typeof c === "object") {
+		const o = c;
+		return `rgb(${o.r},${o.g},${o.b})`;
+	}
+	return String(c);
+}
+//#endregion
+//#region packages/ag-term/src/renderer.ts
+/**
+* Unified Render API for silvery
+*
+* Composable primitives:
+* - render(element, opts | store) — always sync, returns full App
+* - createStore(providers) — flattens providers into { cols, rows, events() }
+* - run(app, events?) — event loop driver (sync or async)
+* - createApp(element, providers) — sugar: render + createStore + run
+* - createRenderer(opts | store) — factory with auto-cleanup
+*/
+const act = React.act ?? ((cb) => cb());
+const log = createLogger("silvery:render");
+function invalidateRootAfterLayoutFeedback(root) {
+	root.dirtyBits = 31;
+	root.dirtyEpoch = getRenderEpoch();
+}
+/**
+* Track all active (mounted) render instances to detect leaks.
+* Uses a Set of WeakRefs so GC can clean up unreferenced apps.
+*/
+const activeRenders = /* @__PURE__ */ new Set();
+let renderIdCounter = 0;
+/**
+* Maximum number of active render instances before throwing.
+* Set high to allow large test files (each test may create a render without unmount),
+* but catch genuine leaks like infinite loops creating renders.
+*/
+const ACTIVE_RENDER_LEAK_THRESHOLD = 1e3;
+/**
+* Prune GC'd entries from activeRenders and return live count.
+*/
+function pruneAndCountActiveRenders() {
+	let count = 0;
+	for (const ref of activeRenders) if (ref.deref() === void 0) activeRenders.delete(ref);
+	else count++;
+	return count;
+}
+/**
+* Assert that the layout engine is initialized before rendering.
+* This catches the common mistake of calling render() without await ensureEngine().
+*/
+function assertLayoutEngine() {
+	if (!isLayoutEngineInitialized()) throw new Error("silvery: Layout engine not initialized. Call `await ensureEngine()` before render(), or use the testing module which initializes it automatically via top-level await.");
+}
+let engineReady = null;
+/**
+* Ensure layout engine is initialized (async, cached).
+*/
+async function ensureEngine() {
+	if (isLayoutEngineInitialized()) return;
+	if (!engineReady) engineReady = ensureDefaultLayoutEngine();
+	await engineReady;
+}
+function isStore(arg) {
+	if (arg === null || typeof arg !== "object") return false;
+	const obj = arg;
+	return typeof obj.cols === "number" && typeof obj.rows === "number" && !("layoutEngine" in obj) && !("debug" in obj) && !("incremental" in obj) && !("maxLayoutPasses" in obj) && !("autoRender" in obj) && !("onFrame" in obj) && !("kittyMode" in obj) && !("wrapRoot" in obj) && !("stdin" in obj);
+}
+/**
+* Render a React element synchronously. Returns a full App with locators,
+* press(), text, ansi, etc.
+*
+* Layout engine must be initialized before calling (use ensureEngine() or
+* the top-level await in testing module).
+*
+* Overloads:
+* - render(element, { cols, rows }) — headless with dimensions
+* - render(element, store) — with a Store from createStore()
+*
+* @example
+* ```tsx
+* const app = render(<Counter />, { cols: 80, rows: 24 })
+* expect(app.text).toContain('Count: 0')
+* await app.press('j')
+* expect(app.text).toContain('Count: 1')
+* ```
+*/
+function render(element, optsOrStore = {}) {
+	assertLayoutEngine();
+	const storeMode = isStore(optsOrStore);
+	const cols = storeMode ? optsOrStore.cols : optsOrStore.cols ?? 80;
+	const rows = storeMode ? optsOrStore.rows : optsOrStore.rows ?? 24;
+	const debug = storeMode ? false : optsOrStore.debug ?? false;
+	const incremental = storeMode ? true : optsOrStore.incremental ?? true;
+	const maxLayoutPasses = storeMode ? MAX_CONVERGENCE_PASSES : optsOrStore.maxLayoutPasses ?? MAX_CONVERGENCE_PASSES;
+	const kittyMode = storeMode ? false : optsOrStore.kittyMode ?? false;
+	const autoRender = storeMode ? false : optsOrStore.autoRender ?? false;
+	const handleTabCycling = storeMode ? true : optsOrStore.handleTabCycling ?? true;
+	const onFrame = storeMode ? void 0 : optsOrStore.onFrame;
+	const onBufferReady = storeMode ? void 0 : optsOrStore.onBufferReady;
+	const wrapRoot = storeMode ? void 0 : optsOrStore.wrapRoot;
+	const stdinStream = storeMode ? void 0 : optsOrStore.stdin;
+	const liveCount = pruneAndCountActiveRenders();
+	if (liveCount >= ACTIVE_RENDER_LEAK_THRESHOLD) throw new Error(`silvery: ${liveCount} active render instances without unmount(). This is a render leak. Use createRenderer() for auto-cleanup, or call unmount() when done with each render.`);
+	if (!storeMode && optsOrStore.layoutEngine) setLayoutEngine(optsOrStore.layoutEngine);
+	const renderId = ++renderIdCounter;
+	const instance = {
+		frames: [],
+		container: null,
+		fiberRoot: null,
+		prevBuffer: null,
+		prevPaintedBuffer: null,
+		postState: createRenderPostState(),
+		mounted: true,
+		rendering: false,
+		columns: cols,
+		rows,
+		inputEmitter: new EventEmitter(),
+		debug,
+		incremental,
+		renderCount: 0,
+		maxLayoutPasses,
+		kittyActive: false
+	};
+	let hadReactCommit = false;
+	let autoRenderScheduled = false;
+	let inRenderCycle = false;
+	let currentElement = element;
+	const clsMonitor = createClsMonitor();
+	instance.container = createContainer(() => {
+		hadReactCommit = true;
+		if (autoRender && !instance.rendering && !inRenderCycle && !autoRenderScheduled && instance.mounted) {
+			autoRenderScheduled = true;
+			queueMicrotask(() => {
+				autoRenderScheduled = false;
+				if (!instance.mounted || instance.rendering || inRenderCycle) return;
+				inRenderCycle = true;
+				try {
+					let newFrame = doRender();
+					const root = getContainerRoot(instance.container);
+					hadReactCommit = false;
+					withActEnvironment(() => {
+						act(() => {
+							commitLayoutSnapshot(root);
+						});
+						if (hadReactCommit) act(() => {
+							reconciler.flushSyncWork();
+						});
+					});
+					if (hadReactCommit) newFrame = doRender();
+					instance.frames.push(newFrame);
+					onFrame?.(newFrame, instance.prevBuffer, getRootContentHeight());
+				} finally {
+					inRenderCycle = false;
+				}
+			});
+		}
+	});
+	instance.fiberRoot = createFiberRoot(instance.container);
+	/**
+	* Get the content extent of the root node's children (for buffer padding trimming).
+	* Returns the max outer bottom edge of the root's direct children, including
+	* margins. The root itself stretches to fill the terminal, but its children
+	* have specific layout-computed heights plus margins that extend beyond.
+	* Returns 0 if no children have layout (empty tree).
+	* Returns undefined if root has no layout at all.
+	*/
+	const getRootContentHeight = () => {
+		try {
+			const root = getContainerRoot(instance.container);
+			if (!root?.boxRect) return void 0;
+			let maxBottom = 0;
+			let hasChildren = false;
+			for (const child of root.children) if (child.boxRect) {
+				hasChildren = true;
+				const props = child.props;
+				const mb = props.marginBottom ?? props.marginY ?? props.margin ?? 0;
+				const childBottom = child.boxRect.y + child.boxRect.height + mb;
+				if (childBottom > maxBottom) maxBottom = childBottom;
+			}
+			return hasChildren ? maxBottom : 0;
+		} catch {
+			return;
+		}
+	};
+	let exitCalledFlag = false;
+	let exitErrorValue;
+	const handleExit = (error) => {
+		exitCalledFlag = true;
+		exitErrorValue = error;
+		if (debug) console.log("[silvery] exit() called", error ? `with error: ${error.message}` : "");
+	};
+	const stdoutEmitter = new EventEmitter();
+	const mockStdout = {
+		columns: instance.columns,
+		rows: instance.rows,
+		write: () => true,
+		isTTY: true,
+		on: (event, listener) => {
+			stdoutEmitter.on(event, listener);
+			return mockStdout;
+		},
+		off: (event, listener) => {
+			stdoutEmitter.off(event, listener);
+			return mockStdout;
+		},
+		once: (event, listener) => {
+			stdoutEmitter.once(event, listener);
+			return mockStdout;
+		},
+		removeListener: (event, listener) => {
+			stdoutEmitter.removeListener(event, listener);
+			return mockStdout;
+		},
+		addListener: (event, listener) => {
+			stdoutEmitter.addListener(event, listener);
+			return mockStdout;
+		}
+	};
+	const mockTerm = createTerm({
+		cols: instance.columns,
+		rows: instance.rows,
+		caps: { colorLevel: "truecolor" }
+	});
+	const updateMockTermSize = mockTerm.size.update;
+	const focusManager = createFocusManager();
+	setContainerNodeLifecycle(instance.container, {
+		onNodeRemoved: (removedNode) => focusManager.handleSubtreeRemoved(removedNode),
+		onNodeUpdated: (updatedNode) => focusManager.handleNodeUpdated(updatedNode),
+		onSubtreeAttached: (attachedRoot) => focusManager.handleSubtreeAttached(attachedRoot)
+	});
+	const cursorStore = createCursorStore();
+	const renderScope = createScope("test-render");
+	const childApp = createChildApp();
+	const chainAppContextValue = toChainAppContextValue(childApp);
+	instance.inputEmitter.on("input", (data) => {
+		const [input, key] = parseKey(data);
+		childApp.rawKeys.notify(input, key);
+		childApp.dispatch({
+			type: "input:key",
+			input,
+			key
+		});
+		childApp.drainEffects();
+	});
+	instance.inputEmitter.on("paste", (text) => {
+		childApp.dispatch({
+			type: "term:paste",
+			text
+		});
+		childApp.drainEffects();
+	});
+	const runtimeValue = {
+		exit: handleExit,
+		panic: (reason) => handleExit(reason instanceof Error ? reason : new Error(String(reason)))
+	};
+	function wrapWithContexts(el) {
+		const inner = wrapRoot ? wrapRoot(el) : el;
+		return React.createElement(ScopeProvider, {
+			scope: renderScope,
+			appScope: renderScope
+		}, React.createElement(CursorProvider, { store: cursorStore }, React.createElement(TermContext.Provider, { value: mockTerm }, React.createElement(StdoutContext.Provider, { value: {
+			stdout: mockStdout,
+			write: () => {}
+		} }, React.createElement(FocusManagerContext.Provider, { value: focusManager }, React.createElement(RuntimeContext.Provider, { value: runtimeValue }, React.createElement(ChainAppContext.Provider, { value: chainAppContextValue }, inner)))))));
+	}
+	const strictEnv = process.env.SILVERY_STRICT;
+	const strictMode = incremental && strictEnv && strictEnv !== "0" && strictEnv !== "false";
+	/** Run the full pipeline: layout + render + output phase. */
+	function runPipeline(root, cols, rows, prevBuffer, opts) {
+		const ag = createAg(root);
+		ag.layout({
+			cols,
+			rows
+		}, opts);
+		const { buffer, carryForwardBuffer, overlay } = ag.render({
+			prevBuffer,
+			postState: opts?.fresh ? createRenderPostState() : instance.postState
+		});
+		let output = outputPhase(instance.prevPaintedBuffer ?? prevBuffer, buffer, "fullscreen");
+		if (overlay.length > 0) {
+			output += overlay;
+			instance.kittyActive = true;
+		} else if (instance.kittyActive) {
+			output += "\x1B7" + kittyDeleteAllScrimPlacements() + "\x1B8";
+			instance.kittyActive = false;
+		}
+		return {
+			output,
+			buffer,
+			carryForwardBuffer,
+			overlay
+		};
+	}
+	function doRender() {
+		let output;
+		let buffer;
+		let incrementalOverlay = "";
+		let multiPassConverged = false;
+		let passCount = 0;
+		const cap = instance.maxLayoutPasses;
+		if (INSTRUMENT) beginConvergenceLoop();
+		for (let pass = 0; pass < cap; pass++) {
+			hadReactCommit = false;
+			passCount++;
+			if (INSTRUMENT) beginPass(pass);
+			let renderError = null;
+			let carryForwardBuffer;
+			withActEnvironment(() => {
+				act(() => {
+					const root = getContainerRoot(instance.container);
+					try {
+						const result = runPipeline(root, instance.columns, instance.rows, incremental ? instance.prevBuffer : null);
+						output = result.output;
+						buffer = result.buffer;
+						carryForwardBuffer = result.carryForwardBuffer;
+						incrementalOverlay = result.overlay;
+					} catch (e) {
+						renderError = e;
+						const attachedBuffer = e?.__silvery_buffer;
+						if (attachedBuffer) {
+							buffer = attachedBuffer;
+							carryForwardBuffer = attachedBuffer;
+						}
+					}
+					if (buffer) {
+						instance.prevBuffer = carryForwardBuffer ?? buffer;
+						instance.prevPaintedBuffer = buffer;
+					}
+					instance.renderCount++;
+					onBufferReady?.(output, buffer, getRootContentHeight());
+				});
+				if (!hadReactCommit) act(() => {
+					reconciler.flushSyncWork();
+				});
+			});
+			if (renderError) {
+				if (!(renderError instanceof IncrementalRenderMismatchError)) throw renderError;
+			}
+			if (!hadReactCommit) {
+				multiPassConverged = true;
+				break;
+			}
+			invalidateRootAfterLayoutFeedback(getContainerRoot(instance.container));
+			if (pass === cap - 1) recordPassRing("unknown", "layout-pass-exhaustion");
+			if (INSTRUMENT) {
+				notePassCommit(pass);
+				if (pass === cap - 1) logPass({
+					cause: "unknown",
+					detail: "layout-pass-exhaustion"
+				});
+			}
+		}
+		if (hadReactCommit && passCount >= cap) assertBoundedConvergence(passCount, "layout-pass", cap);
+		if (incremental && buffer && passCount > 1) buffer.markAllRowsDirty();
+		clsMonitor.onCommit(getContainerRoot(instance.container), instance.columns, instance.rows, false);
+		if (strictMode && instance.renderCount > 1 && multiPassConverged) {
+			const root = getContainerRoot(instance.container);
+			const { buffer: freshBuffer, overlay: freshOverlay } = doFreshRenderFull();
+			if (incrementalOverlay !== freshOverlay) throw new IncrementalRenderMismatchError(formatRendererOverlayMismatch(incrementalOverlay, freshOverlay, instance.renderCount));
+			for (let y = 0; y < buffer.height; y++) for (let x = 0; x < buffer.width; x++) {
+				const a = buffer.getCell(x, y);
+				const b = freshBuffer.getCell(x, y);
+				if (!cellEquals(a, b)) {
+					let trapInfo = "";
+					const trap = {
+						x,
+						y,
+						log: []
+					};
+					globalThis.__silvery_write_trap = trap;
+					try {
+						doFreshRender();
+					} catch {}
+					globalThis.__silvery_write_trap = null;
+					if (trap.log.length > 0) trapInfo = `\nWRITE TRAP (${trap.log.length} writes to (${x},${y})):\n${trap.log.join("\n")}\n`;
+					else trapInfo = `\nWRITE TRAP: NO WRITES to (${x},${y})\n`;
+					const ctx = buildMismatchContext(root, x, y, a, b, instance.renderCount);
+					const renderPhaseStats = globalThis.__silvery_content_detail ? structuredClone(globalThis.__silvery_content_detail) : void 0;
+					const debugInfo = formatMismatchContext(ctx, renderPhaseStats);
+					const incText = bufferToText(buffer);
+					const freshText = bufferToText(freshBuffer);
+					throw new IncrementalRenderMismatchError(debugInfo + trapInfo + `--- incremental ---\n${incText}\n--- fresh ---\n${freshText}`, {
+						renderPhaseStats,
+						mismatchContext: ctx
+					});
+				}
+			}
+			if (instance.prevBuffer && instance.renderCount > 1 && multiPassConverged && isResidueStrictEnabled()) {
+				const root2 = getContainerRoot(instance.container);
+				const realPrev = instance.prevBuffer.clone();
+				const poisonedPrev = instance.prevBuffer.clone();
+				poisonBufferWithSentinel(poisonedPrev);
+				const sentinelResult = runPipeline(root2, instance.columns, instance.rows, poisonedPrev, {
+					skipLayoutNotifications: true,
+					skipScrollStateUpdates: true,
+					fresh: true
+				});
+				const { buffer: freshFromZero } = doFreshRenderFull();
+				verifyNoResidueLeak(realPrev, sentinelResult.buffer, freshFromZero, instance.renderCount);
+			}
+		}
+		return output;
+	}
+	function doFreshRenderFull() {
+		const root = getContainerRoot(instance.container);
+		const freshLayout = isStrictEnabled(FRESH_LAYOUT_STRICT_SLUG, 2);
+		if (freshLayout) markLayoutTreeDirty(root);
+		const { buffer, overlay } = runPipeline(root, instance.columns, instance.rows, null, {
+			skipLayoutNotifications: true,
+			skipScrollStateUpdates: true,
+			fresh: true,
+			forceFullPropagate: freshLayout
+		});
+		return {
+			buffer,
+			overlay
+		};
+	}
+	function doFreshRender() {
+		return doFreshRenderFull().buffer;
+	}
+	instance.rendering = true;
+	try {
+		withActEnvironment(() => {
+			act(() => {
+				reconciler.updateContainerSync(wrapWithContexts(currentElement), instance.fiberRoot, null, null);
+				reconciler.flushSyncWork();
+			});
+		});
+	} finally {
+		instance.rendering = false;
+	}
+	/**
+	* Promote in-flight rect signals to their committed peers, then drain any
+	* resulting React work with one more `doRender()` if needed.
+	*
+	* Reactive `useBoxRect()` / `useScrollRect()` / `useScreenRect()` hooks
+	* read the COMMITTED rect signals (stable across all convergence passes
+	* within one batch). Calling `commitLayoutSnapshot` advances them by one
+	* frame, which may fire `effect()` callbacks that trigger React
+	* `forceUpdate`s. Those forceUpdates need to land before the test
+	* driver's caller observes the frame — otherwise the first frame would
+	* show the empty-rect fallback for any reactive layout consumer.
+	*
+	* The settle pass is bounded to ONE doRender. Any in-flight rect changes
+	* produced by it are intentionally NOT committed in this batch — they
+	* belong to the next event boundary (one-frame-late contract).
+	*
+	* See bead `@km/silvery/use-deferred-box-rect-and-post-commit-observers`.
+	*/
+	function settleAfterCommit(prevOutput) {
+		const root = getContainerRoot(instance.container);
+		let scheduled = false;
+		hadReactCommit = false;
+		withActEnvironment(() => {
+			act(() => {
+				commitLayoutSnapshot(root);
+			});
+			if (hadReactCommit) {
+				act(() => {
+					reconciler.flushSyncWork();
+				});
+				scheduled = true;
+			}
+		});
+		if (!scheduled) return prevOutput;
+		return doRender();
+	}
+	/**
+	* Drain additional commit / layout cycles until the React tree is stable
+	* (no pending commit, no dirty layout nodes) OR a budget is reached.
+	* Resolves once stable so tests can assert post-convergence state.
+	*
+	* The default is production timing — `render()` exposes a frame after the
+	* production-cap `MAX_CONVERGENCE_PASSES`. Tests asserting layout that
+	* requires more passes to settle (multi-layer measurement chains,
+	* Suspense-driven first-paint cascades, etc.) call this explicitly:
+	*
+	* ```ts
+	* const app = render(<MyApp />)
+	* await app.waitForLayoutStable()
+	* expect(app.text).toMatchSnapshot()
+	* ```
+	*
+	* Stability detection: a pass is run, then `flushSyncWork` runs in a
+	* separate `act()`. If `hadReactCommit` flips during the flush, layout
+	* is still in-flight; loop again (run another commit boundary + flush).
+	* Same predicate the renderer uses internally — does not invent a new
+	* readiness probe.
+	*
+	* Bounded by `maxPasses` (default 20) and `timeoutMs` (default 50ms).
+	* If the cap is reached, resolves WITHOUT throwing — an infinitely
+	* non-converging app is a bug, not a test fault. The contract is "best
+	* effort within the budget."
+	*
+	* Bead: `@km/silvery/test-harness-convergence-cap-parity`.
+	*/
+	async function waitForLayoutStable(opts) {
+		if (!instance.mounted) return;
+		const timeoutMs = opts?.timeoutMs ?? 50;
+		const maxPasses = opts?.maxPasses ?? 20;
+		const start = performance.now();
+		let lastFrame = instance.frames[instance.frames.length - 1] ?? "";
+		for (let pass = 0; pass < maxPasses; pass++) {
+			if (performance.now() - start >= timeoutMs) return;
+			if (!instance.mounted) return;
+			hadReactCommit = false;
+			instance.rendering = true;
+			try {
+				await act(async () => {
+					await Promise.resolve();
+				});
+			} finally {
+				instance.rendering = false;
+			}
+			const reactCommittedThisPass = hadReactCommit;
+			let next = lastFrame;
+			if (reactCommittedThisPass) next = doRender();
+			next = settleAfterCommit(next);
+			if (!reactCommittedThisPass && next === lastFrame && !hadReactCommit) {
+				try {
+					const root = getContainerRoot(instance.container);
+					if (root && !isAnyDirty(root.dirtyBits, root.dirtyEpoch)) return;
+				} catch {
+					return;
+				}
+				return;
+			}
+			if (next !== lastFrame) {
+				lastFrame = next;
+				instance.frames.push(next);
+				onFrame?.(next, instance.prevBuffer, getRootContentHeight());
+			}
+		}
+	}
+	let output = doRender();
+	output = settleAfterCommit(output);
+	instance.frames.push(output);
+	onFrame?.(output, instance.prevBuffer, getRootContentHeight());
+	if (debug) console.log("[silvery] Initial render:", output);
+	if (instance.prevBuffer) {
+		const bufW = instance.prevBuffer.width;
+		const bufH = instance.prevBuffer.height;
+		const totalCells = bufW * bufH;
+		if (totalCells >= 4e3) {
+			const painted = instance.prevBuffer.countPaintedCells();
+			const ratio = painted / totalCells;
+			if (ratio < .05) {
+				const msg = `silvery: degenerate frame after first render — only ${painted} of ${totalCells} cells painted (${(ratio * 100).toFixed(2)}%) at ${bufW}x${bufH}. Likely cause: the root component does not pin width/height (no <Screen> wrapper). createRenderer({cols, rows}) passes dimensions as the AVAILABLE size to layout, but does NOT set root.style.width/height — wrap the tree in <Box width={cols} height={rows}> or <Screen>. Per-test opt-out: SILVERY_STRICT=1,!canary. See @km/silvery/render-degenerate-frame-canary.`;
+				if (isStrictEnabled("canary", 2)) throw new Error(msg);
+				else log.debug?.(msg);
+			}
+		}
+	}
+	let stdinOnReadable;
+	if (stdinStream) {
+		stdinOnReadable = () => {
+			let chunk;
+			while ((chunk = stdinStream.read?.()) !== null && chunk !== void 0) instance.inputEmitter.emit("input", chunk);
+		};
+		stdinStream.on("readable", stdinOnReadable);
+	}
+	const getContainer = () => getContainerRoot(instance.container);
+	const getBuffer = () => instance.prevPaintedBuffer ?? instance.prevBuffer;
+	const sendInput = (data) => {
+		if (!instance.mounted) throw new Error("Cannot write to stdin after unmount");
+		if (instance.rendering) throw new Error("silvery: Re-entrant render detected. Cannot call press()/stdin.write() from inside a React render or effect. Use setTimeout or an event handler instead.");
+		const t0 = performance.now();
+		instance.rendering = true;
+		try {
+			let pasteResult = null;
+			try {
+				pasteResult = parseBracketedPaste(data);
+			} catch (err) {
+				if (isProtocolError(err)) log.debug?.(`bracketed paste parser flagged malformed input in press(): ${err.reason} (len=${err.inputLength})`);
+				else throw err;
+			}
+			if (pasteResult) withActEnvironment(() => {
+				act(() => {
+					instance.inputEmitter.emit("paste", pasteResult.content);
+				});
+			});
+			else withActEnvironment(() => {
+				for (const keypress of splitRawInput(data)) {
+					const [, key] = parseKey(keypress);
+					if (handleTabCycling && key.tab && !key.shift) {
+						act(() => {
+							const root = getContainerRoot(instance.container);
+							focusManager.focusNext(root);
+						});
+						continue;
+					}
+					if (handleTabCycling && key.tab && key.shift) {
+						act(() => {
+							const root = getContainerRoot(instance.container);
+							focusManager.focusPrev(root);
+						});
+						continue;
+					}
+					if (key.escape && focusManager.activeElement) {
+						act(() => {
+							focusManager.blur();
+						});
+						continue;
+					}
+					act(() => {
+						instance.inputEmitter.emit("input", keypress);
+					});
+				}
+			});
+		} finally {
+			instance.rendering = false;
+		}
+		const t1 = performance.now();
+		let newFrame = doRender();
+		let doRenderCount = 1;
+		if (instance.maxLayoutPasses <= MAX_CONVERGENCE_PASSES) {
+			let flushCount = 0;
+			if (INSTRUMENT) beginConvergenceLoop();
+			for (let flush = 0; flush < MAX_CONVERGENCE_PASSES; flush++) {
+				hadReactCommit = false;
+				flushCount = flush + 1;
+				if (INSTRUMENT) beginPass(flush);
+				withActEnvironment(() => {
+					act(() => {
+						reconciler.flushSyncWork();
+					});
+				});
+				if (!hadReactCommit) break;
+				if (flush === MAX_CONVERGENCE_PASSES - 1) recordPassRing("unknown", "effect-flush-exhaustion");
+				if (INSTRUMENT) {
+					notePassCommit(flush);
+					if (flush === MAX_CONVERGENCE_PASSES - 1) logPass({
+						cause: "unknown",
+						detail: "effect-flush-exhaustion"
+					});
+				}
+				newFrame = doRender();
+				doRenderCount++;
+			}
+			if (flushCount >= MAX_CONVERGENCE_PASSES && hadReactCommit) assertBoundedConvergence(flushCount, "effect-flush", MAX_CONVERGENCE_PASSES);
+		}
+		const settled = settleAfterCommit(newFrame);
+		if (settled !== newFrame) {
+			newFrame = settled;
+			doRenderCount++;
+		}
+		if (incremental && doRenderCount > 1 && instance.prevBuffer) instance.prevBuffer.markAllRowsDirty();
+		const t2 = performance.now();
+		instance.frames.push(newFrame);
+		onFrame?.(newFrame, instance.prevBuffer, getRootContentHeight());
+		if (debug) console.log("[silvery] stdin.write:", newFrame);
+		globalThis.__silvery_last_timing = {
+			actMs: t1 - t0,
+			renderMs: t2 - t1
+		};
+	};
+	const rerenderFn = (newElement) => {
+		if (!instance.mounted) throw new Error("Cannot rerender after unmount");
+		if (instance.rendering) throw new Error("silvery: Re-entrant render detected. Cannot call rerender() from inside a React render or effect.");
+		instance.rendering = true;
+		try {
+			withActEnvironment(() => {
+				act(() => {
+					currentElement = newElement;
+					reconciler.updateContainerSync(wrapWithContexts(currentElement), instance.fiberRoot, null, null);
+					reconciler.flushSyncWork();
+				});
+			});
+		} finally {
+			instance.rendering = false;
+		}
+		const newFrame = settleAfterCommit(doRender());
+		instance.frames.push(newFrame);
+		onFrame?.(newFrame, instance.prevBuffer, getRootContentHeight());
+		if (debug) console.log("[silvery] Rerender:", newFrame);
+	};
+	const renderTracker = {
+		unmount: () => {},
+		id: renderId
+	};
+	const renderRef = new WeakRef(renderTracker);
+	activeRenders.add(renderRef);
+	const unmountFn = () => {
+		if (!instance.mounted) throw new Error("Already unmounted");
+		const fiberRoot = instance.fiberRoot;
+		withActEnvironment(() => {
+			act(() => {
+				reconciler.updateContainerSync(null, fiberRoot, null, null);
+				reconciler.flushSyncWork();
+			});
+		});
+		renderScope[Symbol.asyncDispose]().catch((error) => reportDisposeError(error, {
+			phase: "app-exit",
+			scope: renderScope
+		}));
+		instance.mounted = false;
+		instance.rendering = false;
+		autoRenderScheduled = false;
+		inRenderCycle = false;
+		instance.inputEmitter.removeAllListeners();
+		stdoutEmitter.removeAllListeners();
+		if (stdinStream && stdinOnReadable) {
+			stdinStream.removeListener("readable", stdinOnReadable);
+			stdinOnReadable = void 0;
+		}
+		activeRenders.delete(renderRef);
+		clearFn();
+		instance.kittyActive = false;
+		releaseContainer(instance.container);
+		instance.fiberRoot = null;
+		if (debug) console.log("[silvery] Unmounted");
+	};
+	renderTracker.unmount = unmountFn;
+	const clearFn = () => {
+		instance.frames.length = 0;
+		instance.prevBuffer = null;
+		instance.prevPaintedBuffer = null;
+		instance.postState = createRenderPostState();
+	};
+	const debugFn = () => {
+		console.log(debugTree(getContainerRoot(instance.container)));
+	};
+	const actAndRenderFn = (fn) => {
+		if (!instance.mounted) return;
+		withActEnvironment(() => {
+			act(() => {
+				fn();
+				reconciler.updateContainerSync(wrapWithContexts(currentElement), instance.fiberRoot, null, null);
+				reconciler.flushSyncWork();
+			});
+		});
+		const newFrame = settleAfterCommit(doRender());
+		instance.frames.push(newFrame);
+		onFrame?.(newFrame, instance.prevBuffer, getRootContentHeight());
+	};
+	const resizeFn = (newCols, newRows) => {
+		if (!instance.mounted) throw new Error("Cannot resize after unmount");
+		instance.columns = newCols;
+		instance.rows = newRows;
+		mockStdout.columns = newCols;
+		mockStdout.rows = newRows;
+		updateMockTermSize?.(newCols, newRows);
+		stdoutEmitter.emit("resize");
+		instance.prevBuffer = null;
+		instance.prevPaintedBuffer = null;
+		instance.postState = createRenderPostState();
+		let newFrame = doRender();
+		let doRenderCount = 1;
+		if (instance.maxLayoutPasses <= MAX_CONVERGENCE_PASSES) for (let flush = 0; flush < MAX_CONVERGENCE_PASSES; flush++) {
+			hadReactCommit = false;
+			withActEnvironment(() => {
+				act(() => {
+					reconciler.flushSyncWork();
+				});
+			});
+			if (!hadReactCommit) break;
+			newFrame = doRender();
+			doRenderCount++;
+		}
+		const settled = settleAfterCommit(newFrame);
+		if (settled !== newFrame) {
+			newFrame = settled;
+			doRenderCount++;
+		}
+		const prevBufferForDirtying = instance.prevBuffer;
+		if (incremental && doRenderCount > 1 && prevBufferForDirtying) prevBufferForDirtying.markAllRowsDirty();
+		instance.frames.push(newFrame);
+		onFrame?.(newFrame, instance.prevBuffer, getRootContentHeight());
+		if (debug) console.log("[silvery] Resize:", newCols, "x", newRows);
+	};
+	return buildApp({
+		getContainer,
+		getBuffer,
+		sendInput,
+		rerender: rerenderFn,
+		unmount: unmountFn,
+		waitUntilExit: () => Promise.resolve(),
+		clear: clearFn,
+		exitCalled: () => exitCalledFlag,
+		exitError: () => exitErrorValue,
+		freshRender: doFreshRender,
+		debugFn,
+		frames: instance.frames,
+		columns: cols,
+		rows,
+		kittyMode,
+		actAndRender: actAndRenderFn,
+		resize: resizeFn,
+		focusManager,
+		getCursorState: cursorStore.accessors.getCursorState,
+		waitForLayoutStable,
+		clsMonitor
+	});
+}
+/**
+* Create a Store from provider options.
+*
+* A Store is the TermDef-like environment: cols, rows, and optionally events.
+*
+* @example
+* ```tsx
+* const store = createStore({ cols: 80, rows: 24 })
+* const app = render(<App />, store)
+* ```
+*/
+function createStore(options = {}) {
+	const { cols = 80, rows = 24, events: eventsSource } = options;
+	const store = {
+		cols,
+		rows
+	};
+	if (eventsSource) store.events = () => eventsSource;
+	return store;
+}
+/**
+* Create a render function that auto-cleans previous renders.
+*
+* By default, incremental rendering is ENABLED for test renders.
+* This matches production behavior (live scheduler uses incremental)
+* and enables withDiagnostics to catch incremental vs fresh mismatches.
+*
+* **Instance reuse:** When the same renderer is called repeatedly with a
+* compatible element (no overrides that would require fresh state), the
+* returned function calls `current.rerender(element)` instead of
+* unmount+remount. This avoids paying the full React reconciler init +
+* fiberRoot creation cost on each iteration — which otherwise dominates
+* cold-render microbenchmarks. See bead `km-silvery.renderer-reuse`.
+*
+* Reuse is skipped (forcing fresh mount) when:
+* - The previous instance has been unmounted (rerender would throw)
+* - Per-render overrides are supplied that conflict with baseOpts
+*   (e.g., flipping `incremental`, `maxLayoutPasses`, or `kittyMode`)
+* - The base options are a Store (store-mode renders manage their own
+*   lifecycle and we conservatively force a fresh mount)
+*
+* @example
+* ```tsx
+* const render = createRenderer({ cols: 80, rows: 24 })
+* const app1 = render(<Foo />)  // fresh mount
+* const app2 = render(<Bar />)  // reuses app1 via rerender()
+* // app1 === app2 when reuse kicks in
+*
+* // Explicitly disable incremental if needed
+* const render2 = createRenderer({ cols: 80, rows: 24, incremental: false })
+* ```
+*/
+function createRenderer(optsOrStore = {}) {
+	let current = null;
+	let currentReusable = false;
+	const baseOpts = isStore(optsOrStore) ? {
+		incremental: true,
+		cols: optsOrStore.cols,
+		rows: optsOrStore.rows
+	} : {
+		incremental: true,
+		...optsOrStore
+	};
+	return (element, overrides) => {
+		if (current && currentReusable && canReuseInstance(overrides, baseOpts)) try {
+			current.rerender(element);
+			return current;
+		} catch {
+			currentReusable = false;
+		}
+		if (current) try {
+			current.unmount();
+		} catch {}
+		let opts = baseOpts;
+		if (overrides && !isStore(opts)) opts = {
+			...opts,
+			...overrides
+		};
+		current = render(element, opts);
+		currentReusable = true;
+		return current;
+	};
+}
+/**
+* Can we reuse the current App instance for this call? Overrides that would
+* change reconciler/layout semantics force a fresh mount.
+*/
+function canReuseInstance(overrides, baseOpts) {
+	if (!overrides) return true;
+	if (overrides.incremental !== void 0 && overrides.incremental !== (baseOpts.incremental ?? true)) return false;
+	if (overrides.maxLayoutPasses !== void 0 && overrides.maxLayoutPasses !== baseOpts.maxLayoutPasses) return false;
+	if (overrides.kittyMode !== void 0 && overrides.kittyMode !== (baseOpts.kittyMode ?? false)) return false;
+	return true;
+}
+function run(app, events) {
+	if (events !== void 0 && !isAsyncIterable(events)) {
+		const iter = Array.isArray(events) ? events : events;
+		const processedEvents = [];
+		for (const key of iter) {
+			app.stdin.write(keyToAnsi(key));
+			processedEvents.push(key);
+		}
+		return {
+			get text() {
+				return app.text;
+			},
+			app,
+			[Symbol.iterator]() {
+				return processedEvents[Symbol.iterator]();
+			}
+		};
+	}
+	let stopped = false;
+	const unmount = () => {
+		stopped = true;
+		app.unmount();
+	};
+	return {
+		get text() {
+			return app.text;
+		},
+		app,
+		unmount,
+		then(onfulfilled, onrejected) {
+			return (async () => {
+				if (events) for await (const key of events) {
+					if (stopped) break;
+					await app.press(key);
+				}
+				else await app.run();
+			})().then(onfulfilled, onrejected);
+		},
+		[Symbol.asyncIterator]() {
+			if (!events) {
+				let yielded = false;
+				return { async next() {
+					if (yielded || stopped) return {
+						done: true,
+						value: void 0
+					};
+					yielded = true;
+					return {
+						done: false,
+						value: app.text
+					};
+				} };
+			}
+			const iter = events[Symbol.asyncIterator]();
+			return {
+				async next() {
+					if (stopped) return {
+						done: true,
+						value: void 0
+					};
+					const result = await iter.next();
+					if (result.done) return {
+						done: true,
+						value: void 0
+					};
+					await app.press(result.value);
+					return {
+						done: false,
+						value: app.text
+					};
+				},
+				async return() {
+					unmount();
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+			};
+		}
+	};
+}
+function isAsyncIterable(value) {
+	return value !== null && typeof value === "object" && Symbol.asyncIterator in value;
+}
+/**
+* Run a function with IS_REACT_ACT_ENVIRONMENT temporarily set to true.
+* This ensures act() works correctly without polluting the global scope.
+*/
+function withActEnvironment(fn) {
+	const prev = globalThis.IS_REACT_ACT_ENVIRONMENT;
+	globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+	try {
+		fn();
+	} finally {
+		globalThis.IS_REACT_ACT_ENVIRONMENT = prev;
+	}
+}
+/**
+* Get the number of currently active (mounted) render instances.
+* Useful for tests to verify cleanup.
+*/
+function getActiveRenderCount() {
+	return pruneAndCountActiveRenders();
+}
+/**
+* Format a human-readable diff when the incremental and fresh Kitty overlays
+* disagree. The overlay is a Kitty graphics protocol escape sequence emitted
+* by `realizeToKitty` (see `pipeline/backdrop/`) — it
+* places translucent "scrim" images over emoji cells inside faded regions.
+* The invariant is that the fresh and incremental paths emit byte-identical
+* strings for the same tree; any drift is a determinism bug.
+*
+* The diff surfaces the placement IDs that differ — the Kitty protocol uses
+* `p=<id>` in each placement command, so grep-friendly IDs are the quickest
+* path from "test failed" to "which cell drifted".
+*/
+function formatRendererOverlayMismatch(incremental, fresh, renderNum) {
+	const incPlacements = extractOverlayPlacementIds(incremental);
+	const freshPlacements = extractOverlayPlacementIds(fresh);
+	const incSet = new Set(incPlacements);
+	const freshSet = new Set(freshPlacements);
+	const onlyIncremental = incPlacements.filter((id) => !freshSet.has(id));
+	const onlyFresh = freshPlacements.filter((id) => !incSet.has(id));
+	const lines = [
+		`[SILVERY_STRICT] Kitty overlay mismatch at render #${renderNum}`,
+		`  incremental length: ${incremental.length} bytes, placements: ${incPlacements.length}`,
+		`  fresh       length: ${fresh.length} bytes, placements: ${freshPlacements.length}`
+	];
+	if (onlyIncremental.length > 0) lines.push(`  only in incremental (moved/appeared): ${onlyIncremental.join(", ")}`);
+	if (onlyFresh.length > 0) lines.push(`  only in fresh       (missing/disappeared): ${onlyFresh.join(", ")}`);
+	if (onlyIncremental.length === 0 && onlyFresh.length === 0) lines.push(`  placements match — drift is in scrim-image payload or ordering`);
+	const cap = 400;
+	lines.push(`  incremental[0..${cap}]: ${JSON.stringify(incremental.slice(0, cap))}`, `  fresh      [0..${cap}]: ${JSON.stringify(fresh.slice(0, cap))}`);
+	return lines.join("\n");
+}
+/**
+* Extract the list of `p=<id>` placement IDs from a Kitty overlay string, in
+* emission order. Used by the STRICT diagnostic to show which placements
+* moved/appeared/disappeared.
+*/
+function extractOverlayPlacementIds(overlay) {
+	const ids = [];
+	const re = /p=(\d+)/g;
+	let m;
+	while ((m = re.exec(overlay)) !== null) ids.push(m[1]);
+	return ids;
+}
+//#endregion
+//#region packages/test/src/index.tsx
+/**
+* Silvery Testing Library
+*
+* Unified App-based API for testing Silvery components.
+* Uses the actual silvery render pipeline for accurate ANSI output.
+*
+* ## Import Syntax
+*
+* ```tsx
+* import { createRenderer, bufferToText, stripAnsi } from '@silvery/test';
+* ```
+*
+* ## Auto-cleanup
+*
+* Each render() call from createRenderer automatically unmounts the previous render,
+* so you don't need explicit cleanup.
+*
+* ## Basic Testing
+*
+* @example
+* ```tsx
+* import { createRenderer } from '@silvery/test';
+* import { Text, Box } from '@silvery/ag-react';
+*
+* const render = createRenderer({ cols: 80, rows: 24 });
+*
+* test('renders text', () => {
+*   const app = render(<Text>Hello</Text>);
+*
+*   // Plain text (no ANSI)
+*   expect(app.text).toContain('Hello');
+*
+*   // Auto-refreshing locators
+*   expect(app.getByText('Hello').count()).toBe(1);
+* });
+* ```
+*
+* ## Keyboard Input Testing
+*
+* @example
+* ```tsx
+* test('handles keyboard', () => {
+*   const app = render(<MyComponent />);
+*
+*   await app.press('j');           // Letter key
+*   await app.press('ArrowUp');     // Arrow keys
+*   await app.press('Escape');      // Special keys
+*   await app.press('Enter');       // Enter
+*
+*   expect(app.text).toContain('expected result');
+* });
+* ```
+*
+* ## Auto-refreshing Locators
+*
+* @example
+* ```tsx
+* test('locators auto-refresh', () => {
+*   const app = render(<Board />);
+*   const cursor = app.locator('[data-cursor]');
+*
+*   expect(cursor.textContent()).toBe('item1');
+*   await app.press('j');
+*   expect(cursor.textContent()).toBe('item2');  // Same locator, fresh result!
+* });
+* ```
+*
+* ## Querying by ID
+*
+* Two equivalent approaches for identifying components:
+*
+* @example
+* ```tsx
+* // Option 1: id prop with #id selector (CSS-style, preferred)
+* const app = render(<Box id="sidebar">Content</Box>);
+* expect(app.locator('#sidebar').textContent()).toBe('Content');
+*
+* // Option 2: testID prop with getByTestId (React Testing Library style)
+* const app = render(<Box testID="sidebar">Content</Box>);
+* expect(app.getByTestId('sidebar').textContent()).toBe('Content');
+* ```
+*/
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+await ensureDefaultLayoutEngine();
+await preloadStrictTerminalBackends({
+	ghostty: true,
+	initGhosttyWasm: false
+});
+/**
+* Live-termless tracker. Each `createTermless()` registers a WeakRef to the
+* returned Term; when the Term is disposed (Symbol.dispose → emulator.close
+* → backend.destroy → xterm Terminal.dispose), the GC eventually clears the
+* ref. A large number of live un-disposed terminals typically means a test
+* forgot to use `using term = createTermless(...)` — the xterm Terminal
+* (1000-line scrollback buffer) stays resident until the worker exits.
+*
+* See bead km-silvery.termless-memleak.
+*/
+const liveTermlessInstances = /* @__PURE__ */ new Set();
+/** Tunable guard threshold — print a warning when we exceed this many live Terms. */
+const TERMLESS_LEAK_WARN_THRESHOLD = 128;
+/** Warning ID for the shared warnOnce latch. */
+const TERMLESS_LEAK_WARNING_ID = "silvery/test:termless-leak";
+/**
+* Prune GC'd entries from the tracker and return the count of still-live
+* instances. Cheap O(n) scan; n is small in practice.
+*/
+function pruneLiveTermless() {
+	let live = 0;
+	for (const ref of liveTermlessInstances) if (ref.deref() === void 0) liveTermlessInstances.delete(ref);
+	else live++;
+	return live;
+}
+/**
+* Return the current count of live (un-GC'd) termless Term instances.
+* Exported for tests that want to assert cleanup happened.
+*/
+function getActiveTermlessCount() {
+	return pruneLiveTermless();
+}
+function parseTermlessTrackpadFlickProfileFromDebugLog(logText, options = {}) {
+	const events = [];
+	for (const line of logText.split(/\r?\n/)) {
+		if (!line.startsWith("{")) continue;
+		let record;
+		try {
+			record = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		if (typeof record !== "object" || record === null) continue;
+		const obj = record;
+		if (obj.name !== "silvery:input-owner" || typeof obj.msg !== "string") continue;
+		if (!obj.msg.startsWith("parsed mouse: action=wheel")) continue;
+		const parsed = parseDebugWheelMessage(obj.msg, obj.time);
+		if (parsed !== null) events.push(parsed);
+	}
+	if (events.length === 0) throw new Error("No silvery input-owner wheel events found in debug log");
+	const first = events[0];
+	const cellSize = options.cellSize ?? inferDebugWheelCellSize(first);
+	const coordinateMode = options.coordinateMode ?? (cellSize === void 0 ? "cell" : "pixel");
+	return {
+		x: options.x ?? first.x,
+		y: options.y ?? first.y,
+		direction: first.delta < 0 ? "up" : "down",
+		coordinateMode,
+		...cellSize === void 0 ? {} : { cellSize },
+		packets: eventsToTrackpadPackets(events)
+	};
+}
+function parseDebugWheelMessage(msg, time) {
+	if (typeof time !== "string") return null;
+	const timestamp = Date.parse(time);
+	if (!Number.isFinite(timestamp)) return null;
+	const coords = msg.match(/\bx=([-0-9.]+)\s+y=([-0-9.]+)\s+delta=([-0-9.]+)/);
+	if (coords === null) return null;
+	const x = Number(coords[1]);
+	const y = Number(coords[2]);
+	const delta = Number(coords[3]);
+	if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(delta)) return null;
+	const sgr = msg.match(/\\u001b\[<(\d+);(\d+);(\d+)[Mm]/) ?? msg.match(new RegExp(`${String.fromCharCode(27)}\\[<(\\d+);(\\d+);(\\d+)[Mm]`));
+	return {
+		time: timestamp,
+		x,
+		y,
+		delta,
+		...sgr === null ? {} : {
+			button: Number(sgr[1]),
+			sgrX: Number(sgr[2]),
+			sgrY: Number(sgr[3])
+		}
+	};
+}
+function inferDebugWheelCellSize(event) {
+	if (event.sgrX === void 0 || event.sgrY === void 0 || event.x <= 0 || event.y <= 0) return;
+	const width = (event.sgrX - 1) / event.x;
+	const height = (event.sgrY - 1) / event.y;
+	if (!Number.isFinite(width) || !Number.isFinite(height)) return void 0;
+	if (width <= 1 || height <= 1) return void 0;
+	return {
+		width: Math.round(width * 1e3) / 1e3,
+		height: Math.round(height * 1e3) / 1e3
+	};
+}
+function eventsToTrackpadPackets(events) {
+	const firstTime = events[0].time;
+	const packets = [];
+	for (const event of events) {
+		const atMs = Math.max(0, Math.round(event.time - firstTime));
+		const last = packets[packets.length - 1];
+		if (last !== void 0 && last.atMs === atMs && last.delta === event.delta && last.button === event.button && last.x === void 0 && last.y === void 0) {
+			last.count = (last.count ?? 1) + 1;
+			continue;
+		}
+		packets.push({
+			atMs,
+			count: 1,
+			delta: event.delta,
+			...event.button === void 0 ? {} : { button: event.button }
+		});
+	}
+	return packets;
+}
+/** Default sleep between steps in `drag()`. Short enough to be fast, long
+* enough for async event dispatch to flush. */
+const DEFAULT_DRAG_STEP_DELAY_MS = 20;
+const DEFAULT_WHEEL_CADENCE_MS = 8;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const DEFAULT_REFLOW_RESIDUE_MARKER = "CMUX-REFLOW-RESIDUE";
+function strictTerminalRequestsGhostty(value) {
+	const normalized = value?.toLowerCase().trim();
+	if (!normalized) return false;
+	if (normalized === "all" || normalized === "both") return true;
+	return normalized.split(",").map((part) => part.trim()).includes("ghostty");
+}
+function inferBackendFromStrictTerminal() {
+	if (typeof process === "undefined") return void 0;
+	return strictTerminalRequestsGhostty(process.env.SILVERY_STRICT_TERMINAL) ? "ghostty" : void 0;
+}
+function withReflowResidue(backend, marker = DEFAULT_REFLOW_RESIDUE_MARKER) {
+	let armed = false;
+	const encoder = new TextEncoder();
+	const decoder = new TextDecoder();
+	const residue = {
+		marker,
+		arm() {
+			armed = true;
+		},
+		clear() {
+			armed = false;
+		},
+		get armed() {
+			return armed;
+		}
+	};
+	const wrapped = Object.create(backend);
+	Object.defineProperties(wrapped, {
+		name: { get() {
+			return `${backend.name}+reflow-residue`;
+		} },
+		init: { value(opts) {
+			backend.init(opts);
+		} },
+		destroy: { value() {
+			backend.destroy();
+		} },
+		feed: { value(data) {
+			const text = decoder.decode(data);
+			const defeatsResidue = text.includes("\x1B[2J") || text.includes("\x1B[H");
+			if (defeatsResidue) armed = false;
+			backend.feed(data);
+			if (armed && !defeatsResidue) backend.feed(encoder.encode(`\x1b[H${marker}`));
+		} },
+		resize: { value(cols, rows) {
+			backend.resize(cols, rows);
+			armed = true;
+		} }
+	});
+	return {
+		backend: wrapped,
+		residue
+	};
+}
+function applyMouseModifierBits(btn, options) {
+	if (options?.shift) btn += 4;
+	if (options?.alt || options?.meta) btn += 8;
+	if (options?.ctrl) btn += 16;
+	return btn;
+}
+function sgrButtonByte(options) {
+	return applyMouseModifierBits(options?.button ?? 0, options);
+}
+/**
+* Create a Term backed by a termless xterm.js emulator for full ANSI testing.
+*
+* Convenience wrapper around `createTerm(createXtermBackend(), dims)` that
+* handles the xterm.js backend import. Use with `run()` to render components
+* into a real terminal emulator in-process — no PTY, no timing issues.
+*
+* The returned Term exposes two testing conveniences:
+* - `term.mouse.*` — ergonomic mouse API (click, drag, down/up/move, wheel)
+* - `term.clipboard` — OSC 52 capture (`term.clipboard.last`, `.all`)
+*
+* **Always dispose with `using` or an explicit `term[Symbol.dispose]()`.**
+* Without disposal, each call leaks the xterm.js Terminal (~1 MB scrollback
+* per instance). This accumulated to 18-28 GB per vitest worker in CI before
+* `km-silvery.termless-memleak` was fixed.
+*
+* @example Mouse drag + clipboard capture
+* ```tsx
+* using term = createTermless({ cols: 40, rows: 10 })
+* const handle = await run(<App />, term, { selection: true, mouse: true })
+*
+* await term.mouse.drag({ from: [5, 2], to: [20, 2] })
+* expect(term.clipboard.last).toContain("selected text")
+* ```
+*
+* @example Plain click
+* ```tsx
+* await term.mouse.click(10, 5)
+* await term.mouse.click(10, 5, { shift: true })
+* ```
+*
+* @example Override capabilities (defaults-contract tests)
+* ```tsx
+* using term = createTermless({ cols: 80, rows: 24, caps: { colorLevel: '256' } })
+* ```
+*
+* Without a `caps` override, `term.caps` is populated from `defaultCaps()`
+* (truecolor / unicode / mouse). Callers that want a specific terminal
+* profile for a test — Apple_Terminal's lack of `maybeWideEmojis`, Kitty's
+* `kittyKeyboard`, etc. — can pass a `Partial<TerminalCaps>` here.
+*/
+function createTermless(dims = {
+	cols: 80,
+	rows: 24
+}) {
+	const envBackend = typeof process !== "undefined" ? process.env.TERMLESS_BACKEND : void 0;
+	const choice = dims.backend ?? envBackend ?? inferBackendFromStrictTerminal() ?? "xterm";
+	let backend;
+	if (choice === "ghostty") backend = createGhosttyBackend();
+	else if (choice === "ghostty-native") backend = createGhosttyNativeBackend();
+	else if (choice === "xterm") backend = createXtermBackend();
+	else throw new Error(`[silvery/test] createTermless: unknown backend "${choice}". Valid choices: "xterm", "ghostty", "ghostty-native". For a custom backend, call createTerm(backend, dims) directly.`);
+	let reflowResidue;
+	if (dims.reflowResidue) {
+		const marker = typeof dims.reflowResidue === "object" ? dims.reflowResidue.marker : void 0;
+		const wrapped = withReflowResidue(backend, marker);
+		backend = wrapped.backend;
+		reflowResidue = wrapped.residue;
+	}
+	const term = createTerm(backend, dims);
+	liveTermlessInstances.add(new WeakRef(term));
+	const live = pruneLiveTermless();
+	if (live >= TERMLESS_LEAK_WARN_THRESHOLD) warnOnce(TERMLESS_LEAK_WARNING_ID, () => {
+		console.warn(`[silvery/test] ${live} live termless Term instances detected — likely a test forgot to use \`using term = createTermless(...)\`. Each un-disposed Term retains an xterm.js Terminal with ~1 MB scrollback. See bead km-silvery.termless-memleak.`);
+	});
+	const sendInput = (data) => {
+		term.sendInput(data);
+	};
+	const PIXEL_CELL_W = 8;
+	const PIXEL_CELL_H = 17;
+	const SGR_PIXELS_ENABLE = "\x1B[?1016h";
+	let cachedPixelMode = null;
+	const out = term.out;
+	function isPixelMode() {
+		if (cachedPixelMode !== null) return cachedPixelMode;
+		if (!out) return false;
+		if (out.getText().includes(SGR_PIXELS_ENABLE)) {
+			cachedPixelMode = true;
+			return true;
+		}
+		return false;
+	}
+	function encodeCoord(cellX, cellY, options) {
+		const coordinateMode = options?.coordinateMode ?? "auto";
+		if (coordinateMode === "pixel" || coordinateMode === "auto" && isPixelMode()) {
+			const cellSize = options?.cellSize ?? {
+				width: PIXEL_CELL_W,
+				height: PIXEL_CELL_H
+			};
+			const pixelX = cellX * cellSize.width;
+			const pixelY = cellY * cellSize.height;
+			return {
+				sgrX: Math.round(pixelX) + 1,
+				sgrY: Math.round(pixelY) + 1
+			};
+		}
+		return {
+			sgrX: cellX + 1,
+			sgrY: cellY + 1
+		};
+	}
+	function packetEventCount(packet) {
+		const count = packet.count ?? packet.events ?? Math.abs(packet.delta ?? 1);
+		return Math.max(0, Math.floor(count));
+	}
+	function packetDelta(packet, profile) {
+		if (packet.delta !== void 0) return packet.delta;
+		return (packet.direction ?? profile.direction ?? "up") === "up" ? -1 : 1;
+	}
+	function packetButton(packet, profile) {
+		if (packet.button !== void 0) return packet.button;
+		return packetDelta(packet, profile) < 0 ? 64 : 65;
+	}
+	function groupTrackpadPackets(packets) {
+		const sorted = packets.map((packet, order) => ({
+			packet,
+			order
+		})).sort((a, b) => a.packet.atMs - b.packet.atMs || a.order - b.order);
+		const groups = [];
+		for (const { packet } of sorted) {
+			const atMs = Math.max(0, Math.round(packet.atMs));
+			const last = groups[groups.length - 1];
+			if (last && last.atMs === atMs) last.packets.push(packet);
+			else groups.push({
+				atMs,
+				packets: [packet]
+			});
+		}
+		return groups;
+	}
+	const mouse = {
+		async down(x, y, options) {
+			const btn = sgrButtonByte(options);
+			const { sgrX, sgrY } = encodeCoord(x, y);
+			sendInput(`\x1b[<${btn};${sgrX};${sgrY}M`);
+			await Promise.resolve();
+		},
+		async up(x, y, options) {
+			const btn = sgrButtonByte(options);
+			const { sgrX, sgrY } = encodeCoord(x, y);
+			sendInput(`\x1b[<${btn};${sgrX};${sgrY}m`);
+			await Promise.resolve();
+		},
+		async move(x, y, options) {
+			const btn = 32 + sgrButtonByte(options);
+			const { sgrX, sgrY } = encodeCoord(x, y);
+			sendInput(`\x1b[<${btn};${sgrX};${sgrY}M`);
+			await Promise.resolve();
+		},
+		async click(x, y, options) {
+			await mouse.down(x, y, options);
+			await mouse.up(x, y, options);
+		},
+		async dblclick(x, y, options) {
+			await mouse.click(x, y, options);
+			await mouse.click(x, y, options);
+		},
+		async drag({ from, to, via, options, stepDelay = DEFAULT_DRAG_STEP_DELAY_MS }) {
+			await mouse.down(from[0], from[1], options);
+			await sleep(stepDelay);
+			if (via) for (const [x, y] of via) {
+				await mouse.move(x, y, options);
+				await sleep(stepDelay);
+			}
+			await mouse.move(to[0], to[1], options);
+			await sleep(stepDelay);
+			await mouse.up(to[0], to[1], options);
+		},
+		async wheel(x, y, deltaOrOptions, maybeOptions) {
+			const options = typeof deltaOrOptions === "number" ? maybeOptions : deltaOrOptions;
+			const deltaX = typeof deltaOrOptions === "number" ? options?.deltaX ?? 0 : deltaOrOptions.deltaX ?? 0;
+			const deltaY = typeof deltaOrOptions === "number" ? deltaOrOptions : deltaOrOptions.deltaY ?? deltaOrOptions.lines ?? 0;
+			const { sgrX, sgrY } = encodeCoord(x, y, {
+				coordinateMode: options?.coordinateMode,
+				cellSize: options?.cellSize
+			});
+			const reports = [];
+			const appendReports = (baseButton, count) => {
+				const button = applyMouseModifierBits(baseButton, options);
+				for (let i = 0; i < count; i++) reports.push(`\x1b[<${button};${sgrX};${sgrY}M`);
+			};
+			const horizontalCount = Math.max(0, Math.floor(Math.abs(deltaX)));
+			if (horizontalCount > 0) appendReports(deltaX < 0 ? 66 : 67, horizontalCount);
+			const verticalCount = Math.max(0, Math.floor(Math.abs(deltaY)));
+			if (verticalCount > 0) appendReports(deltaY < 0 ? 64 : 65, verticalCount);
+			const cadenceMs = options?.cadenceMs ?? DEFAULT_WHEEL_CADENCE_MS;
+			for (let index = 0; index < reports.length; index++) {
+				sendInput(reports[index]);
+				await Promise.resolve();
+				if (cadenceMs > 0 && index < reports.length - 1) await sleep(cadenceMs);
+			}
+		},
+		async trackpadFlick(profile, options) {
+			const groups = groupTrackpadPackets(profile.packets);
+			const deliveredGroups = [];
+			let lastAtMs = 0;
+			let eventCount = 0;
+			for (let index = 0; index < groups.length; index++) {
+				const group = groups[index];
+				const waitMs = Math.max(0, group.atMs - lastAtMs);
+				if (waitMs > 0) await sleep(waitMs);
+				lastAtMs = group.atMs;
+				let chunk = "";
+				let deltaSum = 0;
+				let groupEventCount = 0;
+				for (const packet of group.packets) {
+					const count = packetEventCount(packet);
+					if (count === 0) continue;
+					const delta = packetDelta(packet, profile);
+					const button = packetButton(packet, profile);
+					const { sgrX, sgrY } = encodeCoord(packet.x ?? profile.x, packet.y ?? profile.y, {
+						coordinateMode: profile.coordinateMode,
+						cellSize: profile.cellSize
+					});
+					chunk += Array.from({ length: count }, () => `\x1b[<${button};${sgrX};${sgrY}M`).join("");
+					deltaSum += delta * count;
+					groupEventCount += count;
+				}
+				if (chunk.length === 0) continue;
+				sendInput(chunk);
+				eventCount += groupEventCount;
+				await Promise.resolve();
+				const deliveredGroup = {
+					index,
+					atMs: group.atMs,
+					packetCount: group.packets.length,
+					eventCount,
+					deltaSum
+				};
+				deliveredGroups.push(deliveredGroup);
+				await options?.afterGroup?.(deliveredGroup);
+			}
+			if (profile.settleMs !== void 0 && profile.settleMs > 0) await sleep(profile.settleMs);
+			return {
+				eventCount,
+				durationMs: lastAtMs,
+				groups: deliveredGroups
+			};
+		}
+	};
+	const clipboardPayloads = [];
+	const emulator = term._emulator;
+	if (emulator) {
+		const origFeed = emulator.feed.bind(emulator);
+		const OSC52_RE = /* @__PURE__ */ new RegExp("\\x1b\\]52;c;([A-Za-z0-9+/=]*)\\x07", "g");
+		emulator.feed = (data) => {
+			OSC52_RE.lastIndex = 0;
+			let match;
+			while ((match = OSC52_RE.exec(data)) !== null) try {
+				const decoded = globalThis.Buffer.from(match[1], "base64").toString("utf-8");
+				clipboardPayloads.push(decoded);
+			} catch {}
+			origFeed(data);
+		};
+	}
+	const clipboard = {
+		get last() {
+			return clipboardPayloads.length > 0 ? clipboardPayloads[clipboardPayloads.length - 1] : null;
+		},
+		get all() {
+			return clipboardPayloads;
+		},
+		clear() {
+			clipboardPayloads.length = 0;
+		}
+	};
+	Object.defineProperty(term, "mouse", {
+		value: mouse,
+		enumerable: true
+	});
+	Object.defineProperty(term, "clipboard", {
+		value: clipboard,
+		enumerable: true
+	});
+	if (reflowResidue) Object.defineProperty(term, "reflowResidue", {
+		value: reflowResidue,
+		enumerable: true
+	});
+	return term;
+}
+/**
+* Normalize frame output for comparison.
+* - Strips ANSI codes
+* - Trims trailing whitespace from lines
+* - Removes empty trailing lines
+*/
+function normalizeFrame(frame) {
+	return stripAnsi(frame).split("\n").map((line) => line.trimEnd()).join("\n").trimEnd();
+}
+/**
+* Wait for a condition to be true, polling at intervals.
+* Useful for waiting for async state updates.
+*/
+async function waitFor(condition, { timeout = 1e3, interval = 10 } = {}) {
+	const start = Date.now();
+	while (!condition()) {
+		if (Date.now() - start > timeout) throw new Error(`waitFor timed out after ${timeout}ms`);
+		await new Promise((resolve) => {
+			setTimeout(resolve, interval);
+		});
+	}
+}
+//#endregion
+export { CLS_STRICT_MIN_TIER, CLS_STRICT_SLUG, CODE_TO_KEY, UnexpectedLayoutShiftError, bufferToHTML, bufferToStyledText, bufferToText, compareBuffers, createAutoLocator, createRenderer, createStore, createTermless, debugTree, diagnosticScheme, diagnosticTheme, ensureEngine, formatMismatch, formatSelectableCells, getActiveRenderCount, getActiveTermlessCount, isClsStrictEnabled, keyToAnsi, keyToKittyAnsi, normalizeFrame, parseTermlessTrackpadFlickProfileFromDebugLog, readCellRow, readCellSnapshot, recordFrames, render, run, stripAnsi, waitFor };
+
+//# sourceMappingURL=test.mjs.map