@pi-extensions/pi-pacman 0.1.0 → 0.1.1

package/README.md

@@ -1,68 +1,87 @@
-# pi-pacman
+# @pi-extensions/pi-pacman
 
-Pac-Man working indicator for [pi](https://github.com/earendil-works/pi).
+Pac-Man **working indicator** for [pi](https://github.com/earendil-works/pi): replaces the streaming spinner with pellet runs, ghost chases, arcade tunnels, and fruit bonuses.
 
-Replaces the streaming spinner with pellet runs, ghost chases, arcade tunnels, and fruit bonuses.
+Part of the [pi-extensions](https://github.com/smarzban/pi-extensions) monorepo.
 
-## Install
+## Highlights
+
+- **Drop-in working indicator**: uses `setWorkingIndicator` / `setWorkingMessage` (normal streaming only)
+- **Five looks**: full-width `classic` & `chase`, plus fixed-width `mini`, `arcade`, `fruit` (default 10 cells, configurable)
+- **Rotate mode**: cycle short looks every agent message (`/pacman rotate`)
+- **Random working blurbs**: arcade + AI/token-flavored lines each run (or lock your own)
+- **Remembers your choice**: look, rotate, cells, and custom message in `~/.pi/agent/pacman-thinking.json`
+
+## Quickstart
 
 ```bash
-# from npm (after publish)
 pi install npm:@pi-extensions/pi-pacman
+```
+
+Restart pi (or start a new session), send a message, and you should see a yellow `ᗧ` chomping pellets next to the working line:
 
-# local path (this monorepo)
-pi install /absolute/path/to/pi-extentions/packages/pi-pacman
+```text
+ᗧ······  waka waka...
 ```
 
-### Publish to npm
+Default look is **classic** (full-width pellet run). Footer status shows `ᗧ classic` while the extension is active.
 
-Releases are **tag-driven** (OIDC trusted publishing) — see [docs/releases.md](../../docs/releases.md).
+The indicator only appears while the agent is **streaming a normal response**, not during compaction/retry loaders.
 
-```bash
-# after version bump on main:
-git tag v0.1.0 && git push origin v0.1.0
-```
+## Install
 
-One-time: reservation publish with OTP + Trusted Publisher on npmjs.com (same doc).
+| Method | Loads | Command |
+|--------|-------|---------|
+| **npm** (recommended) | This package only | `pi install npm:@pi-extensions/pi-pacman` |
+| **local path** | This package only | `pi install /absolute/path/to/pi-extensions/packages/pi-pacman` |
+| **git** (whole monorepo) | All packages in the repo | `pi install git:github.com/smarzban/pi-extensions` |
 
-Then anyone can:
+More detail: [docs/install](../../docs/install/README.md) (one package vs whole monorepo).
 
-```bash
-pi install npm:@pi-extensions/pi-pacman
-pi install npm:@pi-extensions/pi-pacman@0.1.0
-```
+## Usage
 
-## Commands
+```text
+/pacman list
+/pacman chase
+/pacman rotate
+/pacman cells 12
+/pacman message chomping tokens...
+/pacman off
+```
 
-| Command | Effect |
+| Command | Result |
 |---------|--------|
-| `/pacman` | Show current look |
-| `/pacman list` | Catalog of looks |
-| `/pacman <look>` | Lock to that look (stops rotate) |
-| `/pacman rotate` | Cycle a different look every message |
-| `/pacman off` | Hide the indicator (stops rotate) |
-| `/pacman message <text>` | Custom working message |
-| `/pacman message` | Reset message to look default |
-| `/pacman clear` | Hide the look list widget |
-
-### Looks
-
-| Look | Vibe |
-|------|------|
+| `/pacman` | Current look, rotate, cells, message, strip width |
+| `/pacman list` | Catalog under the editor |
+| `/pacman <look>` | Lock a look (stops rotate) |
+| `/pacman rotate` | Cycle short looks every message |
+| `/pacman cells [n]` | Fixed-look width (default 10, range 4–40) |
+| `/pacman message …` | Lock custom working text (empty = auto-random) |
+| `/pacman off` | Hide indicator |
+
+Full reference: [docs/usage/commands.md](../../docs/usage/commands.md).
+
+## Looks
+
+| Look | Notes |
+|------|--------|
 | `classic` | Full-width pellet run (default) |
-| `chase` | Full-width Blinky hunt → revenge |
-| `mini` | 7-cell pellet run |
-| `arcade` | 7-cell maze tunnel |
-| `fruit` | 7-cell cherry bonus |
+| `chase` | Full-width Blinky hunt → power pellet → revenge |
+| `mini` / `arcade` / `fruit` | Fixed-width animations (**in rotate**); width via `cells` config |
 
-Speeds: full-width **80ms**/frame · fixed **110ms**/frame.
+Details: [docs/usage/looks.md](../../docs/usage/looks.md). Persistence: [docs/usage/persistence.md](../../docs/usage/persistence.md).
 
-## Persistence
+## Documentation
 
-Look, rotate on/off, rotate index, and custom message save to `~/.pi/agent/pacman-thinking.json`.
+| Doc | What |
+|-----|------|
+| [Quickstart](../../docs/quickstart.md) | Fastest path to first chomp |
+| [Commands](../../docs/usage/commands.md) | Every `/pacman` subcommand |
+| [Looks](../../docs/usage/looks.md) | Frame / width notes |
+| [Persistence](../../docs/usage/persistence.md) | State file fields |
+| [Architecture](../../docs/architecture.md) | How the extension hooks pi |
+| [Releases](../../docs/releases.md) | Maintainer publish flow |
 
-## One-shot (without install)
+## License
 
-```bash
-pi --extension ./index.ts
-```
+[MIT](LICENSE)

package/index.ts

@@ -4,7 +4,7 @@
  * Replaces pi's streaming working indicator with a Pac-Man animation.
  *
  * Install:
- *   pi install /path/to/pi-extentions/packages/pi-pacman
+ *   pi install /path/to/pi-extensions/packages/pi-pacman
  *   pi --extension ./index.ts
  *
  * Commands:
@@ -33,16 +33,19 @@ const PELLET = "\x1b[38;2;255;184;174m";
 const POWER = "\x1b[38;2;255;184;255m";
 const WALL = "\x1b[38;2;33;33;255m";
 const CHERRY = "\x1b[38;2;255;0;0m";
-const SCORE = "\x1b[38;2;255;255;255m";
 const GHOSTS = {
 	blinky: "\x1b[38;2;255;0;0m",
 	scared: "\x1b[38;2;33;33;255m",
 } as const;
 
-/** Full-width looks (classic / chase) — snappier chomp. */
+/** Full-width looks (classic / chase): snappier chomp. */
 const FRAME_MS_FULL = 80;
-/** Fixed 7-cell looks (mini / arcade / fruit) — a bit slower. */
+/** Fixed-width looks (mini / arcade / fruit): a bit slower. */
 const FRAME_MS_FIXED = 110;
+/** Default strip length for mini / arcade / fruit (cells). Overridable via config. */
+const DEFAULT_CELLS = 10;
+const CELLS_MIN = 4;
+const CELLS_MAX = 40;
 
 type Facing = "right" | "left";
 
@@ -127,13 +130,15 @@ function runTrack(track: number): string[] {
 
 // ── looks ────────────────────────────────────────────────────────────
 
-/** Fixed strip length for mini / arcade / fruit (cells). */
-const FIXED_CELLS = 7;
+function clampCells(n: number): number {
+	if (!Number.isFinite(n)) return DEFAULT_CELLS;
+	return Math.max(CELLS_MIN, Math.min(CELLS_MAX, Math.round(n)));
+}
 
 const LOOKS: Look[] = [
 	{
 		id: "classic",
-		blurb: "Full-width pellet run — dots span the terminal",
+		blurb: "Full-width pellet run, dots span the terminal",
 		message: "waka waka...",
 		fullWidth: true,
 		frames: (track) => runTrack(track),
@@ -193,16 +198,16 @@ const LOOKS: Look[] = [
 	},
 	{
 		id: "mini",
-		blurb: "7-cell pellet run",
+		blurb: "fixed-width pellet run",
 		message: "chomp chomp...",
-		frames: () => runTrack(FIXED_CELLS),
+		frames: (track) => runTrack(track),
 	},
 	{
 		id: "arcade",
-		blurb: "7-cell maze tunnel with blue walls",
+		blurb: "fixed-width maze tunnel with blue walls",
 		message: "insert coin...",
-		frames: () => {
-			const last = FIXED_CELLS - 1;
+		frames: (track) => {
+			const last = track - 1;
 			const frames: string[] = [];
 			const wall = paint(WALL, "│");
 			for (let i = 0; i <= last; i++) {
@@ -216,7 +221,7 @@ const LOOKS: Look[] = [
 					frames.push(`${wall}${mid}${wall}`);
 				}
 			}
-			frames.push(`${wall}${paint(WALL, "≈".repeat(FIXED_CELLS))}${wall}`);
+			frames.push(`${wall}${paint(WALL, "≈".repeat(track))}${wall}`);
 			for (let i = last; i >= 0; i--) {
 				for (const open of [true, false]) {
 					let mid = "";
@@ -233,10 +238,10 @@ const LOOKS: Look[] = [
 	},
 	{
 		id: "fruit",
-		blurb: "7-cell cherry bonus run",
+		blurb: "fixed-width cherry bonus run",
 		message: "fruit bonus...",
-		frames: () => {
-			const last = FIXED_CELLS - 1;
+		frames: (track) => {
+			const last = track - 1;
 			const frames: string[] = [];
 
 			// Rightward: cherry waits at the far end
@@ -253,8 +258,6 @@ const LOOKS: Look[] = [
 					frames.push(row);
 				}
 			}
-			frames.push(`${" ".repeat(Math.max(0, FIXED_CELLS - 3))}${paint(SCORE, "100")}`);
-			frames.push(`${" ".repeat(Math.max(0, FIXED_CELLS - 3))}${paint(SCORE, "100")}`);
 
 			// Leftward: cherry waits at the start
 			for (let i = last; i >= 0; i--) {
@@ -270,26 +273,66 @@ const LOOKS: Look[] = [
 					frames.push(row);
 				}
 			}
-			frames.push(`${paint(SCORE, "300")}${" ".repeat(Math.max(0, FIXED_CELLS - 3))}`);
-			frames.push(`${paint(SCORE, "300")}${" ".repeat(Math.max(0, FIXED_CELLS - 3))}`);
 			return frames;
 		},
 	},
 ];
 
 const LOOK_BY_ID = new Map(LOOKS.map((l) => [l.id, l]));
-/** Looks eligible for rotate/random (excludes off/default). */
-const ROTATE_LOOKS = LOOKS.map((l) => l.id);
+/** Rotate only cycles short looks; full-width classic/chase stay opt-in via /pacman <look>. */
+const ROTATE_LOOKS = LOOKS.filter((l) => !l.fullWidth).map((l) => l.id);
+
+/** Fun working-line blurbs; one is picked at random each agent turn (unless custom message). */
+const MESSAGE_POOL = [
+	"waka waka...",
+	"chomp chomp...",
+	"nom nom nom...",
+	"pellet run...",
+	"extra life...",
+	"maze clear...",
+	"level up...",
+	"thinking in 8-bit...",
+	"chomping tokens...",
+	"munching context...",
+	"dot duty...",
+	"blinky inbound...",
+	"still hungry...",
+	"just one more pellet...",
+	"pac-ing thoughts...",
+	"busy in the maze...",
+	"sampling next token...",
+	"warming up the weights...",
+	"attention is all you need...",
+	"prompt cache go brrr...",
+	"context window snacking...",
+	"tool call pending...",
+	"reasoning tokens burning...",
+	"embedding the maze...",
+	"softmaxing vibes...",
+	"gradient descending...",
+	"hallucinating less... hopefully...",
+	"compacting the snack tray...",
+	"waiting on the model...",
+	"streaming tokens...",
+	"fine-tuning my appetite...",
+	"loading more context...",
+	"thinking tokens go chomp...",
+	"RAG-ing the pellets...",
+	"temperature set to spicy...",
+	"beam search for snacks...",
+];
 
 type Mode = string;
 
 interface PersistedState {
 	mode?: string;
-	/** @deprecated old field — migrated to `rotate` */
+	/** @deprecated old field, migrated to `rotate` */
 	mix?: string;
 	rotate?: boolean;
 	rotateIndex?: number;
 	customMessage?: string;
+	/** Fixed strip length for mini / arcade / fruit (cells). Default 10. */
+	cells?: number;
 }
 
 function statePath(): string {
@@ -312,20 +355,24 @@ function saveState(state: PersistedState): void {
 		mkdirSync(dirname(path), { recursive: true });
 		writeFileSync(path, `${JSON.stringify(state, null, "\t")}\n`, "utf-8");
 	} catch {
-		// Non-fatal — indicator still works without persistence
+		// Non-fatal: indicator still works without persistence
 	}
 }
 
-function resolveTrack(look: Look, message: string): number {
+function resolveTrack(look: Look, message: string, cells: number): number {
 	if (look.fullWidth) return indicatorWidth(message);
-	return FIXED_CELLS;
+	return cells;
 }
 
-function getIndicator(mode: Mode, message: string): WorkingIndicatorOptions | undefined {
+function getIndicator(
+	mode: Mode,
+	message: string,
+	cells: number,
+): WorkingIndicatorOptions | undefined {
 	if (mode === "off") return { frames: [] };
 	const look = LOOK_BY_ID.get(mode);
 	if (!look) return undefined;
-	const track = resolveTrack(look, message);
+	const track = resolveTrack(look, message, cells);
 	const intervalMs = look.fullWidth ? FRAME_MS_FULL : FRAME_MS_FIXED;
 	return { frames: look.frames(track), intervalMs };
 }
@@ -333,26 +380,31 @@ function getIndicator(mode: Mode, message: string): WorkingIndicatorOptions | un
 function describeMode(mode: Mode): string {
 	if (mode === "off") return "hidden";
 	const look = LOOK_BY_ID.get(mode);
-	return look ? `${look.id} — ${look.blurb}` : mode;
+	return look ? `${look.id}: ${look.blurb}` : mode;
 }
 
-function defaultMessageFor(mode: Mode): string | undefined {
-	if (mode === "off") return " ";
-	return LOOK_BY_ID.get(mode)?.message;
+function pickRandomMessage(previous?: string): string {
+	const pool =
+		previous && MESSAGE_POOL.length > 1
+			? MESSAGE_POOL.filter((m) => m !== previous)
+			: MESSAGE_POOL;
+	return pool[Math.floor(Math.random() * pool.length)]!;
 }
 
 function listLooks(): string {
 	const lines = LOOKS.map((l) => {
 		const tag = l.fullWidth ? " (full width)" : "";
-		return `  ${l.id.padEnd(8)} ${l.blurb}${tag}`;
+		const rot = !l.fullWidth ? " · in rotate" : "";
+		return `  ${l.id.padEnd(8)} ${l.blurb}${tag}${rot}`;
 	});
 	return [
 		"Pac-Man looks:",
 		...lines,
 		"",
-		"  rotate   Different look each message (cycle)",
+		"  rotate   Cycle short looks each message (mini/arcade/fruit)",
 		"  off      Hide indicator",
 		"",
+		"Working text is random each run (unless /pacman message …).",
 		"Pick a look name to lock it (stops rotate).",
 	].join("\n");
 }
@@ -376,6 +428,10 @@ export default function (pi: ExtensionAPI) {
 		typeof saved.customMessage === "string" && saved.customMessage.length > 0
 			? saved.customMessage
 			: undefined;
+	let cells =
+		typeof saved.cells === "number" ? clampCells(saved.cells) : DEFAULT_CELLS;
+	/** Last auto-picked blurb (not persisted); used to avoid immediate repeats. */
+	let autoMessage: string = pickRandomMessage();
 	let lastUi: ExtensionUIContext | undefined;
 
 	const persist = () => {
@@ -384,6 +440,7 @@ export default function (pi: ExtensionAPI) {
 			rotate,
 			rotateIndex,
 			customMessage,
+			cells,
 		});
 	};
 
@@ -392,11 +449,22 @@ export default function (pi: ExtensionAPI) {
 		return `ᗧ ${mode}${rotate ? " ↻" : ""}`;
 	};
 
+	const workingMessage = (): string => {
+		if (mode === "off") return " ";
+		if (customMessage) return customMessage;
+		return autoMessage;
+	};
+
+	const refreshAutoMessage = () => {
+		if (customMessage) return;
+		autoMessage = pickRandomMessage(autoMessage);
+	};
+
 	const apply = (ctx: ExtensionContext) => {
 		lastUi = ctx.ui;
-		const message = customMessage ?? defaultMessageFor(mode) ?? "Working...";
-		ctx.ui.setWorkingIndicator(getIndicator(mode, message));
-		ctx.ui.setWorkingMessage(mode === "off" ? " " : message);
+		const message = workingMessage();
+		ctx.ui.setWorkingIndicator(getIndicator(mode, message, cells));
+		ctx.ui.setWorkingMessage(message);
 		ctx.ui.setStatus("pacman-thinking", ctx.ui.theme.fg("dim", statusLabel()));
 		persist();
 	};
@@ -404,30 +472,40 @@ export default function (pi: ExtensionAPI) {
 	const isFullWidthMode = () => LOOK_BY_ID.get(mode)?.fullWidth === true;
 
 	const pickNextRotatedLook = () => {
+		if (ROTATE_LOOKS.length === 0) return;
 		mode = ROTATE_LOOKS[rotateIndex % ROTATE_LOOKS.length]!;
 		rotateIndex++;
 	};
 
 	const reapplyIfFullWidth = () => {
 		if (!lastUi || !isFullWidthMode()) return;
-		const message = customMessage ?? defaultMessageFor(mode) ?? "Working...";
-		lastUi.setWorkingIndicator(getIndicator(mode, message));
+		const message = workingMessage();
+		lastUi.setWorkingIndicator(getIndicator(mode, message, cells));
 	};
 
 	process.stdout.on?.("resize", reapplyIfFullWidth);
 
 	pi.on("session_start", async (_event, ctx) => {
-		// Don't advance rotate here — agent_start picks per message.
+		// Don't advance rotate here; agent_start picks per message.
+		refreshAutoMessage();
 		apply(ctx);
 	});
 
 	pi.on("agent_start", async (_event, ctx) => {
+		// Fresh random blurb every run (unless user set /pacman message)
+		refreshAutoMessage();
 		if (rotate) {
 			pickNextRotatedLook();
 			apply(ctx);
 			return;
 		}
-		if (isFullWidthMode()) apply(ctx);
+		// Always re-apply so the new message (and full-width width) stick
+		apply(ctx);
+	});
+
+	pi.on("session_shutdown", async () => {
+		// Drop the resize listener so reloads don't stack duplicates.
+		process.stdout.off?.("resize", reapplyIfFullWidth);
 	});
 
 	pi.registerCommand("pacman", {
@@ -435,15 +513,16 @@ export default function (pi: ExtensionAPI) {
 		handler: async (args, ctx) => {
 			const raw = args.trim();
 			if (!raw) {
-				const msg = customMessage ?? defaultMessageFor(mode) ?? "Working...";
+				const msg = workingMessage();
 				const extra = isFullWidthMode()
 					? ` · width ${indicatorWidth(msg)} cells`
 					: LOOK_BY_ID.has(mode)
-						? ` · width ${FIXED_CELLS} cells`
+						? ` · width ${cells} cells`
 						: "";
-				const rotInfo = rotate ? " · rotate on" : "";
+				const rotInfo = rotate ? " · rotate on (short looks)" : "";
+				const msgMode = customMessage ? "custom" : "auto";
 				ctx.ui.notify(
-					`Pac-Man: ${describeMode(mode)}${rotInfo} · message: "${msg}"${extra}`,
+					`Pac-Man: ${describeMode(mode)}${rotInfo} · cells ${cells} · message (${msgMode}): "${msg}"${extra}`,
 					"info",
 				);
 				return;
@@ -470,24 +549,47 @@ export default function (pi: ExtensionAPI) {
 			if (head === "message") {
 				const text = rest.join(" ").trim();
 				customMessage = text.length > 0 ? text : undefined;
+				if (!customMessage) refreshAutoMessage();
 				apply(ctx);
 				ctx.ui.notify(
 					customMessage
-						? `Working message set to: ${customMessage}`
-						: "Working message reset to mode default",
+						? `Working message locked to: ${customMessage}`
+						: `Working message is auto again (now: "${autoMessage}")`,
 					"info",
 				);
 				return;
 			}
 
+			if (head === "cells" || head === "width") {
+				const rawN = rest[0]?.trim();
+				if (!rawN) {
+					ctx.ui.notify(
+						`Pac-Man cells: ${cells} (default ${DEFAULT_CELLS}, range ${CELLS_MIN}–${CELLS_MAX}). Set with /pacman cells <n> or in ~/.pi/agent/pacman-thinking.json`,
+						"info",
+					);
+					return;
+				}
+				const n = Number(rawN);
+				if (!Number.isFinite(n)) {
+					ctx.ui.notify(`Invalid cells "${rawN}". Use a number ${CELLS_MIN}–${CELLS_MAX}.`, "error");
+					return;
+				}
+				cells = clampCells(n);
+				apply(ctx);
+				ctx.ui.notify(`Pac-Man short-look width: ${cells} cells`, "info");
+				return;
+			}
+
 			if (head === "rotate" || head === "cycle") {
 				rotate = true;
+				// Only short looks participate; jump into that cycle cleanly
 				const idx = ROTATE_LOOKS.indexOf(mode);
 				rotateIndex = idx >= 0 ? idx : 0;
 				pickNextRotatedLook();
+				refreshAutoMessage();
 				apply(ctx);
 				ctx.ui.notify(
-					`Pac-Man rotate on — cycles each message (now: ${mode}). Pick a look to lock it.`,
+					`Pac-Man rotate on. Short looks only: ${ROTATE_LOOKS.join(", ")} (now: ${mode}).`,
 					"info",
 				);
 				return;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pi-extensions/pi-pacman",
-	"version": "0.1.0",
-	"description": "Pac-Man working indicator for pi — replaces the streaming spinner with pellet runs, ghost chases, and more",
+	"version": "0.1.1",
+	"description": "Pac-Man working indicator for pi: replaces the streaming spinner with pellet runs, ghost chases, and more",
 	"type": "module",
 	"keywords": [
 		"pi-package",
@@ -14,13 +14,13 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/smarzban/pi-extentions.git",
+		"url": "git+https://github.com/smarzban/pi-extensions.git",
 		"directory": "packages/pi-pacman"
 	},
 	"bugs": {
-		"url": "https://github.com/smarzban/pi-extentions/issues"
+		"url": "https://github.com/smarzban/pi-extensions/issues"
 	},
-	"homepage": "https://github.com/smarzban/pi-extentions/tree/main/packages/pi-pacman#readme",
+	"homepage": "https://github.com/smarzban/pi-extensions/tree/main/packages/pi-pacman#readme",
 	"engines": {
 		"node": ">=18.0.0"
 	},
@@ -29,6 +29,9 @@
 			"./index.ts"
 		]
 	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*"
+	},
 	"files": [
 		"index.ts",
 		"README.md",