@underactive/pi-topping 0.1.1 → 0.2.1

package/src/format.ts

@@ -0,0 +1,149 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+
+/** 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: 999_500, divisor: 1_000, decimals: 0, suffix: "k" },
+		{ threshold: 10_000_000, divisor: 1_000_000, decimals: 1, suffix: "M" },
+		{ threshold: 1_000_000_000, divisor: 1_000_000, decimals: 0, suffix: "M" },
+		{ threshold: 1e15, divisor: 1_000_000_000, decimals: 1, suffix: "B" },
+	];
+	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 `${(count / 1_000_000_000).toFixed(1)}B`;
+}
+
+/** Format elapsed milliseconds as a compact human-readable duration, skipping leading zero units. */
+export function formatElapsed(ms: number): string {
+	let totalSeconds = Math.max(0, Math.floor(ms / 1000));
+	const parts: string[] = [];
+
+	const days = Math.floor(totalSeconds / 86400);
+	totalSeconds -= days * 86400;
+	const hours = Math.floor(totalSeconds / 3600);
+	totalSeconds -= hours * 3600;
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+
+	if (days > 0) parts.push(`${days}d`);
+	if (hours > 0) parts.push(`${hours}h`);
+	if (minutes > 0) parts.push(`${minutes}m`);
+	parts.push(`${seconds}s`);
+
+	return parts.join(" ");
+}
+
+/** Codex-style light-sweep shimmer using the active Pi theme. */
+export function isFullyDefaultAppearance(features: {
+	substituteDefaultMessage: boolean;
+	elapsedTime: boolean;
+	outputTokens: boolean;
+}, decorations: { shimmer: boolean; tokenActivityMonitor: boolean }): boolean {
+	return !features.substituteDefaultMessage && !decorations.shimmer && !decorations.tokenActivityMonitor && !features.elapsedTime && !features.outputTokens;
+}
+
+/** Assemble the styled word, meter, and optional detail fields. */
+export function buildWorkingMessage(
+	theme: Pick<Theme, "fg">,
+	word: string,
+	frame: string,
+	elapsed: string,
+	tokens: string,
+	features: { elapsedTime: boolean; outputTokens: boolean },
+): string {
+	const parts = [word, frame].filter(Boolean);
+	const details = [features.elapsedTime ? elapsed : "", features.outputTokens ? `↓ ${tokens} tokens` : ""].filter(Boolean);
+	if (details.length) parts.push(theme.fg("dim", `(${details.join(" · ")})`));
+	return parts.join(" ");
+}
+
+export function shimmerString(
+	text: string,
+	elapsedMs: number,
+	theme: Pick<Theme, "getFgAnsi">,
+): string {
+	const chars = [...text];
+	if (chars.length === 0) return "";
+	const SHIMMER_SWEEP_S = 2.0;
+	const SHIMMER_BAND_HALF = 5.0;
+	const SHIMMER_PADDING = 10;
+	const SHIMMER_BASE = ansiToRgb(theme.getFgAnsi("dim"));
+	const SHIMMER_HIGHLIGHT = ansiToRgb(theme.getFgAnsi("text"));
+	const period = chars.length + SHIMMER_PADDING * 2;
+	const elapsedS = elapsedMs / 1000;
+	const pos = ((elapsedS % SHIMMER_SWEEP_S) / SHIMMER_SWEEP_S) * period;
+
+	return chars
+		.map((ch, i) => {
+			const dist = Math.abs((i + SHIMMER_PADDING) - pos);
+			const t = dist <= SHIMMER_BAND_HALF
+				? 0.5 * (1 + Math.cos(Math.PI * dist / SHIMMER_BAND_HALF))
+				: 0;
+			const alpha = t * 0.9;
+			const r = Math.round(SHIMMER_HIGHLIGHT[0] * alpha + SHIMMER_BASE[0] * (1 - alpha));
+			const g = Math.round(SHIMMER_HIGHLIGHT[1] * alpha + SHIMMER_BASE[1] * (1 - alpha));
+			const b = Math.round(SHIMMER_HIGHLIGHT[2] * alpha + SHIMMER_BASE[2] * (1 - alpha));
+			const bold = t > 0.2 ? "\x1b[1m" : "";
+			return `${bold}\x1b[38;2;${r};${g};${b}m${ch}\x1b[22m`;
+		})
+		.join("") + "\x1b[0m";
+}
+
+function ansiToRgb(ansi: string): [number, number, number] {
+	const match = ansi.match(/^\x1b\[38;2;(\d+);(\d+);(\d+)m$/);
+	if (!match) throw new Error(`Shimmer requires truecolor theme colors, received ${JSON.stringify(ansi)}`);
+	return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * 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
+	);
+}

package/{menu.ts → src/menu.ts}

@@ -136,23 +136,45 @@ export class MenuComponent implements Component {
 	}
 
 	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 } });
+		if (this.flat.length === 0) {
+			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 } });
+			}
+			return;
+		}
+
+		// Map input to a normalized key name.
+		let mappedKey: string | undefined;
+		for (const k of [Key.up, Key.down, Key.space, Key.enter, Key.escape]) {
+			if (matchesKey(data, k)) {
+				mappedKey = k;
+				break;
+			}
 		}
+		if (!mappedKey && matchesKey(data, Key.ctrl("c"))) mappedKey = Key.escape;
+
+		const keyActions: Record<string, () => void> = {
+			[Key.up]: () => {
+				this.cursor = (this.cursor - 1 + this.flat.length) % this.flat.length;
+				this.invalidate();
+			},
+			[Key.down]: () => {
+				this.cursor = (this.cursor + 1) % this.flat.length;
+				this.invalidate();
+			},
+			[Key.space]: () => {
+				const item = this.flat[this.cursor]!;
+				this.values[item.id] = !this.values[item.id];
+				this.invalidate();
+			},
+			[Key.enter]: () => this.done({ applied: true, values: { ...this.values } }),
+			[Key.escape]: () => this.done({ applied: false, values: { ...this.initialValues } }),
+		};
+
+		const handler = mappedKey ? keyActions[mappedKey] : undefined;
+		if (handler) handler();
 	}
 
 	invalidate(): void {
@@ -186,42 +208,33 @@ export class MenuComponent implements Component {
 		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));
+	private samplePreview(): string[] | undefined {
+		return this.previewFn ? this.previewFn(this.values, this.previewOrigin !== undefined ? Date.now() - this.previewOrigin : 0) : undefined;
+	}
 
-		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));
-		}
+	private buildPreviewBlock(previewLines: string[] | undefined, innerWidth: number): string[] {
+		if (!previewLines?.length) return [];
+		return [this.renderSectionDivider("Preview", innerWidth), this.renderBlankRow(innerWidth), ...previewLines.map(line => this.renderContentRow(` ${line}`, innerWidth)), this.renderBlankRow(innerWidth)];
+	}
 
+	private buildToggleSections(innerWidth: number): string[] {
 		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));
-		}
+		return this.sections.flatMap(section => [
+			this.renderSectionDivider(section.title, innerWidth),
+			...section.items.map(item => this.renderItemRow(item, flatIndex++ === this.cursor, innerWidth)),
+			this.renderBlankRow(innerWidth),
+		]);
+	}
 
-		lines.push(this.renderSeparator(innerWidth));
-		lines.push(this.renderHintsRow(innerWidth));
-		lines.push(this.renderBottomBorder(innerWidth));
+	private buildFooter(innerWidth: number): string[] {
+		return [this.renderSeparator(innerWidth), this.renderHintsRow(innerWidth), this.renderBottomBorder(innerWidth)];
+	}
 
-		return lines.map((line) => truncateToWidth(line, boxWidth, ""));
+	private buildLines(maxWidth: number): string[] {
+		const previewLines = this.samplePreview();
+		const boxWidth = Math.max(0, Math.min(Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, this.preferredWidth(previewLines))), maxWidth));
+		const innerWidth = Math.max(0, boxWidth - 2);
+		return [this.renderTopBorder(innerWidth), ...this.buildPreviewBlock(previewLines, innerWidth), ...this.buildToggleSections(innerWidth), ...this.buildFooter(innerWidth)].map(line => truncateToWidth(line, boxWidth, ""));
 	}
 
 	private wrap(left: string, content: string, right: string): string {
@@ -229,13 +242,34 @@ export class MenuComponent implements Component {
 		return th.fg("accent", left) + content + th.fg("accent", right);
 	}
 
-	private renderTopBorder(innerWidth: number): string {
+	/** Render a filled horizontal line with optional title. */
+	private renderFilledLine(
+		left: string,
+		right: string,
+		fillChar: string,
+		innerWidth: number,
+		title?: string,
+		titlePrefix?: string,
+		titleSuffix?: string,
+		boldTitle?: boolean,
+	): 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");
+		if (!title) {
+			const content = th.fg("accent", fillChar.repeat(innerWidth));
+			return this.wrap(left, content, right);
+		}
+		const prefix = titlePrefix ?? "";
+		const suffix = titleSuffix ?? "";
+		const maxTitleLen = Math.max(0, innerWidth - prefix.length - suffix.length);
+		const shownTitle = title.length > maxTitleLen ? truncateToWidth(title, maxTitleLen) : title;
+		const styledTitle = boldTitle ? th.bold(shownTitle) : shownTitle;
+		const fillCount = Math.max(0, innerWidth - visibleWidth(prefix + shownTitle + suffix));
+		const content = th.fg("accent", `${prefix}${styledTitle}${suffix}${fillChar.repeat(fillCount)}`);
+		return this.wrap(left, content, right);
+	}
+
+	private renderTopBorder(innerWidth: number): string {
+		return this.renderFilledLine("\u2554", "\u2557", "\u2550", innerWidth, this.title, "\u2550[ ", " ]", true);
 	}
 
 	private renderBottomBorder(innerWidth: number): string {
@@ -246,17 +280,11 @@ export class MenuComponent implements Component {
 	}
 
 	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");
+		return this.renderFilledLine("\u255f", "\u2562", "\u2500", innerWidth, title, "\u2500 ", " \u2500");
 	}
 
 	private renderSeparator(innerWidth: number): string {
-		const content = this.theme.fg("accent", "\u2500".repeat(innerWidth));
-		return this.wrap("\u255f", content, "\u2562");
+		return this.renderFilledLine("\u255f", "\u2562", "\u2500", innerWidth);
 	}
 
 	private renderBlankRow(innerWidth: number): string {

package/src/preview.ts

@@ -0,0 +1,47 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ActivityMeter, rateToLevel } from "./activity-meter.ts";
+import { buildWorkingMessage, formatElapsed, formatTokens, isFullyDefaultAppearance, shimmerString } from "./format.ts";
+import { pickRandomWord } from "./words.ts";
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const METER_INTERVAL_MS = 100;
+const METER_PERIOD_MS = 2400;
+const METER_PEAK_RATE = 46;
+const TOKEN_RATE_PER_SEC = 28;
+const DEFAULT_WORKING_WORD = "Working…";
+
+function meterRate(elapsedMs: number): number {
+	return ((1 - Math.cos((2 * Math.PI * elapsedMs) / METER_PERIOD_MS)) / 2) * METER_PEAK_RATE;
+}
+
+/** Stateful, per-menu live preview renderer. */
+export class PreviewRenderer {
+	readonly #word = pickRandomWord();
+	readonly #meter = new ActivityMeter();
+	#lastMeterUpdate = 0;
+	readonly #ctx: ExtensionContext;
+
+	constructor(ctx: ExtensionContext) { this.#ctx = ctx; }
+
+	render(values: Record<string, boolean>, elapsedMs: number): string[] {
+		this.#meter.setDirection(values.meterDirection_rtl ? "rtl" : "ltr");
+		if (elapsedMs - this.#lastMeterUpdate >= METER_INTERVAL_MS) {
+			this.#meter.push(rateToLevel(meterRate(elapsedMs)));
+			this.#lastMeterUpdate = elapsedMs;
+		}
+		const features = {
+			substituteDefaultMessage: values.substituteDefaultMessage ?? true,
+			elapsedTime: values.elapsedTime ?? true,
+			outputTokens: values.outputTokens ?? true,
+		};
+		const decorations = { shimmer: values.shimmer ?? true, tokenActivityMonitor: values.tokenActivityMonitor ?? true };
+		const spinner = values.animatedSpinner
+			? this.#ctx.ui.theme.fg("accent", SPINNER_FRAMES[Math.floor(elapsedMs / 80) % SPINNER_FRAMES.length]!)
+			: "";
+		if (isFullyDefaultAppearance(features, decorations)) return [[spinner, this.#ctx.ui.theme.fg("dim", DEFAULT_WORKING_WORD)].filter(Boolean).join(" ")];
+		const word = features.substituteDefaultMessage ? this.#word : DEFAULT_WORKING_WORD;
+		const styledWord = decorations.shimmer ? shimmerString(word, elapsedMs, this.#ctx.ui.theme) : this.#ctx.ui.theme.fg("text", word);
+		const meter = decorations.tokenActivityMonitor ? this.#meter.render((level, char) => ActivityMeter.colorizeCell(level, char, this.#ctx.ui.theme)) : "";
+		return [[spinner, buildWorkingMessage(this.#ctx.ui.theme, styledWord, meter, formatElapsed(elapsedMs), formatTokens(Math.max(0, Math.floor(elapsedMs / 1000 * TOKEN_RATE_PER_SEC))), features)].filter(Boolean).join(" ")];
+	}
+}

package/src/session.ts

@@ -0,0 +1,43 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { ActivityMeter, rateToLevel, TokRateTracker } from "./activity-meter.ts";
+import { buildWorkingMessage, formatElapsed, formatTokens, isFullyDefaultAppearance, shimmerString, StreamingWordCounter } from "./format.ts";
+import { showMenu } from "./menu.ts";
+import { applyMenuResult, buildMenuSections, loadSettings, saveSettings } from "./settings.ts";
+import { PreviewRenderer } from "./preview.ts";
+import { pickRandomWord, pickRawWord } from "./words.ts";
+
+const DONE_ENTRY_TYPE = "pi-topping-done";
+const DEFAULT_WORKING_WORD = "Working…";
+const SHIMMER_INTERVAL = 50;
+const METER_INTERVAL_MS = 100;
+export interface DoneEntryData { word: string; elapsedMs: number; }
+export interface SessionState { startTime: number; currentWord: string; confirmTokens: number; liveTokens: number; shimmerOrigin: number; activityMeter: ActivityMeter; rateTracker: TokRateTracker; lastActivityMeterUpdate: number; timer: ReturnType<typeof setInterval> | null; busy: boolean; }
+export function makeFreshState(): SessionState { return { startTime: 0, currentWord: "", confirmTokens: 0, liveTokens: 0, shimmerOrigin: 0, activityMeter: new ActivityMeter(), rateTracker: new TokRateTracker(), lastActivityMeterUpdate: 0, timer: null, busy: false }; }
+
+/** Owns mutable extension state and Pi lifecycle registrations. */
+export class SessionManager {
+	#counter = new StreamingWordCounter(); #state = makeFreshState(); #settings = loadSettings(); #currentCtx: ExtensionContext | null = null;
+	readonly #pi: ExtensionAPI;
+	constructor(pi: ExtensionAPI) { this.#pi = pi; }
+	install(): void {
+		this.#pi.on("session_start", async (_e, ctx) => { this.stopTimer(); this.#counter.reset(); this.#currentCtx = null; this.#state = makeFreshState(); this.#settings = loadSettings(); this.#state.activityMeter.setDirection(this.#settings.decorations.meterDirection); this.#currentCtx = ctx; if (this.usable(ctx)) this.applyIndicator(ctx); });
+		this.#pi.on("input", async (_e, ctx) => { this.#currentCtx = ctx; if (this.usable(ctx)) this.resetTurn(Date.now()); });
+		this.#pi.on("agent_start", async (_e, ctx) => { this.#currentCtx = ctx; if (!this.usable(ctx)) return; if (!this.#state.startTime) this.resetTurn(Date.now()); this.#state.busy = true; this.startTimer(); this.tick(); });
+		this.#pi.on("message_start", async (e, ctx) => { this.#currentCtx = ctx; if (this.usable(ctx) && e.message.role === "assistant") { this.#state.liveTokens = 0; this.#counter.reset(); } });
+		this.#pi.on("message_update", async (e, ctx) => { this.#currentCtx = ctx; const a = e.assistantMessageEvent; if (this.usable(ctx) && a && (a.type === "text_delta" || a.type === "thinking_delta")) this.#state.liveTokens += this.#counter.count(a.delta, a.type); });
+		this.#pi.on("message_end", async (e, ctx) => { this.#currentCtx = ctx; if (!this.usable(ctx) || e.message.role !== "assistant") return; this.#state.confirmTokens += e.message.usage?.output ?? this.#state.liveTokens; this.#state.liveTokens = 0; this.#counter.reset(); });
+		this.#pi.on("tool_execution_start", async (_e, ctx) => { this.#currentCtx = ctx; if (this.usable(ctx)) { this.#state.currentWord = pickRandomWord(); this.#state.shimmerOrigin = Date.now(); } });
+		this.#pi.on("agent_settled", async (_e, ctx) => { this.#currentCtx = ctx; if (!this.usable(ctx)) return; const hadPrompt = !!this.#state.startTime; const elapsedMs = hadPrompt ? Date.now() - this.#state.startTime : 0; this.#state.busy = false; this.#state.startTime = 0; this.#counter.reset(); this.stopTimer(); ctx.ui.setWorkingMessage(); this.applyIndicator(ctx); this.#state.activityMeter.reset(); this.#state.rateTracker.reset(); this.#state.lastActivityMeterUpdate = 0; if (this.#settings.features.doneMarker && hadPrompt) this.#pi.appendEntry<DoneEntryData>(DONE_ENTRY_TYPE, { word: pickRawWord().past_tense, elapsedMs }); this.#currentCtx = null; });
+		this.#pi.on("session_shutdown", async () => this.stopTimer());
+		this.#pi.registerEntryRenderer<DoneEntryData>(DONE_ENTRY_TYPE, (entry, _o, theme) => entry.data ? new Text(`${theme.fg("text", "π")}${theme.fg("dim", ` ${entry.data.word} for ${formatElapsed(entry.data.elapsedMs)}`)}`) : undefined);
+		this.#pi.registerCommand("topping-settings", { description: "Configure pi-topping's spinner, shimmer, activity meter, and message details.", handler: async (_a, ctx) => this.showSettings(ctx) });
+	}
+	private usable(ctx: ExtensionContext): boolean { return !!ctx.hasUI && ctx.mode !== "print"; }
+	private applyIndicator(ctx: ExtensionContext): void { ctx.ui.setWorkingIndicator(this.#settings.decorations.animatedSpinner ? undefined : { frames: [] }); }
+	private stopTimer(): void { if (this.#state.timer) { clearInterval(this.#state.timer); this.#state.timer = null; } }
+	private startTimer(): void { if (!this.#state.timer) this.#state.timer = setInterval(() => this.tick(), SHIMMER_INTERVAL); }
+	private resetTurn(now: number): void { const s = this.#state; s.startTime = now; s.shimmerOrigin = now; s.currentWord = pickRandomWord(); s.confirmTokens = 0; s.liveTokens = 0; s.activityMeter.reset(); s.rateTracker.reset(); s.lastActivityMeterUpdate = 0; this.#counter.reset(); }
+	private tick(): void { const ctx = this.#currentCtx, s = this.#state; if (!s.busy || !ctx) return; const now = Date.now(), total = s.confirmTokens + s.liveTokens; if (now - s.lastActivityMeterUpdate >= METER_INTERVAL_MS) { s.activityMeter.push(rateToLevel(s.rateTracker.sample(total, now))); s.lastActivityMeterUpdate = now; } const f = this.#settings.features, d = this.#settings.decorations; if (isFullyDefaultAppearance(f, d)) return ctx.ui.setWorkingMessage(); const word = f.substituteDefaultMessage ? s.currentWord : DEFAULT_WORKING_WORD; const styled = d.shimmer ? shimmerString(word, now - s.shimmerOrigin, ctx.ui.theme) : ctx.ui.theme.fg("text", word); const meter = d.tokenActivityMonitor ? s.activityMeter.render((l, c) => ActivityMeter.colorizeCell(l, c, ctx.ui.theme)) : ""; ctx.ui.setWorkingMessage(buildWorkingMessage(ctx.ui.theme, styled, meter, formatElapsed(now - s.startTime), formatTokens(total), f)); }
+	private async showSettings(ctx: ExtensionCommandContext): Promise<void> { if (ctx.mode !== "tui") { ctx.ui.notify("/topping-settings requires TUI mode", "error"); return; } const before = this.#settings.decorations.animatedSpinner; const preview = new PreviewRenderer(ctx); const result = await showMenu<Record<string, boolean>>(ctx, { title: "Pi Topping: Settings", sections: buildMenuSections(this.#settings), hints: ["↑↓ move", "␣ toggle", "⏎ apply", "esc cancel"], preview: preview.render.bind(preview) }); if (!result.applied) return; this.#settings = applyMenuResult(this.#settings, result.values); saveSettings(this.#settings); if (before !== this.#settings.decorations.animatedSpinner) this.applyIndicator(ctx); this.#state.activityMeter.setDirection(this.#settings.decorations.meterDirection); ctx.ui.notify("Pi Topping settings saved", "info"); }
+}

package/src/settings.ts

@@ -0,0 +1,215 @@
+/**
+ * settings.ts
+ *
+ * Persistent, per-user settings for pi-topping, stored at
+ * `~/.pi/agent/pi-topping/settings.json`. All seven 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";
+import type { MenuSection } from "./menu.ts";
+
+export interface DecoratorSettings {
+	decorations: {
+		animatedSpinner: boolean;
+		shimmer: boolean;
+		tokenActivityMonitor: boolean;
+		meterDirection: "ltr" | "rtl";
+	};
+	features: {
+		substituteDefaultMessage: boolean;
+		elapsedTime: boolean;
+		outputTokens: boolean;
+		doneMarker: boolean;
+	};
+}
+
+export const DEFAULT_SETTINGS: DecoratorSettings = {
+	decorations: {
+		animatedSpinner: true,
+		shimmer: true,
+		tokenActivityMonitor: true,
+		meterDirection: "ltr",
+	},
+	features: {
+		substituteDefaultMessage: true,
+		elapsedTime: true,
+		outputTokens: true,
+		doneMarker: 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);
+}
+
+/**
+ * Merge persisted JSON values onto a defaults object, accepting both boolean
+ * fields and a known enum-typed string field (`meterDirection`). Any unknown
+ * or wrong-typed keys are silently ignored so hand-edited settings.json can't
+ * corrupt the resulting shape.
+ */
+function mergeDecorations(
+	defaults: DecoratorSettings["decorations"],
+	parsed: unknown,
+): DecoratorSettings["decorations"] {
+	const merged = { ...defaults };
+	if (!isPlainObject(parsed)) return merged;
+	for (const [key, value] of Object.entries(parsed)) {
+		if (key === "meterDirection") {
+			if (value === "ltr" || value === "rtl") {
+				merged.meterDirection = value;
+			}
+		} else if (typeof value === "boolean" && key in merged) {
+			(merged as Record<string, unknown>)[key] = value;
+		}
+	}
+	return merged;
+}
+
+function mergeBooleanGroup<T extends Record<string, boolean>>(defaults: T, parsed: unknown): T {
+	const merged = { ...defaults } as T;
+	if (!isPlainObject(parsed)) return merged;
+	for (const [key, value] of Object.entries(parsed)) {
+		if (typeof value === "boolean" && key in merged) {
+			merged[key as keyof T] = value as T[keyof T];
+		}
+	}
+	return merged;
+}
+
+interface DecorationBooleanMenuEntry {
+	id: "animatedSpinner" | "shimmer" | "tokenActivityMonitor";
+	label: string;
+	section: "Decorations";
+	group: "decorations";
+}
+
+interface FeatureBooleanMenuEntry {
+	id: "substituteDefaultMessage" | "elapsedTime" | "outputTokens" | "doneMarker";
+	label: string;
+	section: "Options";
+	group: "features";
+}
+
+interface DirectionMenuEntry {
+	id: "meterDirection_rtl";
+	label: string;
+	section: "Options";
+	group: "decorations";
+}
+
+type MenuEntry = DecorationBooleanMenuEntry | FeatureBooleanMenuEntry | DirectionMenuEntry;
+
+/** The ordered settings-menu schema and its explicit settings conversions. */
+export const MENU_ENTRIES: readonly MenuEntry[] = [
+	{ id: "animatedSpinner", label: "Animated spinner", section: "Decorations", group: "decorations" },
+	{ id: "shimmer", label: "“Working...” text shimmer", section: "Decorations", group: "decorations" },
+	{ id: "tokenActivityMonitor", label: "Token activity monitor", section: "Decorations", group: "decorations" },
+	{ id: "substituteDefaultMessage", label: "Substitute Pi's “Working…” message", section: "Options", group: "features" },
+	{ id: "elapsedTime", label: "Elapsed time since prompt", section: "Options", group: "features" },
+	{ id: "outputTokens", label: "Show output tokens", section: "Options", group: "features" },
+	{ id: "doneMarker", label: "Show completion marker", section: "Options", group: "features" },
+	{ id: "meterDirection_rtl", label: "Scrolling: Right → Left", section: "Options", group: "decorations" },
+];
+
+/** Build the ordered toggle-menu sections from persisted settings. */
+export function buildMenuSections(settings: DecoratorSettings): MenuSection[] {
+	return ["Decorations", "Options"].map((title) => ({
+		title,
+		items: MENU_ENTRIES.filter((entry) => entry.section === title).map((entry) => ({
+			id: entry.id,
+			label: entry.label,
+			value:
+				entry.id === "meterDirection_rtl"
+					? settings.decorations.meterDirection === "rtl"
+					: entry.group === "decorations"
+						? settings.decorations[entry.id]
+						: settings.features[entry.id],
+		})),
+	}));
+}
+
+/** Clone settings and apply recognized menu values, including direction conversion. */
+export function applyMenuResult(
+	settings: DecoratorSettings,
+	values: Record<string, boolean>,
+): DecoratorSettings {
+	const next = structuredClone(settings);
+	for (const entry of MENU_ENTRIES) {
+		const value = values[entry.id];
+		if (value === undefined) continue;
+		if (entry.id === "meterDirection_rtl") {
+			next.decorations.meterDirection = value ? "rtl" : "ltr";
+		} else if (entry.group === "decorations") {
+			next.decorations[entry.id] = value;
+		} else {
+			next.features[entry.id] = value;
+		}
+	}
+	return next;
+}
+
+function cloneDefaults(): DecoratorSettings {
+	return structuredClone(DEFAULT_SETTINGS);
+}
+
+/**
+ * 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: mergeDecorations(defaults.decorations, parsed.decorations),
+			features: mergeBooleanGroup(defaults.features, parsed.features),
+		};
+	} 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);
+}