@bismawy/pi-arnative 0.3.10 → 0.5.1

package/lib/ansi.ts

@@ -38,15 +38,70 @@ export function setActiveTheme<T>(th: T | null): void {
 	else delete (globalThis as Record<symbol, T>)[THEME_PROXY_KEY];
 }
 
-/** Painter for the `accentSoft` token, which only arnative themes define; other themes fall back to accent (probed once). */
-export function accentSoftOf(th: { fg?(c: string, t: string): string } | null): (s: string) => string {
+/**
+ * Painter for arnative's soft accent (`accentSoft`).
+ *
+ * Pi <=1.1.0 let a theme declare extra tokens in `colors`, so `accentSoft` was
+ * addressable directly. 1.2.0 validates `colors` with `additionalProperties: false`
+ * and rejects the whole theme if it carries one, so the token now lives only in
+ * `vars` and `fg("accentSoft")` throws. The soft accent stays available through the
+ * resolved `accent` color (1.2.0 exposes `theme.colors`): its hue and chroma are
+ * softened to the generator's `*Soft` recipe, which keeps the two-tone look instead
+ * of collapsing to grey. Falls back to `muted`, then `accent`, on any older theme.
+ */
+export function softOf(th: {
+	fg?(c: string, t: string): string;
+	style?(t: string, o: { fg: unknown }): string;
+	colors?: Record<string, { kind?: string; c?: number; h?: number }>;
+} | null): (s: string) => string {
 	const fg = th?.fg?.bind(th);
 	if (!fg) return (s) => s;
 	try {
 		fg("accentSoft", "");
 		return (s) => fg("accentSoft", s);
 	} catch {
-		return (s) => fg("accent", s);
+		// 1.2.0+ rejects `accentSoft`: derive the soft tint from the resolved accent.
+	}
+	const accent = th?.colors?.accent;
+	const style = th?.style?.bind(th);
+	if (accent?.kind === "oklch" && style) {
+		// The generator's `*Soft` recipe: lightness 0.82, a fifth of the accent chroma.
+		const soft = { kind: "oklch" as const, l: 0.82, c: (accent.c ?? 0) * 0.18, h: accent.h ?? 0 };
+		return (s) => style(s, { fg: soft });
+	}
+	return (s) => fg("muted", s);
+}
+
+/** pi defines one theme slot per thinking level (`thinkingOff`…`thinkingMax`), so a box
+ *  can follow the model instead of a hardcoded palette — switching theme keeps the
+ *  meaning of the color. Shared by `usage.ts` and `arnative.ts`. */
+const THINKING_SLOTS: Record<string, string> = {
+	minimal: "thinkingMinimal",
+	low: "thinkingLow",
+	medium: "thinkingMedium",
+	high: "thinkingHigh",
+	xhigh: "thinkingXhigh",
+	max: "thinkingMax",
+};
+
+function thinkingColorSlot(level: string | undefined): string {
+	return THINKING_SLOTS[(level ?? "off").toLowerCase()] ?? "thinkingOff";
+}
+
+/** Painter for a thinking level, probed once; falls back to `dim` when the theme lacks
+ *  the slot, so a non-arnative theme draws a plain border instead of throwing. */
+export function thinkingColorOf(
+	th: { fg?(c: string, t: string): string } | null,
+	level: string | undefined,
+): (s: string) => string {
+	const fg = th?.fg?.bind(th);
+	if (!fg) return (s) => s;
+	const slot = thinkingColorSlot(level);
+	try {
+		fg(slot, "");
+		return (s) => fg(slot, s);
+	} catch {
+		return (s) => fg("dim", s);
 	}
 }
 
@@ -65,14 +120,42 @@ if (isMain(import.meta.url)) {
 	assert(getActiveTheme<object>() === null, "clearing the active theme leaves no stale slot");
 
 	const tag = { fg: (c: string, t: string) => `<${c}>${t}</${c}>` };
-	assert(accentSoftOf(tag)("x") === "<accentSoft>x</accentSoft>", "accentSoftOf uses accentSoft when the theme defines it");
+	assert(softOf(tag)("x") === "<accentSoft>x</accentSoft>", "softOf uses accentSoft when the theme defines it");
 	const noSoft = {
 		fg: (c: string, t: string) => {
 			if (c === "accentSoft") throw new Error("Unknown theme color: accentSoft");
 			return `<${c}>${t}</${c}>`;
 		},
 	};
-	assert(accentSoftOf(noSoft)("x") === "<accent>x</accent>", "accentSoftOf falls back to accent without the token");
-	assert(accentSoftOf(null)("x") === "x", "accentSoftOf without a theme is identity");
+	assert(softOf(noSoft)("x") === "<muted>x</muted>", "softOf falls back to muted without the token or colors");
+	assert(softOf(null)("x") === "x", "softOf without a theme is identity");
+	// Pi 1.2.0: acentSoft is rejected, so the soft tint is derived from `colors.accent`.
+	const modern = {
+		fg: (c: string, t: string) => {
+			throw new Error(`Unknown theme color: ${c}`);
+		},
+		style: (t: string, o: { fg: unknown }) => `<soft:${JSON.stringify(o.fg)}>${t}</soft>`,
+		colors: { accent: { kind: "oklch", c: 0.2, h: 355 } },
+	};
+	const modernOut = softOf(modern)("x");
+	assert(modernOut.includes('"l":0.82') && modernOut.includes('"c":0.036'), "softOf derives the soft tint from accent (l=0.82, c=accent*0.18)");
+	assert(modernOut.includes("x"), "softOf keeps the text");
+
+	assert(thinkingColorSlot("off") === "thinkingOff", "thinking off maps to thinkingOff");
+	assert(thinkingColorSlot(undefined) === "thinkingOff", "missing level falls back to thinkingOff");
+	assert(thinkingColorSlot("HIGH") === "thinkingHigh", "matching is case-insensitive");
+	assert(thinkingColorSlot("xhigh") === "thinkingXhigh", "xhigh has its own slot");
+	assert(thinkingColorSlot("max") === "thinkingMax", "max maps to thinkingMax");
+	assert(thinkingColorSlot("nonsense") === "thinkingOff", "an unknown level degrades to thinkingOff");
+	assert(thinkingColorOf(tag, "high")("x") === "<thinkingHigh>x</thinkingHigh>", "thinkingColorOf paints the level's slot");
+	assert(thinkingColorOf(tag, undefined)("x") === "<thinkingOff>x</thinkingOff>", "thinkingColorOf defaults to thinkingOff");
+	assert(thinkingColorOf(null, "high")("x") === "x", "thinkingColorOf without a theme is identity");
+	const noThinking = {
+		fg: (c: string, t: string) => {
+			if (c.startsWith("thinking")) throw new Error(`Unknown theme color: ${c}`);
+			return `<${c}>${t}</${c}>`;
+		},
+	};
+	assert(thinkingColorOf(noThinking, "max")("x") === "<dim>x</dim>", "thinkingColorOf falls back to dim without the slot");
 	console.log("lib/ansi.ts OK");
 }

package/lib/box.ts

@@ -3,19 +3,23 @@
  * and usage.ts — edit here, all follow. Lives outside `extensions/*.ts` so pi
  * never loads it as an extension.
  */
-import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { thinkingColorOf } from "./ansi.ts";
 import { assert, isMain } from "./check.ts";
 
-export type BoxTheme = { fg(color: string, text: string): string; bg?(color: string, text: string): string };
+export type BoxTheme = { fg(color: string, text: string): string; bg?(color: string, text: string): string; bold?(text: string): string };
 type Dim = (s: string) => string;
 
 export const boxEdge = (l: string, r: string, width: number, dim: Dim): string =>
 	dim(`${l}${"─".repeat(Math.max(0, width - 2))}${r}`);
 
-/** Content row: │ <text> │, exactly `width` wide. */
+/** Content row: │ <text> │, exactly `width` wide. Content is truncated to preserve border. */
 export const boxRow = (content: string, width: number, dim: Dim): string => {
-	const pad = Math.max(0, width - visibleWidth(content) - 4);
-	return `${dim("│")} ${content}${" ".repeat(pad)} ${dim("│")}`;
+	// Minimum 4 columns required for borders and padding (skill arnative-pi §6 rule 5).
+	if (width < 4) return "";
+	const fitted = truncateToWidth(content, width - 4, "");
+	const pad = Math.max(0, width - visibleWidth(fitted) - 4);
+	return `${dim("│")} ${fitted}${" ".repeat(pad)} ${dim("│")}`;
 };
 
 const applyBg = (line: string, width: number, bgFn: (text: string) => string): string => {
@@ -23,6 +27,50 @@ const applyBg = (line: string, width: number, bgFn: (text: string) => string): s
 	return bgFn(line + " ".repeat(pad));
 };
 
+/** What every arnative screen says about itself. `title` follows `<setting> - <extension>`
+ *  (see {@link screenTitle}); `description` is the one-liner under it. */
+export interface ScreenText {
+	title: string;
+	description: string;
+	/** Keybind legend, drawn as the last row above the bottom edge. */
+	legend: string;
+}
+
+/** `Arnative⠙` — the braille mark that brands every arnative screen. */
+export const BRAND = "\u2819";
+
+/** The one title shape for an arnative screen: `<setting> - <extension>⠙`. */
+export function screenTitle(setting: string, extension = `Arnative${BRAND}`): string {
+	return `${setting} - ${extension}`;
+}
+
+/** The chrome every arnative screen shares: frame, title in `accent`+bold, description in
+ *  `muted`, blank, the screen's `body`, blank, legend in `dim`. One function so the screens
+ *  cannot drift apart; `body` rows arrive already painted and truncated. */
+export function renderScreen(
+	theme: BoxTheme | null,
+	width: number,
+	text: ScreenText,
+	body: string[],
+	/** Border painter. Defaults to the thinking slot (skill arnative-pi §6 rule 1: the frame
+	 *  follows the session's thinking level); pass the real level so the box tracks the model. */
+	border: Dim = thinkingColorOf(theme, undefined),
+): string[] {
+	const fg = (color: string, s: string) => (theme ? theme.fg(color, s) : s);
+	const bold = theme?.bold?.bind(theme) ?? ((s: string) => s);
+	const row = (content: string) => boxRow(content, width, border);
+	return [
+		boxEdge("╭", "╮", width, border),
+		row(fg("accent", bold(text.title))),
+		row(fg("muted", text.description)),
+		row(""),
+		...body.map(row),
+		row(""),
+		row(fg("dim", text.legend)),
+		boxEdge("╰", "╯", width, border),
+	].map((l) => truncateToWidth(l, width, ""));
+}
+
 /** Wrap `rows` (plain or ANSI-colored) into a box. `bgType` = theme bg name (no-op when the theme has no `bg`); `borderColor` = border color.
  *  `theme` may be null: a box is patched in at module load, before `session_start`
  *  delivers the active theme. An uncolored box for that first frame beats a null
@@ -53,8 +101,45 @@ if (isMain(import.meta.url)) {
 	assert(plain[1] === "│ hello                │", "content line padded flush");
 	assert(renderBoxLines(th, 24, ["x".repeat(40)]).length === 4, "long line wrapped");
 	assert(renderBoxLines(th, 20, ["hi"], "customMessageBg").length === 3, "bg ignored when the theme has no bg");
+	// A row wider than the box must lose its own tail, never its right wall: `boxRow` used to
+	// pad only, so the wall overflowed `width` and the caller's `truncateToWidth` cut the wall.
+	const overlong = boxRow("x".repeat(60), 20, (s) => s);
+	assert(visibleWidth(overlong) === 20, `an overlong row is still exactly the width, got ${visibleWidth(overlong)}`);
+	assert(overlong.endsWith("│"), `an overlong row keeps its right wall, got ${JSON.stringify(overlong)}`);
+	assert(!overlong.includes("x".repeat(17)), "an overlong row truncates its own content");
 	const nullTheme = renderBoxLines(null, 24, ["hello"], "customMessageBg");
 	assert(nullTheme.every((l) => visibleWidth(l) === 24), "null theme renders an uncolored box instead of throwing");
 	assert(nullTheme[0]!.startsWith("╭") && nullTheme[1] === "│ hello                │", "null-theme frame and padding intact");
+	// Rule 5: too narrow for `│ │`, a row is empty rather than 4 columns wide — pi may hand a
+	// component the width of a sidebar, and a 4-wide row would overflow it.
+	for (const w of [1, 2, 3]) assert(boxRow("hello", w, (s) => s) === "", `a row narrower than four columns is empty at width ${w}`);
+
+	// The shared screen chrome: one sequence for every arnative screen.
+	assert(screenTitle("Settings") === `Settings - Arnative${BRAND}`, "screenTitle pins the <setting> - <extension> shape");
+	assert(screenTitle("Usage") === "Usage - Arnative\u2819", "the brand is the braille mark, not a Nerd Font glyph");
+	const screen = renderScreen(th, 60, { title: "Usage - Arnative\u2819", description: "Token & cost", legend: "[Esc] Close" }, ["a row", ""]);
+	assert(screen[0]!.startsWith("╭") && screen[screen.length - 1]!.startsWith("╰"), "screen frame intact");
+	assert(screen.every((l) => visibleWidth(l) === 60), "every screen line is exactly the width");
+	assert(screen[1]!.includes("Usage - Arnative\u2819"), "the title sits on the first row inside the frame");
+	assert(screen[2]!.includes("Token & cost"), "the description sits under the title");
+	assert(screen[screen.length - 2]!.includes("[Esc] Close"), "the legend is the last row above the bottom edge");
+	// No full-width rule inside the frame (skill rule 7): the chrome is the whole chrome.
+	assert(!screen.some((l) => /[├┤]/.test(l)), "the shared chrome draws no inner rule");
+	const taggedBox = { fg: (c: string, t: string) => `<${c}>${t}</>`, bold: (t: string) => `<bold>${t}</bold>` };
+	const taggedScreen = renderScreen(taggedBox, 60, { title: "T", description: "d", legend: "l" }, []);
+	assert(taggedScreen[1]!.includes("<accent><bold>T"), "the title is accent + bold");
+	assert(taggedScreen[2]!.includes("<muted>d"), "the description is muted");
+	assert(taggedScreen[taggedScreen.length - 2]!.includes("<dim>l"), "the legend is dim");
+	assert(renderScreen(null, 40, { title: "t", description: "d", legend: "l" }, ["x"]).every((l) => visibleWidth(l) === 40), "a null theme still frames the screen");
+	// The header copy is longer than a narrow terminal: the wall must win over the text.
+	const longCopy = "Selection previews live — same list as /settings → Theme.";
+	for (const w of [40, 50, 56, 60]) {
+		const narrow = renderScreen(th, w, { title: screenTitle("Themes"), description: longCopy, legend: "[Esc] Revert" }, []);
+		assert(narrow.every((l) => visibleWidth(l) === w), `a long description keeps every line at width ${w}`);
+		assert(
+			narrow.filter((l) => l.startsWith("│")).every((l) => l.endsWith("│")),
+			`a long description keeps the right wall at width ${w}`,
+		);
+	}
 	console.log("lib/box.ts OK");
 }

package/lib/shortcuts.ts

@@ -1,16 +1,6 @@
-// Platform-correct key ids for the package's single-letter shortcuts (t / n / r).
-//
-// Windows Terminal >= 1.24 aliases every Ctrl+Alt combo to AltGr (microsoft/terminal
-// PR #20052), so the legacy "ESC + control byte" pair (ctrl+alt+r = \x1b\x12) that
-// matchesKey() looks for is never emitted — the keystroke dies inside the terminal.
-// A WSL pane inherits that same input translation, so it counts as Windows-like too,
-// mirroring pi's own useWindowsKeybindings() (not exported from the package root).
-// pi falls back to alt+<letter> for this class of problem (app.clipboard.pasteImage ->
-// alt+v, app.model.cycleBackward -> alt+p) and every Windows terminal prefixes
-// alt+<letter> with ESC (libuv win/tty.c), so do the same here. macOS keeps ctrl+alt
-// only: plain Option there composes characters (Option+r = ®) unless "Use Option as
-// Meta key" is enabled, while ctrl+alt transmits in every macOS terminal.
-import { Key, matchesKey } from "@earendil-works/pi-tui";
+// Platform-aware single-letter shortcuts. Windows/WSL uses Alt+<char> to avoid AltGr
+// aliasing; macOS displays Option; other platforms use Ctrl+Alt.
+import { Key, matchesKey, visibleWidth } from "@earendil-works/pi-tui";
 import { assert, isMain } from "./check.ts";
 
 /** Windows Terminal's AltGr aliasing hits native Windows and WSL panes alike. */
@@ -46,6 +36,44 @@ export const SHORTCUT_RELOAD = build("r");
  *  (same platform split as the shortcuts above). */
 export const SHORTCUT_TOGGLE_FOOTER = build("m");
 
+/** The one "go back" key: `←` leaves a screen for its parent, while Esc closes or reverts
+ *  it. Defined here so no screen can advertise a key another screen does not handle. */
+export const BACK_KEY_LABEL = "←";
+export function matchesBack(data: string): boolean {
+	return matchesKey(data, "left");
+}
+
+/** A key a screen advertises: its label plus the matcher the handler acts on. A legend
+ *  built from these cannot drift from the handler — the same `matches` decides both. */
+export interface KeySet {
+	label: string;
+	matches: (data: string) => boolean;
+}
+
+const keySet = (label: string, ...keyIds: string[]): KeySet => ({
+	label,
+	matches: (data) => keyIds.some((keyId) => matchesKey(data, keyId)),
+});
+
+/** One label for the pair — the handler moves on either arrow. */
+const MOVE = keySet("↑↓", "up", "down");
+const CHOOSE = keySet("Enter", "enter");
+const BACK = keySet(BACK_KEY_LABEL, "left");
+const CANCEL = keySet("Esc", "escape");
+const QUIT = keySet("q/Esc", "q", "escape");
+
+const legend = (...pairs: [string, string][]): string => pairs.map(([key, action]) => `[${key}] ${action}`).join("  ");
+
+/** Root menu: move and open. No `[←]` — the menu has no screen behind it. */
+export const LEGEND_MOVE = legend([MOVE.label, "Move"], [CHOOSE.label, "Open"], [CANCEL.label, "Close"]);
+/** Live-preview list: moving applies, Enter keeps, `←` steps out, Esc reverts. */
+export const LEGEND_LIVE = legend([MOVE.label, "Preview"], [CHOOSE.label, "Select"], [BACK.label, "Back"], [CANCEL.label, "Revert"]);
+/** The read-only usage dashboard. The full legend needs the room, so a narrow box degrades. */
+export function legendUsage(width: number): string {
+	const full = legend([MOVE.label, "Move"], ["Click", "Open/close"], [BACK.label, "Back"], [QUIT.label, "Exit"]);
+	return width >= visibleWidth(full) ? full : legend([QUIT.label, "Exit"]);
+}
+
 if (isMain(import.meta.url)) {
 	assert(SHORTCUT_RELOAD.keys[0] === Key.ctrlAlt("r"), "ctrl+alt+r is registered on every platform");
 	assert(
@@ -72,5 +100,26 @@ if (isMain(import.meta.url)) {
 		"alt+m is registered only where Ctrl+Alt is aliased away",
 	);
 	assert(!SHORTCUT_TOGGLE_FOOTER.matches("\x1b\x12"), "ctrl+alt+r does not match the footer toggle");
+	assert(matchesBack("\x1b[D"), "← (CSI) matches the back key");
+	assert(matchesBack("\x1bOD"), "← (SS3, application cursor mode) matches the back key");
+	assert(!matchesBack("\x1b[C"), "→ is not the back key");
+	assert(!matchesBack("\x1b"), "Esc is not the back key: Esc closes, ← steps back");
+	assert(!matchesBack("h"), "a bare letter is not the back key");
+	// The legends are built from the same keys the handlers match, so a key cannot be
+	// advertised on one screen and handled on none.
+	assert(LEGEND_MOVE === "[↑↓] Move  [Enter] Open  [Esc] Close", `root menu legend pinned, got ${LEGEND_MOVE}`);
+	assert(!LEGEND_MOVE.includes(BACK_KEY_LABEL), "the root menu does not advertise ←");
+	assert(
+		LEGEND_LIVE === `[↑↓] Preview  [Enter] Select  [${BACK_KEY_LABEL}] Back  [Esc] Revert`,
+		`live legend pinned, got ${LEGEND_LIVE}`,
+	);
+	assert(MOVE.matches("\x1b[A") && MOVE.matches("\x1b[B"), "the ↑↓ key matches both arrows");
+	assert(CHOOSE.matches("\r"), "[Enter] matches carriage return");
+	assert(BACK.matches("\x1b[D"), "[←] in the legend is the same key matchesBack accepts");
+	assert(CANCEL.matches("\x1b"), "[Esc] matches escape");
+	assert(!CANCEL.matches("\x1b[D"), "[Esc] is not the back key");
+	assert(legendUsage(120).includes(`[${BACK_KEY_LABEL}] Back`), "a wide usage legend advertises back");
+	assert(legendUsage(120).includes("[Click] Open/close"), "a wide usage legend advertises the mouse");
+	assert(legendUsage(20) === "[q/Esc] Exit", "a narrow usage legend degrades to the one key that still fits");
 	console.log("shortcuts.ts self-check OK");
 }

package/lib/spinner.ts

@@ -0,0 +1,270 @@
+/**
+ * Working-indicator presets for `/arnative` → **Animations** and their painters.
+ * Single source of truth for frames, cadence, and colours.
+ */
+import { assert, isMain } from "./check.ts";
+
+export const SPINNER_PRESETS = [
+	"Pi (system)",
+	"Diamond Glow",
+	"Diamond Pulse",
+	"Circle Pulse",
+	"Circle Wave",
+	"Shade Wave",
+	"Braille Column",
+	"Braille Level",
+	"Kanji Count",
+	"Suzhou Tally",
+	"Gemini",
+	"Claude",
+] as const;
+export type SpinnerPreset = (typeof SPINNER_PRESETS)[number];
+export const DEFAULT_SPINNER_PRESET: SpinnerPreset = "Diamond Glow";
+
+/** Persistence key in `arnative-config.json` (see `lib/preset-store.ts`). */
+export const SPINNER_PRESET_KEY = "spinnerPreset";
+
+interface Preset {
+	/** Animation frames. Empty leaves pi's indicator alone. */
+	frames: readonly string[];
+	/** Frame delay in ms. `0` keeps pi's interval. */
+	intervalMs: number;
+	/** How the frame is painted. */
+	paint: "accent" | "gradient" | "claude";
+	/** Shown in the picker row after `·`. */
+	note: string;
+}
+
+/** Claude Code mark animation frames, adapting to Ghostty and non-macOS font fallbacks. */
+function defaultClaudeCharacters(): readonly string[] {
+	if (process.env.TERM === "xterm-ghostty") {
+		return ["\u00b7", "\u2722", "\u2733", "\u2736", "\u273b", "*"];
+	}
+	return process.platform === "darwin"
+		? ["\u00b7", "\u2722", "\u2733", "\u2736", "\u273b", "\u273d"]
+		: ["\u00b7", "\u2722", "*", "\u2736", "\u273b", "\u273d"];
+}
+
+const CLAUDE_BASE_FRAMES = defaultClaudeCharacters();
+const CLAUDE_PING_PONG_FRAMES = [...CLAUDE_BASE_FRAMES, ...[...CLAUDE_BASE_FRAMES].reverse()] as const;
+
+/**
+ * `Pi (system)` exists to hand the slot back: empty frames and a zero interval mean the
+ * extension installs nothing, so pi's own Braille spinner and colour are untouched. It is
+ * also the only way to get the default Braille dots once a preset is stored.
+ */
+export const SPINNER_PRESET_DEFS: Record<SpinnerPreset, Preset> = {
+	"Pi (system)": {
+		frames: [],
+		intervalMs: 0,
+		paint: "accent",
+		note: "pi's own Braille spinner",
+	},
+	// The diamond closing from outlined to filled and back; 200ms × 4 is one turn per 0.8s,
+	// the rate pi's Braille default turns at (80ms × 10).
+	"Diamond Glow": {
+		frames: ["\u2b25", "\u25c8", "\u25c6", "\u25c7"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "diamond closing, 0.8s",
+	},
+	// Three-diamond travelling pulse: a filled diamond moving across hollow ones.
+	"Diamond Pulse": {
+		frames: ["\u25c6\u25c7\u25c7", "\u25c7\u25c6\u25c7", "\u25c7\u25c7\u25c6"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "travelling diamond pulse",
+	},
+	// Three-circle fill ladder: filled dots filling from left to right (● ◌ ◌ → ● ● ◌ → ● ● ●).
+	"Circle Pulse": {
+		frames: ["\u25cf \u25cc \u25cc", "\u25cf \u25cf \u25cc", "\u25cf \u25cf \u25cf"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "filling circles, one to three",
+	},
+	// Three-circle travelling wave: a filled dot moving across hollow dots (● ◌ ◌ → ◌ ● ◌ → ◌ ◌ ●).
+	"Circle Wave": {
+		frames: ["\u25cf \u25cc \u25cc", "\u25cc \u25cf \u25cc", "\u25cc \u25cc \u25cf"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "travelling circle wave",
+	},
+	// Three-block travelling shade wave from light to dark shading.
+	"Shade Wave": {
+		frames: ["\u2591\u2592\u2593", "\u2593\u2591\u2592", "\u2592\u2593\u2591"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "travelling block shade wave",
+	},
+	// Braille stepping dots: rotating/tumbling dot pairs (⠖ ⠲ ⠴ ⠦).
+	"Braille Column": {
+		frames: ["\u2816", "\u2832", "\u2834", "\u2826"],
+		intervalMs: 160,
+		paint: "accent",
+		note: "stepping braille dot pattern",
+	},
+	// Braille fill levels: rising horizontal dot lines from bottom to top (⣀ ⣤ ⣶ ⣿).
+	"Braille Level": {
+		frames: ["\u28c0", "\u28e4", "\u28f6", "\u28ff", "\u28f6", "\u28e4"],
+		intervalMs: 140,
+		paint: "accent",
+		note: "rising braille dot level fill",
+	},
+	// Kanji stroke count: one, two, three lines (一 二 三).
+	"Kanji Count": {
+		frames: ["\u4e00", "\u4e8c", "\u4e09"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "kanji numerals, one to three",
+	},
+	// Suzhou numerals (tally marks): vertical bars one to three (〡 〢 〣).
+	"Suzhou Tally": {
+		frames: ["\u3021", "\u3022", "\u3023"],
+		intervalMs: 200,
+		paint: "accent",
+		note: "vertical tally bars, one to three",
+	},
+	// Gemini CLI's spinner is the `dots` entry from the `cli-spinners` package, the same
+	// Braille set pi ships; what makes it Gemini is the Google brand gradient sweeping the
+	// glyph on a 4s cycle (GeminiSpinner.tsx paints `CliSpinner` through `tinygradient`).
+	Gemini: {
+		frames: ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834", "\u2826", "\u2827", "\u2807", "\u280f"],
+		intervalMs: 80,
+		paint: "gradient",
+		note: "pi's Braille + Google gradient",
+	},
+	// Claude Code's mark animation: ping-pong loop of dingbats swelling and contracting,
+	// matching upstream SpinnerAnimationRow (120ms per frame).
+	Claude: {
+		frames: CLAUDE_PING_PONG_FRAMES,
+		intervalMs: 120,
+		paint: "claude",
+		note: "Claude Code's pulsing marks, 120ms",
+	},
+};
+
+/** Google brand gradient midpoints (sRGB), seamless 4s loop. */
+const GOOGLE_BRAND: ReadonlyArray<readonly [number, number, number]> = [
+	[168, 130, 234], // purple
+	[66, 133, 244], // blue
+	[52, 168, 172], // cyan
+	[52, 168, 83], // green
+	[251, 188, 4], // yellow
+	[234, 67, 53], // red
+	[168, 130, 234], // back to purple
+];
+
+/** Claude Code's own spinner colour: the 256-colour grey-orange index it brands around. */
+const CLAUDE_RGB: readonly [number, number, number] = [215, 119, 87];
+
+const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
+
+/** The brand gradient at `t` in [0, 1), as sRGB. Wraps, so any t is valid. */
+export function googleGradientRgb(t: number): [number, number, number] {
+	const wrapped = t - Math.floor(t);
+	const spans = GOOGLE_BRAND.length - 1;
+	const scaled = wrapped * spans;
+	const i = Math.min(Math.floor(scaled), spans - 1);
+	const f = scaled - i;
+	const a = GOOGLE_BRAND[i]!;
+	const b = GOOGLE_BRAND[i + 1]!;
+	return [Math.round(lerp(a[0], b[0], f)), Math.round(lerp(a[1], b[1], f)), Math.round(lerp(a[2], b[2], f))];
+}
+
+/** Truecolor SGR for one glyph. pi's own `fg` cannot take a raw RGB, so the escape is ours. */
+const fgRgb = ([r, g, b]: readonly [number, number, number]): string => `\x1b[38;2;${r};${g};${b}m`;
+
+/** Painter for a preset's spinner; gradient and claude use fixed branding, accent uses theme. */
+export function spinnerPainter(
+	preset: SpinnerPreset,
+	theme: { fg?(color: string, text: string): string } | null,
+): (text: string) => string {
+	const def = SPINNER_PRESET_DEFS[preset];
+	if (def.paint === "gradient") {
+		return (text) => `${fgRgb(googleGradientRgb(Date.now() / 4000))}${text}\x1b[0m`;
+	}
+	if (def.paint === "claude") {
+		return (text) => `${fgRgb(CLAUDE_RGB)}${text}\x1b[0m`;
+	}
+	const fg = theme?.fg?.bind(theme);
+	if (!fg) return (text) => text;
+	return (text) => fg("accent", text);
+}
+
+/** Frames for the picker preview row, e.g. `⬥ ◈ ◆ ◇`. `Pi (system)` reports its own set. */
+export function previewFrames(preset: SpinnerPreset): string {
+	const def = SPINNER_PRESET_DEFS[preset];
+	const frames = def.frames.length > 0 ? def.frames : SPINNER_PRESET_DEFS.Gemini.frames;
+	return frames.join(" ");
+}
+
+
+// Self-check: `node lib/spinner.ts`
+if (isMain(import.meta.url)) {
+	for (const p of SPINNER_PRESETS) {
+		const def = SPINNER_PRESET_DEFS[p];
+		assert(def.note.length > 0, `${p} carries a picker note`);
+		for (const frame of def.frames) {
+			assert(!/\ufffd|\ue000-\uf8ff/.test(frame), `${p}: frame ${frame} is not a blank private-use cell`);
+		}
+		if (def.frames.length > 0) {
+			assert(def.intervalMs > 0, `${p} with frames must set an interval`);
+			assert(new Set(def.frames).size > 1, `${p} must animate, not repeat one frame`);
+		}
+	}
+
+	// `Pi (system)` is the escape hatch: it must install nothing at all.
+	assert(SPINNER_PRESET_DEFS["Pi (system)"].frames.length === 0, "Pi (system) leaves pi's frames alone");
+	assert(SPINNER_PRESET_DEFS["Pi (system)"].intervalMs === 0, "Pi (system) leaves pi's interval alone");
+
+	// Gemini's Braille is the one sanctioned exception: Braille Patterns is a block every
+	// terminal font covers (it is pi's own default set, so a terminal that shows pi at all has
+	// it), and the ten cells share one face because U+2800-U+28FF is a single contiguous run.
+	const braille = /^[\u2800-\u28ff]+$/;
+	assert(SPINNER_PRESET_DEFS.Gemini.frames.every((f) => braille.test(f)), "Gemini frames are Braille cells");
+	assert(SPINNER_PRESET_DEFS.Gemini.frames.length === 10, "Gemini uses the ten-frame dots spinner");
+	assert(
+		SPINNER_PRESET_DEFS.Gemini.intervalMs === 80,
+		"Gemini keeps the cli-spinners cadence (80ms)",
+	);
+
+	// Diamond Glow uses the Geometric Shapes block; `⬥ ◈ ◆ ◇` all live in one contiguous run
+	// and are hosted by the terminal face on the platforms this package targets.
+	for (const f of SPINNER_PRESET_DEFS["Diamond Glow"].frames) {
+		assert(/^[\u25a0-\u25ff\u2b00-\u2bff]$/.test(f), `Diamond Glow frame ${f} is a geometric shape`);
+	}
+
+	// Claude preset: upstream dingbats in ping-pong order, matching Claude Code.
+	const claude = SPINNER_PRESET_DEFS.Claude.frames;
+	assert(claude[0] === "\u00b7", "Claude starts on the interpunct");
+	assert(claude.length === 12, "Claude uses a 12-frame ping-pong loop");
+	assert(SPINNER_PRESET_DEFS.Claude.intervalMs === 120, "Claude matches upstream 120ms cadence");
+	assert(claude.join("") === [...claude].reverse().join(""), "Claude's ping-pong frames are a palindrome");
+	for (const f of claude) assert(f !== " " && f.length === 1, `Claude frame ${JSON.stringify(f)} is one glyph`);
+
+	// The gradient closes: t=1 must equal t=0, or the 4s sweep would jump at the seam.
+	assert(
+		googleGradientRgb(0).join() === googleGradientRgb(1).join(),
+		"the Google gradient wraps without a seam",
+	);
+	assert(googleGradientRgb(0.9999).join() !== googleGradientRgb(0.5).join(), "the gradient actually moves");
+	assert(googleGradientRgb(-0.25).join() === googleGradientRgb(0.75).join(), "a negative t wraps like a positive one");
+	for (const rgb of [googleGradientRgb(0), googleGradientRgb(0.37), googleGradientRgb(0.91)]) {
+		assert(rgb.every((c) => Number.isInteger(c) && c >= 0 && c <= 255), `gradient stays in sRGB: ${rgb.join()}`);
+	}
+
+	// The accent painter must go through the theme, not a hardcoded colour.
+	assert(
+		spinnerPainter("Diamond Glow", { fg: (c, t) => `<${c}>${t}` })("x") === "<accent>x",
+		"accent presets paint through the theme token",
+	);
+	assert(spinnerPainter("Diamond Glow", null)("x") === "x", "no theme -> identity painter, never a crash");
+	const grad = spinnerPainter("Gemini", null)("x");
+	assert(grad.startsWith("\x1b[38;2;") && grad.endsWith("x\x1b[0m"), "the gradient painter emits truecolor + reset");
+	assert(spinnerPainter("Claude", null)("x").startsWith("\x1b[38;2;215;119;87m"), "Claude uses its own mark colour");
+
+	assert(previewFrames("Diamond Glow").split(" ").length === 4, "the picker preview shows every Diamond frame");
+	assert(previewFrames("Pi (system)").length > 0, "Pi (system) still previews pi's Braille set");
+
+	console.log("spinner.ts self-check OK");
+}