gentle-pi 2.3.0 → 2.5.0

package/tests/gentle-todo.test.ts

@@ -0,0 +1,182 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import gentleTodo, { todoCollapseKey, todoEnabled } from "../extensions/gentle-todo.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+// The Gentle Todo extension: the `todo` tool, the card above the editor,
+// the per-turn prompt block, and the staleness signal, driven by fakes.
+
+type Handler = (event: unknown, ctx: ExtensionContext) => unknown;
+
+interface Registered {
+	execute(toolCallId: string, params: unknown, signal: undefined, onUpdate: undefined, ctx: ExtensionContext): Promise<{ content: Array<{ type: string; text: string }>; details: Record<string, unknown> }>;
+	renderCall(args: unknown, theme: unknown): { render(width: number): string[] };
+	renderResult(result: unknown, options: { expanded: boolean }, theme: unknown): { render(width: number): string[] };
+}
+
+const plainTheme = {
+	fg(_color: string, text: string) {
+		return text;
+	},
+	strikethrough(text: string) {
+		return `~${text}~`;
+	},
+};
+const fakeTui = { requestRender() {} };
+
+function fakePi() {
+	const handlers = new Map<string, Handler[]>();
+	const tools = new Map<string, Registered>();
+	const shortcuts = new Map<string, { handler(ctx: ExtensionContext): Promise<void> }>();
+	const pi = {
+		on(event: string, handler: Handler) {
+			handlers.set(event, [...(handlers.get(event) ?? []), handler]);
+		},
+		registerTool(tool: Registered & { name: string }) {
+			tools.set(tool.name, tool);
+		},
+		registerShortcut(key: string, registration: { handler(ctx: ExtensionContext): Promise<void> }) {
+			shortcuts.set(key, registration);
+		},
+	} as unknown as ExtensionAPI;
+	const fire = async (event: string, ctx: ExtensionContext, payload: unknown = {}) => {
+		let last: unknown;
+		for (const handler of handlers.get(event) ?? []) last = await handler(payload, ctx);
+		return last;
+	};
+	return { pi, tools, shortcuts, fire };
+}
+
+function fakeContext(branch: unknown[] = [], hasUI = true) {
+	const widgets = new Map<string, (tui: unknown, theme: unknown) => { render(width: number): string[] }>();
+	const ctx = {
+		hasUI,
+		sessionManager: { getSessionId: () => "s1", getBranch: () => branch },
+		ui: {
+			setWidget(key: string, content: ((tui: unknown, theme: unknown) => { render(width: number): string[] }) | undefined) {
+				if (content === undefined) widgets.delete(key);
+				else widgets.set(key, content);
+			},
+		},
+	} as unknown as ExtensionContext;
+	const widget = () => {
+		const factory = widgets.get("gentle-todo");
+		return factory ? factory(fakeTui, plainTheme).render(70).map(stripAnsi) : undefined;
+	};
+	return { ctx, widgets, widget };
+}
+
+test("todoEnabled and todoCollapseKey read their environment flags", () => {
+	assert.equal(todoEnabled({}), true);
+	assert.equal(todoEnabled({ GENTLE_PI_TODO: "0" }), false);
+	assert.equal(todoEnabled({ GENTLE_PI_AGENTS_CHILD: "1" }), false);
+	assert.equal(todoCollapseKey({}), "ctrl+shift+t");
+	assert.equal(todoCollapseKey({ GENTLE_PI_TODO_KEY: "alt+t" }), "alt+t");
+	assert.equal(todoCollapseKey({ GENTLE_PI_TODO_KEY: "off" }), undefined);
+	const off = fakePi();
+	gentleTodo(off.pi, { GENTLE_PI_TODO: "off" });
+	assert.equal(off.tools.size, 0);
+});
+
+test("the todo tool writes the list, shows the card after the call, and carries the snapshot in details", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx, widget } = fakeContext();
+	await fire("session_start", ctx);
+	assert.equal(widget(), undefined, "no card without tasks");
+
+	const tool = tools.get("todo")!;
+	const result = await tool.execute("c1", { action: "write", tasks: [{ title: "Write the parser", status: "in_progress", note: "parsing" }, { title: "Add tests" }] }, undefined, undefined, ctx);
+	assert.match(result.content[0].text, /2 tasks · 0 done · 1 in progress/);
+	assert.equal((result.details.gentleTodo as { tasks: unknown[] }).tasks.length, 2);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	const lines = widget()!;
+	assert.match(lines[0], /^╭─ ❀ Todos · 0 of 2 ─+╮$/);
+	assert.match(lines[1], /◐ Write the parser · parsing/);
+	assert.match(lines[2], /○ Add tests/);
+	assert.equal(lines[lines.length - 1], "", "a blank line keeps the card off the prompt");
+
+	const bad = await tool.execute("c2", { action: "update", id: 9, status: "done" }, undefined, undefined, ctx);
+	assert.match(bad.content[0].text, /Error: no task #9/);
+	assert.equal(bad.details.error, "no task #9");
+	assert.match(tool.renderCall({ action: "write" }, plainTheme).render(40).join(""), /❀ todo · write/);
+	assert.equal(tool.renderResult({ content: [{ type: "text", text: "a\nb" }] }, { expanded: false }, plainTheme).render(40).join("|").trimEnd(), "a");
+});
+
+test("every turn carries the open tasks in the system prompt and the card goes stale after two silent turns", async () => {
+	const { pi, tools, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx, widget } = fakeContext();
+	await fire("session_start", ctx);
+	await fire("before_agent_start", ctx, { systemPrompt: "base" });
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "Fix the bug" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+
+	const withTasks = (await fire("before_agent_start", ctx, { systemPrompt: "base" })) as { systemPrompt: string };
+	assert.match(withTasks.systemPrompt, /^base\n\n## Todo list/);
+	assert.match(withTasks.systemPrompt, /1\. \[pending\] Fix the bug/);
+	assert.doesNotMatch(widget()![0], /stale/);
+
+	const stale = (await fire("before_agent_start", ctx, { systemPrompt: "base" })) as { systemPrompt: string };
+	assert.match(stale.systemPrompt, /stale: 2 turns without an update/);
+	assert.match(widget()![0], /stale · 2 turns/);
+
+	await tools.get("todo")!.execute("c2", { action: "update", id: 1, status: "in_progress", note: "on it" }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	assert.doesNotMatch(widget()![0], /stale/);
+});
+
+test("a finished list stays for its turn and clears at the next, and the collapse key folds the card", async () => {
+	const { pi, tools, shortcuts, fire } = fakePi();
+	gentleTodo(pi, {});
+	const { ctx, widget } = fakeContext();
+	await fire("session_start", ctx);
+	await tools.get("todo")!.execute("c1", { action: "write", tasks: [{ title: "A", status: "in_progress" }, { title: "B" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	await shortcuts.get("ctrl+shift+t")!.handler(ctx);
+	assert.equal(widget()!.length, 4, "collapsed: top, one row, bottom, spacer");
+	assert.match(widget()![1], /◐ A/);
+	await shortcuts.get("ctrl+shift+t")!.handler(ctx);
+	assert.equal(widget()!.length, 5);
+
+	await tools.get("todo")!.execute("c2", { action: "write", tasks: [{ id: 1, title: "A", status: "done" }, { id: 2, title: "B", status: "done" }] }, undefined, undefined, ctx);
+	await fire("tool_execution_end", ctx, { toolName: "todo" });
+	await fire("agent_end", ctx);
+	assert.match(widget()![0], /Todos · 2 of 2/, "the finished list is still visible at the end of its turn");
+	const next = await fire("before_agent_start", ctx, { systemPrompt: "base" });
+	assert.equal(next, undefined, "nothing open, nothing to add to the prompt");
+	assert.equal(widget(), undefined, "the card clears at the next turn");
+});
+
+test("session_start replays the list from the branch, rpiv-todo results included, and counts past turns", async () => {
+	const { pi, fire } = fakePi();
+	gentleTodo(pi, {});
+	const branch = [
+		{ type: "message", message: { role: "user", content: "hi" } },
+		{ type: "message", message: { role: "toolResult", toolName: "todo", isError: false, details: { action: "create", params: {}, tasks: [{ id: 1, subject: "Old task", status: "in_progress", activeForm: "still going" }], nextId: 2 } } },
+		{ type: "message", message: { role: "user", content: "again" } },
+	];
+	const { ctx, widget } = fakeContext(branch);
+	await fire("session_start", ctx);
+	const lines = widget()!;
+	assert.match(lines[0], /Todos · 0 of 1/);
+	assert.match(lines[1], /◐ Old task · still going/);
+	const headless = fakeContext(branch, false);
+	await fire("session_start", headless.ctx);
+	assert.equal(headless.widget(), undefined);
+});
+
+test("session_start drops a list that was already finished, so a reload never shows stale done work", async () => {
+	const { pi, fire } = fakePi();
+	gentleTodo(pi, {});
+	const finished = [
+		{ type: "message", message: { role: "user", content: "hi" } },
+		{ type: "message", message: { role: "toolResult", toolName: "todo", isError: false, details: { gentleTodo: { tasks: [{ id: 1, title: "Done A", status: "done" }, { id: 2, title: "Done B", status: "done" }], nextId: 3, updatedTurn: 1 } } } },
+	];
+	const { ctx, widget } = fakeContext(finished);
+	await fire("session_start", ctx);
+	assert.equal(widget(), undefined, "nothing to show after a reload of finished work");
+	const prompt = (await fire("before_agent_start", ctx, { systemPrompt: "base" })) as { systemPrompt: string } | undefined;
+	assert.equal(prompt, undefined, "and nothing is injected into the prompt");
+});

package/tests/issue-creation-skill.test.ts

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import test from "node:test";
+
+const repoRoot = join(import.meta.dirname, "..");
+const skill = readFileSync(join(repoRoot, "skills", "issue-creation", "SKILL.md"), "utf8");
+
+test("preserves the prefixed skill identity and complete Issue Form metadata", () => {
+	assert.match(skill, /^name: gentle-ai-issue-creation$/m);
+	assert.match(skill, /^description: ".+"$/m);
+	assert.match(skill, /^  version: "1\.3"$/m);
+});
+
+test("makes YAML Issue Forms the deterministic automated format authority", () => {
+	assert.match(skill, /YAML Issue Forms are the format authority/i);
+	assert.match(skill, /`input`, `textarea`, `dropdown`, and `checkboxes`/);
+	assert.match(skill, /declared order/i);
+	assert.match(skill, /visible labels and options/i);
+	assert.match(skill, /multi-select.*declared options order/i);
+	assert.match(skill, /optional dropdown[\s\S]{0,180}_No response_/i);
+	assert.match(skill, /Markdown controls are non-answer guidance/i);
+	assert.match(skill, /visible instructions[\s\S]{0,180}adjacent answers/i);
+	assert.match(skill, /do not render them as response sections/i);
+	assert.match(skill, /individually required checkbox/i);
+	assert.match(skill, /explicit first-person affirmation/i);
+	assert.match(skill, /textarea\.attributes\.render/);
+	assert.match(skill, /fence the answer with the declared language/i);
+});
+
+test("fails closed before publication for invalid required Issue Form data", () => {
+	assert.match(skill, /Fail closed before mutation/i);
+	assert.match(skill, /malformed, unsupported, missing, or ambiguous required structure or answers/i);
+	assert.match(skill, /malformed schema[\s\S]{0,200}do not open a browser/i);
+	assert.match(skill, /Never invent answers, selections, confirmations, or labels/i);
+});
+
+test("publishes reviewed Issue Form bodies through a private body file", () => {
+	assert.match(skill, /private `BODY_FILE`/);
+	assert.match(skill, /gh issue create --repo "\$TARGET" --title "\$TITLE" --body-file "\$BODY_FILE"/);
+	assert.match(skill, /target verification/i);
+	assert.match(skill, /duplicate search/i);
+	assert.match(skill, /Before commenting on a confirmed duplicate[\s\S]{0,250}privacy scan\/redaction[\s\S]{0,250}exact comment body/i);
+	assert.match(skill, /privacy scan/i);
+	assert.match(skill, /permitted labels/i);
+	assert.match(skill, /one mutation attempt/i);
+	assert.match(skill, /target-host read-back/i);
+});
+
+function assertBrowserContract(candidate: string) {
+	assert.match(candidate, /gh issue create --repo "\$TARGET" --title "\$TITLE" --body-file "\$BODY_FILE"/);
+	assert.match(
+		candidate,
+		/user explicitly requests browser completion[\s\S]{0,350}syntactically valid selected form cannot safely\/faithfully be represented by the automated path/i,
+	);
+	assert.match(candidate, /malformed schema[\s\S]{0,200}do not open a browser/i);
+	assert.match(candidate, /missing or ambiguous required[\s\S]{0,200}fail closed[\s\S]{0,200}do not open a browser/i);
+	assert.match(candidate, /browser handoff[\s\S]{0,160}never proof of publication/i);
+	assert.doesNotMatch(candidate, /Do not parse or render[\s\S]{0,300}stop for human completion/i);
+	assert.doesNotMatch(candidate, /(?:always|must|only)\s+(?:open|use|route to)\s+(?:the )?browser(?:\s+for)?\s+(?:Issue Forms?|YAML)/i);
+	assert.doesNotMatch(candidate, /YAML Issue Forms require human completion in the web issue chooser\./i);
+	assert.doesNotMatch(candidate, /Always route Issue Forms to the browser\./i);
+	assert.doesNotMatch(
+		candidate,
+		/\bfor\s+(?:YAML\s+)?Issue\s+Forms?\b[\s\S]{0,160}\b(?:open|use|route to|go to)\b[\s\S]{0,100}\b(?:browser|web issue chooser|web)\b/i,
+	);
+}
+
+test("keeps automated and conditional browser Issue Form paths distinct", () => {
+	assertBrowserContract(skill);
+
+	const unsafeMutations = [
+		"For YAML Issue Forms, open the web issue chooser and stop for human completion.",
+		"YAML Issue Forms require human completion in the web issue chooser.",
+		"Always route Issue Forms to the browser.",
+	];
+	for (const mutation of unsafeMutations) {
+		assert.throws(() => assertBrowserContract(`${skill}\n\n${mutation}`), mutation);
+	}
+});
+
+test("discovers support routing and keeps all issue files private until cleanup", () => {
+	assert.match(skill, /README\.md/);
+	assert.match(skill, /\.github\/ISSUE_TEMPLATE\/config\.yml/);
+	assert.match(skill, /Discussions\/contact routing/i);
+	assert.match(skill, /questions\/support[\s\S]{0,250}(?:Discussions|contact)[\s\S]{0,250}otherwise ask or stop/i);
+	assert.doesNotMatch(skill, /TMP_DIR="\$\(mktemp -d\)"/);
+	assert.match(skill, /TMPDIR=\/tmp mktemp -d/);
+	assert.match(skill, /REPO_ROOT="\$\(git rev-parse --show-toplevel\)"/);
+	assert.match(skill, /REPO_ROOT="\$\(cd "\$REPO_ROOT" && pwd -P\)"/);
+	assert.match(skill, /if \[ "\$REPO_ROOT" = "\/" \]/);
+	assert.match(skill, /trap 'rm -rf -- "\$TMP_DIR"' EXIT/);
+	assert.match(skill, /TMP_DIR_REAL="\$\(cd "\$TMP_DIR" && pwd -P\)"/);
+	assert.match(skill, /case "\$TMP_DIR_REAL\/" in[\s\S]{0,200}"\$REPO_ROOT\/"\*/);
+	assert.match(skill, /if \[ "\$REPO_ROOT" = "\/" \][\s\S]{0,200}Temporary directory is inside the repository/);
+	assert.match(skill, /REPO_ROOT="\$\(cd "\$REPO_ROOT" && pwd -P\)"[\s\S]{0,200}TMPDIR=\/tmp mktemp -d/);
+	assert.match(skill, /TMPDIR=\/tmp mktemp -d[\s\S]{0,200}trap 'rm -rf -- "\$TMP_DIR"' EXIT/);
+	assert.match(skill, /chmod 700 "\$TMP_DIR_REAL"/);
+	assert.match(skill, /umask 077/);
+	assert.match(skill, /BODY_FILE="\$TMP_DIR_REAL\//);
+	assert.match(skill, /READBACK_FILE="\$TMP_DIR_REAL\//);
+	assert.doesNotMatch(skill, /TMP_DIR="\$\(cd "\$TMP_DIR" && pwd -P\)"/);
+});

package/tests/native-choice-list.test.ts

@@ -0,0 +1,202 @@
+import assert from "node:assert/strict";
+import test, { mock } from "node:test";
+import {
+	KeybindingsManager, stripTerminalSequences, Text, TUI_KEYBINDINGS,
+	type Component, type TuiMouseEvent, visibleWidth,
+} from "@earendil-works/pi-tui";
+import { NativeChoiceList } from "../lib/native-choice-list.ts";
+import {
+	NativePointerScope,
+	type NativePointerRegionCallbacks,
+} from "../lib/native-pointer-region.ts";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
+
+const selectedForeground = "\u001b[38;5;39m";
+const hoverBackground = "\u001b[48;5;236m";
+const theme = {
+	selectedPrefix: (text: string) => `${selectedForeground}${text}\u001b[39m`,
+	selectedText: (text: string) => `${selectedForeground}${text}\u001b[39m`,
+	description: (text: string) => `\u001b[38;5;244m${text}\u001b[39m`,
+	hoverBackground: (text: string) => `${hoverBackground}${text}\u001b[49m`,
+};
+
+function event(
+	type: TuiMouseEvent["type"], button: TuiMouseEvent["button"],
+	y: number, width: number, height: number, wheelDelta?: number,
+): TuiMouseEvent {
+	return {
+		type, button, x: 0, y, screenX: 0, screenY: y, width, height,
+		shift: false, alt: false, ctrl: false, wheelDelta,
+	};
+}
+
+function layout(
+	list: NativeChoiceList<{ id: string; label: string; description: string }>, width: number, text: string,
+) {
+	const lines = list.render(width);
+	assert.ok(lines.every((line) => visibleWidth(line) <= width), "ANSI-stripped lines fit the current render width");
+	const row = lines.findIndex((line) => stripTerminalSequences(line).includes(text));
+	assert.ok(row >= 0, "the current wrapped layout locates the requested row");
+	return { lines, row };
+}
+
+test("native choice list presents one hovered wrapped option without changing selection", () => {
+	const list = new NativeChoiceList([
+		{
+			id: "same", label: "Duplicate label",
+			description: "A wrapped description that spans more than one display line at this width.",
+		},
+		{
+			id: "other", label: "Duplicate label",
+			description: "The second item has the same label but a distinct stable identity.",
+		},
+	], theme);
+	const narrow = layout(list, 40, "second item");
+	assert.equal(list.handleMouse(event("move", "none", narrow.row, 40, narrow.lines.length))?.render, true);
+	const narrowHover = list.render(40);
+	assert.ok(
+		narrowHover.every((line, index) => index >= narrow.row - 1 || !line.includes(hoverBackground)),
+		"only the hovered option rows have a background",
+	);
+	assert.ok(
+		narrowHover.some((line) => line.includes(selectedForeground) && !line.includes(hoverBackground)),
+		"keyboard selection has a distinct foreground",
+	);
+	assert.equal(list.handleMouse(event("move", "none", narrow.row, 40, narrow.lines.length))?.render, false);
+	assert.equal(list.getSelectedItem()?.id, "same");
+
+	const wider = layout(list, 56, "second item");
+	assert.doesNotMatch(
+		wider.lines.join("\n"),
+		new RegExp(hoverBackground.replace(/[\[\]]/g, "\\$&")), "resize clears hover",
+	);
+	assert.equal(list.handleMouse(event("move", "none", wider.row, 56, wider.lines.length))?.render, true);
+	const hovered = list.render(56);
+	assert.ok(hovered.some((line) => line.includes(hoverBackground)), "real SGR background marks the second option");
+	const firstRow = hovered.findIndex((line) => stripTerminalSequences(line).includes("Duplicate label"));
+	assert.ok(firstRow >= 0);
+	list.handleMouse(event("move", "none", firstRow, 56, hovered.length));
+	const selectedHover = list.render(56)[firstRow];
+	assert.ok(
+		selectedHover?.includes(selectedForeground) && selectedHover.includes(hoverBackground),
+		"selected and hovered styles combine",
+	);
+	list.invalidate();
+	assert.doesNotMatch(list.render(56).join("\n"), new RegExp(hoverBackground.replace(/[\[\]]/g, "\\$&")));
+});
+
+test("native choice list ignores Kitty key releases", () => {
+	const list = new NativeChoiceList(
+		[{ id: "first", label: "First" }, { id: "second", label: "Second" }],
+		theme, new KeybindingsManager(TUI_KEYBINDINGS),
+	);
+	const selected: string[] = [];
+	let cancelled = 0;
+	list.onSelect = (item) => selected.push(item.id);
+	list.onCancel = () => { cancelled++; };
+	list.handleInput("\u001b[B");
+	list.handleInput("\r");
+	assert.deepEqual(selected, ["second"], "legacy arrow and Enter use semantic bindings");
+	list.setSelectedIndex(0);
+	selected.length = 0;
+	list.handleInput("\u001b[1;1:3B");
+	assert.equal(list.getSelectedItem()?.id, "first", "Kitty arrow release does not navigate");
+	list.handleInput("\u001b[1;1:1B");
+	assert.equal(list.getSelectedItem()?.id, "second", "Kitty arrow press navigates");
+	list.setSelectedIndex(0);
+	list.handleInput("\u001b[1;1:2B");
+	assert.equal(list.getSelectedItem()?.id, "second", "Kitty arrow repeat still navigates");
+	list.handleInput("\u001b[13;1:3u");
+	list.handleInput("\u001b[27;1:3u");
+	assert.deepEqual([selected, cancelled], [[], 0], "Kitty confirm and cancel releases do not activate callbacks");
+	list.handleInput("\u001b[13;1:1u");
+	list.handleInput("\u001b[27;1:1u");
+	assert.deepEqual([selected, cancelled], [["second"], 1], "Kitty confirm and cancel presses still activate");
+});
+
+test("root observer clears hover and disabled controls ignore every input", () => {
+	const list = new NativeChoiceList([
+		{ id: "first", label: "First choice", description: "First detail." },
+		{ id: "second", label: "Second choice", description: "Second detail." },
+	], theme);
+	let renders = 0;
+	let selected = 0;
+	let cancelled = 0;
+	list.onSelect = () => { selected++; };
+	list.onCancel = () => { cancelled++; };
+	const root = createNativeFullscreenInteraction({
+		keyboardTarget: list, requestRender: () => { renders++; },
+		mouseObserver: list.createMouseObserver(() => { renders++; }),
+	});
+	root.addChild(new Text("Header", 0, 0));
+	root.addChild(list);
+	root.addChild(new Text("Footer", 0, 0));
+	const lines = root.render(48);
+	const firstRow = lines.findIndex((line) => stripTerminalSequences(line).includes("First"));
+	const secondRow = lines.findIndex((line) => stripTerminalSequences(line).includes("Second"));
+	assert.ok(firstRow >= 0 && secondRow >= 0);
+	root.handleMouse(event("move", "none", secondRow, 48, lines.length));
+	assert.match(root.render(48).join("\n"), new RegExp(hoverBackground.replace(/[\[\]]/g, "\\$&")));
+	root.handleMouse(event("move", "none", 0, 48, lines.length));
+	assert.doesNotMatch(root.render(48).join("\n"), new RegExp(hoverBackground.replace(/[\[\]]/g, "\\$&")));
+	assert.equal(renders, 1);
+	root.handleMouse(event("move", "none", 0, 48, lines.length));
+	assert.equal(renders, 1);
+	list.handleMouse(event("move", "none", secondRow, 48, lines.length));
+	list.setDisabled(true);
+	assert.doesNotMatch(
+		root.render(48).join("\n"),
+		new RegExp(hoverBackground.replace(/[\[\]]/g, "\\$&")), "disabling clears hover",
+	);
+	const before = list.getSelectedItem()?.id;
+	for (const [type, button, delta] of [
+		["move", "none"], ["press", "left"],
+		["click", "left"], ["wheel", "none", 1],
+	] as const) {
+		assert.equal(
+			root.handleMouse(event(type, button, firstRow, 48, lines.length, delta)), undefined,
+		);
+	}
+	for (const input of ["\r", "\u001b"]) list.handleInput(input);
+	assert.deepEqual(
+		[list.getSelectedItem()?.id, selected, cancelled], [before, 0, 0],
+		"disabled mouse and keyboard events cannot mutate or activate",
+	);
+});
+
+test("empty native choice lists do not activate phantom selections", () => {
+	const list = new NativeChoiceList([], theme);
+	let selected = 0;
+	let cancelled = 0;
+	list.onSelect = () => { selected++; };
+	list.onCancel = () => { cancelled++; };
+	list.handleInput("\r");
+	list.handleInput("\u001b");
+	assert.equal(selected, 0);
+	assert.equal(cancelled, 1);
+});
+
+test("native choice list composes rows through the shared pointer scope", () => {
+	const originalWrap = NativePointerScope.prototype.wrap;
+	let wraps = 0;
+	const spy = mock.method(NativePointerScope.prototype, "wrap", function (
+		this: NativePointerScope, child: Component, callbacks: NativePointerRegionCallbacks,
+	) {
+		wraps++;
+		return originalWrap.call(this, child, callbacks);
+	});
+	try {
+		const list = new NativeChoiceList([
+			{ id: "first", label: "First" },
+			{ id: "second", label: "Second" },
+		], theme);
+		const lines = list.render(40);
+		assert.equal(wraps, 2, "each choice row uses the composable shared pointer primitive");
+		const second = lines.findIndex((line) => line.includes("Second"));
+		assert.ok(second >= 0);
+		assert.equal(list.handleMouse(event("move", "none", second, 40, lines.length))?.render, true);
+		assert.equal(list.getSelectedItem()?.id, "first", "hover remains distinct from keyboard selection");
+	} finally {
+		spy.mock.restore();
+	}
+});

package/tests/native-fullscreen-interaction.test.ts

@@ -0,0 +1,125 @@
+import assert from "node:assert/strict";
+import test, { mock } from "node:test";
+import { Container, MouseRegion, type TuiMouseEvent, SelectList, Text } from "@earendil-works/pi-tui";
+import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
+
+const items = [
+	{ value: "first", label: "First option", description: "A description keeps the list layout realistic." },
+	{ value: "second", label: "Second option", description: "A second description verifies the target row." },
+];
+
+const theme = {
+	selectedPrefix: (text: string) => text,
+	selectedText: (text: string) => text,
+	description: (text: string) => text,
+	scrollInfo: (text: string) => text,
+	noMatch: (text: string) => text,
+};
+
+function mouse(
+	type: TuiMouseEvent["type"],
+	button: TuiMouseEvent["button"],
+	y: number,
+	height: number,
+	wheelDelta?: number,
+): TuiMouseEvent {
+	return {
+		type,
+		button,
+		x: 0,
+		y,
+		screenX: 0,
+		screenY: y,
+		width: 80,
+		height,
+		shift: false,
+		alt: false,
+		ctrl: false,
+		wheelDelta,
+	};
+}
+
+test("native fullscreen interaction preserves observer order and native dispatch identity", () => {
+	const order: string[] = [];
+	const root = createNativeFullscreenInteraction({
+		keyboardTarget: new Text("keyboard", 0, 0),
+		requestRender() {},
+		mouseObserver: { beforeMouse: () => order.push("before"), afterMouse: () => order.push("after") },
+	});
+	root.addChild(new Text("before child", 0, 0));
+	root.addChild(new MouseRegion(new Text("native child", 0, 0), () => {
+		order.push("native child");
+		return { handled: true, focus: true };
+	}));
+	root.addChild(new Text("after child", 0, 0));
+	const lines = root.render(80);
+	const row = lines.findIndex((line) => line.includes("native child"));
+	assert.ok(row >= 0);
+	const nativeHandleMouse = Container.prototype.handleMouse;
+	let nativeResult: ReturnType<typeof nativeHandleMouse>;
+	const spy = mock.method(Container.prototype, "handleMouse", function (this: Container, event: TuiMouseEvent) {
+		nativeResult = nativeHandleMouse.call(this, event);
+		return nativeResult;
+	});
+	try {
+		const result = root.handleMouse(mouse("press", "left", row, lines.length));
+		assert.deepEqual(order, ["before", "native child", "after"]);
+		assert.equal(result, nativeResult, "the observer returns the exact native Container result");
+		assert.equal(result?.focusTarget, root, "native focus ownership remains with the root");
+	} finally {
+		spy.mock.restore();
+	}
+});
+
+test("native fullscreen interaction preserves Container geometry and SelectList behavior", () => {
+	const list = new SelectList(items, items.length, theme);
+	const selected: string[] = [];
+	let renders = 0;
+	list.onSelect = (item) => selected.push(item.value);
+	const root = createNativeFullscreenInteraction({
+		keyboardTarget: list,
+		requestRender: () => { renders++; },
+	});
+	root.addChild(new Text("A long header wraps before the SelectList and must not define hit rows.", 1, 0));
+	root.addChild(list);
+
+	assert.ok(root instanceof Container);
+	assert.ok(root.render(20).length > items.length, "the narrow render includes a wrapped header");
+	const lines = root.render(80);
+	const secondRow = lines.findIndex((line) => line.includes("Second option"));
+	assert.ok(secondRow >= 0, "the test locates the actual rendered SelectList row");
+
+	const wheel = root.handleMouse(mouse("wheel", "none", secondRow, lines.length, 1));
+	assert.equal(wheel?.handled, true);
+	assert.equal(wheel?.render, true);
+	assert.deepEqual(selected, [], "wheel never activates an option");
+	assert.equal(
+		root.handleMouse(mouse("wheel", "none", secondRow, lines.length, 1))?.render,
+		false,
+		"wheel clamps at the final item",
+	);
+	assert.equal(root.handleMouse(mouse("move", "none", secondRow, lines.length)), undefined);
+	assert.equal(list.getSelectedItem()?.value, "second", "move does not change native selection");
+
+	root.handleInput("\u001b[A");
+	assert.equal(renders, 1, "keyboard input forwards to the native control and requests a render");
+	assert.equal(list.getSelectedItem()?.value, "first", "keyboard selection remains independent of pointer movement");
+	assert.deepEqual(selected, [], "keyboard navigation does not activate an option");
+
+	const press = root.handleMouse(mouse("press", "left", secondRow, lines.length));
+	assert.equal(press?.handled, true);
+	assert.equal(press?.focus, true);
+	assert.equal(press?.focusTarget, root, "the root remains the keyboard focus owner");
+	assert.deepEqual(selected, [], "press never activates an option");
+	assert.equal(root.handleMouse(mouse("release", "left", secondRow, lines.length)), undefined);
+	assert.equal(root.handleMouse(mouse("click", "right", secondRow, lines.length)), undefined);
+	assert.equal(root.handleMouse(mouse("click", "left", lines.length, lines.length)), undefined);
+
+	root.handleInput("\r");
+	assert.equal(renders, 2, "Enter renders after activating the focused native item");
+	assert.deepEqual(selected, ["second"], "Enter activates the item selected by press");
+
+	const click = root.handleMouse(mouse("click", "left", secondRow, lines.length));
+	assert.equal(click?.handled, true);
+	assert.deepEqual(selected, ["second", "second"]);
+});