@xynogen/pix-pretty 1.7.7 → 1.7.9

package/README.md

@@ -1,38 +1,59 @@
 # pix-pretty
 
-Complete rendering and formatting solution for Pi Coding Agent with syntax highlighting, file icons, tree views, FFF search, paste chip formatting, and reasoning tag cleanup.
-
-## Features
-
-### Tool Output Rendering
-
-- **Syntax highlighting** - Uses `cli-highlight` (highlight.js-backed) for code blocks
-- **File icons** - Visual file type indicators in ls/find output
-- **Tree views** - Hierarchical directory display
-- **FFF search** - Fast full-text search integration with `@ff-labs/fff-node`
-- **Diff rendering** - Enhanced git diff and edit/write tool output
-- **Image metadata** - Display image dimensions and format info
-- **Bash exit summary** - Command status and timing info
-
-### Paste Chip Formatting
-
-- **Image path collapsing** - Converts `/tmp/pi-clipboard-abc.png` → `[paste image #1]`
-- **Text paste markers** - Long pasted text → `[paste text +42 lines]`
-- **Atomic deletion** - Delete entire paste markers as single units
-- **Type-aware labels** - Visual distinction between image and text pastes
-
-### Permission Dialog Overlay
-
-- **Shared gate overlay** - `showOverlay(ui, config)` (export `./gate-overlay`) is the one permission-dialog component used by both `pix-gate` and `pix-sudo`. Two modes: `mode:"confirm"` shows a SelectList only; `mode:"sudo"` shows a SelectList then a masked password stage. Returns `{ action: "approved" | "denied" | "timeout", password? }`. All dialogs are padded (`Box` `paddingX=2`, `paddingY=1`). The simpler `./confirm` export stays for plain boolean Yes/No prompts — `gate-overlay` is its richer multi-choice, password-capable sibling.
-
-### Reasoning Tag Rendering
-
-- **Live streaming** - Splits `<think>`/`<thinking>` regions into native Pi `thinking` content blocks token-by-token during streaming
-- **Finalized cleanup** - On `message_end`, re-splits every affected text block for persistence (the finalized message bypasses the live rebuild)
-- **Partial-tag safety** - Strips trailing half-streamed tags (e.g. `<thin`) so they never flash as literal text
-- **Visual distinction** - Uses Pi's native `thinking` block rendering (dim + italic via `thinkingText` theme token) — no ANSI injection, no markdown blockquote shim
-
-## Installation
+Rendering and formatting library for Pi Coding Agent with syntax highlighting, file icons, tree views, FFF search integration, and gate-dialog overlay.
+
+## What it does
+
+This package is a **library + a small extension** that other pix packages
+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, 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
+
+- **Syntax highlighting** — `cli-highlight` (highlight.js-backed)
+- **File icons** — type-aware icons in ls/find output
+- **Tree views** — hierarchical directory display for ls
+- **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
+  shared by `pix-gate` and `pix-sudo`. Two modes: `confirm` (SelectList) and
+  `sudo` (SelectList + masked password). Returns
+  `{ action: "approved" | "denied" | "timeout", password? }`. Padded with
+  `Box` `paddingX=2`, `paddingY=1`. The simpler `./confirm` export is the
+  plain boolean Yes/No dialog.
+
+UI features that used to live here have moved to [`pix-display`](packages/pix-display):
+paste chip rendering and reasoning-tag (`<think>`/`<thinking>`) → native
+`thinking` content blocks.
+
+## Install
 
 ```bash
 pi install npm:@xynogen/pix-pretty
@@ -42,40 +63,42 @@ pi install npm:@xynogen/pix-pretty
 
 ### Environment Variables
 
-**Tool rendering:**
+- `PRETTY_THEME` — color theme for syntax highlighting
+- `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` — 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`)
 
-- `PRETTY_THEME` - Color theme for syntax highlighting
-- `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` - Enable/disable file icons
-- `PRETTY_DISABLE_TOOLS` - Comma-separated list of tools to skip rendering
-- `PRETTY_IMAGE_PROTOCOL` - Protocol for image display (tmux passthrough)
-- `PRETTY_FFF_DIR` - Override FFF state dir (default: `~/.cache/pi/fff`)
+## Public exports
 
-## Architecture
+The package exposes its sub-modules via `exports`:
 
-This package combines two rendering systems:
-
-1. **Theme + FFF commands** (`src/index.ts`) - Initialises syntax-highlight theme from Pi settings, clears highlight cache, and registers FFF slash commands. Tool renderers live in the standalone `pix-{read,bash,ls,find,grep,edit,write}` packages — each self-registers via its own Pi extension entry point.
-2. **Paste chip formatting** (`src/paste-chips.ts`) - Custom editor component for paste markers.
-3. **Reasoning tag rendering** (`src/thinking.ts`) - Converts leaked `<think>`/`<thinking>` tags into native Pi `thinking` content blocks (dim + italic via `thinkingText` theme token).
-
-Both work independently but complement each other for a cohesive visual experience.
-
-## Origin
-
-Tool rendering replaced `npm:@heyhuynhgiabuu/pi-pretty` (which was previously replaced by `npm:@heyhuynhgiabuu/pi-diff`). This package is a clean reimplementation — no code was copied directly. Developed independently; changes are not submitted back and upstream changes are not pulled in.
-
-Key divergences from upstream:
-
-1. **Highlight engine: shiki → cli-highlight** - Simpler, no WASM, synchronous
-2. **FFF state dir** - `~/.pi/agent/pi-pretty/fff` → `~/.cache/pi/fff` (XDG cache)
-3. **Split diff view for edit/write tools** - Full side-by-side diff with gutter, line numbers, syntax highlighting
-4. **Paste chip formatting** - Custom editor component for Pi's paste marker system (not in upstream)
-5. **Reasoning tag rendering** - Converts leaked `<think>`/`<thinking>` tags into native Pi `thinking` content blocks (not in upstream)
-
-Paste chip formatting and reasoning tag rendering are original additions with no upstream equivalent.
+```
+@xynogen/pix-pretty            (default — extension entry)
+@xynogen/pix-pretty/ansi
+@xynogen/pix-pretty/confirm
+@xynogen/pix-pretty/progress
+@xynogen/pix-pretty/config
+@xynogen/pix-pretty/diff
+@xynogen/pix-pretty/diff-render
+@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
+@xynogen/pix-pretty/utils
+@xynogen/pix-pretty/resize
+@xynogen/pix-pretty/context
+@xynogen/pix-pretty/gate-overlay
+@xynogen/pix-pretty/modal-frame
+```
 
 ## Full distro
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@xynogen/pix-pretty",
-	"version": "1.7.7",
-	"description": "Enhanced tool output rendering with syntax highlighting, file icons, tree views, FFF search, and paste chip formatting",
+	"version": "1.7.9",
+	"description": "Enhanced tool output rendering with syntax highlighting, file icons, tree views, diff rendering, and FFF search",
 	"type": "module",
 	"main": "src/index.ts",
 	"exports": {
@@ -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/README.md

@@ -1,66 +1,36 @@
-# pretty (vendored)
+# pix-pretty/src
 
-Local fork of [`@heyhuynhgiabuu/pi-pretty`](https://github.com/buddingnewinsights/pi-pretty)
-(v0.5.1). Enhances built-in `read` / `bash` / `ls` / `find` / `grep` /
-`multi_grep` tool output with syntax highlighting, file icons, tree views, and
-FFF-backed search.
+> **Historical doc — kept for reference only.**
+>
+> This file originally described pix-pretty as a vendored fork of
+> `@heyhuynhgiabuu/pi-pretty`. That is no longer accurate: pix-pretty has
+> been completely reimplemented. The current source layout, exports, and
+> dependency graph live in the package-level [`README.md`](../README.md).
+>
+> The notes below remain only as a record of two behavioral decisions that
+> differ from the original upstream; both are still in force.
 
-## Why vendored
+## Behavioral decisions that survive the rewrite
 
-We need two behavioral changes the upstream package does not expose as config,
-so the source is copied here 1:1 and patched:
+These two changes were made when pix-pretty was a vendored fork and are
+preserved in the reimplementation:
 
 1. **Highlight engine: shiki → cli-highlight.**
-   Upstream uses `@shikijs/cli` (`codeToANSI`, TextMate grammars + WASM).
-   This fork uses [`cli-highlight`](https://www.npmjs.com/package/cli-highlight)
-   (highlight.js-backed, synchronous). The `hlBlock` interface, language table,
+   Upstream used `@shikijs/cli` (`codeToANSI`, TextMate grammars + WASM).
+   The reimplementation uses [`cli-highlight`](https://www.npmjs.com/package/cli-highlight)
+   (highlight.js-backed, synchronous). `HLJS_LANG_ALIAS` maps shiki-style ids
+   (`tsx`, `jsx`, `jsonc`, `mdx`, `make`, `svelte`, `vue`) onto
+   highlight.js-supported ids. The `hlBlock` interface, language table,
    line-number layout, and low-contrast normalization are unchanged.
 
 2. **FFF state dir: `~/.pi/agent/pi-pretty/fff` → `~/.cache/pi/fff`.**
-   `getPiPrettyFffDir()` now resolves to `$XDG_CACHE_HOME/pi/fff`
-   (default `~/.cache/pi/fff`), overridable with `PRETTY_FFF_DIR`.
+   `getPiPrettyFffDir()` resolves to `$XDG_CACHE_HOME/pi/fff` (default
+   `~/.cache/pi/fff`), overridable with `PRETTY_FFF_DIR`.
 
-Everything else (bash exit summary, ls tree, find grouping, grep highlighting,
-image metadata, tmux passthrough, `/fff-health`, `/fff-rescan`, multi_grep
-ripgrep fallback) is byte-for-byte upstream.
+## What moved out
 
-## Diff vs upstream
+- **Paste chip formatting** → [`@xynogen/pix-display`](../pix-display)
+- **Reasoning tag (`<think>`/`<thinking>`) rendering** →
+  [`@xynogen/pix-display`](../pix-display)
 
-- `index.ts`
-  - imports: `@shikijs/cli` + `shiki` types → `cli-highlight` (lazy `require`)
-    with local `BundledLanguage`/`BundledTheme = string` aliases.
-  - `FORCE_COLOR=3` default before chalk init (shiki always emitted truecolor;
-    chalk decides level once at load). Respects an explicit `FORCE_COLOR` /
-    `NO_COLOR`.
-  - `HLJS_LANG_ALIAS` maps shiki-style ids (`tsx`, `jsx`, `jsonc`, `mdx`,
-    `make`, `svelte`, `vue`) onto highlight.js-supported ids.
-  - `hlBlock()` calls `highlight(code, { language, ignoreIllegals: true })`
-    instead of `await codeToANSI(...)`. Still async-typed so call sites match.
-  - `getPiPrettyFffDir()` → `~/.cache/pi/fff`.
-- `fff-helpers.ts`, `multi-grep-fallback.ts` — unchanged.
-
-## Runtime deps & module resolution
-
-`cli-highlight` and `@ff-labs/fff-node` are installed into pi's npm root
-(`~/.pi/agent/npm/node_modules`) by `setup.sh`. Because the extensions dir is a
-symlink into dotfiles and Node dereferences symlinks before resolving bare
-imports, `setup.sh` also creates a git-ignored
-`extensions/node_modules` → `~/.pi/agent/npm/node_modules` bridge next to the
-real source so `require("cli-highlight")` / `import("@ff-labs/fff-node")`
-resolve.
-
-The upstream `npm:@heyhuynhgiabuu/pi-pretty` package is uninstalled by
-`setup.sh` — both register the same tool names and pi does not share tool-name
-ownership across extensions.
-
-## Env vars
-
-Same as upstream (`PRETTY_THEME`, `PRETTY_MAX_HL_CHARS`,
-`PRETTY_MAX_PREVIEW_LINES`, `PRETTY_CACHE_LIMIT`, `PRETTY_ICONS`,
-`PRETTY_DISABLE_TOOLS`, `PRETTY_IMAGE_PROTOCOL`) plus:
-
-- `PRETTY_FFF_DIR` — override the FFF state dir (default `~/.cache/pi/fff`).
-
-## License
-
-MIT — upstream by huynhgiabuu. See upstream repo.
+See the package-level README for the current export map.

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]!;
+				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]!);
+					};
+
+					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

@@ -1,15 +1,20 @@
 /**
- * pi-pretty — Pretty terminal output for pi built-in tools.
+ * pix-pretty — Pretty terminal output for pi built-in tools.
  *
- * Pure rendering library — no Pi lifecycle hooks or extensions.
+ * Primarily a rendering library (highlight/diff/icons/fff, imported by the tool
+ * packages). This default export is also a thin Pi extension: on load it inits
+ * the pretty theme, clears the highlight cache, and registers the FFF slash
+ * commands (/fff-health, /fff-rescan). pix-core activates it for that purpose.
  * UI features (paste chips, thinking blocks) live in pix-display.
  */
 
 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 {
@@ -25,14 +30,14 @@ 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.
 	registerFffCommands(pi, fffState);
 }
-
-/**
- * piPrettyExtension still exports a default function for packages that
- * import it as an extension (pix-core activates it for theme + FFF).
- * UI extensions (paste-chips, thinking) moved to pix-display.
- */