@luan.sh/pi-libtui 0.3.8

package/test/appearance.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+	configureTuiAppearance,
+	DEFAULT_TUI_APPEARANCE,
+	getTuiAppearance,
+	isTuiActivityIndicatorStyle,
+	requestPhaseAnimation,
+	resolveActivityPresentation,
+	subscribeTuiAppearance,
+	TUI_ACTIVITY_INDICATOR_OPTIONS,
+} from "../src/appearance.ts";
+
+describe("shared TUI appearance", () => {
+	afterEach(() => configureTuiAppearance(DEFAULT_TUI_APPEARANCE));
+
+	test("starts with portable defaults", () => {
+		expect(DEFAULT_TUI_APPEARANCE).toEqual({
+			iconPack: "unicode",
+			activityIndicator: "spinner",
+			activityMessage: "phase",
+			textEffect: "off",
+			textEffectScope: "message",
+			pulseEffect: "off",
+			statusPresentation: "standard",
+			animationSpeed: "normal",
+			animationSmoothness: "balanced",
+			thinkingIndicator: "inherit",
+			thinkingMessage: "inherit",
+			thinkingTextEffect: "inherit",
+			thinkingPulseEffect: "inherit",
+			thinkingPresentation: "inherit",
+			workingIndicator: "inherit",
+			workingMessage: "inherit",
+			workingTextEffect: "inherit",
+			workingPulseEffect: "inherit",
+			workingPresentation: "inherit",
+			toolIndicator: "inherit",
+			toolMessage: "inherit",
+			toolTextEffect: "inherit",
+			toolPulseEffect: "inherit",
+			toolPresentation: "inherit",
+			powerline: false,
+			powerlineButtons: false,
+			softCursor: false,
+			insertionCursor: "virtual",
+			navigationCursor: "virtual",
+			selectionCursor: "virtual",
+		});
+		expect(getTuiAppearance()).toEqual(DEFAULT_TUI_APPEARANCE);
+	});
+
+	test("notifies subscribers only for effective changes", () => {
+		let changes = 0;
+		const remove = subscribeTuiAppearance(() => {
+			changes += 1;
+		});
+
+		configureTuiAppearance({ iconPack: "emoji" });
+		configureTuiAppearance({ iconPack: "emoji" });
+		expect(changes).toBe(1);
+
+		remove();
+		configureTuiAppearance(DEFAULT_TUI_APPEARANCE);
+		expect(changes).toBe(1);
+	});
+
+	test("isolates subscriber failures", () => {
+		let changes = 0;
+		const removeBroken = subscribeTuiAppearance(() => {
+			throw new Error("broken renderer");
+		});
+		const removeWorking = subscribeTuiAppearance(() => {
+			changes += 1;
+		});
+
+		configureTuiAppearance({ powerline: true });
+		expect(changes).toBe(1);
+		removeBroken();
+		removeWorking();
+	});
+
+	test("resolves inline composition, mixed composition, and exclusive scenes", () => {
+		expect(resolveActivityPresentation("spinner", "typewriter", "aurora", "inline", "color", "standard")).toEqual({
+			kind: "inline",
+			indicatorStyle: "spinner",
+			messageStyle: "typewriter",
+			textEffectStyle: "aurora",
+			textEffectScope: "inline",
+			pulseEffectStyle: "color",
+		});
+		expect(resolveActivityPresentation("spinner", "phase", "off", "message", "color", "brainstorm")).toEqual({
+			kind: "composition",
+			style: "brainstorm",
+		});
+		expect(resolveActivityPresentation("spinner", "phase", "off", "message", "color", "starfield")).toEqual({
+			kind: "scene",
+			style: "starfield",
+		});
+
+		configureTuiAppearance({
+			activityMessage: "typewriter",
+			textEffect: "glow",
+			textEffectScope: "inline",
+			thinkingIndicator: "off",
+			thinkingMessage: "phase",
+			thinkingPulseEffect: "color",
+		});
+		expect(requestPhaseAnimation("thinking")).toEqual({
+			kind: "inline",
+			indicatorStyle: "off",
+			messageStyle: "phase",
+			textEffectStyle: "glow",
+			textEffectScope: "inline",
+			pulseEffectStyle: "color",
+		});
+	});
+
+	test("ignores invalid values at the shared-state boundary", () => {
+		configureTuiAppearance({
+			iconPack: "emoji",
+			activityIndicator: "static",
+			pulseEffect: "color",
+			statusPresentation: "block-wave",
+			textEffect: "glow",
+			textEffectScope: "inline",
+			animationSpeed: "fast",
+			animationSmoothness: "smooth",
+			thinkingIndicator: "off",
+			thinkingPresentation: "pacman",
+			toolTextEffect: "rainbow",
+			powerlineButtons: true,
+			softCursor: true,
+			insertionCursor: "steady-bar",
+		});
+		configureTuiAppearance({
+			iconPack: "invalid" as never,
+			activityIndicator: "marquee" as never,
+			statusPresentation: "marquee" as never,
+			textEffect: "flash" as never,
+			textEffectScope: "yes" as never,
+			animationSpeed: "warp" as never,
+			animationSmoothness: "maximum" as never,
+			thinkingIndicator: "marquee" as never,
+			thinkingPresentation: "marquee" as never,
+			toolTextEffect: "flash" as never,
+			powerline: "yes" as never,
+			powerlineButtons: "yes" as never,
+			softCursor: "yes" as never,
+			insertionCursor: "beam" as never,
+			navigationCursor: "box" as never,
+			selectionCursor: "line" as never,
+		});
+
+		expect(getTuiAppearance()).toEqual({
+			...DEFAULT_TUI_APPEARANCE,
+			iconPack: "emoji",
+			activityIndicator: "static",
+			pulseEffect: "color",
+			statusPresentation: "block-wave",
+			textEffect: "glow",
+			textEffectScope: "inline",
+			animationSpeed: "fast",
+			animationSmoothness: "smooth",
+			thinkingIndicator: "off",
+			thinkingPresentation: "pacman",
+			toolTextEffect: "rainbow",
+			powerlineButtons: true,
+			softCursor: true,
+			insertionCursor: "steady-bar",
+		});
+	});
+
+	test("accepts the dim-to-bright pulse independently from color pulse", () => {
+		configureTuiAppearance({ pulseEffect: "pulse", toolPulseEffect: "pulse" });
+
+		expect(getTuiAppearance().pulseEffect).toBe("pulse");
+		expect(requestPhaseAnimation("tool")).toMatchObject({ pulseEffectStyle: "pulse" });
+	});
+
+	test("accepts every published activity indicator at the shared boundary", () => {
+		expect(TUI_ACTIVITY_INDICATOR_OPTIONS.every((option) => isTuiActivityIndicatorStyle(option.value))).toBe(true);
+	});
+});

package/test/bounded-stream.test.ts

@@ -0,0 +1,150 @@
+import { describe, expect, test } from "bun:test";
+import { BoundedStreamBuffer } from "../src/stream.ts";
+
+describe("BoundedStreamBuffer", () => {
+	test("never exposes an incomplete ANSI control before truncation", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 64 });
+		expect(stream.append("ready\x1b[3").text).toBe("ready");
+		expect(stream.append("1mred").text).toBe("ready\x1b[31mred");
+	});
+
+	test("keeps exact output and the current partial line while under budget", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 64 });
+		stream.append("one\ntw");
+		const snapshot = stream.append("o\npartial");
+
+		expect(snapshot).toMatchObject({
+			text: "one\ntwo\npartial",
+			head: "one\ntwo\npartial",
+			tail: "",
+			partialLine: "partial",
+			truncated: false,
+			totalBytes: 15,
+			lineCount: 3,
+		});
+	});
+
+	test("decodes split UTF-8 and UTF-16 chunks without broken code points", () => {
+		const bytes = new TextEncoder().encode("A😀界Z");
+		const byteStream = new BoundedStreamBuffer({ maxBytes: 64 });
+		for (const byte of bytes) byteStream.append(Uint8Array.of(byte));
+		expect(byteStream.flush().text).toBe("A😀界Z");
+
+		const stringStream = new BoundedStreamBuffer({ maxBytes: 64 });
+		const emoji = "😀";
+		stringStream.append(emoji.slice(0, 1));
+		expect(stringStream.snapshot().text).toBe("");
+		stringStream.append(emoji.slice(1));
+		expect(stringStream.snapshot().text).toBe(emoji);
+	});
+
+	test("retains code-point-safe head and tail edges", () => {
+		const stream = new BoundedStreamBuffer({
+			maxBytes: 12,
+			omissionMarker: (bytes) => `<${bytes}>`,
+		});
+		const snapshot = stream.append("A😀BCDEF😀Z");
+
+		expect(snapshot).toMatchObject({
+			head: "A😀B",
+			tail: "F😀Z",
+			truncated: true,
+			omittedBytes: 3,
+			totalBytes: 15,
+		});
+		expect(snapshot.text).toBe("A😀B<3>F😀Z");
+		expect(snapshot.text).not.toContain("�");
+	});
+
+	test("never cuts an ANSI sequence and resets styling around an omission", () => {
+		const stream = new BoundedStreamBuffer({
+			maxBytes: 18,
+			omissionMarker: () => "<cut>",
+		});
+		const snapshot = stream.append("\x1b[31mred-red-red-red\x1b[39m tail");
+
+		expect(snapshot.truncated).toBe(true);
+		expect(snapshot.head.endsWith("\x1b[")).toBe(false);
+		expect(snapshot.tail.startsWith("31m")).toBe(false);
+		expect(snapshot.text).toContain("\x1b[0m<cut>\x1b[0m");
+		expect(snapshot.text.endsWith("\x1b[0m")).toBe(true);
+	});
+
+	test("never cuts an eight-bit CSI sequence at a retained edge", () => {
+		const head = new BoundedStreamBuffer({ maxBytes: 8, omissionMarker: () => "<cut>" });
+		const headSnapshot = head.append("\u009b31mred-red-red-red\u009b39m tail");
+		expect(headSnapshot.head).toBe("");
+		expect(headSnapshot.text).not.toContain("\u009b31");
+
+		const tail = new BoundedStreamBuffer({ maxBytes: 12, omissionMarker: () => "<cut>" });
+		const tailSnapshot = tail.append(`${"x".repeat(30)}\u009b31mred`);
+		expect(tailSnapshot.tail).toBe("red");
+		expect(tailSnapshot.text).not.toContain("31mred");
+	});
+
+	test("retains an ANSI sequence split across chunks without exposing its partial bytes", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 24, omissionMarker: () => "<cut>" });
+		stream.append(`${"x".repeat(50)}\x1b[3`);
+		expect(stream.snapshot().text).not.toContain("\x1b[3");
+
+		const completed = stream.append("1mred");
+		expect(completed.tail).toContain("\x1b[31mred");
+		expect(completed.text).toContain("\x1b[31mred\x1b[0m");
+	});
+
+	test("retains an eight-bit CSI sequence split across chunks", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 24, omissionMarker: () => "<cut>" });
+		stream.append(`${"x".repeat(50)}\u009b3`);
+		expect(stream.snapshot().text).not.toContain("\u009b3");
+
+		const completed = stream.append("1mred");
+		expect(completed.tail).toContain("\u009b31mred");
+		expect(completed.text).toContain("\u009b31mred\x1b[0m");
+	});
+
+	test("keeps a split string-control boundary intact while retaining stream styling", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 24, omissionMarker: () => "<cut>" });
+		stream.append(`${"x".repeat(50)}\x1b]52;c;secret`);
+		const completed = stream.append("\x9ctail");
+
+		expect(completed.tail).not.toStartWith("]52;");
+		expect(completed.tail).toEndWith("tail");
+	});
+
+	test("lets an authoritative final value replace speculative chunks", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 10 });
+		stream.append("speculative output that will disappear");
+		const final = stream.replaceFinal("final ✓");
+
+		expect(final).toMatchObject({
+			text: "final ✓",
+			head: "final ✓",
+			tail: "",
+			truncated: false,
+			authoritative: true,
+			totalBytes: 9,
+		});
+	});
+
+	test("stays bounded across many tiny chunks", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 128 });
+		for (let index = 0; index < 100_000; index += 1) stream.append(`line-${index}\n`);
+		const snapshot = stream.snapshot();
+
+		expect(snapshot.truncated).toBe(true);
+		expect(Buffer.byteLength(snapshot.head) + Buffer.byteLength(snapshot.tail)).toBeLessThanOrEqual(128);
+		expect(snapshot.tail).toEndWith("line-99999\n");
+		expect(snapshot.partialLine).toBe("");
+		expect(snapshot.lineCount).toBe(100_000);
+	});
+
+	test("keeps lazy snapshots stable while later chunks arrive", () => {
+		const stream = new BoundedStreamBuffer({ maxBytes: 1_024 });
+		const before = stream.append("before");
+		stream.append(" after");
+
+		expect(before.text).toBe("before");
+		expect(before.partialLine).toBe("before");
+		expect(stream.snapshot().text).toBe("before after");
+	});
+});

package/test/bridge-client.test.ts

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { expect, test } from "bun:test";
+import { createTerminalBridgeClient, parseTerminalBridgeReadResponse } from "../src/terminal/bridge-client.ts";
+
+test("rejects an invalid native response and replaces its bridge generation", async () => {
+	let generation = 0;
+	const bridge = createTerminalBridgeClient({
+		binaryPath: async () => process.execPath,
+		spawnBridge: () => {
+			generation += 1;
+			const source =
+				generation === 1
+					? 'process.stdin.once("data", () => process.stdout.write("bad\\n")); setInterval(() => {}, 1000)'
+					: 'process.stdin.once("data", data => { const r = JSON.parse(data); process.stdout.write(JSON.stringify({ request_id: r.request_id, ok: true, result: "replacement" }) + "\\n", () => process.exit(0)) })';
+			return spawn(process.execPath, ["-e", source], { stdio: "pipe" });
+		},
+	});
+
+	await expect(bridge.request({ op: "first" })).rejects.toThrow("invalid response");
+	await expect(bridge.request({ op: "second" })).resolves.toBe("replacement");
+	await bridge.shutdown();
+});
+
+test("rejects non-contiguous terminal read sequences", () => {
+	const base = { exited: false, closed: false };
+	const parse = (chunks: object[], nextSeq: number) => parseTerminalBridgeReadResponse({ ...base, chunks, nextSeq });
+	expect(parse([{ startSeq: 1, seq: 3, stream: "pty", chunk: "YQ==" }], 4)).toBeDefined();
+	expect(
+		parse(
+			[
+				{ seq: 1, stream: "pty", chunk: "YQ==" },
+				{ seq: 3, stream: "pty", chunk: "Yg==" },
+			],
+			4,
+		),
+	).toBeUndefined();
+	expect(parse([{ seq: 1, stream: "pty", chunk: "not base64" }], 2)).toBeUndefined();
+	expect(parseTerminalBridgeReadResponse({ ...base, chunks: [], nextSeq: 2 }, 1)).toBeUndefined();
+	expect(
+		parseTerminalBridgeReadResponse({ ...base, chunks: [{ seq: 2, stream: "pty", chunk: "YQ==" }], nextSeq: 3 }, 1),
+	).toBeUndefined();
+});

package/test/color-preview.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { COLOR256_PREVIEW_WIDTH, renderColor256Preview } from "../src/color/preview.ts";
+
+describe("color256 preview", () => {
+	test("matches the terminal grid dimensions and labels", () => {
+		const lines = renderColor256Preview("harmonious");
+		expect(lines).toHaveLength(20);
+		expect(lines.every((line) => visibleWidth(line) === COLOR256_PREVIEW_WIDTH)).toBe(true);
+		expect(stripAnsi(lines.at(-1)!)).toContain("harmonious");
+	});
+
+	test("renders the active 256-color indexes instead of a second RGB palette", () => {
+		const output = renderColor256Preview("harmonious").join("\n");
+		expect(output).toContain("\x1b[38;5;231;7m");
+		expect(output).toContain("\x1b[48;5;52m");
+		expect(output).toContain("\x1b[38;5;15;7m");
+	});
+});
+
+function stripAnsi(value: string): string {
+	return value.replaceAll(/\x1b\[[0-9;]*m/gu, "");
+}

package/test/component-stack.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, test } from "bun:test";
+import type { Component } from "@earendil-works/pi-tui";
+import { ComponentStack } from "../src/component-stack.ts";
+import type { TuiMouseEvent } from "../src/mouse.ts";
+
+class TestComponent implements Component {
+	readonly inputs: string[] = [];
+	invalidations = 0;
+
+	constructor(readonly lines: string[]) {}
+
+	handleInput(data: string): void {
+		this.inputs.push(data);
+	}
+
+	invalidate(): void {
+		this.invalidations += 1;
+	}
+
+	render(): string[] {
+		return [...this.lines];
+	}
+}
+
+class MouseComponent extends TestComponent {
+	readonly events: TuiMouseEvent[] = [];
+
+	onMouse(event: TuiMouseEvent): boolean {
+		this.events.push(event);
+		return true;
+	}
+}
+
+class FocusableComponent extends TestComponent {
+	focused = false;
+}
+
+class ViewportComponent extends TestComponent {
+	constructor(
+		lines: string[],
+		private readonly handled: boolean,
+	) {
+		super(lines);
+	}
+
+	handleViewportInput(data: string): boolean {
+		this.inputs.push(data);
+		return this.handled;
+	}
+}
+
+function mouseEvent(row: number, col = 0): TuiMouseEvent {
+	return {
+		type: "press",
+		row,
+		col,
+		screenRow: row,
+		screenCol: col,
+		button: 0,
+		wheel: undefined,
+		shift: false,
+		alt: false,
+		ctrl: false,
+	};
+}
+
+describe("ComponentStack", () => {
+	test("renders children vertically and records exact spans", () => {
+		const first = new TestComponent(["one", "two"]);
+		const second = new TestComponent(["three"]);
+		const stack = new ComponentStack([first, second]);
+
+		expect(stack.render(20)).toEqual(["one", "two", "three"]);
+		expect(stack.getSpans()).toEqual([
+			{ component: first, index: 0, row: 0, height: 2, width: 20 },
+			{ component: second, index: 1, row: 2, height: 1, width: 20 },
+		]);
+	});
+
+	test("routes input to the active child and keeps its identity across replacement", () => {
+		const first = new TestComponent(["one"]);
+		const active = new TestComponent(["active"]);
+		const stack = new ComponentStack([first, active], { activeChild: 1 });
+
+		stack.handleInput("a");
+		stack.setChildren([active, first]);
+		stack.handleInput("b");
+
+		expect(first.inputs).toEqual([]);
+		expect(active.inputs).toEqual(["a", "b"]);
+		expect(stack.getActiveChild()).toBe(active);
+	});
+
+	test("propagates overlay focus to the active child", () => {
+		const first = new FocusableComponent(["first"]);
+		const second = new FocusableComponent(["second"]);
+		const stack = new ComponentStack([first, second]);
+
+		stack.focused = true;
+		expect([first.focused, second.focused]).toEqual([true, false]);
+		stack.setActiveChild(second);
+		expect([first.focused, second.focused]).toEqual([false, true]);
+		stack.focused = false;
+		expect(second.focused).toBe(false);
+	});
+
+	test("can route input to every child in display order", () => {
+		const order: string[] = [];
+		const child = (name: string): Component => ({
+			render: () => [],
+			invalidate() {},
+			handleInput: (data) => order.push(`${name}:${data}`),
+		});
+		const stack = new ComponentStack([child("first"), child("second")], { inputMode: "all" });
+
+		stack.handleInput("x");
+
+		expect(order).toEqual(["first:x", "second:x"]);
+	});
+
+	test("routes viewport input to the active child and falls back to legacy input", () => {
+		const viewport = new ViewportComponent(["viewport"], true);
+		const legacy = new TestComponent(["legacy"]);
+		const stack = new ComponentStack([viewport, legacy]);
+
+		expect(stack.handleViewportInput("right")).toBe(true);
+		stack.setActiveChild(legacy);
+		expect(stack.handleViewportInput("down")).toBe(false);
+
+		expect(viewport.inputs).toEqual(["right"]);
+		expect(legacy.inputs).toEqual(["down"]);
+	});
+
+	test("anchors the final child and dispatches translated pointer input", () => {
+		const body = new MouseComponent(["body", "body"]);
+		const footer = new MouseComponent(["footer"]);
+		const stack = new ComponentStack([body, footer], { height: 6, anchorLastChild: true });
+
+		expect(stack.render(12)).toEqual(["body", "body", "", "", "", "footer"]);
+		expect(stack.getSpans().map(({ index, row, height }) => ({ index, row, height }))).toEqual([
+			{ index: 0, row: 0, height: 2 },
+			{ index: 1, row: 5, height: 1 },
+		]);
+		expect(stack.onMouse(mouseEvent(5, 4))).toBe(true);
+		expect(footer.events[0]).toMatchObject({ row: 0, col: 4, screenRow: 5, screenCol: 4 });
+		expect(body.events).toEqual([]);
+	});
+
+	test("dispatches recursively to the deepest nested stack child", () => {
+		const leaf = new MouseComponent(["leaf"]);
+		const inner = new ComponentStack([new TestComponent(["label"]), leaf]);
+		const outer = new ComponentStack([new TestComponent(["title"]), inner]);
+		outer.render(10);
+
+		expect(outer.onMouse(mouseEvent(2, 3))).toBe(true);
+		expect(leaf.events[0]).toMatchObject({ row: 0, col: 3, screenRow: 2, screenCol: 3 });
+	});
+
+	test("owns hover transitions and capture across nested children", () => {
+		const first = new MouseComponent(["first"]);
+		const second = new MouseComponent(["second"]);
+		const stack = new ComponentStack([first, second]);
+		stack.render(12);
+		stack.onMouse({ ...mouseEvent(0), type: "move" });
+		stack.onMouse({ ...mouseEvent(1), type: "move" });
+		stack.onMouse(mouseEvent(0));
+		stack.onMouse({ ...mouseEvent(9), type: "release" });
+
+		expect(first.events.map((event) => event.type)).toEqual(["enter", "move", "leave", "press", "release"]);
+		expect(second.events.map((event) => event.type)).toEqual(["enter", "move", "leave"]);
+		expect(first.events.at(-1)).toMatchObject({ row: 9 });
+	});
+
+	test("preserves a handled hover when its redraw invalidates nested geometry", () => {
+		let stack: ComponentStack;
+		const child = new MouseComponent(["child"]);
+		const original = child.onMouse.bind(child);
+		child.onMouse = (event) => {
+			const handled = original(event);
+			if (event.type === "enter") stack.invalidate();
+			return handled;
+		};
+		stack = new ComponentStack([child]);
+		stack.render(12);
+
+		expect(stack.onMouse({ ...mouseEvent(0), type: "move" })).toBe(true);
+		stack.render(12);
+		expect(stack.onMouse(mouseEvent(0))).toBe(true);
+		expect(stack.onMouse({ ...mouseEvent(0), type: "release" })).toBe(true);
+	});
+
+	test("clips spans to a fixed height and invalidates every current child", () => {
+		const first = new TestComponent(["one", "two"]);
+		const second = new TestComponent(["three", "four"]);
+		const stack = new ComponentStack([first, second], { height: 3 });
+
+		expect(stack.render(8)).toEqual(["one", "two", "three"]);
+		expect(stack.getSpans().map(({ row, height }) => ({ row, height }))).toEqual([
+			{ row: 0, height: 2 },
+			{ row: 2, height: 1 },
+		]);
+		stack.invalidate();
+		expect([first.invalidations, second.invalidations]).toEqual([1, 1]);
+		expect(stack.getSpans()).toEqual([]);
+	});
+});