pi-libtui 0.3.2

package/test/content-text.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+import { sanitizeTuiAnsiChunk, sanitizeTuiFieldPreview, sanitizeTuiTextPreview } from "../src/content/terminal-text.ts";
+
+test("sanitizes split SGR and OSC sequences only after their boundary arrives", () => {
+	const sgrStart = sanitizeTuiAnsiChunk("before\x1b[3");
+	const sgrEnd = sanitizeTuiAnsiChunk(`${sgrStart.pending}1mred`);
+	const oscStart = sanitizeTuiAnsiChunk("before\x1b]52;c;secret");
+	const oscEnd = sanitizeTuiAnsiChunk(`${oscStart.pending}\x1b\\after`);
+
+	expect(sgrStart.text).toBe("before");
+	expect(sgrEnd.text).toBe("\x1b[31mred");
+	expect(oscStart.text).toBe("before");
+	expect(oscEnd.text).toBe("after");
+});
+
+test("bounds display previews without splitting Unicode or terminal controls", () => {
+	expect(sanitizeTuiTextPreview("a🙂b", 2)).toBe("a…");
+	expect(sanitizeTuiTextPreview("a🙂b", 3)).toBe("a🙂…");
+	expect(sanitizeTuiTextPreview("before\x1b]52;c;secret", 12)).toBe("before…");
+	expect(sanitizeTuiFieldPreview("one\ntwo\tthree", 7)).toBe("one two…");
+});

package/test/cursor-bridge.test.ts

@@ -0,0 +1,151 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { CURSOR_MARKER, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+import { configureTuiAppearance, DEFAULT_TUI_APPEARANCE } from "../src/appearance.ts";
+import { markNativeCursorPosition, renderSemanticCursor } from "../src/cursor.ts";
+import { installCursorBridge } from "../src/host/cursor-bridge.ts";
+
+// type-boundary: The cursor bridge fixture implements only the TUI surface used by the compatibility patch.
+type TuiBoundary = unknown;
+// type-boundary: The cursor renderer fixture implements only the theme methods used by semantic colors.
+type ThemeBoundary = unknown;
+
+const theme = {
+	name: "dark",
+	fg: (_color: string, text: string) => text,
+	bg: (_color: string, text: string) => text,
+	getFgAnsi: () => "",
+	getBgAnsi: () => "",
+} as ThemeBoundary as Theme;
+
+class CursorTuiFixture {
+	readonly mode = "fullscreen";
+	readonly writes: string[] = [];
+	readonly terminal = { write: (data: string) => this.writes.push(data) };
+	visible: boolean;
+
+	constructor(visible = false) {
+		this.visible = visible;
+	}
+
+	getShowHardwareCursor(): boolean {
+		return this.visible;
+	}
+	setShowHardwareCursor(enabled: boolean): void {
+		this.visible = enabled;
+	}
+
+	extractCursorPosition(lines: string[], height: number): { row: number; col: number } | null {
+		const top = Math.max(0, lines.length - height);
+		for (let row = lines.length - 1; row >= top; row -= 1) {
+			const marker = lines[row]?.indexOf(CURSOR_MARKER) ?? -1;
+			if (marker < 0) continue;
+			const line = lines[row] ?? "";
+			const col = visibleWidth(line.slice(0, marker));
+			lines[row] = line.slice(0, marker) + line.slice(marker + CURSOR_MARKER.length);
+			return { row, col };
+		}
+		return null;
+	}
+}
+
+describe("semantic hardware cursor bridge", () => {
+	afterEach(() => configureTuiAppearance(DEFAULT_TUI_APPEARANCE));
+
+	test("positions a native cursor, applies its DEC shape, and removes private markers", () => {
+		configureTuiAppearance({ insertionCursor: "blinking-bar" });
+		const fixture = new CursorTuiFixture();
+		const dispose = installCursorBridge(fixture as TuiBoundary as TUI);
+		const lines = [`before ${renderSemanticCursor(theme, "\x1b[31mx\x1b[0m", { role: "insertion" })} after`];
+
+		expect(fixture.extractCursorPosition(lines, 20)).toEqual({ row: 0, col: 7 });
+		expect(fixture.visible).toBe(true);
+		expect(fixture.writes).toEqual(["\x1b[5 q"]);
+		expect(lines[0]).toBe("before \x1b[31mx\x1b[0m after");
+		dispose();
+		expect(fixture.visible).toBe(false);
+		expect(fixture.writes.at(-1)).toBe("\x1b[0 q");
+	});
+
+	test("applies an embedded terminal's projected native cursor shape", () => {
+		const fixture = new CursorTuiFixture();
+		const dispose = installCursorBridge(fixture as TuiBoundary as TUI);
+		const lines = [markNativeCursorPosition(`copy ${CURSOR_MARKER}x`, "blinking-block")];
+
+		expect(fixture.extractCursorPosition(lines, 1)).toEqual({ row: 0, col: 5 });
+		expect(fixture.visible).toBe(true);
+		expect(fixture.writes).toEqual(["\x1b[1 q"]);
+		expect(lines[0]).toBe("copy x");
+		dispose();
+	});
+
+	test("restores a live hardware-cursor preference after a native role", () => {
+		configureTuiAppearance({ navigationCursor: "steady-block" });
+		const fixture = new CursorTuiFixture(true);
+		const dispose = installCursorBridge(fixture as TuiBoundary as TUI);
+		const native = [renderSemanticCursor(theme, "x", { role: "navigation" })];
+		fixture.extractCursorPosition(native, 1);
+		expect(fixture.visible).toBe(true);
+
+		fixture.setShowHardwareCursor(false);
+		expect(fixture.visible).toBe(true);
+		configureTuiAppearance({ navigationCursor: "virtual" });
+		const virtual = [renderSemanticCursor(theme, "x", { role: "navigation" })];
+		expect(fixture.extractCursorPosition(virtual, 1)).toBeNull();
+		expect(fixture.visible).toBe(false);
+		expect(fixture.writes).toEqual(["\x1b[2 q", "\x1b[0 q"]);
+		dispose();
+	});
+
+	test("uses the DEC parameter for every configured native cursor name", () => {
+		const cases = [
+			["terminal-default", 0],
+			["blinking-block", 1],
+			["steady-block", 2],
+			["blinking-underline", 3],
+			["steady-underline", 4],
+			["blinking-bar", 5],
+			["steady-bar", 6],
+		] as const;
+		for (const [style, parameter] of cases) {
+			configureTuiAppearance({ selectionCursor: style });
+			const fixture = new CursorTuiFixture();
+			const dispose = installCursorBridge(fixture as TuiBoundary as TUI);
+			const lines = [renderSemanticCursor(theme, "x", { role: "selection" })];
+			fixture.extractCursorPosition(lines, 1);
+			expect(fixture.writes[0]).toBe(`\x1b[${parameter} q`);
+			dispose();
+		}
+	});
+
+	test("keeps one renderer active until its final bridge lease is released", () => {
+		configureTuiAppearance({ insertionCursor: "steady-bar" });
+		const fixture = new CursorTuiFixture();
+		const tui = fixture as TuiBoundary as TUI;
+		const disposeFirst = installCursorBridge(tui);
+		const disposeSecond = installCursorBridge(tui);
+		fixture.extractCursorPosition([renderSemanticCursor(theme, "x", { role: "insertion" })], 1);
+
+		disposeFirst();
+		expect(fixture.visible).toBe(true);
+		expect(fixture.writes).toEqual(["\x1b[6 q"]);
+		disposeSecond();
+		expect(fixture.visible).toBe(false);
+		expect(fixture.writes).toEqual(["\x1b[6 q", "\x1b[0 q"]);
+	});
+
+	test("carries the baseline preference across a renderer replacement", () => {
+		configureTuiAppearance({ insertionCursor: "blinking-bar" });
+		const previous = new CursorTuiFixture(false);
+		const dispose = installCursorBridge(previous as TuiBoundary as TUI);
+		previous.extractCursorPosition([renderSemanticCursor(theme, "x", { role: "insertion" })], 1);
+		expect(previous.getShowHardwareCursor()).toBe(true);
+
+		// Pi seeds the replacement with the previous renderer's effective value.
+		const next = new CursorTuiFixture(previous.getShowHardwareCursor());
+		next.extractCursorPosition(["plain"], 1);
+		expect(next.visible).toBe(false);
+		dispose();
+		expect(previous.visible).toBe(false);
+	});
+});

package/test/cursor.test.ts

@@ -0,0 +1,147 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { CURSOR_MARKER } from "@earendil-works/pi-tui";
+import { configureTuiAppearance, DEFAULT_TUI_APPEARANCE } from "../src/appearance.ts";
+import { tuiTheme } from "../src/color/theme.ts";
+import { SemanticInput } from "../src/controls/semantic-input.ts";
+import {
+	findCursorPresentation,
+	findCursorRole,
+	markNativeCursorPosition,
+	markEditorCursor,
+	removeUnmarkedEditorCursor,
+	renderSemanticCursor,
+	renderVirtualCursor,
+	stripCursorRoleMarkers,
+} from "../src/cursor.ts";
+
+describe("TUI cursor cleanup", () => {
+	afterEach(() => configureTuiAppearance(DEFAULT_TUI_APPEARANCE));
+
+	test("removes the unfocused editor cursor without removing native selection", () => {
+		expect(removeUnmarkedEditorCursor("prompt \x1b[7m界\x1b[0m rest")).toBe("prompt 界 rest");
+		expect(removeUnmarkedEditorCursor("prompt \x1b[7m界\x1b[27m rest")).toBe("prompt \x1b[7m界\x1b[27m rest");
+		expect(removeUnmarkedEditorCursor("prompt \x1b_pi:c\x07\x1b[7m界\x1b[0m rest")).toBe(
+			"prompt \x1b_pi:c\x07\x1b[7m界\x1b[0m rest",
+		);
+	});
+
+	test("leaves multi-grapheme inverse styling alone", () => {
+		const line = "prompt \x1b[7mtext\x1b[0m rest";
+		expect(removeUnmarkedEditorCursor(line)).toBe(line);
+	});
+
+	test("marks a focused wrapped editor cursor when Pi omitted its marker", () => {
+		expect(markEditorCursor("prompt \x1b[7m界\x1b[0m rest")).toBe("prompt \x1b_pi:c\x07\x1b[7m界\x1b[0m rest");
+		expect(markEditorCursor("prompt \x1b_pi:c\x07\x1b[7m界\x1b[0m rest")).toContain("\x1b_pi:c\x07");
+	});
+
+	test("preserves Pi's native cursor styling when Pi already emitted its marker", () => {
+		const line = markEditorCursor("before \x1b_pi:c\x07\x1b[7m界\x1b[0m after");
+		expect(line).toBe("before \x1b_pi:c\x07\x1b[7m界\x1b[0m after");
+	});
+
+	test("renders a virtual cursor through libtui's semantic surface and text colors", () => {
+		const theme = {
+			name: "harmonious",
+			fg: (_color: string, text: string) => text,
+			bg: (_color: string, text: string) => text,
+			getFgAnsi: () => "",
+			getBgAnsi: () => "",
+		} as unknown as Theme;
+		const rendered = renderVirtualCursor(theme, " ");
+		expect(rendered).toContain("\x1b[7m \x1b[27m");
+	});
+
+	test("can render a softer virtual cursor from a semantic surface", () => {
+		const theme = {
+			name: "harmonious",
+			fg: (_color: string, text: string) => text,
+			bg: (_color: string, text: string) => text,
+			getFgAnsi: () => "",
+			getBgAnsi: () => "",
+		} as unknown as Theme;
+		configureTuiAppearance({ softCursor: true });
+		const rendered = renderVirtualCursor(theme, " ");
+		const colors = tuiTheme(theme);
+		expect(rendered).toBe(colors.bg("surface.cursor", colors.fg("text.primary", " ")));
+		expect(rendered).not.toContain("\x1b[7m");
+	});
+
+	test("renders an active copy cursor with the high-contrast amber cursor", () => {
+		const theme = {
+			name: "harmonious",
+			fg: (_color: string, text: string) => text,
+			bg: (_color: string, text: string) => text,
+			getFgAnsi: () => "",
+			getBgAnsi: () => "",
+		} as unknown as Theme;
+		const colors = tuiTheme(theme);
+		expect(renderVirtualCursor(theme, "x", { selected: true })).toBe(
+			`\x1b[1m${colors.fgAnsi("cursor.selectedText")}${colors.bgAnsi("cursor.selected")}x\x1b[0m`,
+		);
+	});
+
+	test("lets copy mode opt into the softer cursor surface", () => {
+		const theme = {
+			name: "harmonious",
+			fg: (_color: string, text: string) => text,
+			bg: (_color: string, text: string) => text,
+			getFgAnsi: () => "",
+			getBgAnsi: () => "",
+		} as unknown as Theme;
+		configureTuiAppearance({ softCursor: true });
+		const colors = tuiTheme(theme);
+		expect(renderVirtualCursor(theme, "x", { mode: "copy" })).toBe(
+			`\x1b[1m${colors.fgAnsi("text.primary")}${colors.bgAnsi("surface.cursor")}x\x1b[0m`,
+		);
+	});
+
+	test("keeps an IME marker for virtual insertion but not virtual navigation", () => {
+		const theme = {
+			name: "harmonious",
+			fg: (_color: string, text: string) => text,
+			bg: (_color: string, text: string) => text,
+			getFgAnsi: () => "",
+			getBgAnsi: () => "",
+		} as unknown as Theme;
+		expect(renderSemanticCursor(theme, "x", { role: "insertion" })).toContain("\x1b_pi:c\x07");
+		expect(renderSemanticCursor(theme, "x", { role: "navigation" })).not.toContain("\x1b_pi:c\x07");
+	});
+
+	test("pairs a role only with Pi's selected cursor marker", () => {
+		configureTuiAppearance({ insertionCursor: "blinking-bar", navigationCursor: "steady-bar" });
+		const insertion = renderSemanticCursor({} as Theme, "x", { role: "insertion" });
+		const navigation = renderSemanticCursor({} as Theme, "y", { role: "navigation" });
+		expect(findCursorRole([`${insertion}${navigation}`], 1)).toBe("insertion");
+		expect(findCursorRole([`\x1b_pi:c\x07x${navigation}`], 1)).toBeUndefined();
+		expect(findCursorRole([navigation], 1)).toBe("navigation");
+		expect(findCursorRole([navigation, "stale \x1b_pi-libtui:cursor:insertion\x07"], 2)).toBe("navigation");
+	});
+
+	test("preserves a projected terminal's concrete native cursor style", () => {
+		const rendered = markNativeCursorPosition(`x${CURSOR_MARKER}`, "blinking-block");
+		expect(findCursorPresentation([rendered], 1)).toEqual({ style: "blinking-block" });
+		expect(stripCursorRoleMarkers(rendered)).toBe(`x${CURSOR_MARKER}`);
+	});
+
+	test("does not invent a semantic cursor for an unfocused editor", () => {
+		const rendered = markEditorCursor("prompt \x1b[7m界\x1b[0m rest", { theme: {} as Theme, role: "insertion" });
+		expect(rendered).toBe("prompt 界 rest");
+		expect(rendered).not.toContain("\x1b_pi:c\x07");
+	});
+
+	test("restyles Pi Input's SGR 27 cursor and removes it when unfocused", () => {
+		configureTuiAppearance({ insertionCursor: "blinking-bar" });
+		const input = new SemanticInput({} as Theme);
+		input.setValue("abc");
+		input.focused = true;
+		const focused = input.render(20).join("\n");
+		expect(focused).toContain("\x1b_pi:c\x07\x1b_pi-libtui:cursor:insertion\x07");
+		expect(focused).not.toContain("\x1b[7m");
+		input.focused = false;
+		const unfocused = input.render(20).join("\n");
+		expect(unfocused).not.toContain("\x1b_pi:c\x07");
+		expect(unfocused).not.toContain("\x1b[7m");
+	});
+});

package/test/editor-chrome.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { stripTerminalSequences, visibleWidth } from "@earendil-works/pi-tui";
+import { tuiTheme } from "pi-libtui";
+import {
+	type EditorCompositionStyle,
+	renderEditorComposition,
+	renderEditorCompositionPreview,
+	renderEditorCompositionStatus,
+} from "pi-libtui/editor";
+
+const theme = {
+	name: "editor-chrome-test",
+	getColorMode: () => "truecolor",
+	getFgAnsi: () => "\x1b[38;2;100;140;200m",
+	getBgAnsi: () => "\x1b[48;2;24;28;36m",
+} as never as Theme;
+
+const style: EditorCompositionStyle = {
+	surface: "editor",
+	top: "half-block",
+	bottom: "none",
+	leftRail: "animated",
+	rightRail: "static",
+	promptMarker: ["▸", "▹"],
+	promptMarkerMotion: "always",
+	bottomStatus: true,
+	statusSeparator: "dot",
+	statusBand: "transparent",
+	inactiveRailTone: "accent",
+};
+
+describe("editor composition chrome", () => {
+	test("top rule renders the top quadrants", () => {
+		const topRuleStyle = { ...style, top: "rule" } as const;
+		const plain = renderEditorComposition(theme, topRuleStyle, {
+			width: 48,
+			content: ["draft"],
+			topStatus: { left: "Working", right: "ctx 4%" },
+		}).map(stripTerminalSequences);
+
+		expect(plain[0]).toContain("Working");
+		expect(plain[0]).toContain("ctx 4%");
+	});
+	test("keeps every composed row within the exact terminal width", () => {
+		const lines = renderEditorComposition(theme, style, {
+			width: 80,
+			content: ["draft"],
+			topStatus: { right: "~/src/agents · next · GPT-5.6 Sol · xhigh · fast" },
+			active: true,
+			elapsedMs: 720,
+		});
+
+		expect(lines.every((line) => visibleWidth(line) === 80)).toBe(true);
+		expect(stripTerminalSequences(lines.join("\n"))).toContain("draft");
+	});
+
+	test("uses the production renderer for complete candidate previews", () => {
+		const lines = renderEditorCompositionPreview(theme, { style }, 72);
+
+		expect(lines.every((line) => visibleWidth(line) === 72)).toBe(true);
+		expect(stripTerminalSequences(lines.join("\n"))).toContain("Ask anything, edit files, run tools");
+	});
+
+	test("continues the editor surface and rails through its standalone status row", () => {
+		const belowStyle = { ...style, bottomStatus: true } as const;
+		const lines = renderEditorCompositionStatus(theme, belowStyle, { left: "Working", right: "ctx 4%" }, 48, {
+			active: true,
+			elapsedMs: 400,
+		});
+
+		expect(lines).toHaveLength(1);
+		expect(stripTerminalSequences(lines[0] ?? "")).toContain("Working");
+		expect(stripTerminalSequences(lines[0] ?? "").trimEnd()).toEndWith("┃");
+		expect(visibleWidth(lines[0] ?? "")).toBe(48);
+	});
+
+	test("keeps the cap half-height and metadata inline when the prompt row has room", () => {
+		const lines = renderEditorComposition(theme, style, {
+			width: 48,
+			content: ["draft"],
+			topStatus: { right: "metadata" },
+		});
+
+		expect(visibleWidth(lines[0] ?? "")).toBe(48);
+		expect(stripTerminalSequences(lines[0] ?? "")).toStartWith("╻▄");
+		expect(stripTerminalSequences(lines[0] ?? "").trimEnd()).toEndWith("▄╻");
+		expect(lines[0]).not.toContain(tuiTheme(theme).bgAnsi("surface.editor"));
+		expect(stripTerminalSequences(lines[0] ?? "")).not.toContain("metadata");
+		expect(stripTerminalSequences(lines[1] ?? "")).toContain("draft");
+		expect(stripTerminalSequences(lines[1] ?? "")).toContain("metadata");
+	});
+
+	test("lifts metadata and expands the right rail when the prompt row needs the space", () => {
+		const lines = renderEditorComposition(theme, style, {
+			width: 48,
+			content: ["a draft long enough to consume the prompt row"],
+			topStatus: { right: "metadata" },
+		});
+
+		expect(stripTerminalSequences(lines[0] ?? "")).toContain("metadata");
+		expect(stripTerminalSequences(lines[0] ?? "")).toStartWith("╻▄");
+		expect(stripTerminalSequences(lines[0] ?? "").trimEnd()).toEndWith("┃");
+		expect(lines[0]).toContain(`${tuiTheme(theme).bgAnsi("surface.editor")} `);
+		expect(stripTerminalSequences(lines[1] ?? "")).not.toContain("metadata");
+	});
+
+	test("advances multi-frame prompt markers on the supplied UI timeline", () => {
+		const first = stripTerminalSequences(
+			renderEditorComposition(theme, style, { width: 40, content: ["draft"], elapsedMs: 0 })[1] ?? "",
+		);
+		const second = stripTerminalSequences(
+			renderEditorComposition(theme, style, { width: 40, content: ["draft"], elapsedMs: 200 })[1] ?? "",
+		);
+
+		expect(first).toStartWith("┃ ▸ ");
+		expect(second).toStartWith("┃ ▹ ");
+	});
+});

package/test/editor-layout.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import { Container, type Component, type TUI, VStack } from "@earendil-works/pi-tui";
+import { installEditorMinimumRows } from "../src/editor/layout.ts";
+
+function rows(...lines: string[]): Component {
+	return { render: () => lines, invalidate() {} };
+}
+
+describe("editor layout", () => {
+	test("removes Pi's reserved border row for a borderless editor and restores it on dispose", () => {
+		const editor = rows("transition", "prompt");
+		const editorContainer = new Container();
+		editorContainer.addChild(editor);
+		const dock = new VStack([
+			{ component: editorContainer, minSize: 3 },
+			{ component: rows("footer"), minSize: 1 },
+		]);
+		let renders = 0;
+		const tui = { layoutRoot: dock, requestRender: () => renders++ } as never as TUI;
+		const lease = installEditorMinimumRows(tui, 2);
+
+		expect(dock.render(80)).toEqual(["transition", "prompt", "", "footer"]);
+		lease.reconcile(editor);
+		expect(dock.render(80)).toEqual(["transition", "prompt", "footer"]);
+
+		lease.dispose();
+		expect(dock.render(80)).toEqual(["transition", "prompt", "", "footer"]);
+		expect(renders).toBe(1);
+	});
+});

package/test/editor-registry.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test";
+import { runInNewContext } from "node:vm";
+import { CustomEditor, type KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import {
+	dispatchEditorPaste,
+	dispatchEditorRender,
+	EDITOR_REGISTRY_KEY,
+	type EditorRegistry,
+	ensureEditorRegistry,
+} from "../src/editor.ts";
+import { installEditorBridge } from "../src/host/editor-bridge.ts";
+
+// type-boundary: these tests provide only the host methods exercised by Pi's CustomEditor.
+type EditorHostBoundary = unknown;
+
+const tui = { terminal: { rows: 30, columns: 80 }, requestRender() {} } as EditorHostBoundary as never;
+const keys = { matches: () => false } as EditorHostBoundary as KeybindingsManager;
+const editorTheme = {
+	borderColor: (text: string) => text,
+	selectList: {
+		selectedPrefix: (text: string) => text,
+		selectedText: (text: string) => text,
+		description: (text: string) => text,
+		scrollInfo: (text: string) => text,
+		noMatch: (text: string) => text,
+	},
+} as EditorHostBoundary as never;
+
+const prototype = CustomEditor.prototype;
+
+function isolatedRegistry() {
+	return ensureEditorRegistry(Object.create(null) as typeof globalThis);
+}
+
+describe("editor registry ownership", () => {
+	test("reuses structurally valid hidden state from another JavaScript realm", () => {
+		// type-boundary: node:vm returns values from an isolated realm; the editor registry validator narrows it.
+		type ForeignRealmValue = unknown;
+		const foreignRegistry = runInNewContext(`
+			const state = { pasteHandlers: [], renderDecorators: [] };
+			const registry = {
+				protocol: "pi-libtui/editor/registry/v1",
+				version: 1,
+				registerPasteHandler(handler) {
+					state.pasteHandlers.push(handler);
+					return () => state.pasteHandlers.splice(state.pasteHandlers.indexOf(handler), 1);
+				},
+				registerRenderDecorator(decorator) {
+					state.renderDecorators.push(decorator);
+					return () => state.renderDecorators.splice(state.renderDecorators.indexOf(decorator), 1);
+				},
+			};
+			Object.defineProperty(registry, Symbol.for("pi-libtui/editor/registry-state/v1"), { value: state });
+			registry;
+		`) as ForeignRealmValue as EditorRegistry;
+		const scope = Object.create(null) as Record<PropertyKey, ForeignRealmValue>;
+		scope[EDITOR_REGISTRY_KEY] = foreignRegistry;
+
+		const registry = ensureEditorRegistry(scope as typeof globalThis);
+		registry.registerPasteHandler({ id: "foreign.paste", handle: (text) => text.toUpperCase() });
+		registry.registerRenderDecorator({ id: "foreign.render", decorate: (lines) => [...lines, "foreign"] });
+
+		expect(registry).toBe(foreignRegistry);
+		expect(dispatchEditorPaste(registry, "paste")).toBe("PASTE");
+		expect(dispatchEditorRender(registry, ["native"], 40)).toEqual(["native", "foreign"]);
+	});
+
+	test("replaces a compatible-looking registry with malformed hidden state", () => {
+		const scope = Object.create(null) as Record<PropertyKey, unknown>;
+		const malformed = {
+			protocol: "pi-libtui/editor/registry/v1",
+			version: 1,
+			registerPasteHandler: () => () => {},
+			registerRenderDecorator: () => () => {},
+		};
+		Object.defineProperty(malformed, Symbol.for("pi-libtui/editor/registry-state/v1"), {
+			value: { pasteHandlers: [null], renderDecorators: [] },
+		});
+		scope[EDITOR_REGISTRY_KEY] = malformed;
+
+		const registry = ensureEditorRegistry(scope as typeof globalThis);
+		expect(registry).not.toBe(malformed);
+		expect(dispatchEditorRender(registry, ["native"], 40)).toEqual(["native"]);
+	});
+
+	test("resolving the registry does not patch CustomEditor", () => {
+		const handleInput = prototype.handleInput;
+		const insertTextAtCursor = prototype.insertTextAtCursor;
+		const render = prototype.render;
+
+		ensureEditorRegistry(Object.create(null) as typeof globalThis);
+
+		expect(prototype.handleInput).toBe(handleInput);
+		expect(prototype.insertTextAtCursor).toBe(insertTextAtCursor);
+		expect(prototype.render).toBe(render);
+	});
+
+	test("the installed host bridge dispatches paste and render handlers", () => {
+		const registry = isolatedRegistry();
+		const removePaste = registry.registerPasteHandler({
+			id: "test.paste",
+			handle: (text) => (text === "image.png" ? "attachment-token" : undefined),
+		});
+		const removeDecorator = registry.registerRenderDecorator({
+			id: "test.render",
+			decorate: (lines) => [...lines, "decorated"],
+		});
+		const removeBridge = installEditorBridge(registry);
+		try {
+			const nativeEditor = new CustomEditor(tui, editorTheme, keys);
+			nativeEditor.insertTextAtCursor("image.png");
+			expect(nativeEditor.getText()).toBe("attachment-token");
+			expect(nativeEditor.render(40).at(-1)).toBe("decorated");
+
+			const bracketedEditor = new CustomEditor(tui, editorTheme, keys);
+			bracketedEditor.handleInput("\x1b[200~image.png\x1b[201~");
+			expect(bracketedEditor.getText()).toBe("attachment-token");
+		} finally {
+			removeBridge();
+			removeDecorator();
+			removePaste();
+		}
+	});
+
+	test("multiple bridge leases share one patch and restore after the last release", () => {
+		const handleInput = prototype.handleInput;
+		const insertTextAtCursor = prototype.insertTextAtCursor;
+		const render = prototype.render;
+		const registry = isolatedRegistry();
+		const releaseFirst = installEditorBridge(registry);
+		const wrappedHandleInput = prototype.handleInput;
+		const wrappedInsertTextAtCursor = prototype.insertTextAtCursor;
+		const wrappedRender = prototype.render;
+		const releaseSecond = installEditorBridge(registry);
+		try {
+			expect(prototype.handleInput).toBe(wrappedHandleInput);
+			expect(prototype.insertTextAtCursor).toBe(wrappedInsertTextAtCursor);
+			expect(prototype.render).toBe(wrappedRender);
+
+			releaseFirst();
+			releaseFirst();
+			expect(prototype.handleInput).toBe(wrappedHandleInput);
+			expect(prototype.insertTextAtCursor).toBe(wrappedInsertTextAtCursor);
+			expect(prototype.render).toBe(wrappedRender);
+
+			releaseSecond();
+			expect(prototype.handleInput).toBe(handleInput);
+			expect(prototype.insertTextAtCursor).toBe(insertTextAtCursor);
+			expect(prototype.render).toBe(render);
+		} finally {
+			releaseFirst();
+			releaseSecond();
+		}
+	});
+
+	test("render decorators replace by id without stale cleanup removing the active copy", () => {
+		const registry = isolatedRegistry();
+		const first = {
+			id: "shared.decorator",
+			decorate: (lines: readonly string[]) => [...lines, "first"],
+		};
+		const second = {
+			id: "shared.decorator",
+			decorate: (lines: readonly string[]) => [...lines, "second"],
+		};
+		const removeFirst = registry.registerRenderDecorator(first);
+		const removeSecond = registry.registerRenderDecorator(second);
+
+		try {
+			expect(dispatchEditorRender(registry, ["line"], 40)).toEqual(["line", "second"]);
+			removeFirst();
+			expect(dispatchEditorRender(registry, ["line"], 40)).toEqual(["line", "second"]);
+			removeSecond();
+			expect(dispatchEditorRender(registry, ["line"], 40)).toEqual(["line"]);
+		} finally {
+			removeFirst();
+			removeSecond();
+		}
+	});
+
+	test("release preserves a method replaced by another owner", () => {
+		const originalRenderDescriptor = Object.getOwnPropertyDescriptor(prototype, "render");
+		const originalRender = prototype.render;
+		const originalHandleInput = prototype.handleInput;
+		const originalInsertTextAtCursor = prototype.insertTextAtCursor;
+		const release = installEditorBridge(isolatedRegistry());
+		const externalRender = function externalRender(): string[] {
+			return ["external"];
+		};
+		prototype.render = externalRender;
+		try {
+			release();
+			expect(prototype.render).toBe(externalRender);
+			expect(prototype.handleInput).toBe(originalHandleInput);
+			expect(prototype.insertTextAtCursor).toBe(originalInsertTextAtCursor);
+		} finally {
+			release();
+			if (originalRenderDescriptor) Object.defineProperty(prototype, "render", originalRenderDescriptor);
+			else Reflect.deleteProperty(prototype, "render");
+			expect(prototype.render).toBe(originalRender);
+		}
+	});
+});