gentle-pi 3.2.1 → 3.4.0

package/tests/shell-sidebar-layout.test.ts

@@ -1,9 +1,9 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { CURSOR_MARKER, ScrollView, VStack, visibleWidth, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { CURSOR_MARKER, ScrollView, VStack, visibleWidth, type Component, type TUI, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { getScrollViewsAt, renderLayoutFrame, type LayoutBox } from "@earendil-works/pi-tui/dist/layout.js";
 import { installSidebar, invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
-import { sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
+import { sidebarHeader, sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
 import { renderShellSidebarBar } from "../lib/shell-bar.ts";
 import { renderTodoCard, type TodoState } from "../lib/shell-todo.ts";
 
@@ -23,6 +23,20 @@ function rail(f: ReturnType<typeof fixture>): ScrollView {
 	assert.equal(node.type, "hstack");
 	return node.entries[1].component;
 }
+type HstackNode = { type: string; gap: number; align: string; entries: { component: unknown; basis: number | string; grow: number; shrink: number; minSize: number }[] };
+// Finds the [left, scroll] hstack regardless of whether it is returned
+// directly (no active header) or nested one level under the header vstack.
+function hstackOf(f: ReturnType<typeof fixture>): HstackNode {
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: { [NODE]?(): HstackNode } }[] };
+	if (node.type === "hstack") return node as unknown as HstackNode;
+	assert.equal(node.type, "vstack");
+	const nested = node.entries[1]?.component[NODE]?.();
+	assert.ok(nested, "the vstack's second entry must expose the hstack via NODE");
+	return nested!;
+}
+function railWithHeader(f: ReturnType<typeof fixture>): ScrollView {
+	return hstackOf(f).entries[1].component as ScrollView;
+}
 
 test("grouped Status preserves structured fields and opaque integration text", () => {
 	const lines = renderShellSidebarBar({
@@ -32,13 +46,14 @@ test("grouped Status preserves structured fields and opaque integration text", (
 	}, theme, 46);
 	const text = lines.join("\n");
 	let previous = -1;
-	for (const heading of ["Status", "Project", "Changes", "Usage", "Integrations"]) {
+	for (const heading of ["Status", "Project", "Changes", "Integrations"]) {
 		const index = text.indexOf(heading);
 		assert.ok(index > previous, heading);
 		previous = index;
 	}
 	assert.match(text, /opaque integration/);
 	assert.match(text, /Branch.*main/);
+	assert.doesNotMatch(text, /Usage/);
 });
 
 test("scrollable TODO keeps every task while bottom and collapsed cards stay bounded", () => {
@@ -115,7 +130,7 @@ test("wheel scrolls the rail and is consumed at both boundaries and blank space"
 	f.host.terminal.columns = 160;
 	const restored = rail(f);
 	assert.deepEqual(f.bottom.render(80), []);
-	const layout = f.root[NODE]() as unknown as { gap: number; entries: { basis: number; grow: number; shrink: number; minSize: number }[] };
+	const layout = f.root[NODE]() as unknown as { gap: number; entries: { basis: number | string; grow: number; shrink: number; minSize: number }[] };
 	assert.equal(layout.gap, 3);
 	assert.deepEqual(layout.entries.map(({ basis, grow, shrink, minSize }) => ({ basis, grow, shrink, minSize })), [
 		{ basis: 0, grow: 1, shrink: 1, minSize: 1 },
@@ -173,11 +188,13 @@ test("rail dispatches a clipped, scroll-translated left click to only the matchi
 	const hit = scroll.handleMouse(mouse("click", "left", headerY));
 	assert.equal(hit?.handled, true);
 	assert.equal(clicks, 1);
-	assert.deepEqual(received.at(-1) && { x: received.at(-1)!.x, y: received.at(-1)!.y, width: received.at(-1)!.width, height: received.at(-1)!.height }, { x: 1, y: 0, width: 47, height: 2 });
+		// With a transient scrollbar the rail no longer reserves a column, so
+	// clipped parts are one column wider than in the always-on geometry.
+	assert.deepEqual(received.at(-1) && { x: received.at(-1)!.x, y: received.at(-1)!.y, width: received.at(-1)!.width, height: received.at(-1)!.height }, { x: 1, y: 0, width: 48, height: 2 });
 
 	const gapY = headerY - 1;
 	assert.equal(scroll.handleMouse(mouse("click", "left", gapY)), undefined, "section gaps do not hit a neighbor");
-	assert.equal(scroll.handleMouse({ ...mouse("click", "left", headerY), x: 48 }), undefined, "padding outside the clipped part is inert");
+	assert.equal(scroll.handleMouse({ ...mouse("click", "left", headerY), x: 49 }), undefined, "padding outside the clipped part is inert");
 	invalidateSidebar(f.tui);
 	assert.equal(scroll.handleMouse(mouse("click", "left", headerY)), undefined, "stale geometry is inert");
 	f.host.terminal.columns = 139;
@@ -265,14 +282,17 @@ test("real layout frames reuse unchanged sidebar output and invalidate at state
 	assert.deepEqual(f.bottom.render(80), ["Status"]);
 	f.host.terminal.columns = 140;
 	renderLayoutFrame(f.root, 140, 20, () => {});
-	assert.deepEqual(counts, { footer: 3, changes: 0, agents: 3, todo: 3 });
+	// Dipping below the breakpoint and back nulls the whole-rail `prepared`
+	// memo, but the per-section cache survives underneath it: the revision
+	// never moved, so no section actually needed to re-render.
+	assert.deepEqual(counts, { footer: 2, changes: 0, agents: 2, todo: 2 });
 
 	f.host.mode = "regular";
 	renderLayoutFrame(f.root, 140, 20, () => {});
 	assert.deepEqual(f.bottom.render(80), ["Status"]);
 	f.host.mode = "fullscreen";
 	renderLayoutFrame(f.root, 140, 20, () => {});
-	assert.deepEqual(counts, { footer: 4, changes: 0, agents: 4, todo: 4 });
+	assert.deepEqual(counts, { footer: 2, changes: 0, agents: 2, todo: 2 });
 
 	let replacementRenders = 0;
 	sidebarPart(f.tui, "todo", {
@@ -469,3 +489,276 @@ test("native transcript and sidebar keep separate scroll routing across resize,
 		assert.equal(result.frame.root.children.some(box => box.component === rail), mode === "fullscreen" && width >= 140);
 	}
 });
+
+// T3: per-section render memo. Each rail section caches its rendered lines by
+// its own digest, so a section whose digest did not change is never re-run
+// when a sibling section's digest ticks — only the whole rail's assembled
+// `lines`/`hits` are rebuilt from the (possibly cached) per-section lines.
+
+test("a footer digest change does not re-render Agents or TODO", (t) => {
+	const f = fixture();
+	let footerLabel = "one";
+	const counts = { footer: 0, agents: 0, todo: 0 };
+	sidebarPart(f.tui, "footer", { render: () => ["Status"], invalidate() {} }, {
+		digest: () => footerLabel,
+		render: () => { counts.footer++; return [`Footer ${footerLabel}`]; },
+		invalidate() {},
+	});
+	for (const key of ["agents", "todo"] as const) {
+		sidebarPart(f.tui, key, { render: () => [key], invalidate() {} }, {
+			render: () => { counts[key]++; return [key]; },
+			invalidate() {},
+		});
+	}
+	t.after(installSidebar(f.tui, theme));
+
+	assert.match(rail(f).render(50).join("\n"), /Footer one/);
+	assert.deepEqual(counts, { footer: 1, agents: 1, todo: 1 });
+
+	// Re-render with nothing changed at all: the outer unchanged fast path
+	// must not call any section's render either.
+	assert.match(rail(f).render(50).join("\n"), /Footer one/);
+	assert.deepEqual(counts, { footer: 1, agents: 1, todo: 1 });
+
+	footerLabel = "two";
+	assert.match(rail(f).render(50).join("\n"), /Footer two/);
+	assert.deepEqual(counts, { footer: 2, agents: 1, todo: 1 }, "only the section whose digest changed re-renders");
+
+	// invalidateSidebar bumps the global revision, which is only what a
+	// no-digest section keys its cache on: footer's own unchanged digest
+	// still protects it from re-rendering.
+	invalidateSidebar(f.tui);
+	assert.match(rail(f).render(50).join("\n"), /Footer two/);
+	assert.deepEqual(counts, { footer: 2, agents: 2, todo: 2 }, "revision invalidation reaches only the sections with no digest of their own");
+});
+
+test("a throwing digest still degrades to invalidation-only under the per-section memo", (t) => {
+	const f = fixture();
+	let todoRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		digest: () => { throw new Error("broken digest"); },
+		render: () => { todoRenders++; return ["Todo card"]; },
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	assert.match(rail(f).render(50).join("\n"), /Todo card/);
+	assert.equal(todoRenders, 1);
+	assert.match(rail(f).render(50).join("\n"), /Todo card/);
+	assert.equal(todoRenders, 1, "an unchanged frame reuses the cached section even without a digest");
+
+	invalidateSidebar(f.tui);
+	assert.match(rail(f).render(50).join("\n"), /Todo card/);
+	assert.equal(todoRenders, 2, "explicit invalidation still reaches a rail without a digest");
+});
+
+test("a part replaced under the same key never reuses the previous part's cached lines", (t) => {
+	const f = fixture();
+	let firstRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		render: () => { firstRenders++; return ["first"]; },
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+	assert.match(rail(f).render(50).join("\n"), /first/);
+	assert.equal(firstRenders, 1);
+
+	let secondRenders = 0;
+	sidebarPart(f.tui, "todo", { render: () => ["Todo"], invalidate() {} }, {
+		render: () => { secondRenders++; return ["second"]; },
+		invalidate() {},
+	});
+	const text = rail(f).render(50).join("\n");
+	assert.match(text, /second/);
+	assert.doesNotMatch(text, /first/);
+	assert.equal(secondRenders, 1);
+});
+
+// T2: the live header row. A registered "header" part wraps the existing
+// [left, scroll] hstack in a one-row-taller vstack and takes over the brand
+// the banner used to carry inside the rail. Hosts that never register a
+// header (every fixture above) keep the exact old hstack-direct shape.
+
+test("an active header wraps the hstack in a vstack and removes the banner from the rail", (t) => {
+	const f = fixture();
+	sidebarHeader(f.tui, { render: (width: number) => [`HEADER ${width}`], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	const node = f.root[NODE]() as unknown as HstackNode;
+	assert.equal(node.type, "vstack");
+	assert.equal(node.gap, 0);
+	assert.equal(node.align, "stretch");
+	// basis "auto": pi-tui measures the header leaf from its rendered lines
+	// (one line: the status bar; with the rule row: two) instead of hard-pinning the row.
+	assert.deepEqual(node.entries.map(({ basis, grow, shrink, minSize }) => ({ basis, grow, shrink, minSize })), [
+		{ basis: "auto", grow: 0, shrink: 0, minSize: 1 },
+		{ basis: 0, grow: 1, shrink: 1, minSize: 1 },
+	]);
+	const header = node.entries[0].component as { render(width: number): string[] };
+	// The rail card ends two columns before the terminal edge (its padding plus
+	// the scrollbar column); the header stops there too so its right group
+	// lines up with the card border instead of touching the edge.
+	assert.deepEqual(header.render(0), ["HEADER 138"], "the header renders at the terminal width minus the rail's right inset, not the rail width");
+
+	const hstack = hstackOf(f);
+	assert.equal(hstack.type, "hstack");
+	const scroll = railWithHeader(f);
+	const rail = scroll.render(50);
+	assert.doesNotMatch(rail.join("\n"), /✿ Gentle Shell ✿/, "the header carries the brand now, not the banner");
+	// The banner used to hold the first card away from the top; with the
+	// header in its place the rail keeps one blank row so the first card does
+	// not sit flush against the header.
+	assert.equal(rail[0]?.trim(), "", "the rail opens with a blank row under the header");
+	assert.notEqual(rail[1]?.trim(), "", "the first card starts on the second row");
+});
+
+test("the header leaf carries the rule row: a two-line header renders both lines at full width", (t) => {
+	const f = fixture();
+	sidebarHeader(f.tui, {
+		render: (width: number) => [`HEADER ${width}`, `RULE ${width}`],
+		invalidate() {},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: Component }[] };
+	assert.equal(node.type, "vstack", "a two-line header still wraps the hstack in a vstack");
+	const header = node.entries[0]!.component as { render(width: number): string[] };
+	assert.deepEqual(header.render(0), ["HEADER 138", "RULE 138"], "both the status line and the rule row reach the layout, rendered at the terminal width minus the rail's right inset");
+});
+
+test("below the sidebar breakpoint a rule-like header paints no rule row", (t) => {
+	const f = fixture("fullscreen", 139);
+	sidebarHeader(f.tui, { render: (width: number) => [`HEADER ${width}`, `RULE ${width}`], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	// Below SIDEBAR_BREAKPOINT prepare() declines, so the replacement hands
+	// back the native root's own layout node: neither the header wrapper nor
+	// a rule row ever paints.
+	assert.deepEqual(f.root[NODE](), f.original(), "below the breakpoint the rule is removed with the whole sidebar");
+});
+
+test("without a registered header the rail keeps the banner and the plain hstack", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const node = f.root[NODE]() as unknown as { type: string };
+	assert.equal(node.type, "hstack");
+	const scroll = rail(f);
+	assert.match(scroll.render(50).join("\n"), /✿ Gentle Shell ✿/);
+});
+
+test("a header too narrow to show anything falls back to the plain hstack and the banner", (t) => {
+	const f = fixture();
+	sidebarHeader(f.tui, { render: () => [""], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+	const node = f.root[NODE]() as unknown as { type: string };
+	assert.equal(node.type, "hstack", "a blank header line does not earn its own row");
+	const scroll = rail(f);
+	assert.match(scroll.render(50).join("\n"), /✿ Gentle Shell ✿/);
+});
+
+test("header content changes reach the header row while an unrelated part is untouched", (t) => {
+	const f = fixture();
+	let label = "one";
+	sidebarHeader(f.tui, { digest: () => label, render: () => [`HEADER ${label}`], invalidate() {} });
+	t.after(installSidebar(f.tui, theme));
+
+	const headerLines = () => (f.root[NODE]() as unknown as HstackNode).entries[0].component as { render(width: number): string[] };
+	assert.deepEqual(headerLines().render(0), ["HEADER one"]);
+	label = "two";
+	assert.deepEqual(headerLines().render(0), ["HEADER two"]);
+});
+
+test("rail mouse dispatch still maps clicks correctly with the header row above it", (t) => {
+	const f = fixture();
+	let clicks = 0;
+	const todo = {
+		render: () => ["Todo header", "Todo body"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			if (event.type !== "click" || event.button !== "left" || event.y !== 0) return undefined;
+			clicks++;
+			return { handled: true, render: true };
+		},
+	};
+	sidebarPart(f.tui, "todo", todo);
+	sidebarHeader(f.tui, { render: () => ["HEADER"], invalidate() {} });
+	const dispose = installSidebar(f.tui, theme);
+	t.after(dispose);
+	const scroll = railWithHeader(f);
+	const content = scroll.render(50);
+	scroll.updateLayout(content.length, 5, () => {});
+	const headerY = content.findIndex((line) => line.includes("Todo header"));
+	assert.ok(headerY >= 0);
+	// The mouse event carries coordinates local to the scroll component itself
+	// (pi-tui's layout tree translates screen coordinates before dispatch), so
+	// nesting the hstack one level deeper under the header row does not shift
+	// what the rail receives.
+	const hit = scroll.handleMouse({ type: "click", button: "left", x: 2, y: headerY, screenX: 92, screenY: 31 + headerY, width: 50, height: 5, shift: false, alt: false, ctrl: false });
+	assert.equal(hit?.handled, true);
+	assert.equal(clicks, 1);
+});
+
+// T8(c): the header row is a leaf in the layout tree, not inside the rail's
+// ScrollView, so pi-tui's mouse dispatch (tui-alt-screen.js) finds and calls
+// its own handleMouse directly — it never goes through dispatchPartMouse.
+test("the header component's handleMouse delegates to the registered header part", (t) => {
+	const f = fixture();
+	const received: TuiMouseEvent[] = [];
+	let result: { handled: boolean; render?: boolean } | undefined = { handled: true, render: true };
+	sidebarHeader(f.tui, {
+		render: () => ["HEADER"],
+		invalidate() {},
+		handleMouse(event: TuiMouseEvent) {
+			received.push(event);
+			return result;
+		},
+	});
+	t.after(installSidebar(f.tui, theme));
+
+	const node = f.root[NODE]() as unknown as { type: string; entries: { component: Component }[] };
+	assert.equal(node.type, "vstack", "an active header wraps the hstack in a vstack");
+	const header = node.entries[0]!.component as { handleMouse(event: TuiMouseEvent): { handled: boolean; render?: boolean } | undefined };
+
+	const event = { type: "click", button: "left", x: 5, y: 0, screenX: 5, screenY: 0, width: 140, height: 1, shift: false, alt: false, ctrl: false } as TuiMouseEvent;
+	assert.deepEqual(header.handleMouse(event), { handled: true, render: true });
+	assert.equal(received.length, 1);
+	assert.equal(received[0], event, "the event reaches the registered part unmodified");
+
+	result = undefined;
+	assert.equal(header.handleMouse(event), undefined, "an ignored click returns undefined, same as any other component");
+});
+
+test("the header component's handleMouse is a harmless no-op when no header part is registered", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const node = f.root[NODE]() as unknown as { type: string; entries?: { component: Component }[] };
+	// No header registered: the active node stays the plain hstack (T2's
+	// backward-compatible fallback), so there is no header leaf to click at all.
+	assert.equal(node.type, "hstack");
+});
+
+test("rail scrollbar is transient: hidden by default, visible only while scrolling overflow", (t) => {
+	const f = fixture();
+	t.mock.timers.enable({ apis: ["setTimeout"] });
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	// Regression guard: the rail scroll view used to hardcode scrollbar
+	// "always", re-slicing its column on every render pass even when idle.
+	assert.equal(scroll.scrollbar, "auto");
+	sidebarPart(f.tui, "todo", { render: () => Array.from({ length: 60 }, (_, i) => `todo row ${i}`), invalidate() {} });
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	assert.equal(scroll.isScrollbarVisible, false, "no scroll yet: hidden even with overflow");
+	scroll.scrollBy(1);
+	assert.equal(scroll.isScrollbarVisible, true, "rail scroll reveals the transient scrollbar");
+	t.mock.timers.tick(1000);
+	assert.equal(scroll.isScrollbarVisible, false, "hidden again after the transient window");
+});
+
+test("rail scrollbar stays hidden when the rail does not overflow", (t) => {
+	const f = fixture();
+	t.after(installSidebar(f.tui, theme));
+	const scroll = rail(f);
+	renderLayoutFrame(f.root, 140, 20, () => {});
+	scroll.scrollBy(1);
+	assert.equal(scroll.isScrollbarVisible, false);
+});

package/tests/shell-sidebar.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import type { TUI } from "@earendil-works/pi-tui";
-import { sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
+import { sidebarHeader, sidebarPart, sidebarState } from "../lib/shell-sidebar.ts";
 
 const host = (terminal?: object) => ({ terminal }) as TUI;
 const component = () => ({ render: (_width = 80) => ["bottom"], invalidate() {} });
@@ -48,3 +48,27 @@ test("disposing an old part preserves its replacement and releases its bottom",
 	(second as typeof second & { dispose?(): void }).dispose?.();
 	assert.equal(sidebarState(tui).parts.size, 0);
 });
+
+test("sidebarHeader registers the header part under its own key and disposes it without a bottom widget", () => {
+	const tui = host({});
+	const rail = { render: () => ["header line"], invalidate() {}, digest: () => "d" };
+	const dispose = sidebarHeader(tui, rail);
+	assert.equal(sidebarState(tui).parts.get("header"), rail);
+	dispose();
+	assert.equal(sidebarState(tui).parts.get("header"), undefined);
+});
+
+test("sidebarHeader on an unsupported host is a harmless no-op", () => {
+	const dispose = sidebarHeader(host(), { render: () => [], invalidate() {} });
+	assert.doesNotThrow(dispose);
+});
+
+test("sidebarHeader dispose does not remove a replacement rail registered after it", () => {
+	const tui = host({});
+	const first = { render: () => ["first"], invalidate() {} };
+	const dispose = sidebarHeader(tui, first);
+	const second = { render: () => ["second"], invalidate() {} };
+	sidebarHeader(tui, second);
+	dispose();
+	assert.equal(sidebarState(tui).parts.get("header"), second);
+});

package/tests/shell-todo.test.ts

@@ -231,6 +231,42 @@ test("completed titles strike only title cells across wrapped lines, never paddi
 	}
 });
 
+test("renderTodoCard paints the sidebar rail and the bottom widget with the same rose INFO frame", () => {
+	const taggedTheme = {
+		fg(color: string, text: string) {
+			return `<${color}>${text}</${color}>`;
+		},
+		strikethrough(text: string) {
+			return text;
+		},
+	};
+	const sidebar = renderTodoCard(seeded(), taggedTheme, 60, { scrollable: true, collapsed: false, staleTurns: 0 });
+	assert.match(sidebar[0], /<border>╭<\/border>/);
+	assert.match(sidebar[0], /<accent>❀ Todos/);
+
+	const bottom = renderTodoCard(seeded(), taggedTheme, 60, { collapsed: false, staleTurns: 0 });
+	assert.match(bottom[0], /<border>╭<\/border>/);
+	assert.match(bottom[0], /<accent>❀ Todos/);
+});
+
+// H1 (odd/tasks/usage-click-and-changes-attribution.md): the same shared
+// hover role every other clickable surface uses.
+test("renderTodoCard paints its clickable header control in the shared hover role when hovered", () => {
+	const taggedTheme = {
+		fg(color: string, text: string) {
+			return `<${color}>${text}</${color}>`;
+		},
+		strikethrough(text: string) {
+			return text;
+		},
+	};
+	const idle = renderTodoCard(seeded(), taggedTheme, 70, { collapsed: false, staleTurns: 0 });
+	assert.match(idle[0], /<accent>▾ Collapse<\/accent>/, "idle keeps its ordinary accent role");
+	const hovered = renderTodoCard(seeded(), taggedTheme, 70, { collapsed: false, staleTurns: 0, hovered: true });
+	assert.match(hovered[0], /<warning>▾ Collapse<\/warning>/, "hovering paints the shared hover role");
+	assert.doesNotMatch(hovered[0], /<accent>▾ Collapse/);
+});
+
 test("renderTodoCard keeps stale indicators and collapse hints in scrollable lists", () => {
 	const tasks = Array.from({ length: 40 }, (_, index) => ({ title: `Task ${index + 1}`, status: index < 25 ? "done" : "pending" }));
 	const state = applyTodo(emptyTodo(), { action: "write", tasks }, 1).state;

package/tests/shell-usage-view.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { visibleWidth } from "@earendil-works/pi-tui";
+import { visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { stripAnsi } from "../lib/terminal-theme.ts";
 import { parseCodexUsage, UsageStore } from "../lib/shell-usage.ts";
 import { UsageView } from "../lib/shell-usage-view.ts";
@@ -61,3 +61,122 @@ test("UsageView refetches on r and closes on escape or q", async () => {
 	view.handleInput("q");
 	assert.equal(events.filter((event) => event === "close").length, 2);
 });
+
+function click(x: number, y: number, width: number, height: number): TuiMouseEvent {
+	return { type: "click", button: "left", x, y, screenX: x, screenY: y, width, height, shift: false, alt: false, ctrl: false };
+}
+
+test("UsageView.handleMouse clicks the footer hints like the matching key", async () => {
+	const store = new UsageStore();
+	const events: string[] = [];
+	let resolveRefresh: (() => void) | undefined;
+	const view = new UsageView(store, {
+		theme: plainTheme,
+		now: () => NOW,
+		active: () => undefined,
+		onRefresh: () =>
+			new Promise<void>((resolve) => {
+				events.push("refresh");
+				resolveRefresh = resolve;
+			}),
+		onClose: () => events.push("close"),
+		requestRender: () => events.push("render"),
+	});
+	const width = 90;
+	const lines = view.render(width);
+	const rowIndex = lines.findIndex((line) => stripAnsi(line).includes("r refresh"));
+	assert.ok(rowIndex > 0, "the footer hints row must be present");
+	const plain = stripAnsi(lines[rowIndex]);
+	const refreshStart = plain.indexOf("r refresh");
+	const closeStart = plain.indexOf("esc close");
+	assert.ok(refreshStart >= 0 && closeStart >= 0);
+
+	// A click outside any hint span is ignored, like a click on an empty part of the frame.
+	assert.equal(view.handleMouse(click(0, rowIndex, width, lines.length)), undefined);
+	assert.deepEqual(events, []);
+
+	// A click on "r refresh" triggers the same refresh as the r key.
+	assert.deepEqual(view.handleMouse(click(refreshStart + 1, rowIndex, width, lines.length)), { handled: true, render: true });
+	assert.deepEqual(events, ["render", "refresh"]);
+
+	// A second click while the refresh is still in flight must not re-enter it.
+	assert.deepEqual(view.handleMouse(click(refreshStart + 1, rowIndex, width, lines.length)), { handled: true, render: true });
+	assert.deepEqual(events, ["render", "refresh"]);
+	resolveRefresh?.();
+	await new Promise((resolve) => setTimeout(resolve, 0));
+	assert.deepEqual(events, ["render", "refresh", "render"]);
+
+	// A click on "esc close" closes the overlay, like the esc/q keys.
+	assert.deepEqual(view.handleMouse(click(closeStart + 1, rowIndex, width, lines.length)), { handled: true, render: true });
+	assert.equal(events.filter((event) => event === "close").length, 1);
+});
+
+function move(x: number, y: number, width: number, height: number): TuiMouseEvent {
+	return { type: "move", button: "none", x, y, screenX: x, screenY: y, width, height, shift: false, alt: false, ctrl: false };
+}
+
+// H1 (odd/tasks/usage-click-and-changes-attribution.md): the same shared
+// hover role every other clickable surface uses.
+test("UsageView.handleMouse paints the shared hover role over a footer hint, and clears it on leave", () => {
+	const store = new UsageStore();
+	const taggedTheme = { fg: (role: string, text: string) => `<${role}>${text}</${role}>` };
+	const view = new UsageView(store, {
+		theme: taggedTheme,
+		now: () => NOW,
+		active: () => undefined,
+		onRefresh: async () => {},
+		onClose: () => {},
+		requestRender: () => {},
+	});
+	const width = 90;
+	const lines = view.render(width);
+	// The frame draws "│ " (2 columns) before the fitted footer content, and
+	// hints are laid out as plain "key label" text joined by 3 spaces -- these
+	// column offsets are computed purely from that plain text, independent of
+	// the theme, so they hold under taggedTheme exactly as under plainTheme.
+	const rowIndex = lines.length - 2;
+	const refreshStart = 2;
+	const closeStart = refreshStart + "r refresh".length + 3;
+	const height = lines.length;
+
+	assert.equal(view.handleMouse(move(0, rowIndex, width, height)), undefined, "a move outside any hint is not this component's gesture");
+	assert.doesNotMatch(view.render(width).join("\n"), /<warning>/, "idle: nothing painted yet");
+
+	const entered = view.handleMouse(move(refreshStart + 1, rowIndex, width, height));
+	assert.deepEqual(entered, { handled: true, render: true });
+	assert.match(view.render(width).join("\n"), /<warning>r refresh<\/warning>/, "hovering the refresh hint paints it, key and label together");
+	assert.doesNotMatch(view.render(width).join("\n"), new RegExp(`<warning>esc close`), "the other hint stays unpainted");
+
+	// Moving straight to the other hint switches which one is painted.
+	const switched = view.handleMouse(move(closeStart + 1, rowIndex, width, height));
+	assert.deepEqual(switched, { handled: true, render: true });
+	assert.match(view.render(width).join("\n"), /<warning>esc close<\/warning>/);
+	assert.doesNotMatch(view.render(width).join("\n"), /<warning>r refresh/);
+
+	const left = view.handleMouse(move(0, rowIndex, width, height));
+	assert.deepEqual(left, { handled: true, render: true }, "leaving the last hovered hint still requests a repaint");
+	assert.doesNotMatch(view.render(width).join("\n"), /<warning>/, "nothing stays painted once the pointer leaves");
+});
+
+test("a rejected refresh from a click or key never escapes as an unhandled rejection", async () => {
+	const store = new UsageStore();
+	const events: string[] = [];
+	const unhandled: unknown[] = [];
+	const onUnhandled = (reason: unknown) => unhandled.push(reason);
+	process.on("unhandledRejection", onUnhandled);
+	try {
+		const view = new UsageView(store, { theme: plainTheme, now: () => NOW, active: () => undefined, onRefresh: async () => { throw new Error("provider down"); }, onClose: () => events.push("close"), requestRender: () => events.push("render") });
+		const lines = view.render(80);
+		const row = lines.length - 2;
+		const column = lines[row]!.indexOf("r refresh") + 1;
+		view.handleMouse({ type: "click", button: "left", x: column, y: row, width: 80, height: lines.length, screenX: column, screenY: row, shift: false, alt: false, ctrl: false } as never);
+		await new Promise((resolve) => setImmediate(resolve));
+		view.handleInput("r");
+		await new Promise((resolve) => setImmediate(resolve));
+		await new Promise((resolve) => setImmediate(resolve));
+		assert.deepEqual(unhandled, [], "a failing usage fetch is reported by the panel, never thrown at the process");
+		assert.match(view.render(80).join("\n"), /r refresh/, "the refresh hint is back after the failure");
+	} finally {
+		process.off("unhandledRejection", onUnhandled);
+	}
+});