@hank-warren/pi-statusline 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @hank-warren/pi-statusline
 
+## 0.4.1
+
+### Patch Changes
+
+- 2dbfc7a: Stop settings saves from clobbering the file. Sessions load settings once at startup and used to persist their entire in-memory snapshot, so changing any row in a session that started before an edit silently reverted that edit — losing hand-written config and other sessions' changes, and collapsing the file to `{}` because serialization is sparse. Saves now write only the keys a change actually touched, merged over the current file contents, and opening `/statusline` re-reads the file first.
+
+  Also moves the **Cache celebration** row after **Subscription usage** so the menu follows the order elements render in.
+
+## 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,11 +21,14 @@ 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.
 
-Settings live in a single global file, `~/.pi/agent/statusline-settings.json`, written atomically. Only values differing from the defaults are stored, unknown keys from a newer version are preserved, and a missing or malformed file simply yields defaults. The file is read once at session start and is not watched, so hand edits apply to the next session. Concurrent pi sessions are last-writer-wins.
+Settings live in a single global file, `~/.pi/agent/statusline-settings.json`, written atomically. Only values differing from the defaults are stored, unknown keys from a newer version are preserved, and a missing or malformed file simply yields defaults.
+
+Saves are per-key rather than whole-file: a change writes only the fields it actually touched over whatever is on disk at that moment. Sessions load settings once at startup, so a whole-file write would let a session that started hours ago revert edits it never saw — including hand edits and changes made in another session. Opening `/statusline` also re-reads the file first, so the menu always edits current state. Two sessions changing the *same* field are still last-writer-wins; everything else merges.
 
 ## Themes
 
@@ -56,7 +59,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 +67,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,14 +12,23 @@ 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";
-import { defaultSettings, repoAlias, SettingsStore, type StatuslineSettings } from "./settings.ts";
+import {
+	changedSettingKeys,
+	defaultSettings,
+	repoAlias,
+	SettingsStore,
+	type StatuslineSettings,
+} from "./settings.ts";
 import { resolvePalette, type StatuslinePalette, STATUSLINE_THEMES } from "./themes.ts";
 import { type UsageSnapshot, usageBand, UsageTracker } from "./usage.ts";
 import {
@@ -41,7 +50,6 @@ export interface StatuslineData {
 	usage?: UsageSnapshot;
 }
 
-const BOLD = "\x1b[1m";
 const RESET = "\x1b[0m";
 const DEFAULT_PALETTE = STATUSLINE_THEMES.default;
 
@@ -112,11 +120,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 +194,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 +211,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;
@@ -286,7 +299,9 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 		requestRender?.();
 
 		if (!persist) return;
-		settingsStore.save(next).catch((error: unknown) => {
+		const changed = changedSettingKeys(previous, next);
+		if (changed.length === 0) return;
+		settingsStore.save(next, changed).catch((error: unknown) => {
 			ctx.ui.notify(
 				`Could not save statusline settings: ${error instanceof Error ? error.message : String(error)}`,
 				"warning",
@@ -302,8 +317,14 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 				return;
 			}
 
+			// Settings load once per session; refresh before editing so the menu
+			// starts from what is on disk rather than a snapshot that may be hours
+			// old and missing another session's changes.
+			applySettings(ctx, await settingsStore.load(), false);
+
 			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 +334,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 					selectTheme: getSelectListTheme(),
 					home,
 				};
-				return new SettingsList(
+				const list = new SettingsList(
 					buildSettingItems(
 						settings,
 						{
@@ -333,6 +354,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 +401,7 @@ export default function statuslineExtension(pi: ExtensionAPI): void {
 				dispose(): void {
 					stopBranchUpdates();
 					cacheCelebration.dispose();
+					celebrationPreview.dispose();
 					fullRedraw.detach();
 					requestRender = undefined;
 				},
@@ -377,7 +421,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.1",
   "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,14 +75,28 @@ export function buildSettingItems(
 			currentValue: settings.theme,
 			values: [...THEME_NAMES],
 		},
-		...BOOLEAN_ROWS.map((row) => ({
+	];
+
+	// Rows follow the order their elements render in, so the celebration sits
+	// after the usage meters it is appended to on line 1.
+	for (const row of BOOLEAN_ROWS) {
+		items.push({
 			id: row.id,
 			label: row.label,
 			description: row.description,
 			currentValue: toggleValue(settings[row.id]),
 			values: TOGGLE_VALUES,
-		})),
-	];
+		});
+		if (row.id === "showUsage") {
+			items.push({
+				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],
+			});
+		}
+	}
 
 	items.push({
 		id: WORKTREE_ROOT_ID,
@@ -113,6 +132,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;
 	}
 
@@ -147,6 +165,29 @@ function sameAliases(a: Record<string, string>, b: Record<string, string>): bool
 	return aKeys.every((key) => a[key] === b[key]);
 }
 
+/** Every persisted top-level key, so a diff can enumerate them exhaustively. */
+export const SETTING_KEYS = [
+	...BOOLEAN_SETTING_KEYS,
+	"theme",
+	"cacheCelebrationStyle",
+	"worktreeRoot",
+	"repoAliases",
+] as const satisfies readonly (keyof StatuslineSettings)[];
+
+export type SettingKey = (typeof SETTING_KEYS)[number];
+
+/** The keys one edit actually touched; the unit of a merging save. */
+export function changedSettingKeys(
+	previous: StatuslineSettings,
+	next: StatuslineSettings,
+): SettingKey[] {
+	return SETTING_KEYS.filter((key) =>
+		key === "repoAliases"
+			? !sameAliases(previous.repoAliases, next.repoAliases)
+			: previous[key] !== next[key],
+	);
+}
+
 /**
  * Sparse serialization: only values differing from the defaults are written, so
  * a later default change still reaches hosts that never touched that key.
@@ -162,6 +203,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;
@@ -214,10 +258,30 @@ export class SettingsStore {
 		return settings;
 	}
 
-	/** Atomic write via temp file + rename. Rejects so the caller can notify. */
-	async save(settings: StatuslineSettings = this.current): Promise<void> {
+	/** Re-read the file as a plain object; anything unusable reads as empty. */
+	private async readRaw(): Promise<Record<string, unknown>> {
+		try {
+			const parsed: unknown = JSON.parse(await readFile(this.path, "utf8"));
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+			return { ...(parsed as Record<string, unknown>) };
+		} catch {
+			return {};
+		}
+	}
+
+	/**
+	 * Atomic write via temp file + rename. Rejects so the caller can notify.
+	 *
+	 * With `changed`, only those keys are written over whatever is on disk right
+	 * now. Settings load once per session, so a full-snapshot write would let a
+	 * session started before an edit silently revert it — including edits made by
+	 * hand or by another session. Passing the keys one change actually touched
+	 * keeps a writer from claiming fields it was never asked about.
+	 */
+	async save(settings: StatuslineSettings = this.current, changed?: readonly SettingKey[]): Promise<void> {
 		this.current = settings;
-		const payload = `${JSON.stringify(serializeSettings(settings, this.extra, this.home), null, "\t")}\n`;
+		const object = changed ? await this.merge(settings, changed) : serializeSettings(settings, this.extra, this.home);
+		const payload = `${JSON.stringify(object, null, "\t")}\n`;
 		const temporary = `${this.path}.${pid}.tmp`;
 		await mkdir(dirname(this.path), { recursive: true });
 		try {
@@ -228,4 +292,19 @@ export class SettingsStore {
 			throw error;
 		}
 	}
+
+	private async merge(
+		settings: StatuslineSettings,
+		changed: readonly SettingKey[],
+	): Promise<Record<string, unknown>> {
+		const merged = await this.readRaw();
+		// Serialization is sparse, so a key absent here is back at its default and
+		// must be removed rather than written.
+		const desired = serializeSettings(settings, {}, this.home);
+		for (const key of changed) {
+			if (Object.hasOwn(desired, key)) merged[key] = desired[key];
+			else delete merged[key];
+		}
+		return merged;
+	}
 }

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. */