@hank-warren/pi-statusline 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @hank-warren/pi-statusline
 
+## 0.4.0
+
+### Minor Changes
+
+- c5e6e34: Add five cache-celebration animation styles — `flash` (the previous behaviour, still the default), `wave`, `pulse`, `rainbow`, and `sparkle`. The `/statusline` **Cache celebration** row now cycles `off` plus each style instead of `on`/`off`, and selecting the row loops the badge live in the statusline below so you can compare them in place. Choosing `off` preserves the selected style.
+
+  Every style except `rainbow` derives from the active theme's two `celebration` colours, so it recolours with the theme. `npm run demo:celebrations` previews all of them, and `-- --matrix` compares every style against every theme.
+
+  Also fixes `isThemeName` accepting prototype keys such as `__proto__`.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -21,7 +21,8 @@ Colors come from a selectable [theme](#themes), with context warning thresholds.
 `/statusline` opens a `/settings`-style menu (TUI mode only) for configuring the footer. Changes apply live and persist immediately:
 
 - **Theme** — the color palette, cycled with Enter or Space. See [Themes](#themes).
-- **Model**, **Directory & git**, **Context**, **Subscription usage**, **Worktree line**, **Session ID line**, **Cache celebration** — `on`/`off`, cycled with Enter or Space. Disabled segments are dropped from line 1 without leaving a stray ` | ` separator; hiding the worktree line also stops its `git`/`gh` polling, and hiding usage stops the usage poller. With every element off the footer collapses to a single blank row.
+- **Cache celebration** — `off` or one of five badge animations, cycled with Enter or Space and previewed live in the statusline below. See [Animation styles](#animation-styles).
+- **Model**, **Directory & git**, **Context**, **Subscription usage**, **Worktree line**, **Session ID line** — `on`/`off`, cycled with Enter or Space. Disabled segments are dropped from line 1 without leaving a stray ` | ` separator; hiding the worktree line also stops its `git`/`gh` polling, and hiding usage stops the usage poller. With every element off the footer collapses to a single blank row.
 - **Worktree root** — the directory whose immediate children are tracked as session worktrees (default `~/repos/worktrees`). `~` and `$HOME` are expanded; a relative path is rejected and the previous value kept.
 - **Repo aliases** — short display names for repositories on the worktree line. Enter edits the selected `repo → alias` pair, `d` deletes it, and `Add alias…` creates one from a `repo=alias` line.
 
@@ -56,7 +57,7 @@ Usage is fetched from the providers' own usage endpoints with Pi's stored tokens
 
 Polling is host-wide, not per-session. Usage percentages describe the account rather than the session, and a busy machine runs dozens of pi processes, so every process shares `~/.pi/agent/statusline-usage.json`: it holds the last good snapshot plus the time the last poll was *started*, written atomically via a temp file and rename. A session adopts the cached values on its first refresh — so the meters are populated before it has issued a single request — and only polls when that shared timestamp is older than the interval. A provider answering `429` is parked for fifteen minutes (tracked per provider, so a rate-limited Anthropic never stops codex from updating) and stops counting as pending, since retrying harder is what earns the rate limit in the first place. Each provider's cache entry is keyed to a fingerprint (a sha256 prefix, never the token itself) of the credentials that fetched it: switching accounts — or rotating a token — discards that provider's cached numbers and backoff and polls immediately, so an exhausted old account's meters never masquerade as the new account's. Requires a Nerd Font new enough to include the codicon brand glyphs (v3.5.0+); older fonts render them as replacement boxes.
 
-## Neon cache-wave celebration
+## Cache-hit celebration
 
 Whenever one assistant response reaches a prompt-cache hit rate of at least 96%, a temporary module is appended after context usage for about two seconds:
 
@@ -64,7 +65,32 @@ Whenever one assistant response reaches a prompt-cache hit rate of at least 96%,
 gpt-5.6-sol | pi-extensions:main | 135k/272k | ⚡96%·CACHE·HIT
 ```
 
-Only the `⚡96%·CACHE·HIT` badge animates: the whole badge flashes between neon magenta and neon cyan every 60 ms. The existing model, repository, context, separators, worktree, and session-ID rendering do not change.
+Only the `⚡96%·CACHE·HIT` badge animates, at 60 ms per frame. The existing model, repository, context, separators, worktree, and session-ID rendering do not change.
+
+### Animation styles
+
+`/statusline → Cache celebration` cycles through `off` and five animations:
+
+| Style | Motion |
+|---|---|
+| `flash` | The whole badge alternates between the theme's two celebration colors (the default, and what shipped before 0.4.0) |
+| `wave` | A bright crest sweeps left to right, trailing back into the base color |
+| `pulse` | The whole badge ramps between dim and bright on a triangle wave |
+| `rainbow` | A full-spectrum gradient rotates along the characters |
+| `sparkle` | Random characters flare to the highlight color and decay |
+
+Every style except `rainbow` is derived from the active [theme](#themes)'s two `celebration` roles, so they recolor with the theme — in the `white` theme they stay greyscale. `rainbow` is full-spectrum by design and ignores the palette.
+
+Selecting the row previews it live: the real statusline below the menu loops the badge at 96% so you see the final rendering in context, and the loop stops as soon as you move to another row or close the menu. Choosing `off` keeps your style, so turning the celebration back on restores it.
+
+To compare styles outside pi, or to iterate on their implementations:
+
+```bash
+npm run demo:celebrations              # every style on a real statusline
+npm run demo:celebrations -- --matrix  # every style against every theme
+```
+
+That script imports the shipped styles directly, so editing `celebration-styles.ts` and re-running shows exactly what the extension will render.
 
 The rate is evaluated per provider response as:
 

package/celebration-preview.ts

@@ -0,0 +1,125 @@
+import {
+	CACHE_CELEBRATION_FRAME_INTERVAL_MS,
+	type CacheCelebrationSnapshot,
+} from "./cache-celebration.ts";
+import type { SettingsListTheme } from "@earendil-works/pi-tui";
+
+/** Percentage shown by the settings-menu preview badge. */
+export const PREVIEW_PERCENT = 96;
+
+export interface CelebrationPreviewOptions {
+	frameIntervalMs?: number;
+	schedule?: (callback: () => void, intervalMs: number) => unknown;
+	cancel?: (handle: unknown) => void;
+}
+
+function defaultSchedule(callback: () => void, intervalMs: number): unknown {
+	const timer = setInterval(callback, intervalMs);
+	// A settings preview must never keep Pi alive.
+	(timer as { unref?: () => void }).unref?.();
+	return timer;
+}
+
+/**
+ * Loops a fake celebration snapshot for the statusline footer while the
+ * celebration row is selected in `/statusline`.
+ *
+ * Unlike CacheCelebrationController this never ends on its own: it runs until
+ * the row loses focus or the menu closes.
+ */
+export class CelebrationPreview {
+	private frame = 0;
+	private running = false;
+	private timerHandle: unknown;
+	private readonly frameIntervalMs: number;
+	private readonly schedule: (callback: () => void, intervalMs: number) => unknown;
+	private readonly cancel: (handle: unknown) => void;
+
+	constructor(
+		private readonly requestRender: () => void,
+		options: CelebrationPreviewOptions = {},
+	) {
+		this.frameIntervalMs = options.frameIntervalMs ?? CACHE_CELEBRATION_FRAME_INTERVAL_MS;
+		this.schedule = options.schedule ?? defaultSchedule;
+		this.cancel = options.cancel ?? ((handle) => clearInterval(handle as ReturnType<typeof setInterval>));
+	}
+
+	/** Start looping, or keep looping if already started. Idempotent. */
+	start(): void {
+		if (this.running) return;
+		this.running = true;
+		this.frame = 0;
+		this.timerHandle = this.schedule(() => this.tick(), this.frameIntervalMs);
+		this.requestRender();
+	}
+
+	/** Stop looping and clear the preview. Idempotent; only repaints if it was running. */
+	stop(): void {
+		if (!this.running) return;
+		this.running = false;
+		this.clearTimer();
+		this.requestRender();
+	}
+
+	/** Start or stop to match `active`, repainting only on a real transition. */
+	setActive(active: boolean): void {
+		if (active) this.start();
+		else this.stop();
+	}
+
+	isRunning(): boolean {
+		return this.running;
+	}
+
+	snapshot(): CacheCelebrationSnapshot | undefined {
+		return this.running ? { percent: PREVIEW_PERCENT, frame: this.frame } : undefined;
+	}
+
+	dispose(): void {
+		this.running = false;
+		this.clearTimer();
+	}
+
+	private tick(): void {
+		if (!this.running) return;
+		this.frame += 1;
+		this.requestRender();
+	}
+
+	private clearTimer(): void {
+		if (this.timerHandle !== undefined) this.cancel(this.timerHandle);
+		this.timerHandle = undefined;
+	}
+}
+
+/**
+ * Wrap a SettingsList theme so rendering reports which row is highlighted.
+ *
+ * SettingsList keeps `selectedIndex` private, but it calls `theme.label(text,
+ * selected)` for every visible row, so the render pass itself tells us. That
+ * keeps working through search filtering and submenus, where index arithmetic
+ * on our side would silently drift.
+ */
+export function trackSelectedLabel(theme: SettingsListTheme): {
+	theme: SettingsListTheme;
+	/** Reset before a render pass; read the captured label after it. */
+	begin(): void;
+	selected(): string | undefined;
+} {
+	let captured: string | undefined;
+	return {
+		theme: {
+			...theme,
+			label(text: string, selected: boolean): string {
+				if (selected) captured = text.trim();
+				return theme.label(text, selected);
+			},
+		},
+		begin(): void {
+			captured = undefined;
+		},
+		selected(): string | undefined {
+			return captured;
+		},
+	};
+}

package/celebration-styles.ts

@@ -0,0 +1,158 @@
+/**
+ * Cache-hit badge animations.
+ *
+ * Every style is a pure `(frame, palette) -> string[]` colouring of the badge
+ * characters, so a style can be rendered for any frame in any order. That keeps
+ * them testable, and lets the settings menu loop a preview without touching the
+ * real celebration timer.
+ */
+import type { StatuslinePalette } from "./themes.ts";
+
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+
+export interface Rgb {
+	r: number;
+	g: number;
+	b: number;
+}
+
+export const fgCode = ({ r, g, b }: Rgb): string =>
+	`\x1b[38;2;${Math.round(r)};${Math.round(g)};${Math.round(b)}m`;
+
+/** Parse an SGR true-colour prefix back into channels; anything else reads as white. */
+export function parseFg(code: string): Rgb {
+	const match = /^\x1b\[38;2;(\d+);(\d+);(\d+)m$/.exec(code);
+	if (!match) return { r: 255, g: 255, b: 255 };
+	return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]) };
+}
+
+const mix = (a: Rgb, b: Rgb, t: number): Rgb => ({
+	r: a.r + (b.r - a.r) * t,
+	g: a.g + (b.g - a.g) * t,
+	b: a.b + (b.b - a.b) * t,
+});
+
+const scale = ({ r, g, b }: Rgb, factor: number): Rgb => ({
+	r: Math.min(255, r * factor),
+	g: Math.min(255, g * factor),
+	b: Math.min(255, b * factor),
+});
+
+/** Deterministic per-(index, frame) noise; no Math.random so frames are reproducible. */
+function noise(index: number, frame: number): number {
+	const x = Math.sin(index * 127.1 + frame * 311.7) * 43758.5453;
+	return x - Math.floor(x);
+}
+
+function hue(degrees: number): Rgb {
+	const h = (((degrees % 360) + 360) % 360) / 60;
+	const sector = Math.floor(h);
+	const f = h - sector;
+	const q = 255 * (1 - f);
+	const t = 255 * f;
+	switch (sector) {
+		case 0:
+			return { r: 255, g: t, b: 0 };
+		case 1:
+			return { r: q, g: 255, b: 0 };
+		case 2:
+			return { r: 0, g: 255, b: t };
+		case 3:
+			return { r: 0, g: q, b: 255 };
+		case 4:
+			return { r: t, g: 0, b: 255 };
+		default:
+			return { r: 255, g: 0, b: q };
+	}
+}
+
+/** Colour every character of `badge` for one frame. */
+export type CelebrationStyle = (badge: string, frame: number, palette: StatuslinePalette) => string;
+
+const uniform = (badge: string, colour: Rgb): string => `${BOLD}${fgCode(colour)}${badge}${RESET}`;
+
+const perCharacter = (badge: string, colourAt: (index: number) => Rgb): string => {
+	const chars = [...badge];
+	let out = BOLD;
+	let previous = "";
+	for (const [index, char] of chars.entries()) {
+		const code = fgCode(colourAt(index));
+		if (code !== previous) {
+			out += code;
+			previous = code;
+		}
+		out += char;
+	}
+	return out + RESET;
+};
+
+/** The original two-frame alternation. */
+const flash: CelebrationStyle = (badge, frame, palette) =>
+	uniform(badge, parseFg(palette.celebration[frame % 2 === 0 ? 0 : 1]));
+
+/** A bright crest sweeping left to right, trailing back into the base colour. */
+const wave: CelebrationStyle = (badge, frame, palette) => {
+	const base = parseFg(palette.celebration[0]);
+	const crest = parseFg(palette.celebration[1]);
+	const length = [...badge].length;
+	const period = length + 6;
+	const position = (frame % period) - 3;
+	return perCharacter(badge, (index) => {
+		const distance = Math.abs(index - position);
+		const intensity = Math.max(0, 1 - distance / 3);
+		return scale(mix(base, crest, intensity), 1 + intensity * 0.35);
+	});
+};
+
+/** Whole badge ramping between dim and bright on a triangle wave. */
+const pulse: CelebrationStyle = (badge, frame, palette) => {
+	const base = parseFg(palette.celebration[0]);
+	const peak = parseFg(palette.celebration[1]);
+	const period = 20;
+	const phase = (frame % period) / period;
+	const triangle = phase < 0.5 ? phase * 2 : (1 - phase) * 2;
+	return uniform(badge, scale(mix(scale(base, 0.45), peak, triangle), 1 + triangle * 0.25));
+};
+
+/** Full spectrum rotating along the badge; ignores the theme by design. */
+const rainbow: CelebrationStyle = (badge, frame) =>
+	perCharacter(badge, (index) => hue(index * 18 - frame * 12));
+
+/** Random characters flare to the highlight colour and decay back. */
+const sparkle: CelebrationStyle = (badge, frame, palette) => {
+	const base = parseFg(palette.celebration[0]);
+	const spark = parseFg(palette.celebration[1]);
+	return perCharacter(badge, (index) => {
+		const intensity = Math.max(noise(index, frame) ** 6, noise(index, frame - 1) ** 6 * 0.5);
+		return scale(mix(base, spark, intensity), 1 + intensity * 0.5);
+	});
+};
+
+export const CELEBRATION_STYLES = { flash, wave, pulse, rainbow, sparkle } as const;
+
+export type CelebrationStyleName = keyof typeof CELEBRATION_STYLES;
+
+export const DEFAULT_CELEBRATION_STYLE: CelebrationStyleName = "flash";
+export const CELEBRATION_STYLE_NAMES = Object.keys(CELEBRATION_STYLES) as CelebrationStyleName[];
+
+export function isCelebrationStyleName(value: unknown): value is CelebrationStyleName {
+	// hasOwn, not `in`: "__proto__" and "toString" are on the prototype chain.
+	return typeof value === "string" && Object.hasOwn(CELEBRATION_STYLES, value);
+}
+
+/** Format the badge text for a hit percentage. */
+export const cacheBadgeText = (percent: number): string => `\u26a1${percent}%\u00b7CACHE\u00b7HIT`;
+
+/** Render one animation frame of the cache badge. */
+export function renderCacheBadge(
+	percent: number,
+	frame: number,
+	style: string,
+	palette: StatuslinePalette,
+): string {
+	const chosen = isCelebrationStyleName(style) ? style : DEFAULT_CELEBRATION_STYLE;
+	// Math.max(0, NaN) is NaN, which would reach the SGR channels verbatim.
+	const safeFrame = Number.isFinite(frame) ? Math.max(0, Math.trunc(frame)) : 0;
+	return CELEBRATION_STYLES[chosen](cacheBadgeText(percent), safeFrame, palette);
+}

package/index.ts

@@ -12,10 +12,13 @@ import {
 	type CacheCelebrationSnapshot,
 	triggerCacheCelebrationForMessage,
 } from "./cache-celebration.ts";
+import { CelebrationPreview, trackSelectedLabel } from "./celebration-preview.ts";
+import { DEFAULT_CELEBRATION_STYLE, renderCacheBadge } from "./celebration-styles.ts";
 import { FullRedrawScheduler } from "./redraw.ts";
 import {
 	applySettingChange,
 	buildSettingItems,
+	CACHE_CELEBRATION_LABEL,
 	createAliasSubmenu,
 	createWorktreeRootSubmenu,
 } from "./settings-menu.ts";
@@ -41,7 +44,6 @@ export interface StatuslineData {
 	usage?: UsageSnapshot;
 }
 
-const BOLD = "\x1b[1m";
 const RESET = "\x1b[0m";
 const DEFAULT_PALETTE = STATUSLINE_THEMES.default;
 
@@ -112,11 +114,10 @@ export function renderCacheCelebrationLine(
 	summary: string,
 	celebration: CacheCelebrationSnapshot,
 	palette: StatuslinePalette = DEFAULT_PALETTE,
+	style: string = DEFAULT_CELEBRATION_STYLE,
 ): string {
-	const badge = `⚡${celebration.percent}%·CACHE·HIT`;
-	const color = palette.celebration[celebration.frame % 2 === 0 ? 0 : 1];
-	const animatedBadge = `${BOLD}${color}${badge}${RESET}`;
-	return `${summary}${styled(palette.dim, " | ")}${animatedBadge}`;
+	const badge = renderCacheBadge(celebration.percent, celebration.frame, style, palette);
+	return `${summary}${styled(palette.dim, " | ")}${badge}`;
 }
 
 function renderWorktreeLine(
@@ -187,7 +188,12 @@ export function renderStatusline(
 		// A badge-only first line is separator soup, so the celebration needs a summary.
 		const celebration = settings.showCacheCelebration ? data.cacheCelebration : undefined;
 		lines.push(
-			truncateToWidth(celebration ? renderCacheCelebrationLine(summary, celebration, palette) : summary, width),
+			truncateToWidth(
+				celebration
+					? renderCacheCelebrationLine(summary, celebration, palette, settings.cacheCelebrationStyle)
+					: summary,
+				width,
+			),
 		);
 	}
 	if (showWorktreeLine) {
@@ -199,6 +205,7 @@ export function renderStatusline(
 
 export default function statuslineExtension(pi: ExtensionAPI): void {
 	let requestRender: (() => void) | undefined;
+	const celebrationPreview = new CelebrationPreview(() => requestRender?.());
 	const fullRedraw = new FullRedrawScheduler();
 	const cacheCelebration = new CacheCelebrationController(() => requestRender?.());
 	let tracker: SessionWorktreeTracker | undefined;
@@ -303,7 +310,8 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 			}
 
 			await ctx.ui.custom<void>((tui, _theme, _keybindings, done) => {
-				const settingsTheme = getSettingsListTheme();
+				const tracked = trackSelectedLabel(getSettingsListTheme());
+				const settingsTheme = tracked.theme;
 				const submenuHost = {
 					getSettings: () => settings,
 					commit: (next: StatuslineSettings) => applySettings(ctx, next),
@@ -313,7 +321,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					selectTheme: getSelectListTheme(),
 					home,
 				};
-				return new SettingsList(
+				const list = new SettingsList(
 					buildSettingItems(
 						settings,
 						{
@@ -333,6 +341,28 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					() => done(undefined),
 					{ enableSearch: true },
 				);
+
+				// The preview animates the real footer, so it only needs to wrap the
+				// list's render to learn which row currently has focus.
+				return {
+					dispose(): void {
+						// Clear the fake badge from the footer the menu was drawn over.
+						celebrationPreview.dispose();
+						requestRender?.();
+					},
+					invalidate(): void {
+						list.invalidate();
+					},
+					handleInput(data: string): void {
+						list.handleInput(data);
+					},
+					render(width: number): string[] {
+						tracked.begin();
+						const lines = list.render(width);
+						celebrationPreview.setActive(tracked.selected() === CACHE_CELEBRATION_LABEL);
+						return lines;
+					},
+				};
 			});
 		},
 	});
@@ -358,6 +388,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 				dispose(): void {
 					stopBranchUpdates();
 					cacheCelebration.dispose();
+					celebrationPreview.dispose();
 					fullRedraw.detach();
 					requestRender = undefined;
 				},
@@ -377,7 +408,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 								contextWindow: usage?.contextWindow ?? ctx.model?.contextWindow ?? 0,
 								worktrees: tracker?.getWorktrees() ?? [],
 								sessionId: ctx.sessionManager.getSessionId(),
-								cacheCelebration: cacheCelebration.snapshot(),
+								cacheCelebration: celebrationPreview.snapshot() ?? cacheCelebration.snapshot(),
 								usage: usageTracker.snapshot(),
 							},
 							width,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [
@@ -33,6 +33,8 @@
   "files": [
     "index.ts",
     "cache-celebration.ts",
+    "celebration-preview.ts",
+    "celebration-styles.ts",
     "redraw.ts",
     "settings.ts",
     "settings-menu.ts",

package/settings-menu.ts

@@ -10,9 +10,11 @@ import {
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { type BooleanSettingKey, collapseHome, resolveWorktreeRoot, type StatuslineSettings } from "./settings.ts";
+import { CELEBRATION_STYLE_NAMES, isCelebrationStyleName } from "./celebration-styles.ts";
 import { isThemeName, THEME_NAMES } from "./themes.ts";
 
 export const THEME_ID = "theme";
+export const CACHE_CELEBRATION_ID = "showCacheCelebration";
 export const WORKTREE_ROOT_ID = "worktreeRoot";
 export const REPO_ALIASES_ID = "repoAliases";
 export const ADD_ALIAS_VALUE = "\u0000add";
@@ -35,13 +37,16 @@ export const BOOLEAN_ROWS: readonly BooleanRow[] = [
 	{ id: "showUsage", label: "Subscription usage", description: "Show Claude/Codex remaining-headroom meters." },
 	{ id: "showWorktrees", label: "Worktree line", description: "Show touched worktrees and their pull requests." },
 	{ id: "showSessionId", label: "Session ID line", description: "Show the full Pi session id on its own line." },
-	{
-		id: "showCacheCelebration",
-		label: "Cache celebration",
-		description: "Flash a badge after an exceptional prompt-cache hit.",
-	},
 ];
 
+/** Label of the celebration row, used to drive the settings-menu preview loop. */
+export const CACHE_CELEBRATION_LABEL = "Cache celebration";
+
+/** The celebration row folds "off" into the style list, so it is one row, not two. */
+export function celebrationValue(settings: StatuslineSettings): string {
+	return settings.showCacheCelebration ? settings.cacheCelebrationStyle : OFF;
+}
+
 export function toggleValue(enabled: boolean): string {
 	return enabled ? ON : OFF;
 }
@@ -70,6 +75,13 @@ export function buildSettingItems(
 			currentValue: settings.theme,
 			values: [...THEME_NAMES],
 		},
+		{
+			id: CACHE_CELEBRATION_ID,
+			label: CACHE_CELEBRATION_LABEL,
+			description: "Badge animation after an exceptional prompt-cache hit; previews in the statusline below.",
+			currentValue: celebrationValue(settings),
+			values: [OFF, ...CELEBRATION_STYLE_NAMES],
+		},
 		...BOOLEAN_ROWS.map((row) => ({
 			id: row.id,
 			label: row.label,
@@ -113,6 +125,21 @@ export function applySettingChange(
 		if (value !== ON && value !== OFF) return { kind: "error", message: `Unknown value for ${id}: ${value}` };
 		return { kind: "settings", settings: { ...settings, [id]: value === ON } };
 	}
+	if (id === CACHE_CELEBRATION_ID) {
+		if (value === OFF) {
+			return settings.showCacheCelebration
+				? { kind: "settings", settings: { ...settings, showCacheCelebration: false } }
+				: { kind: "ignored" };
+		}
+		if (!isCelebrationStyleName(value)) {
+			return { kind: "error", message: `Unknown cache celebration style: ${value}` };
+		}
+		if (settings.showCacheCelebration && settings.cacheCelebrationStyle === value) return { kind: "ignored" };
+		return {
+			kind: "settings",
+			settings: { ...settings, showCacheCelebration: true, cacheCelebrationStyle: value },
+		};
+	}
 	if (id === THEME_ID) {
 		if (!isThemeName(value)) return { kind: "error", message: `Unknown statusline theme: ${value}` };
 		if (value === settings.theme) return { kind: "ignored" };

package/settings.ts

@@ -2,6 +2,11 @@ import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import { pid } from "node:process";
+import {
+	type CelebrationStyleName,
+	DEFAULT_CELEBRATION_STYLE,
+	isCelebrationStyleName,
+} from "./celebration-styles.ts";
 import { DEFAULT_THEME, isThemeName, type StatuslineThemeName } from "./themes.ts";
 
 /** Toggle keys, in the order the `/statusline` menu lists them. */
@@ -20,6 +25,8 @@ export type BooleanSettingKey = (typeof BOOLEAN_SETTING_KEYS)[number];
 export interface StatuslineSettings extends Record<BooleanSettingKey, boolean> {
 	/** Colour palette name; see themes.ts. */
 	theme: StatuslineThemeName;
+	/** Cache-hit badge animation; only consulted when showCacheCelebration is on. */
+	cacheCelebrationStyle: CelebrationStyleName;
 	/** Directory whose immediate children are treated as session worktrees. */
 	worktreeRoot: string;
 	/** `repository name -> display alias` overrides for the worktree line. */
@@ -40,6 +47,7 @@ export function defaultSettings(home: string = homedir()): StatuslineSettings {
 		showSessionId: true,
 		showCacheCelebration: true,
 		theme: DEFAULT_THEME,
+		cacheCelebrationStyle: DEFAULT_CELEBRATION_STYLE,
 		worktreeRoot: defaultWorktreeRoot(home),
 		repoAliases: {},
 	};
@@ -113,7 +121,13 @@ export function normalizeSettings(value: unknown, home: string = homedir()): Nor
 	const extra: Record<string, unknown> = {};
 	if (!isPlainObject(value)) return { settings, extra };
 
-	const known = new Set<string>([...BOOLEAN_SETTING_KEYS, "theme", "worktreeRoot", "repoAliases"]);
+	const known = new Set<string>([
+		...BOOLEAN_SETTING_KEYS,
+		"theme",
+		"cacheCelebrationStyle",
+		"worktreeRoot",
+		"repoAliases",
+	]);
 	for (const [key, raw] of Object.entries(value)) {
 		if (!known.has(key)) {
 			extra[key] = raw;
@@ -135,6 +149,10 @@ export function normalizeSettings(value: unknown, home: string = homedir()): Nor
 			if (isThemeName(raw)) settings.theme = raw;
 			continue;
 		}
+		if (key === "cacheCelebrationStyle") {
+			if (isCelebrationStyleName(raw)) settings.cacheCelebrationStyle = raw;
+			continue;
+		}
 		if (typeof raw === "boolean") settings[key as BooleanSettingKey] = raw;
 	}
 
@@ -162,6 +180,9 @@ export function serializeSettings(
 		if (settings[key] !== defaults[key]) out[key] = settings[key];
 	}
 	if (settings.theme !== defaults.theme) out.theme = settings.theme;
+	if (settings.cacheCelebrationStyle !== defaults.cacheCelebrationStyle) {
+		out.cacheCelebrationStyle = settings.cacheCelebrationStyle;
+	}
 	if (settings.worktreeRoot !== defaults.worktreeRoot) out.worktreeRoot = settings.worktreeRoot;
 	if (!sameAliases(settings.repoAliases, defaults.repoAliases)) out.repoAliases = { ...settings.repoAliases };
 	return out;

package/themes.ts

@@ -119,7 +119,8 @@ export const DEFAULT_THEME: StatuslineThemeName = "default";
 export const THEME_NAMES = Object.keys(STATUSLINE_THEMES) as StatuslineThemeName[];
 
 export function isThemeName(value: unknown): value is StatuslineThemeName {
-	return typeof value === "string" && value in STATUSLINE_THEMES;
+	// hasOwn, not `in`: "__proto__" and "toString" are on the prototype chain.
+	return typeof value === "string" && Object.hasOwn(STATUSLINE_THEMES, value);
 }
 
 /** Resolve a theme name to its palette; anything unknown falls back to the default. */