@hank-warren/pi-statusline 0.2.4 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @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
+
+- 0e6c204: Add a `/statusline` settings menu for choosing a theme, toggling every footer element, setting the worktree-tracker root, and managing repo aliases. Settings persist to `~/.pi/agent/statusline-settings.json` and apply live.
+
+  Themes: `default` (unchanged), `dracula`, `github-dark`, `catppuccin-mocha`, and `white`. A theme maps eleven colour roles, so switching recolours every element without changing the rendered text.
+
+  Breaking: the built-in repo aliases and the automatic `platform-` prefix strip are gone — they were hardcoded to one machine. Repository names now render verbatim; add your own pairs under `/statusline → Repo aliases`.
+
 ## 0.2.4
 
 ### Patch Changes

package/README.md

@@ -14,7 +14,35 @@ gpt-5.6-sol | pi-extensions:main* ⇣1 | 40k/1.0m |  97·54  80
 - **Worktree lines** — when the session works in or sends tool calls into linked worktrees, one line shows the same branch/dirty/behind state for each worktree plus its associated PR number.
 - **Final line** — the full Pi session ID.
 
-It uses a fixed true-color palette with context warning thresholds.
+Colors come from a selectable [theme](#themes), with context warning thresholds. Every element can be turned off from [`/statusline`](#statusline).
+
+## `/statusline`
+
+`/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).
+- **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.
+
+## Themes
+
+| Name | Notes |
+|---|---|
+| `default` | The palette this package has always used — blue model, cyan branch, neon magenta/cyan cache badge |
+| `dracula` | [Dracula](https://draculatheme.com), with the pink `#ff79c6` branch color used in Herdr sidebar configs |
+| `github-dark` | GitHub's dark default |
+| `catppuccin-mocha` | [Catppuccin](https://catppuccin.com) Mocha |
+| `white` | No color: white text, dimmed punctuation, a white/grey badge flash |
+
+A theme maps eleven roles — `model`, `path`, `branch`, `text`, `dim`, `ok`, `warn`, `caution`, `danger`, `accent`, and the two `celebration` badge frames — so switching recolors every element at once without changing a single character of rendered text. `ok`/`warn`/`caution`/`danger` drive the context meter, the usage meters, and the dirty/behind markers alike, so the warning gradient stays legible in every theme. An unknown theme name in the settings file falls back to `default`.
+
+### Repo aliases are no longer built in
+
+Up to 0.2.x this package hardcoded five alias pairs and stripped a `platform-` prefix from every other repository. Those rules were specific to one machine and shipped to everyone. From 0.3.0 the alias map starts empty and repository names render verbatim — add whatever pairs you want under `/statusline → Repo aliases`.
 
 ## Subscription usage meters
 
@@ -29,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:
 
@@ -37,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:
 
@@ -49,7 +102,7 @@ Output and reasoning tokens are excluded because they are not prompt-cache candi
 
 ## Worktree/PR tracking behavior
 
-- Only worktrees touched on the active Pi session branch are included.
+- Only worktrees directly under the configured worktree root and touched on the active Pi session branch are included. Absolute, `~/`, and `$HOME/` spellings of that root all match.
 - Worktree paths appearing only inside Bash heredoc payloads are ignored.
 - Merged and closed PR worktrees are hidden.
 - State is rebuilt on reload and tree navigation; deleted worktrees are pruned.

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);
+}