@bismawy/pi-arnative 0.3.10 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## [0.5.1] - 2026-10-13
+
+### Fixed
+- Restored all 11 arnative themes on Pi 1.2.0, which validates the `colors` object with `additionalProperties: false` and rejected the whole theme — "must not have additional properties" followed by "Theme not found" (`lib/ansi.ts`, `themes/gen-themes.mjs`, `themes/*.json`, `extensions/ui-render-tweaks.ts`). Arnative's own colors (`accentSoft`, `primary`, `secondary`, `primarySoft`, `secondarySoft`) moved from `colors` to `vars`.
+- Kept the two-tone soft tier instead of collapsing it to grey: `softOf` replaces `accentSoftOf` and derives the soft accent from the resolved `accent` color when `fg("accentSoft")` throws, so the header logo, tab labels, model line, footer labels, tool titles and the usage dashboard keep their tint (`lib/ansi.ts`).
+- Updated `$schema` in every theme and the generator from the raw GitHub `theme-schema.json` path to the published `https://pi.dev/schemas/theme.schema.json` (`themes/gen-themes.mjs`, `themes/*.json`).
+- Replaced the footer's raw `fg("accentSoft")` probe with the shared painter and mapped `primary`/`secondary` onto the official tokens they carry (`mdHeading`, `borderAccent`), since Pi 1.2 rejects custom `colors` keys (`extensions/footer.ts`).
+- Mapped the usage dashboard's name/value/arrow colors off `accentSoft` onto the shared soft painter and plain `dim`/`text`, keeping provider rows distinguishable (`extensions/usage.ts`).
+- Added a self-check that fails when a theme puts a non-schema key in `colors`, so a rogue token breaks `npm test` instead of the user's startup (`extensions/ui-render-tweaks.ts`).
+
+### Notes
+- `0.5.0` is intentionally skipped on the npm registry. It was tagged and merged, but never published, and its themes are the ones Pi 1.2.0 rejects. `0.5.1` carries everything from v0.5.0 plus this fix. The tag stays in the history; install from npm and you get `0.5.1`.
+
+## [0.5.0] - 2026-10-13
+
+### Added
+- Extended theme token hierarchy in `vars` with `primary`, `primarySoft`, `secondary`, and `secondarySoft` across all 11 themes (`themes/gen-themes.mjs`), ensuring unique hex mappings and full perceptual OKLCH color space discipline.
+- Tri-color multi-palette overhauls for expressive themes (`arnative-cyberpunk`, `arnative-synthwave`, `arnative-dracula`, `arnative-gruvbox`, and `arnative-nord`), mapping `mdHeading` to `primary` and `borderAccent`/`mdCode` to `secondary`.
+- Footer multi-color pairing (`extensions/footer.ts`): paired vibrant `accent` icons with readable `secondarySoft` labels and highlighted the model name with `primary`.
+
+### Changed
+- Increased message bubble background lightness (`surfaceMsg` / `userMessageBg`) on `arnative-cyberpunk`, `arnative-matrix`, and `arnative-synthwave` to 24% (`oklch(24% 0.035 ...)`) to ensure container boundaries remain clearly defined against pitch-black terminal canvases.
+
+### Fixed
+- Fixed parenthetical suffix per-row dimming in `/arnative` → **Animations** so `(system)` on `Pi (system)` renders softly in `dim` even when descriptive frame notes are present (`extensions/arnative.ts`).
+- Fixed inline image preview layout spacing by dropping the redundant spacer gap between the tool execution box and the image payload (`extensions/tools.ts`).
+
+## [0.4.0] - 2026-10-12
+
+### Added
+- `/arnative` → **Animations** picker and working-spinner presets (`lib/spinner.ts`, `extensions/animations.ts`): Diamond Glow (default), Diamond Pulse, Circle Pulse, Circle Wave, Shade Wave, Braille Column, Braille Level, Kanji Count, Suzhou Tally, Pi (system), Gemini (Google brand gradient), and Claude (pulsing mark loop).
+- Automatic token cost estimation for unpriced models via pi's `models.json` declared rates (`lib/usage-store.ts`, `extensions/usage.ts`).
+- Usage dashboard integration into `/arnative` → **Usage** alongside standalone `/usage` command (`extensions/arnative.ts`, `extensions/usage.ts`).
+
+### Changed
+- Active session clock tracks duration while active and freezes after inactivity (`IDLE_PAUSE_MS`), ignoring non-keystroke inputs (`extensions/footer.ts`, `test/footer-minimal.test.ts`).
+- Working spinner frames clear `renderIndicatorVerbatim` to apply theme `accent` color while preserving `accentSoft` for labels (`extensions/footer.ts`, `extensions/animations.ts`).
+- Unified screen chrome and title format via `renderScreen` and `screenTitle` in `lib/box.ts`, with adaptive thinking-level border colors across all `/arnative` screens (`lib/box.ts`, `lib/ansi.ts`, `extensions/arnative.ts`, `extensions/usage.ts`).
+- Back key `←` (`matchesBack`) standard across `/arnative` submenus and usage dashboard, stepping back without losing selection context (`lib/shortcuts.ts`, `extensions/arnative.ts`, `extensions/usage.ts`).
+- Compact usage dashboard layout: removed `↑In`/`↓Out`/`Cache` columns from main table (moved to selected row detail line) and added mouse click toggle for provider rows (`extensions/usage.ts`).
+- Aligned list picker layout to standard `Label · note` format, removing redundant `●` indicator column (`extensions/arnative.ts`).
+- Header brand updated to `Arnative⠙ vX.Y.Z` using shared `BRAND` constant (`extensions/section-headers.ts`).
+
+### Fixed
+- Fixed spinner preset selection in `/arnative` → **Animations** by sharing active UI and theme references across extension module instances via `globalThis` (`extensions/animations.ts`).
+- Fixed missing `animations.ts` in `scripts/preview.mjs` extension launch list (`scripts/preview.mjs`).
+- Fixed box row truncation in `boxRow` to prevent right wall clipping on lines narrower than content (`lib/box.ts`).
+- Fixed `boxRow` zero-column overflow when width is below 4 columns (`lib/box.ts`).
+- Avoided repeated synchronous disk reads during usage summary collection by passing memoized price table (`lib/usage-store.ts`).
+- Cleaned up active clock state initialization on fresh sessions (`extensions/footer.ts`).
+- Bounded tool duration cache (`TIMINGS`) to 200 entries with FIFO eviction and cleared on session boundaries to prevent memory growth (`extensions/tools.ts`).
+- Added short-circuit in `repairBubbleBg` to avoid string split/join allocations on lines without ANSI reset sequences (`extensions/timestamps.ts`).
+- Added fast substring check in `shouldHideReloadBox` to bypass `stripAnsi` and array mapping across general containers (`extensions/ui-render-tweaks.ts`).
+
 ## [0.3.10] - 2026-10-11
 
 ### Fixed

package/README.md

@@ -6,21 +6,35 @@ Refined aesthetics. Cohesive tools. Built for Pi.
 [![badge](https://shieldcn.dev/npm/@bismawy/pi-arnative.svg?variant=outline&size=xs)](https://www.npmjs.com/package/@bismawy/pi-arnative)
 [![license](https://shieldcn.dev/github/bismawy/pi-arnative/license.svg?variant=outline&size=xs)](https://github.com/bismawy/pi-arnative)
 
-![Arnative: tabbed header, rounded tool boxes, transcript clock and /usage dashboard](https://raw.githubusercontent.com/bismawy/pi-arnative/main/assets/pi-arnative.webp)
+<img src="https://raw.githubusercontent.com/bismawy/pi-arnative/main/assets/pi-arnative.webp" alt="pi-arnative" width="100%">
 
 ## Overview
 
 pi-arnative replaces pi’s default terminal chrome with a unified, cohesive visual aesthetic.
 
-- Warm Themes: Cohesive, contrast-checked color palettes generated without drift.
-- Tabbed Header: Greeting, version line, and a compact box menu over Directory, Model, Context, Skills, Extensions, and Shortcut.
-  > The Context/Skills/Extensions counts read pi's startup listing, which `"quietStartup": true` (and `"header"`) hides. Under those settings the counts show `—` rather than a misleading `0`; set `"quietStartup": false` to see the real numbers.
-- Rounded Tool Boxes: Clear status, spinner, and duration for every tool call. Built-in `codemode` is boxed and collapsed to two rows (title + first script line) like `bash`/`grep`/`read`; nested calls and output sit behind `[ctrl+o to expand]` (shown whenever the collapsed summary hides more, including `edit` diffs); a failed run always shows its full output. The `chrome_devtools_*` tools box too, replacing their bare "Chrome DevTools: …" lines.
-- Enhanced Footer: fixed 3-row grid — directory/git line, then extension status paired with token metrics. The clock keeps the session's real age across `/resume`, and the working tree's diff (`+500 -100`) sits beside it while there is one.
-  > Three presets via `/arnative` → **Footers**: `Arnative (Full)`, `Pi (system)`, and `Arnative (Minimal)` — a single head row whose two sides expand independently on click (`ctrl+alt+m` toggles both).
-  > The branch is read straight from `.git/HEAD`, so it shows up without a git install. Tag, dirty count, and ahead/behind need the `git` binary — when it is missing (or the repo is owned by another user, which git refuses to touch) that half is left out rather than shown wrong. Run `git config --global --add safe.directory <repo>` (a local, non-synced setting) to make `git` cooperate with such a repo.
-- Transcript Clock: Timestamps for messages with clean bubble backgrounds.
-- Usage Dashboard: /usage command to track tokens and session costs.
+- Warm Themes: Cohesive, contrast-checked OKLCH color palettes generated without drift.
+- Tabbed Header: Compact box menu showing Directory, Model, Context, Skills, Extensions, and Shortcuts.
+- Rounded Tool Boxes: Status, spinner, and duration for every tool call with expandable outputs.
+- Enhanced Footer: 3-row status grid tracking branch, active duration (30s idle freeze), and token speed.
+- Transcript Clock: Timestamps for conversation messages with clean bubble backgrounds.
+- Usage Dashboard: Real-time token counts and cost tracking across all local sessions via `/usage`.
+
+<details>
+<summary><b>Configuration & Presets</b></summary>
+
+### Working Spinner Presets
+Configurable via `/arnative` → **Animations** (saved to `arnative-config.json`):
+- `Diamond Glow` (default), `Diamond Pulse`, `Circle Pulse`, `Circle Wave`, `Shade Wave`
+- `Braille Column`, `Braille Level`, `Kanji Count`, `Suzhou Tally`
+- `Pi (system)`, `Gemini` (Google gradient sweep), and `Claude` (pulsing marks)
+
+### Footer Presets
+Configurable via `/arnative` → **Footers**:
+- `Arnative (Full)` (default 3-row grid)
+- `Arnative (Minimal)` (single collapsible head row; click or `ctrl+alt+m` to toggle)
+- `Pi (system)` (built-in footer)
+
+</details>
 
 ## Install
 
@@ -28,13 +42,12 @@ pi-arnative replaces pi’s default terminal chrome with a unified, cohesive vis
 pi install npm:@bismawy/pi-arnative
 ```
 
-Select a theme via `/settings` → **Theme** → `arnative` (or any `arnative-*` variant).
+Apply a theme via `/settings` → **Theme** → `arnative` (or variant). Requires a [Nerd Font](https://www.nerdfonts.com/font-downloads).
 
-To test locally without installing:
+To test locally:
 ```bash
 pi --extension ./extensions/footer.ts
 ```
-> **Prerequisite:** Requires a [Nerd Font](https://www.nerdfonts.com/font-downloads) (e.g. JetBrains Mono Nerd Font) for icons and rounded box borders.
 
 ## Shortcuts
 
@@ -42,75 +55,76 @@ pi --extension ./extensions/footer.ts
 | --- | --- |
 | `ctrl+alt+t` · `alt+t` | Cycle header tabs |
 | `ctrl+alt+r` · `alt+r` | Quick reload (`/reload`) |
-| `ctrl+alt+n` · `alt+n` | New session (`/new`) — requires keybinding below |
-| `ctrl+alt+m` · `alt+m` | Expand/collapse both sides of the Minimal footer |
-| `/usage` | Show session usage & token metrics |
-| `/arnative` | Settings menu — Themes, Headers, Footers |
-| Click tab | Open selected header tab |
+| `ctrl+alt+n` · `alt+n` | New session (`/new`) |
+| `ctrl+alt+m` · `alt+m` | Toggle Minimal footer |
+| `/usage` | Token & cost dashboard (or `/arnative` → **Usage**) |
+| `/arnative` | Settings menu (Themes, Headers, Footers, Animations, Usage) |
 | Click tool / `ctrl+o` | Toggle tool output box |
+| `←` | Back — step back from submenus/dashboard to menu |
 
-> **Notes:**
-> - **Windows / WSL:** Windows Terminal aliases `Ctrl+Alt` to AltGr; use `alt+…` (or set `"altGrAliasing": false` in WT profile).
-> - **macOS:** uses `ctrl+option+…` (plain Option composes special characters).
-> - **Herdr / tmux glitch:** if shortcuts feel delayed or type stray letters, set `PI_TUI_ESC_TIMEOUT=100` in your shell profile.
-
-### Keybindings
-
-Add to `~/.pi/agent/keybindings.json` to bind `app.session.new`:
+<details>
+<summary><b>Keybindings & Platform Notes</b></summary>
 
+To bind `app.session.new` in `~/.pi/agent/keybindings.json`:
 ```json
 {
   "app.session.new": ["ctrl+alt+n", "alt+n"]
 }
 ```
 
+- **Windows / WSL:** Windows Terminal aliases `Ctrl+Alt` to AltGr; use `alt+…` (or disable `altGrAliasing` in WT profile).
+- **macOS:** Uses `ctrl+option+…`.
+- **tmux / Herdr:** If Esc has delay, set `PI_TUI_ESC_TIMEOUT=100` in your environment.
+- **Navigation:** `←` navigates back to parent menus; `Esc` cancels or closes the active screen.
+
+</details>
+
 ## Architecture
 
 <details>
-<summary><b>Extensions</b></summary>
+<summary><b>Extensions & Components</b></summary>
 
 | File | Role |
 | --- | --- |
 | `extensions/tools.ts` | Rounded tool boxes, spinners, and duration |
 | `extensions/section-headers.ts` | Tabbed header and resource box (preset: `/arnative headers`) |
 | `extensions/footer.ts` | 3-row status grid footer and boxed editor (preset: `/arnative footers`) |
-| `extensions/arnative.ts` | `/arnative` settings menu — live-preview theme/header/footer pickers |
-| `extensions/timestamps.ts` | Message clock and bubble background fixes |
+| `extensions/animations.ts` | Working spinner presets and `/arnative` → Animations picker |
+| `lib/spinner.ts` | Spinner preset catalog: frames, cadence, and painters |
+| `extensions/arnative.ts` | Settings menu with live preview and navigation |
+| `extensions/timestamps.ts` | Message timestamps and bubble backgrounds |
 | `extensions/ui-render-tweaks.ts` | Contrast tweaks, selection style, and UI polish |
-| `extensions/usage.ts` | `/usage` token dashboard |
+| `extensions/usage.ts` | Token and cost dashboard (`/usage`) |
 
 </details>
 
 <details>
-<summary><b>Themes</b></summary>
+<summary><b>Theme Variants</b></summary>
 
-- `themes/gen-themes.mjs` is the single source of truth: it **writes every** `themes/*.json`, including the base `arnative.json`.
-- Each theme is a few parameters (accent hue, chroma, canvas lightness, neutral tint) plus optional hue overrides for the strong palettes; all colors are derived as OKLCH from a shared ramp, so lightness/saturation stay consistent and no two `vars` collapse to the same value.
-- `lib/color.ts` holds the OKLCH↔sRGB math and WCAG contrast used by both the generator and the self-check.
+Theme definitions are generated via `themes/gen-themes.mjs` using OKLCH color math (`lib/color.ts`).
 
 **Variants:** `sun` · `zinc` · `violet` · `emerald` · `matrix` · `cyberpunk` · `synthwave` · `gruvbox` · `nord` · `dracula`
 
 </details>
 
 <details>
-<summary><b>Development</b></summary>
+<summary><b>Development & Verification</b></summary>
 
 ```bash
-npm test        # Run self-checks & theme generator check
+npm test        # Run unit tests and self-checks
 npm run themes  # Rebuild all theme variants
+npm run preview # Live preview the working tree in your own Pi (stamps a pushable commit)
 ```
 
-**CI:** `.github/workflows/ci.yml` runs `npm install` + `npm test` on every push to `main` and every pull request, against Node 22.x (the floor the peer packages require) and 24.x (current LTS). No lockfile is committed, so the workflow installs without a cache key. The suite must pass in a clean checkout — a test that reads `process.cwd()` or a machine-local path will fail there.
-
-**Releasing:** `scripts/release-check.mjs` is a read-only preflight (never writes, tags, pushes or publishes) with one stage per step of the release:
+Pre-publish verification and tag validation are enforced via `scripts/release-check.mjs`.
 
-| Stage | Run before | Checks |
-| :--- | :--- | :--- |
-| `pre-tag` | `git tag` | clean tree on `main`, in sync, no open PRs, `CHANGELOG.md` entry, tag free, version unpublished |
-| `pre-publish` | `npm publish` | the above, plus the tag exists **and is pushed**, and points at `HEAD` |
-| `post-publish` | done | the above, plus the version is live on the registry, `latest` points at it and its tarball URL answers |
+**Local-first push gate:** the global pre-push hook rejects any branch push whose commit
+carries no live-preview stamp, so a fix cannot reach GitHub unseen. `npm run preview`
+launches Pi with this working tree and writes `.git/arnative-preview` for the exact commit
+that was shown; editing `extensions/`, `lib/`, `themes/`, or `package.json` afterwards
+invalidates it and the hook asks for a fresh preview. The preview must run on a clean tree
+— commit or stash first.
 
-`pre-publish` runs automatically through npm's `prepublishOnly` (after `npm test`), so a red build or a missing/unpushed tag aborts the publish (`npm error code 1`) instead of shipping a version whose tag was forgotten. The open-PR check uses `gh` when present and falls back to the public GitHub API otherwise. `npm run release:check` is the `pre-tag` shorthand. Exit codes: `0` pass, `1` a check failed, `2` bad usage.
 </details>
 
 ## License

package/extensions/animations.ts

@@ -0,0 +1,213 @@
+/**
+ * Animations — the working-indicator preset, owned outside the footer because it is not a
+ * footer concern: pi's loader spins in the boxed editor's top border and in the in-place
+ * status row whether or not an arnative footer is installed.
+ *
+ * `/arnative` → **Animations** picks a preset; this module installs it, repaints the live
+ * spinner on the spot, and hands the slot back to pi for `Pi (system)`. The frames, their
+ * cadence and their painter live in `lib/spinner.ts`; the picker UI lives here.
+ *
+ * The Loader's colour hooks are not reachable through pi's public indicator options, so this
+ * module reaches the live editor the footer publishes under `EDITOR_KEY`. That is the one
+ * coupling between the two, and it is a published symbol, not an import.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadChoice, saveChoice } from "../lib/preset-store.ts";
+import {
+	DEFAULT_SPINNER_PRESET,
+	SPINNER_PRESETS,
+	SPINNER_PRESET_DEFS,
+	SPINNER_PRESET_KEY,
+	previewFrames,
+	spinnerPainter,
+	type SpinnerPreset,
+} from "../lib/spinner.ts";
+import { assert, isMain } from "../lib/check.ts";
+
+/** The row divider, matching the one `arnative.ts` draws (`Label · note`). Kept local so
+ *  this module does not reach into the picker just for a separator string. */
+const ROW_DIVIDER = " · ";
+
+/** The arnative editor instance, published by `footer.ts` so the live spinner is reachable. */
+export const EDITOR_KEY = Symbol.for("pi-arnative.editor");
+const SPINNER_PRESET_CONFIG_KEY = Symbol.for("pi-arnative.spinnerPreset");
+
+/** The `setWorkingMessage`/`setWorkingIndicator` surface of `ctx.ui`. */
+type WorkingUi = { setWorkingIndicator?: (options?: unknown) => void } | null | undefined;
+
+/** The live theme, for the accent presets. A gradient preset ignores it. */
+type ThemeLike = { fg?(color: string, text: string): string } | null;
+
+// Active UI and theme are kept on globalThis so choices apply across reloads and multi-instance loads.
+const UI_KEY = Symbol.for("pi-arnative.workingUi");
+const THEME_KEY = Symbol.for("pi-arnative.workingTheme");
+
+/** Record the session's `ctx.ui`, so a later preset pick can install through it. */
+function workingUi(ui: WorkingUi): void {
+	(globalThis as Record<symbol, unknown>)[UI_KEY] = ui ?? undefined;
+}
+
+/** The `ctx.ui` recorded at `session_start`, or null before one ran. */
+function activeWorkingUi(): WorkingUi {
+	return ((globalThis as Record<symbol, unknown>)[UI_KEY] as WorkingUi) ?? null;
+}
+
+/** Record the session's theme, so accent presets follow it instead of a stale colour. */
+function workingTheme(theme: ThemeLike): void {
+	(globalThis as Record<symbol, unknown>)[THEME_KEY] = theme ?? undefined;
+}
+
+/** The theme recorded at `session_start`; a gradient preset ignores it. */
+function activeWorkingTheme(): ThemeLike {
+	return ((globalThis as Record<symbol, unknown>)[THEME_KEY] as ThemeLike) ?? null;
+}
+
+export function activeSpinnerPreset(): SpinnerPreset {
+	const stored =
+		(globalThis as Record<symbol, unknown>)[SPINNER_PRESET_CONFIG_KEY] ??
+		loadChoice(SPINNER_PRESET_KEY, SPINNER_PRESETS);
+	return SPINNER_PRESETS.includes(stored as SpinnerPreset) ? (stored as SpinnerPreset) : DEFAULT_SPINNER_PRESET;
+}
+
+/**
+ * Publish the choice for this process, write it to `arnative-config.json`, and install it on
+ * the running session right away — the picker previews by moving the cursor, so a choice that
+ * only took effect on the next `session_start` would look like the selection did nothing.
+ */
+export function setSpinnerPreset(preset: SpinnerPreset): void {
+	(globalThis as Record<symbol, unknown>)[SPINNER_PRESET_CONFIG_KEY] = preset;
+	saveChoice(SPINNER_PRESET_KEY, preset);
+	applySpinnerPreset(activeWorkingUi(), activeWorkingTheme());
+}
+
+/** Updates custom painter on live workingStatusIndicator if available. */
+export function paintLiveIndicator(painter: (text: string) => string): void {
+	const editor = (globalThis as Record<symbol, any>)[EDITOR_KEY];
+	const indicator = editor?.workingStatusIndicator;
+	if (!indicator) return;
+	indicator.renderIndicatorVerbatim = false;
+	indicator.spinnerColorFn = painter;
+	indicator.updateDisplay?.();
+}
+
+/** Applies preset to working indicator or restores system default for 'Pi (system)'. */
+export function applySpinnerPreset(ui: WorkingUi, theme: ThemeLike): void {
+	const preset = activeSpinnerPreset();
+	const def = SPINNER_PRESET_DEFS[preset];
+	const painter = spinnerPainter(preset, theme);
+	try {
+		if (def.frames.length === 0) ui?.setWorkingIndicator?.();
+		else ui?.setWorkingIndicator?.({ frames: [...def.frames], intervalMs: def.intervalMs });
+	} catch {
+		// older host without the API -> pi's own frames stay
+	}
+	paintLiveIndicator(painter);
+}
+
+/** Picker text. The description states the one seam: a preset applies to the next spinner. */
+export const ANIMATIONS_PICKER_TEXT = {
+	title: "Animations - Arnative\u2819",
+	description: "The working spinner — applies on the next tool call.",
+	legend: "[↑↓] Preview  [Enter] Select  [Esc] Close",
+} as const;
+
+/** One row per preset: the name, then its note and the frames it actually cycles. The
+ *  frames belong in the note — a user picking an animation wants to see the glyphs, and this
+ *  is the screen where that is decided. */
+export function animationRows(): Array<{ label: string; note: string }> {
+	return SPINNER_PRESETS.map((preset) => ({
+		label: preset,
+		note: `${SPINNER_PRESET_DEFS[preset].note}  ${previewFrames(preset)}`,
+	}));
+}
+
+/** The row as one flat string, for the headless fallback and the self-check. */
+export function animationRowText(preset: SpinnerPreset): string {
+	return `${preset}${ROW_DIVIDER}${SPINNER_PRESET_DEFS[preset].note}  ${previewFrames(preset)}`;
+}
+
+/** Register the extension: keep the installed preset in step with the session's theme. */
+export default function registerAnimations(pi: ExtensionAPI): void {
+	pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+		// A preset is installed per session so it survives `/reload` and a theme switch
+		// repaints the accent presets without re-selecting anything. Publish the surfaces first:
+		// `/arnative` → Animations re-applies through them the moment a row is chosen.
+		workingUi(ctx.ui);
+		workingTheme((ctx.ui as unknown as { theme?: ThemeLike })?.theme ?? null);
+		applySpinnerPreset(activeWorkingUi(), activeWorkingTheme());
+	});
+}
+
+// Self-check: `node extensions/animations.ts`. Async because the cross-instance assertion
+// imports a second copy of this module.
+if (isMain(import.meta.url)) {
+	await (async () => {
+	// The rows describe exactly the presets, and every row carries its own note.
+	const rows = animationRows();
+	assert(rows.length === SPINNER_PRESETS.length, "one row per preset");
+	assert(
+		rows.every((r) => r.note.length > 0),
+		"every row has a note",
+	);
+	assert(animationRowText("Diamond Glow").includes("\u2b25"), "the row text previews the frames");
+
+	// Installing a preset goes through pi's indicator API; `Pi (system)` passes nothing.
+	const calls: Array<Record<string, unknown> | undefined> = [];
+	const ui = { setWorkingIndicator: (options?: Record<string, unknown>) => calls.push(options) };
+	(globalThis as Record<symbol, unknown>)[SPINNER_PRESET_CONFIG_KEY] = "Diamond Glow";
+	applySpinnerPreset(ui, null);
+	assert(JSON.stringify(calls[0]?.frames) === JSON.stringify(SPINNER_PRESET_DEFS["Diamond Glow"].frames), "frames installed");
+	assert(calls[0]?.intervalMs === 200, "interval installed");
+	(globalThis as Record<symbol, unknown>)[SPINNER_PRESET_CONFIG_KEY] = "Pi (system)";
+	applySpinnerPreset(ui, null);
+	assert(calls.at(-1) === undefined, "Pi (system) passes no options -> pi restores its own spinner");
+
+	// A stored value that names no preset falls back instead of breaking the load.
+	(globalThis as Record<symbol, unknown>)[SPINNER_PRESET_CONFIG_KEY] = "Nope";
+	assert(activeSpinnerPreset() === DEFAULT_SPINNER_PRESET, "an unknown stored preset falls back to the default");
+	delete (globalThis as Record<symbol, unknown>)[SPINNER_PRESET_CONFIG_KEY];
+
+	// The painter seam: without a published editor there is nothing to paint, and that must
+	// be a no-op rather than a throw (the editor registers after the first session_start).
+	delete (globalThis as Record<symbol, unknown>)[EDITOR_KEY];
+	paintLiveIndicator((t) => t);
+
+	// Picking a preset must apply it NOW, not on the next session — and it must work when the
+	// picker calls a DIFFERENT module instance than the one that ran `session_start`. pi loads
+	// every manifest entry through its own loader while `arnative.ts` imports this module too,
+	// so there are two copies with separate module scope; only `globalThis` is shared. Keeping
+	// the surfaces on globalThis is what this pins, and a same-instance test would not catch it
+	// (the original bug passed such a test: the row moved, the spinner did not).
+	const pickCalls: Array<Record<string, unknown> | undefined> = [];
+	const pickUi = { setWorkingIndicator: (options?: Record<string, unknown>) => pickCalls.push(options) };
+	const handlers: Array<(e: unknown, c: unknown) => unknown> = [];
+	registerAnimations({ on: (_n: string, fn: (e: unknown, c: unknown) => unknown) => handlers.push(fn) } as never);
+	// Instance A runs session_start and records the ui on globalThis.
+	handlers[0]!({}, { ui: pickUi, theme: { fg: (_c: string, t: string) => t } });
+	pickCalls.length = 0;
+	// Instance B — a second copy of the module, like the one `arnative.ts` holds — does the pick.
+	const instanceB = await import(`./animations.ts?second=${Date.now()}`);
+	instanceB.setSpinnerPreset("Claude");
+	assert(pickCalls.length === 1, "a second module instance installs through the shared ui");
+	assert(pickCalls[0]?.frames?.[0] === "\u00b7", "the chosen preset's frames are installed, not the old ones");
+	assert(pickCalls[0]?.intervalMs === 120, "and its cadence (120ms)");
+
+	// Pi (system) still hands the slot back through the same path.
+	pickCalls.length = 0;
+	instanceB.setSpinnerPreset("Pi (system)");
+	assert(pickCalls[0] === undefined, "choosing Pi (system) restores pi's own spinner at once");
+
+	// With one, both the verbatim flag and the painter are set — this is what keeps the
+	// colour on a custom frame.
+	const indicator = { renderIndicatorVerbatim: true, spinnerColorFn: undefined as unknown, updateDisplay: () => {} };
+	let painted = 0;
+	const editor = { workingStatusIndicator: { ...indicator, updateDisplay: () => painted++ } };
+	(globalThis as Record<symbol, any>)[EDITOR_KEY] = editor;
+	paintLiveIndicator((t) => `<a>${t}`);
+	assert(editor.workingStatusIndicator.renderIndicatorVerbatim === false, "verbatim cleared, else pi skips the painter");
+	assert(painted === 1, "the live indicator repaints at once");
+	delete (globalThis as Record<symbol, any>)[EDITOR_KEY];
+
+	console.log("animations.ts self-check OK");
+	})();
+}