@underactive/pi-topping 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Sison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# pi-topping
+
+We garnish our pies. It seemed rude not to extend Pi the same courtesy. This is a [Pi](https://github.com/earendil-works/pi-coding-agent) extension that changes the default "Working..." loader with a shimmering activity word, a scrolling token-activity meter, an elapsed timer, and a live output-token count.
+
+![Demo of pi-topping's shimmering activity word, scrolling activity meter, elapsed timer, and token count](https://raw.githubusercontent.com/underactive/pi-topping/main/demo.gif)
+
+## What it does
+
+- Picks a random activity word (`Cerebrating…`, `Noodling…`, `Zigzagging…`, etc.) when you submit a prompt, and a new one each time a tool call starts.
+- Sweeps a theme-aware shimmer across the word while it's showing.
+- Shows an elapsed timer (`Xm YYs`) that counts up from when you submitted the prompt.
+- Shows a live output-token estimate (`↓ N tokens`), reconciled against the real usage total once each assistant message finishes.
+- Resets everything — word, timer, token count — on each new prompt, and restores Pi's normal loader between turns.
+
+## Activity meter
+
+Next to Pi's spinner there's an eight-column scrolling meter that reflects how fast tokens are streaming in. It updates every 100ms and uses your theme's accent color, so it should blend in with whatever theme you're running.
+
+## Settings
+
+Run `/topping-settings` (TUI only) to toggle things on or off:
+
+```
+╔═[ Pi Topping: Settings ]══════════════════════════╗
+╟─ Preview ─────────────────────────────────────────╢
+║                                                   ║
+║  ⠋ Crafting ⣤⣤⣤⣤ (0m 03s · ↓ 84 tokens)          ║
+║                                                   ║
+╟─ Decorations ─────────────────────────────────────╢
+║  ▸ [■] Animated spinner                       ON  ║
+║    [■] "Working..." text shimmer              ON  ║
+║    [■] Token activity monitor                 ON  ║
+╟─ Features ────────────────────────────────────────╢
+║    [■] Substitute Pi's "Working..." message   ON  ║
+║    [■] Elapsed time since prompt              ON  ║
+║    [■] Show output tokens                     ON  ║
+╟───────────────────────────────────────────────────╢
+║  ↑↓ move  ␣ toggle  ⏎ apply  esc cancel           ║
+╚═══════════════════════════════════════════════════╝
+```
+
+**Decorations** — animated spinner, word shimmer, activity meter.
+
+**Features** — whether to substitute the random word at all, the elapsed timer, and the token count.
+
+The menu has a live preview so you can see changes as you make them. Everything is on by default, so nothing changes unless you open the menu. Use `↑↓` to move, `␣` to toggle, `⏎` to save, `esc` to cancel. Settings are saved to `~/.pi/agent/pi-topping/settings.json`.
+
+The toggle-menu component itself lives in `menu.ts` and is reusable by other extensions if you want a similar settings UI.
+
+## Install
+
+```bash
+pi install npm:@underactive/pi-topping
+```
+
+Restart Pi (or run `/reload`) to pick it up.
+
+## Requirements
+
+- [Pi](https://github.com/earendil-works/pi-coding-agent)
+- Node.js ≥22.19.0
+
+## Development
+
+```bash
+npm install
+npm test
+npm run typecheck
+```
+
+Tests cover the word/shimmer rendering, activity meter behavior, timer resets, settings persistence, the `menu.ts` component, and the settings menu wiring end to end.
+
+## Limitations
+
+- Token counts are a streaming word-count estimate, not an exact tokenizer count — they self-correct when each message finishes, so you'll see a small jump at that point.
+- Elapsed time normally starts when you submit a prompt; for auto-continuations without that event, it starts slightly later instead.
+- If another extension also customizes the working message, whichever one runs last wins.
+
+## Author
+
+Eric Sison

package/activity-meter.ts

@@ -0,0 +1,102 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+export const ActivityMeterLevel = {
+	IDLE: 0,
+	LOW: 1,
+	MEDIUM: 2,
+	HIGH: 3,
+	PEAK_1: 4,
+	PEAK_2: 5,
+	PEAK_3: 6,
+	FULL: 7,
+} as const;
+
+export type ActivityMeterLevel = (typeof ActivityMeterLevel)[keyof typeof ActivityMeterLevel];
+
+const EMA_ALPHA = 0.4;
+const BRAILLE: Record<ActivityMeterLevel, string> = {
+	[ActivityMeterLevel.IDLE]: "⢀",
+	[ActivityMeterLevel.LOW]: "⣀",
+	[ActivityMeterLevel.MEDIUM]: "⣠",
+	[ActivityMeterLevel.HIGH]: "⣤",
+	[ActivityMeterLevel.PEAK_1]: "⣴",
+	[ActivityMeterLevel.PEAK_2]: "⣶",
+	[ActivityMeterLevel.PEAK_3]: "⣾",
+	[ActivityMeterLevel.FULL]: "⣿",
+};
+const WIDTH = 8;
+type CellColorizer = (level: ActivityMeterLevel, char: string) => string;
+
+/** Convert an estimated output-token rate to a display level. */
+export function rateToLevel(tokensPerSecond: number): ActivityMeterLevel {
+	const THRESHOLDS = [0, 5, 10, 15, 22, 30, 40];
+	for (let i = THRESHOLDS.length - 1; i >= 0; i--) {
+		if (tokensPerSecond > THRESHOLDS[i]) return (i + 1) as ActivityMeterLevel;
+	}
+	return 0;
+}
+
+/** EMA-smoothed rate tracker for a cumulative output-token estimate. */
+export class TokRateTracker {
+	#lastTotal = 0;
+	#lastTime = 0;
+	#rate = 0;
+	#hasSample = false;
+
+	sample(totalTokens: number, now: number): number {
+		if (!this.#hasSample) {
+			this.#lastTotal = totalTokens;
+			this.#hasSample = true;
+			this.#lastTime = now;
+			return this.#rate;
+		}
+
+		const elapsedSeconds = (now - this.#lastTime) / 1_000;
+		if (elapsedSeconds <= 0) return this.#rate;
+
+		const instantRate = Math.max(0, (totalTokens - this.#lastTotal) / elapsedSeconds);
+		this.#rate = EMA_ALPHA * instantRate + (1 - EMA_ALPHA) * this.#rate;
+		this.#lastTotal = totalTokens;
+		this.#lastTime = now;
+		return this.#rate;
+	}
+
+	reset(): void {
+		this.#lastTotal = 0;
+		this.#lastTime = 0;
+		this.#rate = 0;
+		this.#hasSample = false;
+	}
+}
+
+/** Eight-column, left-to-right scrolling activity meter. */
+export class ActivityMeter {
+	#levels: ActivityMeterLevel[] = Array<ActivityMeterLevel>(WIDTH).fill(0);
+
+	push(level: ActivityMeterLevel): void {
+		this.#levels.pop();
+		this.#levels.unshift(level);
+	}
+
+	render(colorize?: CellColorizer): string {
+		return this.#levels
+			.map((level) => {
+				const char = BRAILLE[level];
+				return colorize ? colorize(level, char) : char;
+			})
+			.join("");
+	}
+
+	reset(): void {
+		this.#levels.fill(0);
+	}
+
+	/** Colorize a meter cell using the default theme mapping (dim at IDLE, accent otherwise). */
+	static colorizeCell(
+		level: ActivityMeterLevel,
+		char: string,
+		theme: { fg: (style: ThemeColor, s: string) => string },
+	): string {
+		return level === ActivityMeterLevel.IDLE ? theme.fg("dim", char) : theme.fg("accent", char);
+	}
+}

package/format.ts

@@ -0,0 +1,71 @@
+/** Format an output-token count for the working indicator. */
+export function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	const UNITS = [
+		{ threshold: 10_000, divisor: 1_000, decimals: 1, suffix: "k" },
+		{ threshold: 1_000_000, divisor: 1_000, decimals: 0, suffix: "k" },
+		{ threshold: 10_000_000, divisor: 1_000_000, decimals: 1, suffix: "M" },
+	];
+	const unit = UNITS.find(u => count < u.threshold);
+	if (unit) {
+		const value = unit.decimals > 0
+			? (count / unit.divisor).toFixed(unit.decimals)
+			: `${Math.round(count / unit.divisor)}`;
+		return `${value}${unit.suffix}`;
+	}
+	return `${Math.round(count / 1_000_000)}M`;
+}
+
+/** Format elapsed milliseconds as minutes and zero-padded seconds. */
+export function formatElapsed(ms: number): string {
+	const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
+}
+
+/**
+ * Incremental whitespace-boundary word counter.
+ *
+ * The in-word state is retained across streaming chunks so a word split across
+ * multiple deltas is counted exactly once.
+ */
+export class StreamingWordCounter {
+	#inWordByStream = new Map<string, boolean>();
+
+	count(text: string, stream = "default"): number {
+		let inWord = this.#inWordByStream.get(stream) ?? false;
+		let count = 0;
+		for (let i = 0; i < text.length; i++) {
+			const code = text.charCodeAt(i);
+			if (isWhitespace(code)) {
+				inWord = false;
+			} else if (!inWord) {
+				count++;
+				inWord = true;
+			}
+		}
+		this.#inWordByStream.set(stream, inWord);
+		return count;
+	}
+
+	reset(): void {
+		this.#inWordByStream.clear();
+	}
+}
+
+function isWhitespace(code: number): boolean {
+	return (
+		code === 32 ||
+		(code >= 9 && code <= 13) ||
+		code === 160 ||
+		code === 0x1680 ||
+		(code >= 0x2000 && code <= 0x200a) ||
+		code === 0x2028 ||
+		code === 0x2029 ||
+		code === 0x202f ||
+		code === 0x205f ||
+		code === 0x3000 ||
+		code === 0xfeff
+	);
+}