@underactive/pi-topping 0.1.0

package/menu.ts

@@ -0,0 +1,327 @@
+/**
+ * menu.ts
+ *
+ * A reusable, dependency-light box-drawing toggle-menu component for Pi
+ * extensions, built on top of `@earendil-works/pi-tui`'s `Component`
+ * contract and `ctx.ui.custom()` overlay API.
+ *
+ * Renders a titled box containing one or more sections of boolean toggle
+ * items, plus an optional live-updating preview section driven by a
+ * caller-supplied render callback, e.g.:
+ *
+ *   ╔═[ Pi Topping: Settings ]════════════════════════╗
+ *   ╟─ Preview ─────────────────────────────────────╢
+ *   ║                                                  ║
+ *   ║ ⠋ Cerebrating… ⣤⣤⣤⣤ (0m 03s · ↓ 84 tokens)     ║
+ *   ║                                                  ║
+ *   ╟─ Decorations ───────────────────────────────────╢
+ *   ║  ▸ [■] Animated spinner                    ON   ║
+ *   ║    [ ] "Working..." text shimmer           OFF   ║
+ *   ║                                                  ║
+ *   ╟──────────────────────────────────────────────────╢
+ *   ║  ↑↓ move  ␣ toggle  ⏎ apply  esc cancel          ║
+ *   ╚══════════════════════════════════════════[ 1/2 ]═╝
+ *
+ * Intended to be reused by any extension that needs a simple modal toggle
+ * menu; it has no dependency on this extension's own settings shape.
+ */
+
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import { type Component, Key, matchesKey, truncateToWidth, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+
+export interface MenuItem {
+	id: string;
+	label: string;
+	value: boolean;
+}
+
+export interface MenuSection {
+	title: string;
+	items: MenuItem[];
+}
+
+export interface MenuConfig {
+	title: string;
+	sections: MenuSection[];
+	hints?: string[];
+	/**
+	 * Optional live preview renderer, shown in its own "Preview" section above
+	 * the toggle sections. Called on every render with the menu's current
+	 * (possibly toggled but not-yet-applied) values and the number of
+	 * milliseconds elapsed since the menu opened, so callers can drive
+	 * animation (e.g. a shimmer sweep or a scrolling meter). Return one string
+	 * per preview line; lines may contain ANSI styling and are truncated/
+	 * padded to fit automatically.
+	 *
+	 * When set, the menu re-renders itself on an interval (see
+	 * `previewIntervalMs`) so the preview animates even without keyboard
+	 * input.
+	 */
+	preview?: (values: Record<string, boolean>, elapsedMs: number) => string[];
+	/** Interval in ms between preview re-renders when `preview` is set. Default 50. */
+	previewIntervalMs?: number;
+}
+
+export interface MenuResult<T> {
+	applied: boolean;
+	values: T;
+}
+
+const DEFAULT_HINTS = ["\u2191\u2193 move", "\u2423 toggle", "\u23ce apply", "esc cancel"];
+const MIN_WIDTH = 36;
+const MAX_WIDTH = 76;
+
+interface FlatItem {
+	id: string;
+	label: string;
+}
+
+/** Internal Component implementing the box-drawing toggle menu. */
+export class MenuComponent implements Component {
+	private readonly theme: Theme;
+	private readonly done: (result: MenuResult<Record<string, boolean>>) => void;
+	private readonly title: string;
+	private readonly sections: MenuSection[];
+	private readonly hints: string[];
+	private readonly initialValues: Record<string, boolean>;
+	private readonly values: Record<string, boolean>;
+	private readonly flat: FlatItem[];
+	private readonly previewFn: MenuConfig["preview"];
+	private readonly previewOrigin: number | undefined;
+	private previewTimer: ReturnType<typeof setInterval> | undefined;
+	private cursor = 0;
+	private cachedWidth: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	constructor(
+		config: MenuConfig,
+		theme: Theme,
+		done: (result: MenuResult<Record<string, boolean>>) => void,
+		tui?: TUI,
+	) {
+		this.theme = theme;
+		this.done = done;
+		this.title = config.title;
+		this.sections = config.sections;
+		this.hints = config.hints ?? DEFAULT_HINTS;
+		this.values = {};
+		this.flat = [];
+		for (const section of config.sections) {
+			for (const item of section.items) {
+				this.values[item.id] = item.value;
+				this.flat.push({ id: item.id, label: item.label });
+			}
+		}
+		this.initialValues = { ...this.values };
+
+		this.previewFn = config.preview;
+		if (this.previewFn) {
+			this.previewOrigin = Date.now();
+			if (tui) {
+				const intervalMs = config.previewIntervalMs ?? 50;
+				this.previewTimer = setInterval(() => {
+					this.invalidate();
+					tui.requestRender();
+				}, intervalMs);
+			}
+		}
+	}
+
+	/** Stops the preview animation timer, if any. Called automatically when the overlay closes. */
+	dispose(): void {
+		if (this.previewTimer) {
+			clearInterval(this.previewTimer);
+			this.previewTimer = undefined;
+		}
+	}
+
+	handleInput(data: string): void {
+		if (this.flat.length === 0) return;
+
+		if (matchesKey(data, Key.up)) {
+			this.cursor = (this.cursor - 1 + this.flat.length) % this.flat.length;
+			this.invalidate();
+		} else if (matchesKey(data, Key.down)) {
+			this.cursor = (this.cursor + 1) % this.flat.length;
+			this.invalidate();
+		} else if (matchesKey(data, Key.space)) {
+			const item = this.flat[this.cursor]!;
+			this.values[item.id] = !this.values[item.id];
+			this.invalidate();
+		} else if (matchesKey(data, Key.enter)) {
+			this.done({ applied: true, values: { ...this.values } });
+		} else if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.done({ applied: false, values: { ...this.initialValues } });
+		}
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
+		const lines = this.buildLines(width);
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	private preferredWidth(previewLines: string[] | undefined): number {
+		const candidates: number[] = [MIN_WIDTH - 2, 5 + this.title.length];
+		if (previewLines && previewLines.length > 0) {
+			candidates.push(3 + "Preview".length);
+			// +1 for the leading space rendered in front of each preview line.
+			for (const line of previewLines) candidates.push(visibleWidth(line) + 1);
+		}
+		for (const section of this.sections) {
+			candidates.push(3 + section.title.length);
+			for (const item of section.items) {
+				// 8 fixed left columns + label + 2-space default gap + "OFF" (3) + 2 trailing.
+				candidates.push(8 + item.label.length + 2 + 3 + 2);
+			}
+		}
+		candidates.push(2 + this.hints.join("  ").length);
+		return 2 + Math.max(...candidates);
+	}
+
+	private buildLines(maxWidth: number): string[] {
+		// Computed once per render so a stateful `preview` callback (e.g. one
+		// driving a rolling activity meter) is never sampled twice per frame.
+		const previewLines = this.previewFn
+			? this.previewFn(this.values, this.previewOrigin !== undefined ? Date.now() - this.previewOrigin : 0)
+			: undefined;
+
+		const desired = Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, this.preferredWidth(previewLines)));
+		const boxWidth = Math.max(0, Math.min(desired, maxWidth));
+		const innerWidth = Math.max(0, boxWidth - 2);
+
+		const lines: string[] = [];
+		lines.push(this.renderTopBorder(innerWidth));
+
+		if (previewLines && previewLines.length > 0) {
+			lines.push(this.renderSectionDivider("Preview", innerWidth));
+			lines.push(this.renderBlankRow(innerWidth));
+			for (const line of previewLines) lines.push(this.renderContentRow(` ${line}`, innerWidth));
+			lines.push(this.renderBlankRow(innerWidth));
+		}
+
+		let flatIndex = 0;
+		for (const section of this.sections) {
+			lines.push(this.renderSectionDivider(section.title, innerWidth));
+			for (const item of section.items) {
+				lines.push(this.renderItemRow(item, flatIndex === this.cursor, innerWidth));
+				flatIndex++;
+			}
+			lines.push(this.renderBlankRow(innerWidth));
+		}
+
+		lines.push(this.renderSeparator(innerWidth));
+		lines.push(this.renderHintsRow(innerWidth));
+		lines.push(this.renderBottomBorder(innerWidth));
+
+		return lines.map((line) => truncateToWidth(line, boxWidth, ""));
+	}
+
+	private wrap(left: string, content: string, right: string): string {
+		const th = this.theme;
+		return th.fg("accent", left) + content + th.fg("accent", right);
+	}
+
+	private renderTopBorder(innerWidth: number): string {
+		const th = this.theme;
+		const maxTitleLen = Math.max(0, innerWidth - 5);
+		const title = this.title.length > maxTitleLen ? truncateToWidth(this.title, maxTitleLen) : this.title;
+		const fillCount = Math.max(0, innerWidth - 5 - visibleWidth(title));
+		const content = th.fg("accent", `\u2550[ ${th.bold(title)} `) + th.fg("accent", `]${"\u2550".repeat(fillCount)}`);
+		return this.wrap("\u2554", content, "\u2557");
+	}
+
+	private renderBottomBorder(innerWidth: number): string {
+		const counter = `[ ${this.cursor + 1}/${this.flat.length} ]`;
+		const fillCount = Math.max(0, innerWidth - counter.length);
+		const content = `${"\u2550".repeat(fillCount)}${counter}`;
+		return this.wrap("\u255a", this.theme.fg("accent", content), "\u255d");
+	}
+
+	private renderSectionDivider(title: string, innerWidth: number): string {
+		const th = this.theme;
+		const maxTitleLen = Math.max(0, innerWidth - 3);
+		const shownTitle = title.length > maxTitleLen ? truncateToWidth(title, maxTitleLen) : title;
+		const fillCount = Math.max(0, innerWidth - 3 - visibleWidth(shownTitle));
+		const content = th.fg("accent", `\u2500 ${shownTitle} ${"\u2500".repeat(fillCount)}`);
+		return this.wrap("\u255f", content, "\u2562");
+	}
+
+	private renderSeparator(innerWidth: number): string {
+		const content = this.theme.fg("accent", "\u2500".repeat(innerWidth));
+		return this.wrap("\u255f", content, "\u2562");
+	}
+
+	private renderBlankRow(innerWidth: number): string {
+		return this.wrap("\u2551", " ".repeat(innerWidth), "\u2551");
+	}
+
+	/** Pads/truncates an already-styled content string to exactly `innerWidth` and wraps it in border chars. */
+	private renderContentRow(content: string, innerWidth: number): string {
+		const shown = visibleWidth(content) > innerWidth ? truncateToWidth(content, innerWidth) : content;
+		const pad = Math.max(0, innerWidth - visibleWidth(shown));
+		return this.wrap("\u2551", `${shown}${" ".repeat(pad)}`, "\u2551");
+	}
+
+	private renderHintsRow(innerWidth: number): string {
+		const plain = `  ${this.hints.join("  ")}`;
+		return this.renderContentRow(this.theme.fg("dim", plain), innerWidth);
+	}
+
+	private renderItemRow(item: MenuItem, selected: boolean, innerWidth: number): string {
+		const th = this.theme;
+		const value = this.values[item.id]!;
+		const marker = selected ? "\u25b8" : " ";
+		const box = value ? "\u25a0" : " ";
+		const stateWord = value ? "ON" : "OFF";
+		const rightPlain = `${stateWord}  `;
+		const fixedLeftLen = 8; // "  " + marker(1) + " " + "[" + box(1) + "]" + " "
+		const minGap = 1;
+		const maxLabelLen = Math.max(0, innerWidth - fixedLeftLen - rightPlain.length - minGap);
+		const label = item.label.length > maxLabelLen ? truncateToWidth(item.label, maxLabelLen) : item.label;
+
+		const leftPlain = `  ${marker} [${box}] ${label}`;
+		const gap = Math.max(1, innerWidth - visibleWidth(leftPlain) - visibleWidth(rightPlain));
+
+		const markerColored = selected ? th.fg("accent", marker) : marker;
+		const boxColored = value ? th.fg("success", box) : th.fg("muted", box);
+		const labelColored = th.fg("text", label);
+		const stateColored = value ? th.fg("success", stateWord) : th.fg("muted", stateWord);
+
+		const content = `  ${markerColored} [${boxColored}] ${labelColored}${" ".repeat(gap)}${stateColored}  `;
+		return this.wrap("\u2551", content, "\u2551");
+	}
+}
+
+/**
+ * Show a modal box-drawing toggle menu and resolve once the user applies
+ * (Enter) or cancels (Escape / Ctrl+C) it.
+ *
+ * Requires TUI mode; in any other mode this resolves immediately with
+ * `applied: false` and the menu's initial values, doing nothing visible.
+ */
+export async function showMenu<T extends Record<string, boolean>>(
+	ctx: ExtensionCommandContext,
+	config: MenuConfig,
+): Promise<MenuResult<T>> {
+	const initialValues = Object.fromEntries(
+		config.sections.flatMap((section) => section.items.map((item) => [item.id, item.value])),
+	) as T;
+
+	if (ctx.mode !== "tui") {
+		return { applied: false, values: initialValues };
+	}
+
+	return ctx.ui.custom<MenuResult<T>>(
+		(tui, theme, _keybindings, done) =>
+			new MenuComponent(config, theme, done as (result: MenuResult<Record<string, boolean>>) => void, tui),
+		{ overlay: true },
+	);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@underactive/pi-topping",
+  "version": "0.1.0",
+  "description": "A Pi extension that replaces the default \"Working...\" loader with a shimmering, randomized activity word, live elapsed timer, and output-token activity meter",
+  "keywords": ["pi-package", "pi-extension"],
+  "license": "MIT",
+  "author": "Eric Sison",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/underactive/pi-topping.git"
+  },
+  "bugs": {
+    "url": "https://github.com/underactive/pi-topping/issues"
+  },
+  "homepage": "https://github.com/underactive/pi-topping#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["*.ts", "README.md", "LICENSE"],
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.80.6",
+    "@earendil-works/pi-tui": "0.80.6",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  },
+  "pi": {
+    "extensions": ["./index.ts"],
+    "video": "https://cdn.jsdelivr.net/gh/underactive/pi-topping@main/demo.mp4"
+  }
+}

package/settings.ts

@@ -0,0 +1,106 @@
+/**
+ * settings.ts
+ *
+ * Persistent, per-user settings for pi-topping, stored at
+ * `~/.pi/agent/pi-topping/settings.json`. All six toggles
+ * default to enabled so behavior is unchanged for users who never open
+ * `/topping-settings`.
+ */
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface DecoratorSettings {
+	decorations: {
+		animatedSpinner: boolean;
+		shimmer: boolean;
+		tokenActivityMonitor: boolean;
+	};
+	features: {
+		substituteDefaultMessage: boolean;
+		elapsedTime: boolean;
+		outputTokens: boolean;
+	};
+}
+
+export const DEFAULT_SETTINGS: DecoratorSettings = {
+	decorations: {
+		animatedSpinner: true,
+		shimmer: true,
+		tokenActivityMonitor: true,
+	},
+	features: {
+		substituteDefaultMessage: true,
+		elapsedTime: true,
+		outputTokens: true,
+	},
+};
+
+/** Resolve the absolute path to this extension's settings file. */
+export function settingsPath(): string {
+	return join(getAgentDir(), "pi-topping", "settings.json");
+}
+
+/**
+ * True for plain `{}`-style objects only -- excludes `null`, arrays, and
+ * primitives. Used to guard against malformed/hand-edited settings.json
+ * content (e.g. `"decorations": "oops"` or `"decorations": [1,2,3]`) before
+ * spreading it onto the defaults, so a wrong-shaped field can't leak stray
+ * properties (like numeric-string keys from spreading a string) into the
+ * merged settings object.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function cloneDefaults(): DecoratorSettings {
+	return {
+		decorations: { ...DEFAULT_SETTINGS.decorations },
+		features: { ...DEFAULT_SETTINGS.features },
+	};
+}
+
+/**
+ * Load settings from disk, deep-merging any persisted values onto the
+ * defaults. Returns a fresh clone of `DEFAULT_SETTINGS` if the file is
+ * missing or contains malformed JSON -- this function never throws.
+ */
+export function loadSettings(): DecoratorSettings {
+	const defaults = cloneDefaults();
+	let raw: string;
+	try {
+		raw = readFileSync(settingsPath(), "utf8");
+	} catch {
+		return defaults;
+	}
+
+	try {
+		const parsed = JSON.parse(raw) as Partial<DecoratorSettings> | null;
+		if (!isPlainObject(parsed)) return defaults;
+		return {
+			decorations: { ...defaults.decorations, ...(isPlainObject(parsed.decorations) ? parsed.decorations : undefined) },
+			features: { ...defaults.features, ...(isPlainObject(parsed.features) ? parsed.features : undefined) },
+		};
+	} catch {
+		return defaults;
+	}
+}
+
+/**
+ * Persist settings to disk, creating the parent directory if needed.
+ * Writes to a temp file and renames it into place so a crash mid-write
+ * (kill -9, OOM, disk full) can never leave `settings.json` truncated or
+ * corrupt -- `renameSync` is atomic on POSIX filesystems when source and
+ * destination are on the same directory/filesystem, which they always are
+ * here. A stale `.tmp` file left behind by a crash is harmless: the next
+ * successful `saveSettings()` call overwrites it, and `loadSettings()`
+ * never reads it.
+ */
+export function saveSettings(settings: DecoratorSettings): void {
+	const path = settingsPath();
+	mkdirSync(dirname(path), { recursive: true });
+	const tmpPath = `${path}.tmp`;
+	writeFileSync(tmpPath, `${JSON.stringify(settings, null, 2)}\n`);
+	renameSync(tmpPath, path);
+}

package/words.ts

@@ -0,0 +1,195 @@
+/**
+ * Activity word list for the randomized "Working..." indicator.
+ *
+ * A random word is picked on prompt and on tool execution start
+ * (see index.ts).
+ */
+
+export const WORDS: string[] = [
+	"Accomplishing",
+	"Actioning",
+	"Actualizing",
+	"Architecting",
+	"Baking",
+	"Beaming",
+	"Beboppin'",
+	"Befuddling",
+	"Billowing",
+	"Blanching",
+	"Bloviating",
+	"Boogieing",
+	"Boondoggling",
+	"Booping",
+	"Bootstrapping",
+	"Brewing",
+	"Bunning",
+	"Burrowing",
+	"Calculating",
+	"Canoodling",
+	"Caramelizing",
+	"Cascading",
+	"Catapulting",
+	"Cerebrating",
+	"Channeling",
+	"Channelling",
+	"Choreographing",
+	"Churning",
+	"Clauding",
+	"Coalescing",
+	"Cogitating",
+	"Combobulating",
+	"Composing",
+	"Computing",
+	"Concocting",
+	"Considering",
+	"Contemplating",
+	"Cooking",
+	"Crafting",
+	"Creating",
+	"Crunching",
+	"Crystallizing",
+	"Cultivating",
+	"Deciphering",
+	"Deliberating",
+	"Determining",
+	"Dilly-dallying",
+	"Discombobulating",
+	"Doing",
+	"Doodling",
+	"Drizzling",
+	"Ebbing",
+	"Effecting",
+	"Elucidating",
+	"Embellishing",
+	"Enchanting",
+	"Envisioning",
+	"Fermenting",
+	"Fiddle-faddling",
+	"Finagling",
+	"Flambéing",
+	"Flibbertigibbeting",
+	"Flowing",
+	"Flummoxing",
+	"Fluttering",
+	"Forging",
+	"Forming",
+	"Frolicking",
+	"Frosting",
+	"Gallivanting",
+	"Galloping",
+	"Garnishing",
+	"Generating",
+	"Gesticulating",
+	"Germinating",
+	"Gitifying",
+	"Grooving",
+	"Gusting",
+	"Harmonizing",
+	"Hashing",
+	"Hatching",
+	"Herding",
+	"Honking",
+	"Hullaballooing",
+	"Hyperspacing",
+	"Ideating",
+	"Imagining",
+	"Improvising",
+	"Incubating",
+	"Inferring",
+	"Infusing",
+	"Ionizing",
+	"Jitterbugging",
+	"Julienning",
+	"Kneading",
+	"Leavening",
+	"Levitating",
+	"Lollygagging",
+	"Manifesting",
+	"Marinating",
+	"Meandering",
+	"Metamorphosing",
+	"Misting",
+	"Moonwalking",
+	"Moseying",
+	"Mulling",
+	"Mustering",
+	"Musing",
+	"Nebulizing",
+	"Nesting",
+	"Newspapering",
+	"Noodling",
+	"Nucleating",
+	"Orbiting",
+	"Orchestrating",
+	"Osmosing",
+	"Perambulating",
+	"Percolating",
+	"Perusing",
+	"Philosophising",
+	"Photosynthesizing",
+	"Pollinating",
+	"Pondering",
+	"Pontificating",
+	"Pouncing",
+	"Precipitating",
+	"Prestidigitating",
+	"Processing",
+	"Proofing",
+	"Propagating",
+	"Puttering",
+	"Puzzling",
+	"Quantumizing",
+	"Razzle-dazzling",
+	"Razzmatazzing",
+	"Recombobulating",
+	"Reticulating",
+	"Roosting",
+	"Ruminating",
+	"Sautéing",
+	"Scampering",
+	"Schlepping",
+	"Scurrying",
+	"Seasoning",
+	"Shenaniganing",
+	"Shimmying",
+	"Simmering",
+	"Skedaddling",
+	"Sketching",
+	"Slithering",
+	"Smooshing",
+	"Sock-hopping",
+	"Spelunking",
+	"Spinning",
+	"Sprouting",
+	"Stewing",
+	"Sublimating",
+	"Swirling",
+	"Swooping",
+	"Symbioting",
+	"Synthesizing",
+	"Tempering",
+	"Thinking",
+	"Thundering",
+	"Tinkering",
+	"Tomfoolering",
+	"Topsy-turvying",
+	"Transfiguring",
+	"Transmuting",
+	"Twisting",
+	"Undulating",
+	"Unfurling",
+	"Unravelling",
+	"Vibing",
+	"Waddling",
+	"Wandering",
+	"Warping",
+	"Whatchamacalliting",
+	"Whirlpooling",
+	"Whirring",
+	"Whisking",
+	"Wibbling",
+	"Working",
+	"Wrangling",
+	"Zesting",
+	"Zigzagging",
+];