pi-libtui 0.3.2

package/test/split-pane.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import type { Component } from "@earendil-works/pi-tui";
+import {
+	ensureSplitPaneRegistry,
+	mountSplitPane,
+	SPLIT_PANE_PROTOCOL,
+	type SplitPaneDefinition,
+} from "../src/split-pane.ts";
+
+// type-boundary: Runtime-validation fixtures deliberately cross the split-pane contribution boundary.
+type InvalidDefinitionBoundary = unknown;
+
+function component(label: string): Component {
+	return {
+		render: (width) => [`${label}:${width}`],
+		invalidate() {},
+	};
+}
+
+function definition(overrides: Partial<SplitPaneDefinition> = {}): SplitPaneDefinition {
+	return {
+		id: "test.pane",
+		position: "right",
+		component: () => component("pane"),
+		size: 24,
+		minMainSize: 40,
+		...overrides,
+	};
+}
+
+describe("split-pane registry", () => {
+	test("is load-order independent and normalizes the active contribution", () => {
+		const scope = Object.create(null) as typeof globalThis;
+		const registry = ensureSplitPaneRegistry(scope);
+
+		expect(ensureSplitPaneRegistry(scope)).toBe(registry);
+		expect(registry.protocol).toBe(SPLIT_PANE_PROTOCOL);
+		expect(registry.version).toBe(2);
+		expect(registry.current()).toBeUndefined();
+
+		const source = definition();
+		const remove = mountSplitPane(source, scope);
+		expect(registry.current()).toEqual({ ...source, gap: 1, priority: 0 });
+		expect(registry.current()).not.toBe(source);
+
+		remove();
+		expect(registry.current()).toBeUndefined();
+	});
+
+	test("selects the highest priority and the latest mount among ties", () => {
+		const registry = ensureSplitPaneRegistry(Object.create(null) as typeof globalThis);
+		const changes: string[] = [];
+		registry.subscribe(() => changes.push(registry.current()?.id ?? "none"));
+		const removeHigh = registry.mount(definition({ id: "high", priority: 10 }));
+		const removeLow = registry.mount(definition({ id: "low", priority: -1 }));
+		const removeHighTie = registry.mount(definition({ id: "high-tie", priority: 10 }));
+
+		expect(registry.current()?.id).toBe("high-tie");
+		expect(changes).toEqual(["high", "high-tie"]);
+		removeLow();
+		expect(changes).toEqual(["high", "high-tie"]);
+		removeHighTie();
+		expect(registry.current()?.id).toBe("high");
+		removeHigh();
+		expect(changes).toEqual(["high", "high-tie", "high", "none"]);
+	});
+
+	test("uses the newest lease and reveals the previous pane when it is released", () => {
+		const registry = ensureSplitPaneRegistry(Object.create(null) as typeof globalThis);
+		const changes: Array<string | undefined> = [];
+		registry.subscribe(() => changes.push(registry.current()?.id));
+		const removeFirst = registry.mount(definition({ id: "first", position: "left", gap: 0 }));
+		const first = registry.current();
+		const removeSecond = registry.mount(definition({ id: "second", size: 30 }));
+
+		expect(registry.current()?.id).toBe("second");
+		removeFirst();
+		expect(registry.current()?.id).toBe("second");
+		expect(changes).toEqual(["first", "second"]);
+
+		removeSecond();
+		expect(registry.current()).toBeUndefined();
+		expect(changes).toEqual(["first", "second", undefined]);
+
+		// Disposers are identity-safe and idempotent even after another lease used the same id.
+		const removeReplacement = registry.mount(definition({ id: "first", size: 18 }));
+		removeFirst();
+		expect(registry.current()?.size).toBe(18);
+		removeReplacement();
+		expect(first?.id).toBe("first");
+	});
+
+	test("notifies independent listeners and isolates listener failures", () => {
+		const registry = ensureSplitPaneRegistry(Object.create(null) as typeof globalThis);
+		const calls: string[] = [];
+		registry.subscribe(() => {
+			throw new Error("optional listener failed");
+		});
+		const unsubscribe = registry.subscribe(() => calls.push(registry.current()?.id ?? "none"));
+
+		const remove = registry.mount(definition({ id: "visible" }));
+		expect(calls).toEqual(["visible"]);
+		unsubscribe();
+		unsubscribe();
+		remove();
+		expect(calls).toEqual(["visible"]);
+	});
+
+	test("rejects malformed identifiers, positions, factories, and geometry", () => {
+		const registry = ensureSplitPaneRegistry(Object.create(null) as typeof globalThis);
+		const invalid: InvalidDefinitionBoundary[] = [
+			definition({ id: "  " }),
+			{ ...definition(), position: "top" },
+			{ ...definition(), component: "not a factory" },
+			definition({ size: 0 }),
+			definition({ size: 1.5 }),
+			definition({ initialRatio: 0 }),
+			definition({ initialRatio: 1 }),
+			definition({ initialRatio: Number.NaN }),
+			{ ...definition(), onResize: "not a callback" },
+			definition({ minMainSize: 0 }),
+			definition({ minMainSize: Number.POSITIVE_INFINITY }),
+			definition({ gap: -1 }),
+			definition({ gap: 0.5 }),
+			definition({ priority: 0.5 }),
+			definition({ priority: Number.POSITIVE_INFINITY }),
+		];
+
+		for (const candidate of invalid) {
+			expect(() => registry.mount(candidate as SplitPaneDefinition)).toThrow();
+			expect(registry.current()).toBeUndefined();
+		}
+	});
+});

package/test/status-presentation.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { statusPresentationFrame } from "../src/status-presentation.ts";
+import { TUI_STATUS_PRESENTATION_OPTIONS, type TuiStatusPresentationStyle } from "../src/appearance.ts";
+import { tuiTheme } from "../src/color/theme.ts";
+
+const theme = {
+	name: "status-presentation-test",
+	getColorMode: () => "truecolor",
+	getFgAnsi: (token: string) => (token === "accent" ? "\x1b[38;2;80;160;240m" : "\x1b[38;2;180;180;180m"),
+	getBgAnsi: () => "\x1b[48;2;20;20;20m",
+} as never as Theme;
+
+const colors = tuiTheme(theme);
+const activeStyles = TUI_STATUS_PRESENTATION_OPTIONS.map((option) => option.value).filter(
+	(style): style is Exclude<TuiStatusPresentationStyle, "standard"> => style !== "standard",
+);
+
+describe("standalone status presentation", () => {
+	test.each(activeStyles)("renders %s within the requested row width", (style) => {
+		for (const width of [10, 24, 48]) {
+			const rendered = statusPresentationFrame(colors, style, 500, width);
+			expect(rendered).not.toBe("");
+			expect(visibleWidth(rendered)).toBeLessThanOrEqual(width);
+		}
+	});
+
+	test.each(activeStyles)("animates %s across real repaint samples", (style) => {
+		const frames = [0, 180, 420, 900, 1_800].map((elapsedMs) => statusPresentationFrame(colors, style, elapsedMs, 40));
+		expect(new Set(frames).size).toBeGreaterThan(1);
+	});
+
+	test.each(activeStyles)("holds %s still for reduced motion", (style) => {
+		const first = statusPresentationFrame(colors, style, 0, 40, { reducedMotion: true });
+		const later = statusPresentationFrame(colors, style, 4_000, 40, { reducedMotion: true });
+		expect(later).toBe(first);
+	});
+});

package/test/syntax.test.ts

@@ -0,0 +1,59 @@
+import { beforeAll, describe, expect, test } from "bun:test";
+import { highlightSyntaxBlock, whenSyntaxReady } from "../src/syntax.ts";
+
+beforeAll(async () => {
+	await new Promise<void>((resolve) => whenSyntaxReady(resolve));
+});
+
+describe("syntax highlighting", () => {
+	test("adapts Shiki tokens into semantic spans without changing source text", () => {
+		const source = "const Crab: usize = 42; // safe 🦀";
+		const [spans] = highlightSyntaxBlock(source, "src/main.rs");
+
+		expect(spans?.map((span) => span.text).join("")).toBe(source);
+		expect(spans?.filter((span) => span.foreground !== undefined).length).toBeGreaterThan(1);
+	});
+
+	test("falls back to Shiki plain text for unsupported filenames", () => {
+		const source = "ordinary words # remain ordinary";
+		const [spans] = highlightSyntaxBlock(source, "notes.unknown-language");
+
+		expect(spans?.map((span) => span.text).join("")).toBe(source);
+		expect(spans?.some((span) => span.emphasized)).toBe(false);
+	});
+
+	test("keeps JSON punctuation and values on the shared syntax path", () => {
+		const source = '{"value": true}';
+		const [spans] = highlightSyntaxBlock(source, ".json");
+
+		expect(spans?.map((span) => span.text).join("")).toBe(source);
+		expect(spans?.some((span) => span.text.includes('"value"') && span.foreground !== undefined)).toBe(true);
+		expect(spans?.some((span) => span.text.includes("true") && span.foreground !== undefined)).toBe(true);
+	});
+
+	test("uses shared shell spans for command syntax", () => {
+		const source = `echo "$HOME" && printf '%s\\n' ok`;
+		const [spans] = highlightSyntaxBlock(source, "script.sh");
+
+		expect(spans?.map((span) => span.text).join("")).toBe(source);
+		expect(spans?.filter((span) => span.foreground !== undefined).length).toBeGreaterThan(1);
+	});
+
+	test("keeps shell heredoc state across lines", () => {
+		const source = "cat <<EOF\nhello world\nEOF\necho done";
+		const lines = highlightSyntaxBlock(source, "script.sh");
+
+		expect(lines.map((line) => line.map((span) => span.text).join("")).join("\n")).toBe(source);
+		expect(lines[1]).toHaveLength(1);
+		expect(lines[1]?.[0]?.foreground).toEqual(lines[2]?.[0]?.foreground);
+	});
+
+	test("keeps JavaScript template strings open across lines", () => {
+		const source = "const message = `first\nsecond`;\nconsole.log(message);";
+		const lines = highlightSyntaxBlock(source, "message.js");
+
+		expect(lines.map((line) => line.map((span) => span.text).join("")).join("\n")).toBe(source);
+		expect(lines[1]?.[0]?.text).toBe("second`");
+		expect(lines[1]?.[0]?.foreground).toEqual(lines[0]?.at(-1)?.foreground);
+	});
+});

package/test/terminal-colors.test.ts

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import type { TUI, TuiInputListener } from "@earendil-works/pi-tui";
+import { rgb } from "../src/color/palette.ts";
+import { measureTerminalColors, terminalColorsRegistry } from "../src/terminal-colors.ts";
+
+afterEach(() => terminalColorsRegistry().publish(undefined));
+
+describe("terminal color detection", () => {
+	test("rejects stale or malformed cross-realm profiles", () => {
+		expect(() => terminalColorsRegistry().publish({ scheme: "dark", harmonious: true } as never)).toThrow(
+			"Invalid pi-libtui terminal color measurements",
+		);
+		expect(() =>
+			terminalColorsRegistry().publish({
+				defaultBackground: { r: 1.5, g: 2, b: 3 },
+				indexedPalette: "custom",
+				scheme: "dark",
+			}),
+		).toThrow("Invalid pi-libtui terminal color measurements");
+	});
+
+	test("publishes an immutable snapshot of measured colors", () => {
+		const defaultBackground = { r: 10, g: 20, b: 30 };
+		const ansiBase16 = Array.from({ length: 16 }, () => ({ r: 40, g: 50, b: 60 }));
+		terminalColorsRegistry().publish({
+			defaultBackground,
+			ansiBase16,
+			indexedPalette: "custom",
+			scheme: "dark",
+		});
+		defaultBackground.r = 200;
+		ansiBase16[0]!.g = 200;
+		expect(terminalColorsRegistry().current()?.defaultBackground).toEqual(rgb(10, 20, 30));
+		expect(terminalColorsRegistry().current()?.ansiBase16?.[0]).toEqual(rgb(40, 50, 60));
+	});
+
+	test("detects a harmonious palette without consuming ordinary input", async () => {
+		let listener: TuiInputListener | undefined;
+		const writes: string[] = [];
+		const tui = {
+			terminal: {
+				write(data: string) {
+					writes.push(data);
+					if (!data.includes("]10;?")) return;
+					listener?.("\x1b]10;rgb:ee/ee/ee\x1b\\");
+					listener?.("\x1b]4;16;rgb:1111/1111/1111\x1b\\");
+					listener?.("\x1b]4;231;rgb:eeee/eeee/eeee\x1b\\");
+				},
+			},
+			addInputListener(next: TuiInputListener) {
+				listener = next;
+				return () => {
+					listener = undefined;
+				};
+			},
+			queryTerminalBackgroundColor: async () => rgb(17, 17, 17),
+			queryTerminalColorScheme: async () => "dark",
+		} as never as TUI;
+		const profile = await measureTerminalColors(tui, 10);
+		expect(profile.scheme).toBe("dark");
+		expect(writes.some((value) => value.includes("]4;231;?"))).toBe(true);
+	});
+
+	test("frames split and batched replies while preserving residual input and consuming DA1", async () => {
+		let listener: TuiInputListener | undefined;
+		const listenerResults: ReturnType<TuiInputListener>[] = [];
+		const tui = {
+			terminal: {
+				write(data: string) {
+					if (!data.includes("]10;?")) return;
+					listenerResults.push(listener?.("\x1b]10;rgb:aaaa/") as ReturnType<TuiInputListener>);
+					listenerResults.push(
+						listener?.(
+							"bbbb/cccc\x1b\\left\x1b]4;16;rgb:1111/2222/3333\x07\x1b]4;231;rgb:dddd/eeee/ffff\x1b\\\x1b[?1;2cright",
+						) as ReturnType<TuiInputListener>,
+					);
+				},
+			},
+			addInputListener(next: TuiInputListener) {
+				listener = next;
+				return () => {
+					listener = undefined;
+				};
+			},
+			queryTerminalBackgroundColor: async () => rgb(17, 17, 17),
+			queryTerminalColorScheme: async () => "dark",
+		} as never as TUI;
+
+		const profile = await measureTerminalColors(tui, 20);
+		expect(profile.defaultForeground).toEqual(rgb(170, 187, 204));
+		expect(profile.indexedPalette).toBe("custom");
+		expect(profile).not.toHaveProperty("indexed16");
+		expect(profile).not.toHaveProperty("indexed231");
+		expect(listenerResults).toEqual([{ consume: true }, { data: "leftright" }]);
+		expect(listener).toBeUndefined();
+	});
+
+	test("quarantines late color replies after timeout without swallowing adjacent input", async () => {
+		let listener: TuiInputListener | undefined;
+		const tui = {
+			terminal: { write() {} },
+			addInputListener(next: TuiInputListener) {
+				listener = next;
+				return () => {
+					listener = undefined;
+				};
+			},
+			queryTerminalBackgroundColor: async () => undefined,
+			queryTerminalColorScheme: async () => undefined,
+		} as never as TUI;
+
+		await measureTerminalColors(tui, 10);
+		expect(listener?.("\x1b]10;rgb:11/22/33\x1b\\typed")).toEqual({ data: "typed" });
+	});
+});

package/test/terminal-embedding.test.ts

@@ -0,0 +1,12 @@
+import { expect, test } from "bun:test";
+import { stripTopLevelZoneMarkers } from "../src/terminal/embedding.ts";
+
+test("removes transcript zones embedded after another column", () => {
+	expect(
+		stripTopLevelZoneMarkers(["agent │ \x1b]133;A\x07\x1b[48;2;40;46;68mmessage\x1b]133;B\x1b\\\x1b]133;C\x07"]),
+	).toEqual(["agent │ \x1b[48;2;40;46;68mmessage"]);
+});
+
+test("preserves renderer styling and content", () => {
+	expect(stripTopLevelZoneMarkers(["\x1b[32mtool output\x1b[0m"])).toEqual(["\x1b[32mtool output\x1b[0m"]);
+});

package/test/terminal-projection.test.ts

@@ -0,0 +1,312 @@
+import { describe, expect, test } from "bun:test";
+import { CURSOR_MARKER, stripTerminalSequences } from "@earendil-works/pi-tui";
+import { TerminalOutput } from "../src/terminal/output.ts";
+import { type ProjectionScheduler, type ProjectionTimer, TerminalProjection } from "../src/terminal/projection.ts";
+import { findCursorPresentation } from "../src/cursor.ts";
+
+interface ScheduledTask {
+	at: number;
+	callback: () => void;
+	cancelled: boolean;
+}
+
+class FakeScheduler implements ProjectionScheduler {
+	currentTime = 1_000;
+	readonly tasks: ScheduledTask[] = [];
+
+	now(): number {
+		return this.currentTime;
+	}
+
+	schedule(callback: () => void, delayMs: number): ProjectionTimer {
+		const task = { at: this.currentTime + delayMs, callback, cancelled: false };
+		this.tasks.push(task);
+		return { dispose: () => (task.cancelled = true) };
+	}
+
+	advance(milliseconds = 0): void {
+		this.currentTime += milliseconds;
+		for (;;) {
+			const task = this.tasks.find((candidate) => !candidate.cancelled && candidate.at <= this.currentTime);
+			if (!task) return;
+			task.cancelled = true;
+			task.callback();
+		}
+	}
+
+	get pending(): number {
+		return this.tasks.filter((task) => !task.cancelled).length;
+	}
+}
+
+async function write(projection: TerminalProjection, data: string): Promise<void> {
+	projection.write(data);
+	await projection.drain();
+}
+
+test("TerminalOutput consumes cumulative append snapshots without retaining or replaying their prefix", async () => {
+	const output = new TerminalOutput({ requestRender() {}, cols: 40, rows: 4, maxRows: 4 });
+	output.appendCumulative("progress 10%\r");
+	output.appendCumulative("progress 10%\rprogress 100%\n");
+	await output.drain();
+	expect(output.render(40)).toEqual(["progress 100%"]);
+	output.dispose();
+});
+
+test("TerminalOutput renders the initial PTY snapshot during a synchronous repaint", () => {
+	const output = new TerminalOutput({ requestRender() {}, cols: 40, rows: 4, maxRows: 4 });
+	output.setText("progress 10%\rprogress 100%\n");
+
+	expect(output.render(40).map((line) => stripTerminalSequences(line))).toEqual(["progress 100%"]);
+	output.dispose();
+});
+
+test("TerminalOutput preserves PTY state when a caller selects cumulative-tail mode", async () => {
+	const output = new TerminalOutput({ requestRender() {}, cols: 40, rows: 4, maxRows: 4 });
+	const cumulative = `\x1b[31m${"red ".repeat(80)}`;
+	output.appendCumulative(cumulative);
+	await output.drain();
+	output.appendCumulativeTail(cumulative.slice(-100));
+	await output.drain();
+
+	const rendered = output.render(40);
+	expect(rendered.some((line) => line.includes("31m"))).toBe(true);
+	output.dispose();
+});
+
+test("TerminalOutput always replaces stale output even when replacement starts with an old tail", async () => {
+	const output = new TerminalOutput({ requestRender() {}, cols: 40, rows: 4, maxRows: 4 });
+	output.setText(`stale output\nshared-prefix-123456`);
+	output.setText("shared-prefix-123456\nauthoritative output");
+	await output.drain();
+
+	const rendered = output.render(40).join("\n");
+	expect(rendered).toContain("authoritative output");
+	expect(rendered).not.toContain("stale output");
+	output.dispose();
+});
+
+test("TerminalOutput appends a complete cumulative replacement without replaying its prefix", async () => {
+	const output = new TerminalOutput({ requestRender() {}, cols: 40, rows: 4, maxRows: 4 });
+	output.appendCumulative("one\r\n");
+	output.setText("one\r\ntwo");
+	await output.drain();
+
+	expect(output.render(40).join("\n")).toContain("one\ntwo");
+	output.dispose();
+});
+
+test("TerminalOutput exposes an omitted-prefix row for bounded history", async () => {
+	const output = new TerminalOutput({ requestRender() {}, cols: 40, rows: 8, maxRows: 3 });
+	output.setText("one\r\ntwo\r\nthree\r\nfour\r\nfive");
+	await output.drain();
+
+	expect(output.render(40).map((line) => stripTerminalSequences(line).trimEnd())).toEqual([
+		"… 3 rows omitted …",
+		"four",
+		"five",
+	]);
+	expect(output.getOmissionRow()).toBe(0);
+	output.dispose();
+});
+
+test("TerminalOutput delegates burst repaint throttling to its projection", async () => {
+	let renders = 0;
+	const output = new TerminalOutput({ requestRender: () => renders++, cols: 40, rows: 4, maxRows: 4 });
+	let cumulative = "";
+	for (let index = 0; index < 100; index++) {
+		cumulative += "x";
+		output.appendCumulative(cumulative);
+	}
+	await output.drain();
+
+	// The burst reaches the host in one microtask-coalesced repaint.
+	expect(renders).toBe(1);
+	expect(output.render(40).join("\n")).toContain("x".repeat(40));
+	output.dispose();
+});
+
+test("TerminalOutput never repaints after disposal", async () => {
+	let renders = 0;
+	const output = new TerminalOutput({ requestRender: () => renders++, cols: 40, rows: 4 });
+	output.setText("queued");
+	output.dispose();
+	await Bun.sleep(0);
+	expect(renders).toBe(0);
+});
+
+describe("TerminalProjection", () => {
+	test("hard-bounds dimensions, scrollback, and rendered history", async () => {
+		const projection = new TerminalProjection({
+			requestRender() {},
+			cols: 1_000_000,
+			rows: 1_000_000,
+			scrollback: 1_000_000,
+		});
+		expect(projection.cols).toBe(500);
+		expect(projection.rows).toBe(200);
+		projection.write("one\ntwo\nthree");
+		await projection.drain();
+		expect(projection.renderLines({ includeScrollback: true, maxRows: 2 })).toHaveLength(2);
+		projection.dispose();
+	});
+
+	test("projects carriage return, backspace, erase, and cursor movement", async () => {
+		const projection = new TerminalProjection({ requestRender() {}, cols: 8, rows: 3 });
+		await write(projection, "abc\rZ\bY");
+		expect(projection.renderLines()[0]).toBe(`Y${CURSOR_MARKER}bc`);
+
+		await write(projection, "\r\x1b[3C\x1b[K");
+		expect(projection.renderLines()[0]).toBe(`Ybc${CURSOR_MARKER}`);
+
+		await write(projection, "\x1b[2;3HX");
+		expect(projection.renderLines()[1]).toBe(`  X${CURSOR_MARKER}`);
+		projection.dispose();
+	});
+
+	test("tracks whether the projected application requested terminal focus events", async () => {
+		const projection = new TerminalProjection({ requestRender() {} });
+		expect(projection.acceptsFocusEvents).toBe(false);
+		await write(projection, "\x1b[?1004h");
+		expect(projection.acceptsFocusEvents).toBe(true);
+		await write(projection, "\x1b[?1004l");
+		expect(projection.acceptsFocusEvents).toBe(false);
+		projection.dispose();
+	});
+
+	test("projects the embedded application's cursor visibility and native shape", async () => {
+		const projection = new TerminalProjection({ requestRender() {}, cols: 8, rows: 2 });
+		await write(projection, "copy\x1b[1 q");
+		expect(findCursorPresentation(projection.renderLines(), 2)).toEqual({ style: "blinking-block" });
+
+		await write(projection, "\x1b[?25l");
+		expect(projection.renderLines().join("\n")).not.toContain(CURSOR_MARKER);
+
+		await write(projection, "\x1b[5 q\x1b[?25h");
+		expect(findCursorPresentation(projection.renderLines(), 2)).toEqual({ style: "blinking-bar" });
+		projection.dispose();
+	});
+
+	test("preserves wide glyph cell geometry", async () => {
+		const projection = new TerminalProjection({ requestRender() {}, cols: 8, rows: 2 });
+		await write(projection, "界x");
+		expect(projection.renderLines()[0]).toBe(`界x${CURSOR_MARKER}`);
+		projection.dispose();
+	});
+
+	test("replays only cell SGR and drops terminal side effects", async () => {
+		const projection = new TerminalProjection({ requestRender() {}, cols: 12, rows: 2 });
+		await write(projection, "\x1b]2;secret title\x07\x1b]52;c;c2VjcmV0\x07\x1b[31;1mred\x1b[0m");
+		const rendered = projection.renderLines({ cursor: false })[0] ?? "";
+
+		expect(rendered).toContain("\x1b[0;1;31mred\x1b[0m");
+		expect(rendered).not.toContain("secret");
+		expect(rendered).not.toContain("\x1b]");
+		projection.dispose();
+	});
+
+	test("bounds scrollback and reflows on resize", async () => {
+		const projection = new TerminalProjection({ requestRender() {}, cols: 6, rows: 2, scrollback: 2 });
+		await write(projection, "1\r\n2\r\n3\r\n4\r\n5");
+		const history = projection.renderLines({ includeScrollback: true, cursor: false });
+
+		expect(history.length).toBeLessThanOrEqual(4);
+		expect(history.at(-1)).toBe("5");
+		expect(projection.resize(3, 3)).toBe(true);
+		expect(projection.resize(3, 3)).toBe(false);
+		expect(projection).toMatchObject({ cols: 3, rows: 3 });
+		projection.dispose();
+	});
+
+	test("reuses projected cells until terminal state or dimensions change", async () => {
+		const projection = new TerminalProjection({ requestRender() {}, cols: 20, rows: 2 });
+		await write(projection, "stable");
+		const first = projection.renderLines({ includeScrollback: true, cursor: false });
+		expect(projection.renderLines({ includeScrollback: true, cursor: false })).toBe(first);
+		expect(projection.renderLines({ includeScrollback: false, cursor: false })).not.toBe(first);
+		projection.resize(10, 2);
+		expect(projection.renderLines({ includeScrollback: true, cursor: false })).not.toBe(first);
+		projection.dispose();
+	});
+
+	test("coalesces burst repaint requests without sleeping", async () => {
+		const scheduler = new FakeScheduler();
+		let renders = 0;
+		const projection = new TerminalProjection({
+			requestRender: () => (renders += 1),
+			cols: 20,
+			rows: 2,
+			repaintIntervalMs: 40,
+			scheduler,
+		});
+
+		for (let index = 0; index < 1_000; index += 1) projection.write(String(index % 10));
+		await projection.drain();
+		expect(scheduler.pending).toBe(1);
+		scheduler.advance();
+		expect(renders).toBe(1);
+
+		await write(projection, "next");
+		await write(projection, "frame");
+		expect(scheduler.pending).toBe(1);
+		scheduler.advance(39);
+		expect(renders).toBe(1);
+		scheduler.advance(1);
+		expect(renders).toBe(2);
+		projection.dispose();
+	});
+
+	test("publishes synchronized output as one complete frame", async () => {
+		const scheduler = new FakeScheduler();
+		let renders = 0;
+		const projection = new TerminalProjection({
+			requestRender: () => (renders += 1),
+			cols: 20,
+			rows: 2,
+			repaintIntervalMs: 0,
+			scheduler,
+		});
+
+		await write(projection, "\x1b[?2026h");
+		await write(projection, "complete frame");
+		scheduler.advance();
+		expect(renders).toBe(0);
+
+		await write(projection, "\x1b[?2026l");
+		scheduler.advance();
+		expect(renders).toBe(1);
+		expect(projection.renderLines({ cursor: false })[0]).toContain("complete frame");
+		projection.dispose();
+	});
+
+	test("cancels repaint work and ignores writes after disposal", async () => {
+		const scheduler = new FakeScheduler();
+		let renders = 0;
+		const projection = new TerminalProjection({
+			requestRender: () => (renders += 1),
+			scheduler,
+		});
+		await write(projection, "queued");
+		expect(scheduler.pending).toBe(1);
+
+		projection.dispose();
+		expect(scheduler.pending).toBe(0);
+		projection.write("ignored");
+		scheduler.advance(1_000);
+		expect(renders).toBe(0);
+		expect(projection.renderLines()).toEqual([]);
+	});
+
+	test("contains consumer repaint failures", async () => {
+		const scheduler = new FakeScheduler();
+		const projection = new TerminalProjection({
+			requestRender() {
+				throw new Error("host repaint failed");
+			},
+			scheduler,
+		});
+		await write(projection, "queued");
+		expect(() => scheduler.advance()).not.toThrow();
+		projection.dispose();
+	});
+});