@luan.sh/pi-libtui 0.3.8

package/test/mouse/extension.test.ts

@@ -0,0 +1,205 @@
+import { expect, test } from "bun:test";
+import {
+	CustomEditor,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { dispatchEditorRender, ensureEditorRegistry } from "../../src/editor.ts";
+import mouseExtension from "../../src/extension.ts";
+
+type CommandHandler = (args: string, ctx: ExtensionCommandContext) => void | Promise<void>;
+type EventHandler = (event: object, ctx: ExtensionContext) => void | Promise<void>;
+
+// type-boundary: The focused extension harness implements only the ExtensionAPI methods exercised by mouseExtension.
+type ExtensionApiBoundary = unknown;
+
+// type-boundary: The focused context harness is narrowed to the UI methods exercised by command and lifecycle handlers.
+type ExtensionContextBoundary = unknown;
+
+// type-boundary: setWidget content is intentionally opaque to this registration test.
+type WidgetContentBoundary = unknown;
+
+// type-boundary: the focused theme harness implements only the color methods used by the paste decorator.
+type ThemeBoundary = unknown;
+
+const testTheme = {
+	name: "test",
+	getColorMode: () => "truecolor",
+	getFgAnsi: () => "\x1b[39m",
+	getBgAnsi: () => "\x1b[49m",
+} as ThemeBoundary as Theme;
+
+function stripAnsi(value: string): string {
+	return value.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, "");
+}
+
+function createPiHarness(eventBus?: object): {
+	api: ExtensionAPI;
+	handlers: Map<string, EventHandler[]>;
+	commands: Map<string, CommandHandler>;
+} {
+	const handlers = new Map<string, EventHandler[]>();
+	const commands = new Map<string, CommandHandler>();
+	const piHarness = {
+		...(eventBus === undefined ? {} : { events: eventBus }),
+		registerCommand(name: string, command: { handler: CommandHandler }) {
+			commands.set(name, command.handler);
+		},
+		on(name: string, handler: EventHandler) {
+			handlers.set(name, [...(handlers.get(name) ?? []), handler]);
+		},
+	};
+	const boundary: ExtensionApiBoundary = piHarness;
+	return { api: boundary as ExtensionAPI, handlers, commands };
+}
+
+function createContext(widgets: Array<{ key: string; content: WidgetContentBoundary }>): ExtensionContext {
+	const contextHarness = {
+		mode: "tui" as const,
+		hasUI: true,
+		ui: {
+			theme: testTheme,
+			setWorkingIndicator() {},
+			setWorkingMessage() {},
+			getTheme: () => testTheme,
+			setTheme() {},
+			setWidget(key: string, content: WidgetContentBoundary) {
+				widgets.push({ key, content });
+			},
+			notify() {},
+		},
+	};
+	const boundary: ExtensionContextBoundary = contextHarness;
+	return boundary as ExtensionContext;
+}
+
+test("lifecycle mounts and removes the invisible bridge", async () => {
+	const commands = new Map<string, CommandHandler>();
+	const events = new Map<string, EventHandler>();
+	const piHarness = {
+		registerCommand(name: string, command: { handler: CommandHandler }) {
+			commands.set(name, command.handler);
+		},
+		on(name: string, handler: EventHandler) {
+			events.set(name, handler);
+		},
+	};
+	const boundary: ExtensionApiBoundary = piHarness;
+	mouseExtension(boundary as ExtensionAPI);
+	expect(commands.has("libtui:colors")).toBe(true);
+
+	const widgets: Array<{ key: string; content: WidgetContentBoundary }> = [];
+	const notifications: string[] = [];
+	const contextHarness = {
+		mode: "tui",
+		hasUI: true,
+		ui: {
+			setWidget(key: string, content: WidgetContentBoundary) {
+				widgets.push({ key, content });
+			},
+			notify(message: string) {
+				notifications.push(message);
+			},
+		},
+	};
+	const contextBoundary: ExtensionContextBoundary = contextHarness;
+	const eventContext = contextBoundary as ExtensionContext;
+
+	await events.get("session_start")?.({}, eventContext);
+	expect(widgets.at(-1)?.key).toBe("pi-libtui.mouse-bridge");
+	expect(typeof widgets.at(-1)?.content).toBe("function");
+
+	await events.get("session_shutdown")?.({}, eventContext);
+	expect(widgets.at(-1)).toEqual({ key: "pi-libtui.mouse-bridge", content: undefined });
+	expect(notifications).toEqual([]);
+});
+
+test("does not claim the shared TUI host for a non-UI TUI session", async () => {
+	const events = new Map<string, EventHandler>();
+	const piHarness = {
+		on(name: string, handler: EventHandler) {
+			events.set(name, handler);
+		},
+		registerCommand() {},
+	};
+	const boundary: ExtensionApiBoundary = piHarness;
+	mouseExtension(boundary as ExtensionAPI);
+
+	const widgets: Array<{ key: string; content: WidgetContentBoundary }> = [];
+	const contextBoundary: ExtensionContextBoundary = {
+		mode: "tui",
+		hasUI: false,
+		ui: {
+			setWidget(key: string, content: WidgetContentBoundary) {
+				widgets.push({ key, content });
+			},
+		},
+	};
+	const context = contextBoundary as ExtensionContext;
+
+	await events.get("session_start")?.({}, context);
+	await events.get("session_shutdown")?.({ reason: "quit" }, context);
+
+	expect(widgets).toEqual([]);
+});
+
+test("duplicate factory copies share one host lease and a later API installs independently", async () => {
+	const sharedEventBus = {};
+	const first = createPiHarness(sharedEventBus);
+	const factories = await Promise.all(
+		["one", "two", "three"].map(async (copy) => {
+			const module = await import(`../../src/extension.ts?host-copy=${copy}`);
+			return module.default;
+		}),
+	);
+	for (const factory of factories) factory(first.api);
+
+	expect(first.handlers.get("session_start")).toHaveLength(1);
+	expect(first.handlers.get("session_shutdown")).toHaveLength(2);
+
+	const widgets: Array<{ key: string; content: WidgetContentBoundary }> = [];
+	const context = createContext(widgets);
+	const originalRender = CustomEditor.prototype.render;
+	await first.handlers.get("session_start")?.[0]?.({}, context);
+	expect(widgets).toHaveLength(1);
+	expect(widgets[0]?.key).toBe("pi-libtui.mouse-bridge");
+	expect(CustomEditor.prototype.render).not.toBe(originalRender);
+
+	const registry = ensureEditorRegistry();
+	const rendered = dispatchEditorRender(registry, ["[paste #1 +1 lines]"], 40).join("\n");
+	expect(stripAnsi(rendered)).toContain("paste #1 +1 lines");
+
+	let replacementCalls = 0;
+	const removeReplacement = registry.registerRenderDecorator({
+		id: "pi-libtui.native-paste-markers",
+		decorate: (lines) => {
+			replacementCalls += 1;
+			return [...lines, "replacement"];
+		},
+	});
+	expect(dispatchEditorRender(registry, ["line"], 40)).toEqual(["line", "replacement"]);
+	expect(replacementCalls).toBe(1);
+	removeReplacement();
+
+	for (const handler of first.handlers.get("session_shutdown") ?? []) await handler({ reason: "switch" }, context);
+	expect(widgets.at(-1)).toEqual({ key: "pi-libtui.mouse-bridge", content: undefined });
+	expect(CustomEditor.prototype.render).toBe(originalRender);
+	const lateCopyName = "after-switch";
+	const lateCopy = await import(`../../src/extension.ts?host-copy=${lateCopyName}`);
+	lateCopy.default(first.api);
+	expect(first.handlers.get("session_start")).toHaveLength(1);
+	for (const handler of first.handlers.get("session_shutdown") ?? []) await handler({ reason: "reload" }, context);
+
+	const second = createPiHarness(sharedEventBus);
+	factories[0]!(second.api);
+	expect(second.handlers.get("session_start")).toHaveLength(1);
+	expect(second.handlers.get("session_shutdown")).toHaveLength(2);
+	const secondWidgets: Array<{ key: string; content: WidgetContentBoundary }> = [];
+	const secondContext = createContext(secondWidgets);
+	await second.handlers.get("session_start")?.[0]?.({}, secondContext);
+	expect(secondWidgets).toHaveLength(1);
+	for (const handler of second.handlers.get("session_shutdown") ?? [])
+		await handler({ reason: "reload" }, secondContext);
+});

package/test/mouse/registry.test.ts

@@ -0,0 +1,140 @@
+import { expect, test } from "bun:test";
+import { getMouseRegistryState } from "../../src/mouse/registry.ts";
+import { ensureMouseRegistry, MOUSE_PROTOCOL, registerModalPointerShield } from "../../src/mouse.ts";
+
+test("the overlay registry is load-order independent and disposes by identity", () => {
+	const scope = Object.create(null) as typeof globalThis;
+	const registry = ensureMouseRegistry(scope);
+	const first = { id: "same-id", getRect: () => ({ x: 0, y: 0, width: 1, height: 1 }), onMouse: () => false };
+	const second = { ...first };
+	const removeFirst = registry.registerOverlayRegion(first);
+	registry.registerOverlayRegion(second);
+	expect(ensureMouseRegistry(scope)).toBe(registry);
+	expect(registry.protocol).toBe(MOUSE_PROTOCOL);
+	removeFirst();
+	expect(getMouseRegistryState(registry).regions).toEqual([second]);
+});
+
+test("modal pointer shields consume selection gestures but leave wheel and hover available", () => {
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	const remove = registerModalPointerShield(registry, {
+		id: "dialog.shield",
+		getRect: () => ({ x: 0, y: 0, width: 80, height: 24 }),
+	});
+	const shield = getMouseRegistryState(registry).regions[0]!;
+	const event = {
+		row: 0,
+		col: 0,
+		screenRow: 0,
+		screenCol: 0,
+		button: undefined,
+		wheel: undefined,
+		shift: false,
+		alt: false,
+		ctrl: false,
+	};
+	expect(shield.onMouse({ ...event, type: "press", button: 0 })).toBe(true);
+	expect(shield.onMouse({ ...event, type: "drag", button: 0 })).toBe(true);
+	expect(shield.onMouse({ ...event, type: "release", button: 0 })).toBe(true);
+	expect(shield.onMouse({ ...event, type: "wheel", wheel: -1 })).toBe(false);
+	remove();
+	expect(getMouseRegistryState(registry).regions).toEqual([]);
+});
+
+test("viewport input handlers are prioritized, composable, isolated, and disposable", () => {
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	const calls: string[] = [];
+	registry.registerViewportInputHandler({
+		id: "low",
+		handle(data) {
+			calls.push(`low:${data}`);
+			return undefined;
+		},
+	});
+	registry.registerViewportInputHandler({
+		id: "broken",
+		priority: 5,
+		handle() {
+			throw new Error("optional");
+		},
+	});
+	const removeHigh = registry.registerViewportInputHandler({
+		id: "high",
+		priority: 10,
+		handle(data) {
+			calls.push(`high:${data}`);
+			return { data: `${data}!` };
+		},
+	});
+	expect(registry.dispatchViewportInput("key")).toEqual({ data: "key!", consumed: false });
+	expect(calls).toEqual(["high:key", "low:key!"]);
+	removeHigh();
+	calls.length = 0;
+	const removeConsumer = registry.registerViewportInputHandler({
+		id: "consume",
+		priority: 20,
+		handle: () => ({ consume: true, data: "handled" }),
+	});
+	expect(registry.dispatchViewportInput("key")).toEqual({ data: "handled", consumed: true });
+	expect(calls).toEqual([]);
+	removeConsumer();
+});
+
+test("native copy deferrers isolate failures", () => {
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	registry.registerNativeCopyDeferrer(() => {
+		throw new Error("optional");
+	});
+	registry.registerNativeCopyDeferrer(() => false);
+	expect(registry.shouldDeferNativeCopy()).toBe(false);
+	const remove = registry.registerNativeCopyDeferrer(() => true);
+	expect(registry.shouldDeferNativeCopy()).toBe(true);
+	remove();
+	expect(registry.shouldDeferNativeCopy()).toBe(false);
+});
+
+test("screen decorators compose by priority and isolate failures", () => {
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	const calls: string[] = [];
+	const transcriptLines = ["logical zero", "logical one"];
+	let observedTranscriptLines: readonly string[] | undefined;
+	registry.registerScreenDecorator({
+		id: "low",
+		decorate(screen, context) {
+			observedTranscriptLines = context.transcriptLines;
+			calls.push(`low:${context.width}:${screen[0]}`);
+			return [...screen, "low"];
+		},
+	});
+	registry.registerScreenDecorator({
+		id: "broken",
+		priority: 5,
+		decorate() {
+			throw new Error("optional");
+		},
+	});
+	const removeHigh = registry.registerScreenDecorator({
+		id: "high",
+		priority: 10,
+		decorate(screen) {
+			calls.push(`high:${screen[0]}`);
+			return screen.map((line) => `${line}!`);
+		},
+	});
+	expect(
+		registry.dispatchScreenDecorators(["native"], {
+			width: 80,
+			height: 24,
+			hasOverlay: false,
+			transcriptLines,
+		}),
+	).toEqual(["native!", "low"]);
+	expect(observedTranscriptLines).toBe(transcriptLines);
+	expect(calls).toEqual(["high:native", "low:80:native!"]);
+	removeHigh();
+	calls.length = 0;
+	expect(registry.dispatchScreenDecorators(["native"], { width: 80, height: 24, hasOverlay: false })).toEqual([
+		"native",
+		"low",
+	]);
+});

package/test/mouse/screen-decoration.test.ts

@@ -0,0 +1,167 @@
+import { expect, test } from "bun:test";
+import { installScreenDecoration } from "../../src/host/mouse-bridge.ts";
+import { ensureMouseRegistry, type ScreenDecorationContext } from "../../src/mouse.ts";
+
+interface DecorationRenderer {
+	terminal: { columns: number; rows: number };
+	currentLayout: object;
+	selectionAnchor?: object;
+	selectionFocus?: object;
+	hasOverlay(): boolean;
+	applySelection(screen: string[], layout?: object): string[];
+}
+
+function rendererWith(prototype: object, hasOverlay = false, selectionActive = false): DecorationRenderer {
+	const renderer = {
+		terminal: { columns: 90, rows: 30 },
+		currentLayout: { identity: "fallback" },
+		selectionAnchor: selectionActive ? {} : undefined,
+		selectionFocus: selectionActive ? {} : undefined,
+		hasOverlay: () => hasOverlay,
+	} as DecorationRenderer;
+	Object.setPrototypeOf(renderer, prototype);
+	return renderer;
+}
+
+test("screen decoration runs after native selection with the exact current layout and ref-counts", () => {
+	const nativeCalls: string[][] = [];
+	const prototype = {
+		applySelection(screen: string[]): string[] {
+			nativeCalls.push(screen);
+			return [...screen, "native-selection"];
+		},
+	};
+	const original = prototype.applySelection;
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	const contexts: object[] = [];
+	registry.registerScreenDecorator({
+		id: "copy-mode",
+		decorate(screen, context) {
+			contexts.push(context);
+			return [...screen, "decorated"];
+		},
+	});
+	const firstDispose = installScreenDecoration(prototype, registry);
+	const patched = prototype.applySelection;
+	const secondDispose = installScreenDecoration(prototype, registry);
+	const renderer = rendererWith(prototype, true);
+	const replacementRenderer = rendererWith(prototype, false);
+	expect(renderer.applySelection(["screen"], { identity: "passed-layout" })).toEqual([
+		"screen",
+		"native-selection",
+		"decorated",
+	]);
+	expect(replacementRenderer.applySelection(["replacement"], { identity: "passed-layout" })).toEqual([
+		"replacement",
+		"native-selection",
+		"decorated",
+	]);
+	expect(nativeCalls).toEqual([["screen"], ["replacement"]]);
+	expect(contexts).toEqual([
+		{ width: 90, height: 30, hasOverlay: true, selectionActive: false, viewport: undefined },
+		{ width: 90, height: 30, hasOverlay: false, selectionActive: false, viewport: undefined },
+	]);
+	firstDispose();
+	expect(prototype.applySelection).toBe(patched);
+	secondDispose();
+	expect(prototype.applySelection).toBe(original);
+});
+
+test("screen decoration reports native selection state", () => {
+	const prototype = { applySelection: (screen: string[]) => screen };
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	let selectionActive = false;
+	registry.registerScreenDecorator({
+		id: "selection-state",
+		decorate(screen, context) {
+			selectionActive = context.selectionActive === true;
+			return screen;
+		},
+	});
+	const dispose = installScreenDecoration(prototype, registry);
+	rendererWith(prototype, false, true).applySelection(["screen"]);
+	expect(selectionActive).toBe(true);
+	dispose();
+});
+
+test("screen decoration exposes current logical transcript lines with their viewport", () => {
+	const prototype = { applySelection: (screen: string[]) => screen };
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	const lines = ["zero", "one", "two", "three"];
+	const scrollView = { scrollTop: 1, viewportHeight: 2, scrollTo() {} };
+	const component = { render: () => lines, invalidate() {} };
+	const renderer = rendererWith(prototype);
+	renderer.currentLayout = {
+		root: {
+			component,
+			rect: { x: 3, y: 4, width: 20, height: 2 },
+			clip: { x: 3, y: 4, width: 20, height: 2 },
+			children: [],
+			scrollView,
+			scrollContentLines: lines,
+		},
+		primaryScrollView: scrollView,
+	};
+	let context: ScreenDecorationContext | undefined;
+	registry.registerScreenDecorator({
+		id: "transcript",
+		decorate(screen, current) {
+			context = current;
+			return screen;
+		},
+	});
+	const dispose = installScreenDecoration(prototype, registry);
+	renderer.applySelection(["screen"]);
+
+	expect(context?.viewport).toEqual({ x: 3, y: 4, width: 20, height: 2, scrollTop: 1 });
+	expect(context?.transcriptLines).toBe(lines);
+	dispose();
+});
+
+test("no decorators preserve the exact native return", () => {
+	const native = ["same-array"];
+	const prototype = { applySelection: () => native };
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	const dispose = installScreenDecoration(prototype, registry);
+	const renderer = rendererWith(prototype);
+
+	expect(renderer.applySelection(["input"])).toBe(native);
+	dispose();
+});
+
+test("screen decoration lease survives a later delegating wrapper without stacking", () => {
+	const prototype = {
+		applySelection(screen: string[]): string[] {
+			return [...screen, "native"];
+		},
+	};
+	const original = prototype.applySelection;
+	const registry = ensureMouseRegistry(Object.create(null) as typeof globalThis);
+	let decorations = 0;
+	registry.registerScreenDecorator({
+		id: "count",
+		decorate(screen) {
+			decorations += 1;
+			return [...screen, "decorated"];
+		},
+	});
+	const firstDispose = installScreenDecoration(prototype, registry);
+	const decorationBridge = prototype.applySelection;
+	const wrapper = function (this: DecorationRenderer, screen: string[], layout?: object): string[] {
+		return Reflect.apply(decorationBridge, this, [screen, layout]);
+	};
+	prototype.applySelection = wrapper;
+	const renderer = rendererWith(prototype);
+	firstDispose();
+	expect(renderer.applySelection(["screen"])).toEqual(["screen", "native"]);
+	expect(decorations).toBe(0);
+
+	const secondDispose = installScreenDecoration(prototype, registry);
+	expect(prototype.applySelection).toBe(wrapper);
+	expect(renderer.applySelection(["screen"])).toEqual(["screen", "native", "decorated"]);
+	expect(decorations).toBe(1);
+
+	prototype.applySelection = decorationBridge;
+	secondDispose();
+	expect(prototype.applySelection).toBe(original);
+});

package/test/native-binary.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { join } from "node:path";
+import { locateNativeBinary, nativeBuildArguments, TERMINAL_BRIDGE } from "../src/native-binary.ts";
+
+const ENV = TERMINAL_BRIDGE.env;
+const options = (executables: readonly string[], environment: Record<string, string | undefined> = {}) => ({
+	environment,
+	platform: "linux" as const,
+	nativeRoot: "/agent/native",
+	rev: "v1.2.3",
+	isExecutable: (path: string) => executables.includes(path),
+});
+const managed = join("/agent/native", "terminal-bridge", "v1.2.3", "bin", "terminal_bridge");
+
+test("env override wins and must be executable", () => {
+	expect(locateNativeBinary(TERMINAL_BRIDGE, options(["/x/bridge"], { [ENV]: "/x/bridge" }))).toEqual({
+		kind: "found",
+		path: "/x/bridge",
+	});
+	expect(() => locateNativeBinary(TERMINAL_BRIDGE, options([], { [ENV]: "/x/missing" }))).toThrow("not executable");
+});
+
+test("a managed build for the pinned revision is used when present", () => {
+	expect(locateNativeBinary(TERMINAL_BRIDGE, options([managed]))).toEqual({ kind: "found", path: managed });
+});
+
+test("a miss outside a checkout asks for a build into the revision root", () => {
+	expect(locateNativeBinary(TERMINAL_BRIDGE, options([]))).toEqual({
+		kind: "build",
+		installRoot: join("/agent/native", "terminal-bridge", "v1.2.3"),
+		path: managed,
+	});
+});
+
+test("a checkout without a built binary is reported instead of built", () => {
+	const location = locateNativeBinary(TERMINAL_BRIDGE, { ...options([]), developmentStart: import.meta.dirname });
+	expect(location.kind).toBe("unbuilt-checkout");
+});
+
+test("build arguments pin the revision and install root", () => {
+	expect(nativeBuildArguments(TERMINAL_BRIDGE, "v1.2.3", "/agent/native/terminal-bridge/v1.2.3")).toEqual([
+		"install",
+		"--git",
+		"https://github.com/luan/agents",
+		"--rev",
+		"v1.2.3",
+		"--root",
+		"/agent/native/terminal-bridge/v1.2.3",
+		"--locked",
+		"terminal-bridge",
+	]);
+});

package/test/palette.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, test } from "bun:test";
+import { generateColor256, rgb } from "../src/color/palette.ts";
+import { parseBackgroundAnsi } from "../src/color/theme.ts";
+
+describe("color palette", () => {
+	test("parses only the requested basic SGR destination", () => {
+		expect(parseBackgroundAnsi("\x1b[31m\x1b[44m")).toEqual(rgb(0, 0, 128));
+		expect(parseBackgroundAnsi("\x1b[91m\x1b[104m")).toEqual(rgb(0, 0, 255));
+	});
+
+	test("fills the color cube and grayscale ramp from theme anchors", () => {
+		const anchors = [
+			rgb(10, 20, 30),
+			rgb(200, 20, 20),
+			rgb(20, 200, 20),
+			rgb(200, 200, 20),
+			rgb(20, 20, 200),
+			rgb(200, 20, 200),
+			rgb(20, 200, 200),
+			rgb(230, 230, 230),
+		];
+		const palette = generateColor256([...anchors, ...anchors], anchors[0]!, anchors[7]!);
+		expect(palette).toHaveLength(256);
+		expect(palette[16]).toEqual(anchors[0]);
+		expect(palette[21]).toEqual(anchors[4]);
+		expect(palette[46]).toEqual(anchors[2]);
+		expect(palette[196]).toEqual(anchors[1]);
+		expect(palette[231]).toEqual(anchors[7]);
+		expect(palette[232]).not.toEqual(palette[16]);
+		expect(palette[255]).not.toEqual(palette[231]);
+	});
+});

package/test/panels.test.ts

@@ -0,0 +1,74 @@
+import { expect, test } from "bun:test";
+import { ensureSidePanelRegistry, SIDE_PANEL_PROTOCOL, type SidePanelProvider } from "../src/panels.ts";
+
+function provider(id: string, session: object = {}): SidePanelProvider {
+	return { id, session, attach: () => undefined };
+}
+
+test("side-panel providers are load-order independent and identity safe", () => {
+	const scope = Object.create(null) as typeof globalThis;
+	const registry = ensureSidePanelRegistry(scope);
+	const first = provider("review");
+	const replacement = provider("review");
+
+	expect(ensureSidePanelRegistry(scope)).toBe(registry);
+	expect(registry.protocol).toBe(SIDE_PANEL_PROTOCOL);
+	expect(registry.version).toBe(1);
+	const removeFirst = registry.register(first);
+	const removeReplacement = registry.register(replacement);
+	removeFirst();
+	expect(registry.providers()).toEqual([replacement]);
+	removeReplacement();
+	expect(registry.providers()).toEqual([]);
+});
+
+test("side-panel host attaches providers in either load order and owns their lifecycle", () => {
+	const registry = ensureSidePanelRegistry(Object.create(null) as typeof globalThis);
+	const attached: string[] = [];
+	const detached: string[] = [];
+	const session = {};
+	const host = registry.installHost();
+	const detachHost = host.attach(session, {} as never, () => {});
+	const removeChat = registry.register({
+		id: "chat",
+		session,
+		attach: () => {
+			attached.push("chat");
+			return () => detached.push("chat");
+		},
+	});
+	const removeOther = registry.register({
+		id: "other",
+		session: {},
+		attach: () => {
+			attached.push("other");
+		},
+	});
+
+	expect(registry.hasHost()).toBe(true);
+	expect(attached).toEqual(["chat"]);
+	removeChat();
+	expect(detached).toEqual(["chat"]);
+	removeOther();
+	detachHost();
+	host.dispose();
+	expect(registry.hasHost()).toBe(false);
+});
+
+test("side-panel host isolates provider failures and attaches providers registered first", () => {
+	const registry = ensureSidePanelRegistry(Object.create(null) as typeof globalThis);
+	const session = {};
+	const errors: string[] = [];
+	const remove = registry.register({
+		id: "broken",
+		session,
+		attach: () => {
+			throw new Error("broken provider");
+		},
+	});
+	const host = registry.installHost();
+	expect(() => host.attach(session, {} as never, (provider) => errors.push(provider.id))).not.toThrow();
+	expect(errors).toEqual(["broken"]);
+	remove();
+	host.dispose();
+});