@underactive/pi-topping 0.12.0 → 0.13.0

package/README.md

@@ -128,7 +128,7 @@ While a non-default style is active, each prompt also carries a one-line hidden
 
 Output styles also apply in print and RPC modes. Set `"outputStyle": "explanatory"` (or `"simplified"`) in `~/.pi/agent/pi-topping/settings.json`; if you edit the file while an interactive session is running, use `/reload` to load the change. Switching styles changes one system-prompt section. Pi appends that change to the conversation, so providers that support mid-conversation prompt updates keep their cached prefix; other providers may re-read the full prompt once.
 
-The Explanatory prompt is copied word for word from Claude Code's output styles, with two Pi clarifications: a lead-in that frames the instructions for Pi, and an exception allowing Insight blocks despite Pi's conciseness rule. The Simplified Technical English prompt adapts the ASD-STE100 writing rules but does not include the STE dictionary of approved words. A more specific instruction from you, your project instructions, a skill, or the file being edited takes precedence over it. When migrating from `pi-topping-insights`, its saved style is imported until you next save `/topping-settings`. Remove the old extension to avoid duplicate hidden reminders. `/insights` is gone; use `/topping-settings`.
+The Explanatory prompt is copied word for word from Claude Code's output styles, with two Pi clarifications: a lead-in that frames the instructions for Pi, and an exception allowing Insight blocks despite Pi's conciseness rule. The Simplified Technical English prompt adapts the ASD-STE100 writing rules but does not include the STE dictionary of approved words. A more specific instruction from you, your project instructions, a skill, or the file being edited takes precedence over it. If `pi-topping-insights` is still installed, remove it to avoid duplicate hidden reminders; its saved style is no longer read. `/insights` is gone; use `/topping-settings`.
 
 ### Word packs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@underactive/pi-topping",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "A Pi extension that adds quality of life improvements to Pi's UX: a high-vis user prompt, a shimmering working loader with token activity meter and elapsed timer, an end-of-turn completion marker, and selectable output styles",
   "keywords": ["pi-package", "pi-extension"],
   "license": "MIT",
@@ -22,7 +22,7 @@
   },
   "files": ["index.ts", "src/**/*.ts", "wordpacks/*.json", "README.md", "LICENSE"],
   "scripts": {
-    "test": "node --test tests/*.test.ts",
+    "test": "node -C compiled --test tests/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
@@ -30,13 +30,16 @@
     "@earendil-works/pi-tui": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "^24.0.0",
     "typescript": "^5.9.3"
   },
   "pi": {
     "extensions": ["./index.ts"],
     "image": "https://raw.githubusercontent.com/underactive/pi-topping/main/media/working.png"
+  },
+  "dependencies": {
+    "@underactive/pi-topping-primitives": "^0.10.0"
   }
 }

package/src/format.ts

@@ -1,33 +1,19 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import type { ThinkingLevelColor } from "./settings.ts";
 
-/** Pi's default working-indicator frames (same braille spinner as pi-tui's Loader). */
-export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
-/** Milliseconds per spinner frame, matching pi-tui's Loader cadence. */
-export const SPINNER_FRAME_MS = 80;
+/**
+ * Pi's default working-indicator frames (same braille spinner as pi-tui's Loader) and the
+ * milliseconds per frame, matching its cadence.
+ */
+export { SPINNER_FRAME_MS, SPINNER_FRAMES } from "@underactive/pi-topping-primitives/glyphs";
 
 /** Default "Working" text shown when text randomization/substitution is off. */
 export const DEFAULT_WORKING_WORD = "Working";
 
-export type ThinkingLevel = Parameters<Theme["getThinkingBorderColor"]>[0];
-
-export const THINKING_LEVEL_VALUES = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
-
-export function isThinkingLevel(value: unknown): value is ThinkingLevel {
-	return typeof value === "string" && THINKING_LEVEL_VALUES.some(level => level === value);
-}
-
-/** Build a colorizer for a configured color, including Pi's active thinking-level color. */
-export function getThinkingLevelColorizer(
-	theme: Pick<Theme, "fg" | "getThinkingBorderColor">,
-	color: ThinkingLevelColor,
-	thinkingLevel: ThinkingLevel | undefined,
-): (text: string) => string {
-	return color === "thinking-level"
-		? theme.getThinkingBorderColor(thinkingLevel ?? "off")
-		: (text: string) => theme.fg(color, text);
-}
+export {
+	isThinkingLevel,
+	THINKING_LEVELS as THINKING_LEVEL_VALUES,
+	type ThinkingLevel,
+} from "@underactive/pi-topping-primitives/models";
 
 /** Milliseconds between activity meter sample pushes. */
 export const METER_INTERVAL_MS = 100;
@@ -85,83 +71,15 @@ export function formatTokenRate(rate: number): string {
 	return rounded === 0 ? "" : `${rounded.toString().padStart(TOKEN_RATE_DIGITS)} tps`;
 }
 
-/**
- * Wrap text in ANSI dim (SGR 2 / reset 22).
- *
- * theme.fg("dim", ...) sets a gray color instead of the ANSI dim attribute, so it
- * would overwrite an already-applied accent color rather than darkening it; the raw
- * SGR codes are needed to dim on top of an existing color.
- */
-export function dimAttribute(text: string): string {
-	return `\x1b[2m${text}\x1b[22m`;
-}
-
-/** Number of discrete, eased shades used by the token-rate and response-model fades. */
-export const TOKEN_RATE_FADE_SHADE_COUNT = 5;
-
 /** Milliseconds a settled response model remains fully visible before fading. */
 export const RESPONSE_MODEL_HOLD_MS = 3_000;
 
 /** Milliseconds over which a settled response model fades through the theme shades. */
 export const RESPONSE_MODEL_FADE_MS = 500;
 
-/** Milliseconds over which a newly shown response model slides out of the working loader. */
-export const RESPONSE_MODEL_SLIDE_MS = 300;
-
 /** Milliseconds between working-loader repaints while the response model slides out. */
 export const RESPONSE_MODEL_SLIDE_FRAME_MS = 30;
 
-/**
- * The part of a sliding response model visible `elapsedMs` after it appeared. It emerges
- * tail first from behind the separator before it, as pi-topping-statusline slides an
- * embedded status out, and shows whole once RESPONSE_MODEL_SLIDE_MS has passed.
- */
-export function slideOutTail(text: string, elapsedMs: number): string {
-	if (elapsedMs >= RESPONSE_MODEL_SLIDE_MS) return text;
-	const chars = [...text];
-	const progress = Math.max(0, elapsedMs) / RESPONSE_MODEL_SLIDE_MS;
-	const shown = Math.round(chars.length * 0.5 * (1 - Math.cos(Math.PI * progress)));
-	return chars.slice(chars.length - shown).join("");
-}
-
-/** Render one fade shade by blending the colorizer's color toward the active theme's dim color. */
-export function fadeThemeColorString(
-	text: string,
-	shade: number,
-	theme: Pick<Theme, "getFgAnsi">,
-	colorizer: (text: string) => string,
-): string {
-	if (!text) return "";
-	const source = ansiToRgb(colorizer("x"));
-	const dim = ansiToRgb(theme.getFgAnsi("dim"));
-	if (!source || !dim) return colorizer(text);
-	const clampedShade = Math.max(0, Math.min(TOKEN_RATE_FADE_SHADE_COUNT - 1, Math.floor(shade)));
-	const progress = (clampedShade + 1) / TOKEN_RATE_FADE_SHADE_COUNT;
-	const eased = 0.5 * (1 - Math.cos(Math.PI * progress));
-	const blended = source.map((channel, index) => Math.round(channel * (1 - eased) + dim[index]! * eased));
-	return `\x1b[38;2;${blended[0]};${blended[1]};${blended[2]}m${text}\x1b[0m`;
-}
-
-/** 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(" ");
-}
-
 /** True when every appearance toggle is off and Pi's stock loader can be restored. */
 export function isFullyDefaultAppearance(features: {
 	substituteDefaultMessage: boolean;
@@ -205,112 +123,3 @@ export function buildWorkingMessage(
 
 	return segments.join(" ");
 }
-
-const SHIMMER_SWEEP_S = 2.0;
-const SHIMMER_BAND_HALF = 5.0;
-const SHIMMER_PADDING = 10;
-
-/**
- * Codex-style light-sweep shimmer using the active Pi theme.
- *
- * With `invert=true`, the text color is used at rest and the sweep moves toward
- * the theme's dim color.
- */
-export function shimmerString(
-	text: string,
-	elapsedMs: number,
-	theme: Pick<Theme, "getFgAnsi" | "fg">,
-	direction: "ltr" | "rtl" = "ltr",
-	speed: "slow" | "normal" | "fast" = "normal",
-	invert = false,
-): string {
-	const chars = [...text];
-	if (chars.length === 0) return "";
-	const shimmerBase = ansiToRgb(theme.getFgAnsi(invert ? "text" : "dim"));
-	const shimmerHighlight = ansiToRgb(theme.getFgAnsi(invert ? "dim" : "text"));
-	if (!shimmerBase || !shimmerHighlight) return theme.fg("text", text);
-	const period = chars.length + SHIMMER_PADDING * 2;
-	const unitsPerS = period / SHIMMER_SWEEP_S;
-	// The band crosses padding at either end while every character is still dim. Scaling only
-	// the stretch where it actually overlaps the text keeps that dark pause identical at every
-	// speed, so `speed` changes the sweep alone rather than the whole cycle.
-	const litEnter = SHIMMER_PADDING - SHIMMER_BAND_HALF;
-	const litExit = SHIMMER_PADDING + chars.length - 1 + SHIMMER_BAND_HALF;
-	const enterS = litEnter / unitsPerS;
-	const litS = (litExit - litEnter) / unitsPerS / (speed === "slow" ? 0.5 : speed === "fast" ? 2 : 1);
-	const phase = (elapsedMs / 1000) % (enterS + litS + (period - litExit) / unitsPerS);
-	const linear = phase < enterS
-		? phase * unitsPerS
-		: phase < enterS + litS
-			? litEnter + ((phase - enterS) / litS) * (litExit - litEnter)
-			: litExit + (phase - enterS - litS) * unitsPerS;
-	const pos = direction === "rtl" ? period - linear : linear;
-
-	let out = "";
-	for (let i = 0; i < chars.length; i++) {
-		const ch = chars[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(shimmerHighlight[0] * alpha + shimmerBase[0] * (1 - alpha));
-		const g = Math.round(shimmerHighlight[1] * alpha + shimmerBase[1] * (1 - alpha));
-		const b = Math.round(shimmerHighlight[2] * alpha + shimmerBase[2] * (1 - alpha));
-		const bold = !invert && t > 0.2 ? "\x1b[1m" : "";
-		out += `${bold}\x1b[38;2;${r};${g};${b}m${ch}\x1b[22m`;
-	}
-	return out + "\x1b[0m";
-}
-
-function ansiToRgb(ansi: string): [number, number, number] | null {
-	const match = ansi.match(/\x1b\[38;2;(\d+);(\d+);(\d+)m/);
-	if (!match) return null;
-	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/src/loader-message.ts

@@ -1,5 +1,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { buildWorkingMessage, DEFAULT_WORKING_WORD, dimAttribute, fadeThemeColorString, formatElapsed, formatTokens, getThinkingLevelColorizer, isFullyDefaultAppearance, shimmerString, SPINNER_FRAME_MS, SPINNER_FRAMES, TOKEN_RATE_PLACEHOLDER, type LoaderElement, type ThinkingLevel } from "./format.ts";
+import { formatElapsedUnits } from "@underactive/pi-topping-primitives/activity";
+import { dimAttribute, fadeThemeColorString, shimmerString, thinkingLevelColorizer } from "@underactive/pi-topping-primitives/activity-tui";
+import { buildWorkingMessage, DEFAULT_WORKING_WORD, formatTokens, isFullyDefaultAppearance, SPINNER_FRAME_MS, SPINNER_FRAMES, TOKEN_RATE_PLACEHOLDER, type LoaderElement, type ThinkingLevel } from "./format.ts";
 import { getResponseModelColorizer } from "./nvidia-green.ts";
 import type { DecoratorSettings } from "./settings.ts";
 
@@ -27,7 +29,7 @@ export function buildLoaderMessage(
 	loaderOrder: readonly LoaderElement[],
 	parts: LoaderParts,
 ): string {
-	const spinner = parts.spinnerAtMs === undefined ? "" : getThinkingLevelColorizer(theme, decorations.spinnerColor, thinkingLevel)(SPINNER_FRAMES[Math.floor(parts.spinnerAtMs / SPINNER_FRAME_MS) % SPINNER_FRAMES.length]!);
+	const spinner = parts.spinnerAtMs === undefined ? "" : thinkingLevelColorizer(theme, decorations.spinnerColor, thinkingLevel)(SPINNER_FRAMES[Math.floor(parts.spinnerAtMs / SPINNER_FRAME_MS) % SPINNER_FRAMES.length]!);
 	const responseModelColored = parts.responseModel ? getResponseModelColorizer(theme, decorations.responseModelColor, thinkingLevel, provider)(parts.responseModel) : "";
 	const responseModel = responseModelColored && decorations.responseModelDimmed ? dimAttribute(responseModelColored) : responseModelColored;
 	if (isFullyDefaultAppearance(features, decorations)) {
@@ -38,20 +40,20 @@ export function buildLoaderMessage(
 		? shimmerString(word, parts.shimmerAtMs, theme, decorations.shimmerDirection, decorations.shimmerSpeed, decorations.shimmerInverted)
 		: theme.fg("text", word);
 	const meter = decorations.tokenActivityMonitor && parts.renderMeter
-		? parts.renderMeter(getThinkingLevelColorizer(theme, decorations.meterColor, thinkingLevel), decorations.meterDimmed)
+		? parts.renderMeter(thinkingLevelColorizer(theme, decorations.meterColor, thinkingLevel), decorations.meterDimmed)
 		: "";
 	let tokenRate = "";
 	if (features.tokenRate) {
 		if (!parts.tokenRateText) tokenRate = theme.fg("dim", TOKEN_RATE_PLACEHOLDER);
 		else {
-			const colorizer = getThinkingLevelColorizer(theme, decorations.tokenRateColor, thinkingLevel);
+			const colorizer = thinkingLevelColorizer(theme, decorations.tokenRateColor, thinkingLevel);
 			tokenRate = parts.tokenRateShade === undefined ? colorizer(parts.tokenRateText) : fadeThemeColorString(parts.tokenRateText, parts.tokenRateShade, theme, colorizer);
 		}
 		if (tokenRate && decorations.tokenRateDimmed) tokenRate = dimAttribute(tokenRate);
 	}
 	return buildWorkingMessage(theme, {
 		spinner, text, meter,
-		elapsed: features.elapsedTime && parts.elapsedMs !== undefined ? formatElapsed(parts.elapsedMs) : "",
+		elapsed: features.elapsedTime && parts.elapsedMs !== undefined ? formatElapsedUnits(parts.elapsedMs) : "",
 		tokens: features.outputTokens && parts.outputTokens !== undefined ? `↓ ${formatTokens(parts.outputTokens)} tokens` : "",
 		tokenRate, responseModel,
 	}, loaderOrder);

package/src/nvidia-green.ts

@@ -1,19 +1,22 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { getThinkingLevelColorizer, type ThinkingLevel } from "./format.ts";
+import { thinkingLevelColorizer } from "@underactive/pi-topping-primitives/activity-tui";
+import {
+	hexToFgAnsi,
+	isSwitchyardProvider,
+	NVIDIA_GREEN_HEX,
+	SWITCHYARD_PROVIDER,
+} from "@underactive/pi-topping-primitives/color";
+import type { ThinkingLevel } from "./format.ts";
 import type { ThinkingLevelColor } from "./settings.ts";
 
-/** Provider id whose working-loader response model uses NVIDIA green. */
-export const SWITCHYARD_PROVIDER = "switchyard";
-
-/** Bright NVIDIA green shared with pi-topping-statusline's Switchyard border. */
-export const NVIDIA_GREEN_HEX = "#84c51a";
-
-const NVIDIA_GREEN_RGB = [1, 3, 5].map((offset) => Number.parseInt(NVIDIA_GREEN_HEX.slice(offset, offset + 2), 16));
-const NVIDIA_GREEN_ANSI = `\x1b[38;2;${NVIDIA_GREEN_RGB.join(";")}m`;
+/**
+ * The Switchyard provider id, the bright NVIDIA green it shares with pi-topping-statusline's
+ * Switchyard border, and the case- and space-insensitive provider check.
+ */
+export { isSwitchyardProvider, NVIDIA_GREEN_HEX, SWITCHYARD_PROVIDER };
 
-export function isSwitchyardProvider(provider: string | undefined): boolean {
-	return provider?.trim().toLowerCase() === SWITCHYARD_PROVIDER;
-}
+/** Always truecolor, as the response-model colorizer has always been. */
+const NVIDIA_GREEN_ANSI = hexToFgAnsi(NVIDIA_GREEN_HEX, "truecolor");
 
 export function colorizeNvidiaGreen(text: string): string {
 	return `${NVIDIA_GREEN_ANSI}${text}\x1b[39m`;
@@ -33,5 +36,5 @@ export function getResponseModelColorizer(
 ): (text: string) => string {
 	return isSwitchyardProvider(provider)
 		? colorizeNvidiaGreen
-		: getThinkingLevelColorizer(theme, color, thinkingLevel);
+		: thinkingLevelColorizer(theme, color, thinkingLevel);
 }

package/src/output-style.ts

@@ -132,13 +132,6 @@ export function isOutputStyleId(value: unknown): value is OutputStyleId {
 	return typeof value === "string" && OUTPUT_STYLE_IDS.some(id => id === value);
 }
 
-/** Map the old pi-topping-insights style spelling to the current lowercase id. */
-export function fromLegacyOutputStyle(value: unknown): OutputStyleId | undefined {
-	if (value === "default") return "default";
-	if (value === "Explanatory") return "explanatory";
-	return undefined;
-}
-
 /**
  * Apply a style's prompt section and return its hidden reminder. Default removes the section only
  * when it holds one of these styles' text, so another extension's section survives. Hosts without

package/src/pi-installer.ts

@@ -1,4 +1,8 @@
-import { spawn } from "node:child_process";
+import {
+	type PiInvocation,
+	resolvePiInvocation,
+	spawnCollect,
+} from "@underactive/pi-topping-primitives/process";
 
 export interface PiInstallResult {
 	code: number;
@@ -6,67 +10,46 @@ export interface PiInstallResult {
 	stderr: string;
 }
 
-const SIGKILL_GRACE_MS = 5_000;
-const EXIT_TIMEOUT = 124;
+export interface PiInstallOptions {
+	/** Run this instead of the pi hosting the session. For tests, which must not start a real pi. */
+	piInvocation?: PiInvocation;
+}
 
-function spawnPiPackageCommand(command: "install" | "remove", spec: string, timeoutMs: number): Promise<PiInstallResult> {
-	if (!/^npm:@?[\w.-]+(\/[\w.-]+)?$/.test(spec)) {
-		return Promise.resolve({ code: 1, stdout: "", stderr: `invalid spec: ${spec}` });
-	}
-	return new Promise((resolve) => {
-		const isWindows = process.platform === "win32";
-		const [executable, args, options] = isWindows
-			? (["cmd.exe", ["/c", "pi", command, spec], { windowsHide: true }] as const)
-			: (["pi", [command, spec], {}] as const);
-		const processHandle = spawn(executable, args, { ...options, stdio: ["ignore", "pipe", "pipe"] });
-		let stdout = "";
-		let stderr = "";
-		let settled = false;
-		let closed = false;
-		let killTimer: ReturnType<typeof setTimeout> | undefined;
+const PACKAGE_SPEC = /^npm:@?[\w.-]+(\/[\w.-]+)?$/;
 
-		const finish = (result: PiInstallResult): void => {
-			if (settled) return;
-			settled = true;
-			clearTimeout(timeoutTimer);
-			resolve(result);
-		};
+async function spawnPiPackageCommand(
+	command: "install" | "remove",
+	spec: string,
+	timeoutMs: number,
+	options: PiInstallOptions,
+): Promise<PiInstallResult> {
+	if (!PACKAGE_SPEC.test(spec)) {
+		return { code: 1, stdout: "", stderr: `invalid spec: ${spec}` };
+	}
 
-		const timeoutTimer = setTimeout(() => {
-			processHandle.kill("SIGTERM");
-			killTimer = setTimeout(() => {
-				if (!closed) processHandle.kill("SIGKILL");
-			}, SIGKILL_GRACE_MS);
-			finish({
-				code: EXIT_TIMEOUT,
-				stdout,
-				stderr: `${stderr}${stderr ? "\n" : ""}[timed out after ${timeoutMs}ms]`,
-			});
-		}, timeoutMs);
+	// The pi that hosts this session, so install and remove reach the same agent dir.
+	const invocation = options.piInvocation
+		? { command: options.piInvocation.command, args: [...options.piInvocation.args, command, spec], via: "script" as const }
+		: resolvePiInvocation([command, spec]);
+
+	let { command: executable, args } = invocation;
+	// Only `pi` on PATH can be a Windows `.cmd` shim, which a shell-less spawn cannot start. The
+	// spec was validated above, so it carries nothing for cmd.exe to re-parse.
+	if (invocation.via === "path" && process.platform === "win32") {
+		executable = "cmd.exe";
+		args = ["/c", "pi", command, spec];
+	}
 
-		processHandle.stdout?.on("data", (chunk: Buffer) => {
-			stdout += chunk.toString();
-		});
-		processHandle.stderr?.on("data", (chunk: Buffer) => {
-			stderr += chunk.toString();
-		});
-		processHandle.on("error", (error) => {
-			finish({ code: 1, stdout, stderr: `${stderr}${stderr ? "\n" : ""}${error.message}` });
-		});
-		processHandle.on("close", (code) => {
-			closed = true;
-			if (killTimer !== undefined) clearTimeout(killTimer);
-			finish({ code: code ?? 1, stdout, stderr });
-		});
-	});
+	const { code, stdout, stderr } = await spawnCollect(executable, args, { timeoutMs, windowsHide: true });
+	return { code, stdout, stderr };
 }
 
-/** Run `pi install <spec>` without relying on Pi's shell-less exec wrapper on Windows. */
-export function spawnPiInstall(spec: string, timeoutMs: number): Promise<PiInstallResult> {
-	return spawnPiPackageCommand("install", spec, timeoutMs);
+/** Run `pi install <spec>` with the pi hosting this session; a Windows `pi` on PATH goes through `cmd.exe`. */
+export function spawnPiInstall(spec: string, timeoutMs: number, options: PiInstallOptions = {}): Promise<PiInstallResult> {
+	return spawnPiPackageCommand("install", spec, timeoutMs, options);
 }
 
-/** Run `pi remove <spec>` without relying on Pi's shell-less exec wrapper on Windows. */
-export function spawnPiRemove(spec: string, timeoutMs: number): Promise<PiInstallResult> {
-	return spawnPiPackageCommand("remove", spec, timeoutMs);
+/** Run `pi remove <spec>` with the pi hosting this session; a Windows `pi` on PATH goes through `cmd.exe`. */
+export function spawnPiRemove(spec: string, timeoutMs: number, options: PiInstallOptions = {}): Promise<PiInstallResult> {
+	return spawnPiPackageCommand("remove", spec, timeoutMs, options);
 }

package/src/preview.ts

@@ -1,7 +1,8 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_PREVIEW_WIDTH, type PreviewResult } from "./menu.ts";
-import { ActivityMeter, METER_UPPER_BOUND_TPS_MAX, METER_UPPER_BOUND_TPS_MIN, rateToLevel } from "./activity-meter.ts";
-import { DEFAULT_WORKING_WORD, dimAttribute, ELAPSED_INTERVAL_MS, formatTokenRate, getThinkingLevelColorizer, METER_INTERVAL_MS, SHIMMER_INTERVAL_MS, SPINNER_FRAME_MS } from "./format.ts";
+import type { MenuValue, PreviewSlot } from "@underactive/pi-topping-primitives/menu";
+import { ActivityMeter, METER_UPPER_BOUND_TPS_MAX, METER_UPPER_BOUND_TPS_MIN, rateToLevel } from "@underactive/pi-topping-primitives/activity";
+import { dimAttribute, renderMeter, thinkingLevelColorizer } from "@underactive/pi-topping-primitives/activity-tui";
+import { DEFAULT_WORKING_WORD, ELAPSED_INTERVAL_MS, formatTokenRate, METER_INTERVAL_MS, SHIMMER_INTERVAL_MS, SPINNER_FRAME_MS } from "./format.ts";
 import { buildLoaderMessage } from "./loader-message.ts";
 import { getResponseModelColorizer } from "./nvidia-green.ts";
 import { isOutputStyleId, OUTPUT_STYLES } from "./output-style.ts";
@@ -12,12 +13,24 @@ import { isWordPackEnabled, selectWorkingTextSelection, WORD_PACK_MENU_PREFIX, w
 // Simulated load for the menu preview: a 2.4s cosine wave peaking at 46 tps for the meter,
 // flat 28 tps for the token readouts.
 const METER_PERIOD_MS = 2400, METER_PEAK_RATE = 46, TOKEN_RATE_PER_SEC = 28;
+/** Width the preview assumes when rendered outside a menu (tests and probes). */
+export const DEFAULT_PREVIEW_WIDTH = 76;
+type Values = Record<string, MenuValue>;
+type PreviewState = { elapsedMs: number; activeItemId: string | undefined; width: number };
+export interface PreviewResult {
+	lines: string[];
+	nextRefreshInMs?: number;
+}
+/** The shared menu adds no margin; the preview indents every line by one space itself. */
+function indented(result: PreviewResult): PreviewResult {
+	return { ...result, lines: result.lines.map(line => ` ${line}`) };
+}
 const PROMPT_IDS = new Set(MENU_ENTRIES.filter(entry => entry.section === "User Prompt").map(entry => entry.id));
 const MARKER_IDS = new Set(MENU_ENTRIES.filter(entry => entry.section === "Completion Marker").map(entry => entry.id));
 function meterRate(elapsedMs: number): number { return ((1 - Math.cos((2 * Math.PI * elapsedMs) / METER_PERIOD_MS)) / 2) * METER_PEAK_RATE; }
 
 /** Stateful, per-menu preview renderer that follows the active settings section. */
-export class PreviewRenderer {
+export class PreviewRenderer implements PreviewSlot<Values> {
 	// Preserve constructor-time randomness so rendering never changes the preview phrase.
 	readonly #poolFraction = Math.random();
 	readonly #packs: readonly WordPack[];
@@ -30,7 +43,11 @@ export class PreviewRenderer {
 		this.#ctx = ctx;
 		this.#packs = packs;
 	}
-	render(values: Record<string, boolean | string>, elapsedMs: number, activeItemId?: string, width: number = DEFAULT_PREVIEW_WIDTH): PreviewResult {
+	render(values: Values, state: PreviewState = { elapsedMs: 0, activeItemId: undefined, width: DEFAULT_PREVIEW_WIDTH }): PreviewResult {
+		return indented(this.renderContent(values, state.elapsedMs, state.activeItemId, Math.max(0, state.width - 1)));
+	}
+	/** The lines before the one-space indent; `width` is the budget those lines may fill. */
+	private renderContent(values: Values, elapsedMs: number, activeItemId: string | undefined, width: number): PreviewResult {
 		if (PROMPT_IDS.has(activeItemId ?? "")) return this.promptPreview(values, width);
 		if (MARKER_IDS.has(activeItemId ?? "")) return this.markerPreview(values, width);
 		if (activeItemId === "useNerdFont") return { lines: ["", `Icon preview: ${values.useNerdFont ? "" : "π"}`, ""] };
@@ -60,7 +77,7 @@ export class PreviewRenderer {
 			: "";
 		return { lines: ["", this.loaderPreview(values, elapsedMs), help], nextRefreshInMs };
 	}
-	private loaderPreview(values: Record<string, boolean | string>, elapsedMs: number): string {
+	private loaderPreview(values: Values, elapsedMs: number): string {
 		this.#meter.setDirection(fromCycleDirection(values.meterDirection));
 		if (elapsedMs - this.#lastMeterUpdate >= METER_INTERVAL_MS) {
 			this.#meter.push(rateToLevel(meterRate(elapsedMs), fromCycleMeterUpperBound(values.meterUpperBoundTps)));
@@ -97,14 +114,14 @@ export class PreviewRenderer {
 			spinnerAtMs: values.animatedSpinner !== false ? elapsedMs : undefined,
 			word,
 			shimmerAtMs: elapsedMs,
-			renderMeter: (colorizer, dimmed) => this.#meter.render((level, char) => ActivityMeter.colorizeCell(level, char, theme, colorizer, dimmed)),
+			renderMeter: (colorizer, dimmed) => renderMeter(this.#meter, theme, colorizer, dimmed),
 			elapsedMs,
 			outputTokens: Math.max(0, Math.floor(elapsedMs / 1000 * TOKEN_RATE_PER_SEC)),
 			tokenRateText: formatTokenRate(TOKEN_RATE_PER_SEC),
 			responseModel: features.responseModel ? "test-model" : undefined,
 		});
 	}
-	private packValues(values: Record<string, boolean | string>): Record<string, boolean> {
+	private packValues(values: Values): Record<string, boolean> {
 		const enabled: Record<string, boolean> = {};
 		for (const pack of this.#packs) {
 			const value = values[`${WORD_PACK_MENU_PREFIX}${pack.id}`];
@@ -112,14 +129,14 @@ export class PreviewRenderer {
 		}
 		return enabled;
 	}
-	private packPreview(id: string, values: Record<string, boolean | string>): PreviewResult {
+	private packPreview(id: string, values: Values): PreviewResult {
 		const pack = this.#packs.find((candidate) => candidate.id === id);
 		if (!pack) return { lines: ["This word pack is unavailable."] };
 		const enabled = isWordPackEnabled(id, this.packValues(values));
 		const source = pack.bundled ? "Shipped example" : `Custom: ${wordPacksPath()}`;
 		return { lines: [`${pack.name}: ${enabled ? "enabled" : "disabled"}`, `${pack.words.length} phrases · ${source}`, ...(pack.description ? [pack.description] : [])] };
 	}
-	private promptPreview(values: Record<string, boolean | string>, width: number): PreviewResult {
+	private promptPreview(values: Values, width: number): PreviewResult {
 		if (values.decorateUserPrompt !== true) return { lines: ["User prompt decoration is disabled."] };
 
 		const borderColor = values.borderColor;
@@ -141,7 +158,7 @@ export class PreviewRenderer {
 			? { lines }
 			: { lines, nextRefreshInMs: 1_000 - (timestamp % 1_000) };
 	}
-	private markerPreview(values: Record<string, boolean | string>, width: number): PreviewResult {
+	private markerPreview(values: Values, width: number): PreviewResult {
 		if (values.doneMarker !== true) return { lines: ["Completion marker is disabled."] };
 		const theme = this.#ctx.ui.theme;
 		const icon = values.doneMarkerIcon === true ? theme.fg("text", values.useNerdFont === true ? "" : "π") : "";
@@ -153,7 +170,7 @@ export class PreviewRenderer {
 		let model = "";
 		if (values.doneMarkerModel === true) {
 			const color = isThinkingLevelColor(values.doneMarkerModelColor) ? values.doneMarkerModelColor : DEFAULT_SETTINGS.decorations.doneMarkerModelColor;
-			const modelColored = getThinkingLevelColorizer(theme, color, this.#ctx.thinkingLevel)("test-model");
+			const modelColored = thinkingLevelColorizer(theme, color, this.#ctx.thinkingLevel)("test-model");
 			model = values.doneMarkerModelDimmed === true ? dimAttribute(modelColored) : modelColored;
 		}
 		const content = buildCompletionMarkerContent(theme, icon, word, "2m 52s", details, model);