@wierdbytes/pi-facelift 0.6.6 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.7.0
+
+- **Change:** still accent `●` instead of pi's animated spinner in the `Working...` line — no ~12×/s terminal repaints while the model streams; `animateWorkingIndicator` in `/facelift` brings the animation back.
+
 ## 0.6.6
 
 - **Fix:** prompt-cache warm-ups no longer inflate `worked` time / deflate `tps` or start a phantom working timer while idle.

package/README.md

@@ -62,6 +62,11 @@ tool output.
   (`0h12m0s` → `12m0s`); sub-minute values keep one decimal (`45.2s`).
 
   Toggle via `showWorkingTime` in `/facelift`.
+- **still working indicator** — pi's braille spinner in front of the
+  `Working...` line is replaced with a still accent `●`, so the terminal
+  isn't repainted ~12×/s while the model streams (GPU-rendered hosts such
+  as Herdr redraw the whole window for every frame). Turn the animation
+  back on via `animateWorkingIndicator` in `/facelift`.
 
 ## Install
 
@@ -128,7 +133,11 @@ Current schema:
   // each run's model time (`worked`, tools excluded) and wall-clock time
   // (`total`, retries + tools + overhead) as a muted line in chat
   // history. Default true.
-  "showWorkingTime": true
+  "showWorkingTime": true,
+
+  // Animate the spinner in front of the "Working..." line (pi's default,
+  // redrawn every 80ms). Default false: a still accent "●".
+  "animateWorkingIndicator": false
 }
 ```
 
@@ -147,6 +156,7 @@ icons, image protocols) or boot-time toggles:
 | `FACELIFT_IMAGE_PROTOCOL`      | auto            | Force `kitty` / `iterm2` / `none`. Auto-detected from `$TERM_PROGRAM` etc.    |
 | `DIFF_LAYOUT`                  | (none)          | One-shot override for `diffLayout` on first-run seeding.                      |
 | `FACELIFT_SHOW_WORKING_TIME`   | `true`          | One-shot override for `showWorkingTime` on first-run seeding (`0`/`off` ⇒ off). |
+| `FACELIFT_ANIMATE_WORKING`     | `false`         | Default for `animateWorkingIndicator` when the config doesn't set it (`1`/`on` ⇒ animated). |
 
 ## Development
 

package/config.test.ts

@@ -40,6 +40,8 @@ beforeEach(() => {
 	delete process.env.DIFF_LAYOUT;
 	savedEnv.FACELIFT_SHOW_WORKING_TIME = process.env.FACELIFT_SHOW_WORKING_TIME;
 	delete process.env.FACELIFT_SHOW_WORKING_TIME;
+	savedEnv.FACELIFT_ANIMATE_WORKING = process.env.FACELIFT_ANIMATE_WORKING;
+	delete process.env.FACELIFT_ANIMATE_WORKING;
 });
 
 afterEach(() => {
@@ -48,29 +50,32 @@ afterEach(() => {
 	if (savedEnv.FACELIFT_SHOW_WORKING_TIME !== undefined)
 		process.env.FACELIFT_SHOW_WORKING_TIME = savedEnv.FACELIFT_SHOW_WORKING_TIME;
 	else delete process.env.FACELIFT_SHOW_WORKING_TIME;
+	if (savedEnv.FACELIFT_ANIMATE_WORKING !== undefined)
+		process.env.FACELIFT_ANIMATE_WORKING = savedEnv.FACELIFT_ANIMATE_WORKING;
+	else delete process.env.FACELIFT_ANIMATE_WORKING;
 	rmSync(dir, { recursive: true, force: true });
 });
 
 describe("envDefaults", () => {
 	it("returns 'consistent' when DIFF_LAYOUT is unset", () => {
-		expect(envDefaults()).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(envDefaults()).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	for (const layout of VALID_DIFF_LAYOUTS) {
 		it(`honours DIFF_LAYOUT=${layout}`, () => {
 			process.env.DIFF_LAYOUT = layout;
-			expect(envDefaults()).toEqual({ diffLayout: layout, showWorkingTime: true });
+			expect(envDefaults()).toEqual({ diffLayout: layout, showWorkingTime: true, animateWorkingIndicator: false });
 		});
 	}
 
 	it("ignores invalid DIFF_LAYOUT values", () => {
 		process.env.DIFF_LAYOUT = "rainbow";
-		expect(envDefaults()).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(envDefaults()).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("is case-insensitive on DIFF_LAYOUT", () => {
 		process.env.DIFF_LAYOUT = "SPLIT";
-		expect(envDefaults()).toEqual({ diffLayout: "split", showWorkingTime: true });
+		expect(envDefaults()).toEqual({ diffLayout: "split", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("defaults showWorkingTime to true", () => {
@@ -90,15 +95,43 @@ describe("envDefaults", () => {
 	});
 });
 
+describe("animateWorkingIndicator", () => {
+	it("defaults to false (a still indicator)", () => {
+		expect(envDefaults().animateWorkingIndicator).toBe(false);
+	});
+
+	it("honours FACELIFT_ANIMATE_WORKING=1/on/true to animate", () => {
+		for (const v of ["1", "on", "true"]) {
+			process.env.FACELIFT_ANIMATE_WORKING = v;
+			expect(envDefaults().animateWorkingIndicator).toBe(true);
+		}
+	});
+
+	it("persists animateWorkingIndicator=true through save/load", () => {
+		saveConfig({ diffLayout: "split", showWorkingTime: true, animateWorkingIndicator: true }, configFile);
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "split", showWorkingTime: true, animateWorkingIndicator: true });
+	});
+
+	it("sanitises a non-boolean value back to the default", () => {
+		writeFileSync(configFile, JSON.stringify({ diffLayout: "split", animateWorkingIndicator: "yes" }));
+		expect(loadConfig(configFile).animateWorkingIndicator).toBe(false);
+	});
+
+	it("keeps older config files (no field) on the default", () => {
+		writeFileSync(configFile, JSON.stringify({ diffLayout: "split", showWorkingTime: false }));
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "split", showWorkingTime: false, animateWorkingIndicator: false });
+	});
+});
+
 describe("showWorkingTime round-trip", () => {
 	it("persists showWorkingTime=false through save/load", () => {
-		saveConfig({ diffLayout: "consistent", showWorkingTime: false }, configFile);
-		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: false });
+		saveConfig({ diffLayout: "consistent", showWorkingTime: false, animateWorkingIndicator: false }, configFile);
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: false, animateWorkingIndicator: false });
 	});
 
 	it("sanitises a non-boolean showWorkingTime back to the default", () => {
 		writeFileSync(configFile, JSON.stringify({ diffLayout: "split", showWorkingTime: "nope" }));
-		expect(loadConfig(configFile)).toEqual({ diffLayout: "split", showWorkingTime: true });
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "split", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 });
 
@@ -107,7 +140,7 @@ describe("loadConfig + saveConfig round-trip", () => {
 		it(`persists diffLayout=${layout}`, () => {
 			saveConfig({ diffLayout: layout } as WierdFaceliftConfig, configFile);
 			expect(existsSync(configFile)).toBe(true);
-			expect(loadConfig(configFile)).toEqual({ diffLayout: layout, showWorkingTime: true });
+			expect(loadConfig(configFile)).toEqual({ diffLayout: layout, showWorkingTime: true, animateWorkingIndicator: false });
 		});
 	}
 
@@ -116,23 +149,23 @@ describe("loadConfig + saveConfig round-trip", () => {
 			configFile,
 			JSON.stringify({ diffLayout: "consistent", iconMode: "rainbow", junk: 42 }),
 		);
-		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("rejects invalid diffLayout strings and falls back to default", () => {
 		writeFileSync(configFile, JSON.stringify({ diffLayout: "tutti-frutti" }));
-		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("returns defaults when the file is missing (no write)", () => {
 		expect(existsSync(configFile)).toBe(false);
-		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 		expect(existsSync(configFile)).toBe(false);
 	});
 
 	it("returns defaults when the file is malformed JSON", () => {
 		writeFileSync(configFile, "{ not valid json");
-		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(loadConfig(configFile)).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("writes a trailing newline", () => {
@@ -145,22 +178,22 @@ describe("loadOrInitConfig", () => {
 	it("seeds a missing file from env defaults", () => {
 		expect(existsSync(configFile)).toBe(false);
 		const cfg = loadOrInitConfig(configFile);
-		expect(cfg).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(cfg).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 		expect(existsSync(configFile)).toBe(true);
-		expect(JSON.parse(readFileSync(configFile, "utf-8"))).toEqual({ diffLayout: "consistent", showWorkingTime: true });
+		expect(JSON.parse(readFileSync(configFile, "utf-8"))).toEqual({ diffLayout: "consistent", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("respects DIFF_LAYOUT when seeding", () => {
 		process.env.DIFF_LAYOUT = "unified";
 		const cfg = loadOrInitConfig(configFile);
-		expect(cfg).toEqual({ diffLayout: "unified", showWorkingTime: true });
-		expect(JSON.parse(readFileSync(configFile, "utf-8"))).toEqual({ diffLayout: "unified", showWorkingTime: true });
+		expect(cfg).toEqual({ diffLayout: "unified", showWorkingTime: true, animateWorkingIndicator: false });
+		expect(JSON.parse(readFileSync(configFile, "utf-8"))).toEqual({ diffLayout: "unified", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 
 	it("does not overwrite an existing file", () => {
 		writeFileSync(configFile, JSON.stringify({ diffLayout: "split" }));
 		process.env.DIFF_LAYOUT = "unified"; // would override on a fresh seed
 		const cfg = loadOrInitConfig(configFile);
-		expect(cfg).toEqual({ diffLayout: "split", showWorkingTime: true });
+		expect(cfg).toEqual({ diffLayout: "split", showWorkingTime: true, animateWorkingIndicator: false });
 	});
 });

package/config.ts

@@ -10,7 +10,8 @@
  *     extension.
  *   - Saves write atomically (one JSON.stringify + trailing newline).
  *
- * The knobs we expose today are `diffLayout` and `showWorkingTime`, and
+ * The knobs we expose today are `diffLayout`, `showWorkingTime` and
+ * `animateWorkingIndicator`, and
  * the schema is designed to accept more fields (icon mode, max preview
  * lines, etc.) without breaking older config files.
  */
@@ -58,6 +59,18 @@ export interface WierdFaceliftConfig {
 	 * (`0`/`false`/`off` to disable).
 	 */
 	showWorkingTime: boolean;
+
+	/**
+	 * Animate the spinner in front of the streaming "Working…" line (pi's
+	 * default: a braille spinner redrawn every 80ms). Off ⇒ a still accent
+	 * `●` instead, so an idle-looking terminal isn't repainted 12×/s while
+	 * the model streams — GPU-rendered hosts (e.g. Herdr) redraw the whole
+	 * window for each of those frames.
+	 *
+	 * Defaults to `false`; override with env `FACELIFT_ANIMATE_WORKING`
+	 * (`1`/`true`/`on` to animate).
+	 */
+	animateWorkingIndicator: boolean;
 }
 
 function isDiffLayout(value: unknown): value is DiffLayoutPreference {
@@ -88,6 +101,7 @@ export function envDefaults(): WierdFaceliftConfig {
 	return {
 		diffLayout: fromEnv ?? DEFAULT_DIFF_LAYOUT,
 		showWorkingTime: parseBool(process.env.FACELIFT_SHOW_WORKING_TIME, true),
+		animateWorkingIndicator: parseBool(process.env.FACELIFT_ANIMATE_WORKING, false),
 	};
 }
 
@@ -98,6 +112,7 @@ function sanitize(raw: unknown): WierdFaceliftConfig {
 	const cfg: WierdFaceliftConfig = { ...defaults };
 	if (isDiffLayout(obj.diffLayout)) cfg.diffLayout = obj.diffLayout;
 	if (typeof obj.showWorkingTime === "boolean") cfg.showWorkingTime = obj.showWorkingTime;
+	if (typeof obj.animateWorkingIndicator === "boolean") cfg.animateWorkingIndicator = obj.animateWorkingIndicator;
 	return cfg;
 }
 
@@ -143,6 +158,7 @@ export function saveConfig(
 	const out: Record<string, unknown> = {
 		diffLayout: cfg.diffLayout,
 		showWorkingTime: cfg.showWorkingTime,
+		animateWorkingIndicator: cfg.animateWorkingIndicator,
 	};
 	writeFileSync(path, `${JSON.stringify(out, null, 2)}\n`, "utf-8");
 	return path;

package/index.ts

@@ -1258,6 +1258,31 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 		if (entry) pi.appendEntry(WORKING_TIME_ENTRY, entry);
 	});
 
+	// ===================================================================
+	// Working indicator — a still `●` instead of pi's 80ms spinner
+	// -------------------------------------------------------------------
+	// pi's braille spinner repaints the terminal ~12×/s for as long as the
+	// model streams; a GPU-rendered host (Herdr) redraws its whole window
+	// for every one of those frames. A single frame starts no animation
+	// timer at all. pi resets the indicator on every reload / session
+	// switch, so it is applied on each `session_start` (and at once when
+	// the setting changes).
+	// ===================================================================
+
+	const applyWorkingIndicator = (ctx: SessionContextLike): void => {
+		try {
+			if (!ctx.hasUI || typeof ctx.ui.setWorkingIndicator !== "function") return;
+			if (faceliftConfig.animateWorkingIndicator) ctx.ui.setWorkingIndicator();
+			else ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] });
+		} catch {
+			// Stale ctx or an older pi without the API: keep pi's default.
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		applyWorkingIndicator(ctx);
+	});
+
 	// ===================================================================
 	// read — syntax-highlighted file content
 	// ===================================================================
@@ -1866,6 +1891,15 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 				value: faceliftConfig.showWorkingTime,
 				default: true,
 			},
+			{
+				key: "animateWorkingIndicator",
+				type: "boolean",
+				label: "Animated spinner",
+				description:
+					"Animate the spinner in front of the \u201cWorking\u2026\u201d line (pi\u2019s default, redrawn every 80ms). Off shows a still \u25cf, so the terminal isn\u2019t repainted 12\u00d7/s while the model streams \u2014 cheaper in GPU-rendered hosts such as Herdr.",
+				value: faceliftConfig.animateWorkingIndicator,
+				default: false,
+			},
 		];
 		await openSettingsModal(extCtx, {
 			title: "@wierdbytes/pi-facelift",
@@ -1879,6 +1913,11 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 					faceliftConfig = { ...faceliftConfig, showWorkingTime: value as boolean };
 					persistFaceliftConfig(extCtx);
 				}
+				if (key === "animateWorkingIndicator") {
+					faceliftConfig = { ...faceliftConfig, animateWorkingIndicator: value as boolean };
+					persistFaceliftConfig(extCtx);
+					applyWorkingIndicator(extCtx);
+				}
 			},
 		});
 	};
@@ -1888,6 +1927,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 			`config:     ${getFaceliftConfigPath()}`,
 			`diffLayout: ${faceliftConfig.diffLayout}`,
 			`workingTime: ${faceliftConfig.showWorkingTime ? "on" : "off"}`,
+			`spinner:    ${faceliftConfig.animateWorkingIndicator ? "animated" : "still"}`,
 		];
 		extCtx.ui.notify(`@wierdbytes/pi-facelift\n${lines.join("\n")}`, "info");
 	};
@@ -1895,6 +1935,7 @@ export default function piFaceliftExtension(pi: PiFaceliftApi, deps?: PiFacelift
 	const resetFaceliftConfig = (extCtx: ExtensionContext): void => {
 		faceliftConfig = faceliftEnvDefaults();
 		persistFaceliftConfig(extCtx);
+		applyWorkingIndicator(extCtx);
 		extCtx.ui.notify("pi-facelift: config reset to defaults.", "info");
 	};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wierdbytes/pi-facelift",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Cosmetic facelift for built-in pi tool output — open-right rounded frames, syntax-highlighted reads, status-aware bash summaries, find/grep.",
   "type": "module",
   "files": [

package/working-indicator.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for the still working indicator: on `session_start` facelift
+ * replaces pi's 80ms braille spinner with a single accent `●` frame (a
+ * single frame starts no animation timer), unless the config asks for
+ * the animated default (`animateWorkingIndicator: true`).
+ *
+ * The extension reads its config from `${PI_AGENT_DIR}/wierd-facelift/`,
+ * so each test points PI_AGENT_DIR at a temp dir with the config it needs.
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import piFaceliftExtension from "./index.ts";
+
+class MockText {
+	constructor(
+		private text = "",
+		_x = 0,
+		_y = 0,
+	) {}
+	setText(value: string) {
+		this.text = value;
+	}
+	getText() {
+		return this.text;
+	}
+}
+
+let dir: string;
+let savedAgentDir: string | undefined;
+let savedAnimate: string | undefined;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "facelift-indicator-"));
+	savedAgentDir = process.env.PI_AGENT_DIR;
+	savedAnimate = process.env.FACELIFT_ANIMATE_WORKING;
+	process.env.PI_AGENT_DIR = dir;
+	delete process.env.FACELIFT_ANIMATE_WORKING;
+});
+
+afterEach(() => {
+	if (savedAgentDir !== undefined) process.env.PI_AGENT_DIR = savedAgentDir;
+	else delete process.env.PI_AGENT_DIR;
+	if (savedAnimate !== undefined) process.env.FACELIFT_ANIMATE_WORKING = savedAnimate;
+	else delete process.env.FACELIFT_ANIMATE_WORKING;
+	rmSync(dir, { recursive: true, force: true });
+});
+
+function writeConfig(config: Record<string, unknown>) {
+	mkdirSync(join(dir, "wierd-facelift"), { recursive: true });
+	writeFileSync(join(dir, "wierd-facelift", "config.json"), JSON.stringify(config));
+}
+
+function loadExtension(ui: Record<string, unknown> = {}, hasUI = true) {
+	const handlers = new Map<string, (event: unknown, ctx: unknown) => void>();
+	const pi = {
+		registerTool: () => {},
+		registerCommand: () => {},
+		on: (name: string, h: (event: unknown, ctx: unknown) => void) => handlers.set(name, h),
+		registerEntryRenderer: () => {},
+		appendEntry: () => {},
+	};
+	piFaceliftExtension(pi as any, {
+		sdk: {
+			createReadToolDefinition: (_cwd: string) => ({
+				name: "mock",
+				description: "mock",
+				parameters: { type: "object", properties: {} },
+				execute: async () => ({ content: [{ type: "text", text: "" }] }),
+			}),
+			getAgentDir: () => dir,
+		},
+		TextComponent: MockText as any,
+	});
+	const setWorkingIndicator = vi.fn();
+	const ctx = {
+		hasUI,
+		ui: {
+			setWorkingMessage: vi.fn(),
+			setWorkingIndicator,
+			theme: { fg: (token: string, text: string) => `<${token}>${text}</${token}>` },
+			...ui,
+		},
+	};
+	const fire = (name: string) => handlers.get(name)?.({}, ctx);
+	return { fire, setWorkingIndicator, ctx };
+}
+
+describe("working indicator", () => {
+	it("sets a single still accent frame on session_start by default", () => {
+		const { fire, setWorkingIndicator } = loadExtension();
+		fire("session_start");
+		expect(setWorkingIndicator).toHaveBeenCalledTimes(1);
+		expect(setWorkingIndicator).toHaveBeenCalledWith({ frames: ["<accent>●</accent>"] });
+	});
+
+	it("keeps an older config file (no field) on the still indicator", () => {
+		writeConfig({ diffLayout: "split" });
+		const { fire, setWorkingIndicator } = loadExtension();
+		fire("session_start");
+		expect(setWorkingIndicator).toHaveBeenCalledWith({ frames: ["<accent>●</accent>"] });
+	});
+
+	it("restores pi's animated default when animateWorkingIndicator is on", () => {
+		writeConfig({ diffLayout: "split", animateWorkingIndicator: true });
+		const { fire, setWorkingIndicator } = loadExtension();
+		fire("session_start");
+		expect(setWorkingIndicator).toHaveBeenCalledTimes(1);
+		expect(setWorkingIndicator).toHaveBeenCalledWith();
+	});
+
+	it("does nothing without a UI (pi -p, RPC)", () => {
+		const { fire, setWorkingIndicator } = loadExtension({}, false);
+		fire("session_start");
+		expect(setWorkingIndicator).not.toHaveBeenCalled();
+	});
+
+	it("tolerates a pi without setWorkingIndicator", () => {
+		const { fire } = loadExtension({ setWorkingIndicator: undefined });
+		expect(() => fire("session_start")).not.toThrow();
+	});
+
+	it("swallows a stale ctx instead of crashing pi", () => {
+		const { fire } = loadExtension({
+			setWorkingIndicator: () => {
+				throw new Error("extension ctx is stale");
+			},
+		});
+		expect(() => fire("session_start")).not.toThrow();
+	});
+});