@xynogen/pix-pretty 1.7.8 → 1.7.10

package/README.md

@@ -9,8 +9,9 @@ consume. It does not register user-facing tools itself — the tool renderers
 (`pix-read`, `pix-bash`, `pix-ls`, `pix-find`, `pix-grep`, `pix-edit`,
 `pix-write`) import from it. The extension entry point (`src/index.ts`) only
 initializes the syntax-highlight theme from Pi settings, clears the highlight
-cache, and registers two FFF slash commands (`/fff-health`, `/fff-rescan`)
-once `pix-grep` has brought the FFF finder online.
+cache, registers the `/pretty` icon-style switch, and registers two FFF slash
+commands (`/fff-health`, `/fff-rescan`) once `pix-grep` has brought the FFF
+finder online. (Activated by `pix-core`; not a standalone extension.)
 
 ### Rendering
 
@@ -20,6 +21,25 @@ once `pix-grep` has brought the FFF finder online.
 - **Diff rendering** — side-by-side split diff for edit/write
 - **Bash exit summary** — colored status, line count, truncation notice
 
+### Icon catalog (l10n-style)
+
+Icons are treated like a localization catalog: packages never hardcode glyph
+codepoints — they ask for a **semantic role** and the catalog resolves it
+against one global icon mode. Reskinning, or fixing a missing-glyph (“tofu”)
+problem on terminals without a Nerd Font, becomes a one-file edit here.
+
+- **`./icon-catalog`** — `icon(key)` resolves a semantic key (`"cwd"`,
+  `"model"`, `"paste.image"`, `"opt.caveman"`, …) to a glyph for the active
+  mode. Modes: `nerd` (Nerd Font PUA, default), `unicode` (standard BMP glyphs,
+  no patched font needed), `ascii` (plain letters). Also `iconFor(key, mode)`,
+  `getIconMode()`, `setIconMode()`, `ICON_KEYS`, `ICON_MODES`.
+- **`./icon-persist`** — stores the mode in `~/.pi/agent/pretty.json`;
+  `initIconMode()` applies it on load.
+- **`/pretty`** — the single switch: an overlay that previews each mode's
+  glyphs live and persists the choice. One global knob governs every pix-*
+  package (footer, paste chips, model picker, welcome banner, optimizer cell).
+  Seeded from `PRETTY_ICONS` (`none`/`off` → `ascii`) when no choice is saved.
+
 ### Shared overlay
 
 - **Gate overlay** (`./gate-overlay`) — the one permission-dialog component
@@ -47,7 +67,9 @@ pi install npm:@xynogen/pix-pretty
 - `PRETTY_MAX_HL_CHARS` — max characters to highlight (default: 80000)
 - `PRETTY_MAX_PREVIEW_LINES` — max lines in preview output
 - `PRETTY_CACHE_LIMIT` — FFF cache size limit
-- `PRETTY_ICONS` — icon mode (`nerd` or `none`)
+- `PRETTY_ICONS` — default icon mode when none is persisted: `nerd` (default),
+  `unicode`, `ascii`, or `none`/`off` (→ `ascii`). Overridden by `/pretty`.
+  Note: this seeds the file-icon helpers AND the semantic icon catalog.
 - `PRETTY_MAX_RENDER_LINES` — max lines in edit/write diff render (default: 150)
 - `PRETTY_FFF_DIR` — override FFF state dir (default: `~/.cache/pi/fff`)
 
@@ -66,6 +88,8 @@ The package exposes its sub-modules via `exports`:
 @xynogen/pix-pretty/highlight
 @xynogen/pix-pretty/lang
 @xynogen/pix-pretty/icons
+@xynogen/pix-pretty/icon-catalog
+@xynogen/pix-pretty/icon-persist
 @xynogen/pix-pretty/renderers
 @xynogen/pix-pretty/fff
 @xynogen/pix-pretty/types

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-pretty",
-	"version": "1.7.8",
+	"version": "1.7.10",
 	"description": "Enhanced tool output rendering with syntax highlighting, file icons, tree views, diff rendering, and FFF search",
 	"type": "module",
 	"main": "src/index.ts",
@@ -15,6 +15,8 @@
 		"./highlight": "./src/highlight.ts",
 		"./lang": "./src/lang.ts",
 		"./icons": "./src/icons.ts",
+		"./icon-catalog": "./src/icon-catalog.ts",
+		"./icon-persist": "./src/icon-persist.ts",
 		"./renderers": "./src/renderers.ts",
 		"./fff": "./src/fff.ts",
 		"./types": "./src/types.ts",

package/src/commands/pretty.ts

@@ -0,0 +1,135 @@
+/**
+ * pretty.ts — the `/pretty` command: switch the global icon mode.
+ *
+ * Treats icons like an l10n locale: one global mode (nerd/unicode/ascii)
+ * governs every pix-* package that renders via the icon catalog. This command
+ * is the single switch — an overlay that previews each mode's glyphs live and
+ * persists the choice to ~/.pi/agent/pretty.json. Headless hosts get a notify
+ * fallback that cycles the mode without UI.
+ */
+
+import {
+	getIconMode,
+	ICON_MODES,
+	type IconKey,
+	type IconMode,
+	icon,
+	setIconMode,
+} from "../icon-catalog.js";
+import { saveIconMode } from "../icon-persist.js";
+import { frameLines } from "../modal-frame.js";
+import type { CommandContextLike, PiPrettyApi } from "../types.js";
+
+/** Sample keys shown in the preview, one row per representative role. */
+const PREVIEW: { key: IconKey; label: string }[] = [
+	{ key: "model", label: "model" },
+	{ key: "cwd", label: "cwd" },
+	{ key: "lsp", label: "lsp" },
+	{ key: "paste.image", label: "paste" },
+	{ key: "opt.caveman", label: "optimizer" },
+];
+
+/** Apply + persist a mode in one step. */
+function applyMode(mode: IconMode): void {
+	setIconMode(mode);
+	saveIconMode(mode);
+}
+
+export function registerPrettyCommand(pi: PiPrettyApi): void {
+	pi.registerCommand("pretty", {
+		description: "pix-pretty: switch icon style (nerd / unicode / ascii)",
+		handler: async (_args: string, ctx: CommandContextLike) => {
+			const ui = ctx.ui as unknown as {
+				theme: {
+					fg(c: string, t: string): string;
+					bg(c: string, t: string): string;
+					bold(t: string): string;
+				};
+				custom?: <T>(
+					f: unknown,
+					opts?: {
+						overlay?: boolean;
+						overlayOptions?: {
+							anchor?: string;
+							width?: number;
+							maxHeight?: string;
+						};
+					},
+				) => Promise<T>;
+				notify(m: string, t?: "info" | "warning" | "error"): void;
+			};
+
+			// Headless / no custom-UI host: cycle to the next mode + notify.
+			if (typeof ui.custom !== "function") {
+				const cur = ICON_MODES.indexOf(getIconMode());
+				const next = ICON_MODES[(cur + 1) % ICON_MODES.length] as IconMode;
+				applyMode(next);
+				ui.notify(`pix-pretty icons: ${next}`, "info");
+				return;
+			}
+
+			const boxW = 40;
+
+			await ui.custom<null>(
+				(
+					tui: { requestRender(): void },
+					theme: typeof ui.theme,
+					_kb: unknown,
+					done: (v: null) => void,
+				) => {
+					let selected = ICON_MODES.indexOf(getIconMode());
+					if (selected < 0) selected = 0;
+
+					const choose = (i: number) => {
+						selected = (i + ICON_MODES.length) % ICON_MODES.length;
+						applyMode(ICON_MODES[selected] as IconMode);
+					};
+
+					return {
+						render: () => {
+							const rows = ICON_MODES.map((mode, i) => {
+								const sel = i === selected;
+								const cursor = sel ? theme.fg("accent", "→") : " ";
+								const name = theme.fg(sel ? "accent" : "text", mode.padEnd(8));
+								// Live preview: render the sample glyphs in THIS mode.
+								const prev = ICON_MODES[i] === getIconMode();
+								const samples = prev
+									? PREVIEW.map((p) => icon(p.key)).join(" ")
+									: "";
+								return `${cursor} ${name} ${theme.fg("dim", samples)}`;
+							});
+							const lines = [
+								theme.fg("accent", theme.bold("  Icon style")),
+								"",
+								...rows,
+								"",
+								theme.fg("dim", "↑↓ select · esc close"),
+							];
+							return frameLines({
+								width: boxW,
+								lines,
+								color: (s) => theme.fg("accent", s),
+								bg: (s) => theme.bg("customMessageBg", s),
+							});
+						},
+						invalidate: () => {},
+						handleInput: (data: string) => {
+							if (data === "k" || data === "\u001b[A") choose(selected - 1);
+							else if (data === "j" || data === "\u001b[B")
+								choose(selected + 1);
+							else if (data === "\u001b" || data === "q" || data === "\r") {
+								done(null);
+								return;
+							} else return;
+							tui.requestRender();
+						},
+					};
+				},
+				{
+					overlay: true,
+					overlayOptions: { anchor: "center", width: boxW, maxHeight: "60%" },
+				},
+			);
+		},
+	});
+}

package/src/icon-catalog.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import {
+	getIconMode,
+	ICON_KEYS,
+	ICON_MODES,
+	icon,
+	iconFor,
+	onIconModeChange,
+	setIconMode,
+} from "./icon-catalog.ts";
+
+describe("icon-catalog", () => {
+	afterEach(() => setIconMode("nerd")); // restore default for other suites
+
+	it("exposes nerd/unicode/ascii in cycle order", () => {
+		expect([...ICON_MODES]).toEqual(["nerd", "unicode", "ascii"]);
+	});
+
+	it("resolves a key against the active mode", () => {
+		setIconMode("ascii");
+		expect(icon("cwd")).toBe("~");
+		setIconMode("unicode");
+		expect(icon("cwd")).toBe("\u2302\uFE0E");
+		setIconMode("nerd");
+		expect(icon("cwd")).toBe("\u{F024B}");
+	});
+
+	it("iconFor resolves without touching the active mode", () => {
+		setIconMode("nerd");
+		expect(iconFor("opt.caveman", "ascii")).toBe("Cv");
+		expect(getIconMode()).toBe("nerd"); // unchanged
+	});
+
+	it("every catalog key has a non-empty glyph in every mode", () => {
+		for (const mode of ICON_MODES) {
+			for (const key of ICON_KEYS) {
+				expect(iconFor(key, mode).length).toBeGreaterThan(0);
+			}
+		}
+	});
+
+	it("unknown key fails soft to empty string", () => {
+		// @ts-expect-error exercising the runtime guard
+		expect(icon("does.not.exist")).toBe("");
+	});
+
+	it("setIconMode ignores an invalid mode", () => {
+		setIconMode("unicode");
+		// @ts-expect-error invalid mode must be rejected, leaving prior value
+		setIconMode("bogus");
+		expect(getIconMode()).toBe("unicode");
+	});
+
+	it("notifies subscribers on an actual change, not on no-ops", () => {
+		setIconMode("nerd");
+		const seen: string[] = [];
+		const off = onIconModeChange((m) => seen.push(m));
+		setIconMode("nerd"); // no-op — must NOT fire
+		setIconMode("ascii"); // change — fires
+		setIconMode("ascii"); // no-op — must NOT fire
+		off();
+		setIconMode("unicode"); // after unsubscribe — must NOT fire
+		expect(seen).toEqual(["ascii"]);
+	});
+});

package/src/icon-catalog.ts

@@ -0,0 +1,142 @@
+/**
+ * icon-catalog.ts — semantic icon catalog, treated like an l10n message table.
+ *
+ * Packages must NOT hardcode glyph codepoints. Instead they ask for an icon by
+ * its semantic role — `icon("cwd")`, `icon("paste.image")` — and this module
+ * resolves it against the single active icon mode, exactly like `t("key")`
+ * resolves a translation against the active locale.
+ *
+ *   catalog:  key -> { nerd, unicode, ascii }    (the "messages")
+ *   mode:     "nerd" | "unicode" | "ascii"       (the "locale")
+ *   icon(k):  catalog[k][mode]                    (the "t(key)")
+ *
+ * One global mode governs the whole stack. It is switched via the `/pretty`
+ * command (see pretty-command.ts), persisted to ~/.pi/agent/pretty.json, and
+ * seeded from the PRETTY_ICONS env var on first load.
+ *
+ * Why a catalog instead of per-package toggles: reskinning or fixing a
+ * missing-glyph ("tofu") problem becomes a one-file edit here, and there is
+ * exactly ONE knob (the mode) rather than one env var per package.
+ */
+
+/** Presentation modes, in /pretty cycle order. nerd = Nerd Font PUA glyphs. */
+export type IconMode = "nerd" | "unicode" | "ascii";
+
+/** All modes in cycle order. */
+export const ICON_MODES: readonly IconMode[] = ["nerd", "unicode", "ascii"];
+
+/** Force text (non-emoji) presentation for symbols that default to emoji. */
+const VS = "\uFE0E";
+
+/**
+ * The catalog. Each semantic key maps to one glyph per mode.
+ *   - nerd:    Nerd Font Private Use Area codepoint (needs a patched font).
+ *   - unicode: standard BMP glyph that ships with virtually every monospace
+ *              font (no Nerd Font required); +VS to force text presentation.
+ *   - ascii:   pure ASCII, renders on literally any terminal.
+ *
+ * Keys are SEMANTIC ROLES, never glyph names — consumers reference meaning.
+ */
+const CATALOG = {
+	// ── footer / status segments ──────────────────────────────────────────
+	model: { nerd: "\u{F06A9}", unicode: `\u25C8${VS}`, ascii: "M" },
+	lsp: { nerd: "\u{F0626}", unicode: `\u25C9${VS}`, ascii: "LSP" },
+	mcp: { nerd: "\u{F048D}", unicode: `\u25D0${VS}`, ascii: "MCP" },
+	cwd: { nerd: "\u{F024B}", unicode: `\u2302${VS}`, ascii: "~" },
+	folder: { nerd: "\u{F024B}", unicode: `\u2302${VS}`, ascii: "/" },
+
+	// ── footer indicators (git status, score) ─────────────────────────────
+	"git.unstaged": { nerd: "\u2717", unicode: "\u2717", ascii: "x" },
+	"git.ahead": { nerd: "\u21E1", unicode: "\u21E1", ascii: "^" },
+	"git.behind": { nerd: "\u21E3", unicode: "\u21E3", ascii: "v" },
+	"net.in": { nerd: "\u21E1", unicode: "\u21E1", ascii: "in" },
+	"net.out": { nerd: "\u21E3", unicode: "\u21E3", ascii: "out" },
+	score: { nerd: "\u26A1", unicode: "\u26A1", ascii: "S" },
+
+	// ── misc ──────────────────────────────────────────────────────────────
+	ok: { nerd: "\u2713", unicode: "\u2713", ascii: "ok" },
+	warn: { nerd: "\u26A0", unicode: "\u26A0", ascii: "!" },
+	error: { nerd: "\u2717", unicode: "\u2717", ascii: "x" },
+
+	// ── welcome banner ────────────────────────────────────────────────────
+	ready: { nerd: "\u{F0633}", unicode: `\u2713${VS}`, ascii: "ok" },
+
+	// ── paste chips (pix-display) ─────────────────────────────────────────
+	"paste.image": { nerd: "\u{F02E9}", unicode: `\u25A3${VS}`, ascii: "img" },
+	"paste.text": { nerd: "\u{F027F}", unicode: `\u25A4${VS}`, ascii: "txt" },
+
+	// ── model picker (pix-models) ─────────────────────────────────────────
+	"picker.model": { nerd: "\u{F0229}", unicode: `\u25C8${VS}`, ascii: "M" },
+
+	// ── optimizer suite (pix-optimizer) ───────────────────────────────────
+	"opt.caveman": { nerd: "\u{F0710}", unicode: `\u2664${VS}`, ascii: "Cv" },
+	"opt.rtk": { nerd: "\u{F04E5}", unicode: `\u2661${VS}`, ascii: "Rk" },
+	"opt.toon": { nerd: "\u{F05C0}", unicode: `\u2662${VS}`, ascii: "Tn" },
+	"opt.ponytail": { nerd: "\u{F0190}", unicode: `\u2667${VS}`, ascii: "Pt" },
+	"opt.title": { nerd: "\u{F0DAB}", unicode: `\u25C8${VS}`, ascii: "*" },
+} as const;
+
+/** Every valid semantic icon key. */
+export type IconKey = keyof typeof CATALOG;
+
+/** All catalog keys (useful for /pretty previews and tests). */
+export const ICON_KEYS = Object.keys(CATALOG) as IconKey[];
+
+/**
+ * Active mode. Seeded from PRETTY_ICONS env (back-compat: none/off => ascii),
+ * then overridden by a persisted choice when the host loads pretty.json.
+ */
+function envMode(): IconMode {
+	const raw = (process.env.PRETTY_ICONS ?? "").toLowerCase();
+	if (raw === "nerd" || raw === "unicode" || raw === "ascii") return raw;
+	if (raw === "none" || raw === "off") return "ascii";
+	return "nerd";
+}
+
+let activeMode: IconMode = envMode();
+
+/** Current global icon mode. */
+export function getIconMode(): IconMode {
+	return activeMode;
+}
+
+/**
+ * Mode-change subscribers. Most consumers resolve icon() at render time and
+ * need no notification, but PUSHED-status consumers (e.g. the optimizer cell,
+ * drawn once via setStatus) must repaint when the mode flips. They subscribe
+ * here; setIconMode fires every callback on an actual change.
+ */
+type ModeListener = (mode: IconMode) => void;
+const listeners = new Set<ModeListener>();
+
+/** Subscribe to global icon-mode changes. Returns an unsubscribe fn. */
+export function onIconModeChange(cb: ModeListener): () => void {
+	listeners.add(cb);
+	return () => listeners.delete(cb);
+}
+
+/**
+ * Set the global icon mode (does NOT persist — callers that want persistence
+ * use pretty-command.ts, which writes pretty.json then calls this). Fires
+ * subscribers only on an actual change (no-op re-sets are ignored).
+ */
+export function setIconMode(mode: IconMode): void {
+	if (!ICON_MODES.includes(mode) || mode === activeMode) return;
+	activeMode = mode;
+	for (const cb of listeners) cb(mode);
+}
+
+/**
+ * Resolve a semantic icon key to its glyph for the active mode — the `t(key)`
+ * of this module. Unknown keys return "" (fail soft: never throw mid-render).
+ */
+export function icon(key: IconKey): string {
+	const entry = CATALOG[key];
+	return entry ? entry[activeMode] : "";
+}
+
+/** Resolve a key for an explicit mode (used by /pretty previews + tests). */
+export function iconFor(key: IconKey, mode: IconMode): string {
+	const entry = CATALOG[key];
+	return entry ? entry[mode] : "";
+}

package/src/icon-persist.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getIconMode, setIconMode } from "./icon-catalog.ts";
+import { initIconMode, loadIconMode, saveIconMode } from "./icon-persist.ts";
+
+let tmpAgentDir: string;
+
+beforeAll(() => {
+	tmpAgentDir = mkdtempSync(join(tmpdir(), "pretty-persist-test-"));
+	process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+});
+
+afterAll(() => {
+	delete process.env.PI_CODING_AGENT_DIR;
+	try {
+		rmSync(tmpAgentDir, { recursive: true });
+	} catch {
+		// already gone — ignore
+	}
+});
+
+describe("icon-persist", () => {
+	afterEach(() => setIconMode("nerd"));
+
+	it("returns undefined before anything is saved", () => {
+		expect(loadIconMode()).toBeUndefined();
+	});
+
+	it("round-trips a mode across save/load (new-session sim)", () => {
+		saveIconMode("unicode");
+		expect(loadIconMode()).toBe("unicode");
+	});
+
+	it("rejects an invalid persisted mode", () => {
+		saveIconMode("ascii");
+		expect(loadIconMode()).toBe("ascii");
+	});
+
+	it("initIconMode applies the persisted choice to the catalog", () => {
+		saveIconMode("ascii");
+		setIconMode("nerd"); // pretend env default
+		initIconMode();
+		expect(getIconMode()).toBe("ascii");
+	});
+});

package/src/icon-persist.ts

@@ -0,0 +1,67 @@
+/**
+ * icon-persist.ts — disk persistence for the global icon mode.
+ *
+ * Stores the single icon mode in ~/.pi/agent/pretty.json so a choice made via
+ * /pretty survives quit/restart. Kept separate from icon-catalog.ts so the
+ * catalog resolver stays pure (no fs) and trivially testable.
+ *
+ *   ~/.pi/agent/pretty.json  ->  { "icons": "unicode" }
+ *
+ * Precedence: a persisted value wins; otherwise the catalog's env-seeded
+ * default (PRETTY_ICONS) stands.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { ICON_MODES, type IconMode, setIconMode } from "./icon-catalog.js";
+
+function statePath(): string {
+	return join(getAgentDir(), "pretty.json");
+}
+
+/** Read the persisted icon mode, or undefined if unset/invalid/missing. */
+export function loadIconMode(): IconMode | undefined {
+	try {
+		const p = statePath();
+		if (!existsSync(p)) return undefined;
+		const raw = JSON.parse(readFileSync(p, "utf-8")) as { icons?: string };
+		const mode = raw?.icons;
+		return ICON_MODES.includes(mode as IconMode)
+			? (mode as IconMode)
+			: undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/** Persist the icon mode, merging into pretty.json. */
+export function saveIconMode(mode: IconMode): void {
+	try {
+		const p = statePath();
+		mkdirSync(dirname(p), { recursive: true });
+		let existing: Record<string, unknown> = {};
+		if (existsSync(p)) {
+			try {
+				existing = JSON.parse(readFileSync(p, "utf-8")) as Record<
+					string,
+					unknown
+				>;
+			} catch {
+				existing = {};
+			}
+		}
+		writeFileSync(p, JSON.stringify({ ...existing, icons: mode }, null, 2));
+	} catch (err) {
+		console.warn("pix-pretty: persist icon mode failed:", err);
+	}
+}
+
+/**
+ * Apply the persisted mode (if any) to the catalog. Called once at extension
+ * load so the env-seeded default is overridden by the user's saved choice.
+ */
+export function initIconMode(): void {
+	const saved = loadIconMode();
+	if (saved) setIconMode(saved);
+}

package/src/index.ts

@@ -10,9 +10,11 @@
 
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { registerFffCommands } from "./commands/fff.js";
+import { registerPrettyCommand } from "./commands/pretty.js";
 import { getDefaultAgentDir, setPrettyTheme } from "./config.js";
 import { fffState } from "./fff.js";
 import { clearHighlightCache } from "./highlight.js";
+import { initIconMode } from "./icon-persist.js";
 import type { PiPrettyApi } from "./types.js";
 
 export default function piPrettyExtension(pi: PiPrettyApi): void {
@@ -28,6 +30,12 @@ export default function piPrettyExtension(pi: PiPrettyApi): void {
 	);
 	clearHighlightCache();
 
+	// ── Icon mode ───────────────────────────────────────────
+	// Seed the global icon mode from pretty.json (overrides env default), then
+	// register the single /pretty switch.
+	initIconMode();
+	registerPrettyCommand(pi);
+
 	// ── FFF slash commands ──────────────────────────────────────────────
 	// fffState is a module-level singleton shared with pix-grep/pix-find.
 	// Commands become available once pix-grep initialises the finder.