@xynogen/pix-pretty 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-pretty",
-	"version": "1.20.0",
+	"version": "1.21.0",
 	"description": "Enhanced tool output rendering with syntax highlighting, file icons, tree views, diff rendering, and FFF search",
 	"type": "module",
 	"main": "src/index.ts",
@@ -61,10 +61,10 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-runtime": "^0.8.0",
+		"@xynogen/pix-runtime": "^0.8.4",
 		"chalk": "^4.1.2",
 		"cli-highlight": "^2.1.11",
-		"@ff-labs/fff-node": "^0.5.2",
+		"@ff-labs/fff-node": "^0.10.6",
 		"diff": "^8.0.3"
 	},
 	"peerDependencies": {

package/src/confirm.ts

@@ -43,6 +43,9 @@ export interface ConfirmUI {
 }
 
 export interface ConfirmOptions {
+	/** Optional leading glyph for the title row, e.g. `icon("update")`. Rendered
+	 *  as "<icon> <title>" so callers pass a resolved icon + plain text. */
+	icon?: string;
 	/** Title shown bold at the top (e.g. "Update Pi & extensions?"). */
 	title: string;
 	/** Optional body lines rendered under the title. */
@@ -133,7 +136,9 @@ export function confirmOverlay(ui: ConfirmUI, opts: ConfirmOptions): Promise<boo
 							width: mw,
 							maxHeight: terminalModalHeight(tui.terminal?.rows),
 							minHeight: MIN_PERMISSION_MODAL_HEIGHT,
-							header: [theme.fg(accent, theme.bold(opts.title))],
+							header: [
+								theme.fg(accent, theme.bold(opts.icon ? `${opts.icon} ${opts.title}` : opts.title)),
+							],
 							body: (opts.body ?? []).map((line) => theme.fg("text", line)),
 							footer,
 							bodyOffset: pager.bodyOffset,

package/src/gate-overlay.ts

@@ -49,6 +49,13 @@ export interface OverlayChoice {
 interface BaseConfig {
 	/** Accent colour token (e.g. "error", "warning", "accent"). Default "accent". */
 	accent?: string;
+	/**
+	 * Optional leading glyph for the title row, e.g. `icon("lock")`. Kept
+	 * separate from `title` so call sites pass a resolved icon and plain text
+	 * rather than splicing them together; the overlay renders "<icon> <title>"
+	 * in the accent color.
+	 */
+	icon?: string;
 	/** Title shown bold at the top. */
 	title: string;
 	/** Optional body lines under the title. */
@@ -174,7 +181,8 @@ function buildSections(opts: {
 		width,
 	} = opts;
 	const inner = width - 4; // CHROME = 2 border + 2 padding
-	const header = [theme.fg(accent, theme.bold(config.title))];
+	const titleText = config.icon ? `${config.icon} ${config.title}` : config.title;
+	const header = [theme.fg(accent, theme.bold(titleText))];
 	const body = (config.body ?? []).map((line) => {
 		if (line.startsWith("Warning:")) return theme.fg("warning", line);
 		if (line.startsWith("(") && line.endsWith(")")) return theme.fg("muted", line);
@@ -228,7 +236,8 @@ function buildSections(opts: {
  * ```ts
  * const result = await showOverlay(ui, {
  *   mode: "confirm",
- *   title: "⚠️  DANGEROUS",
+ *   icon: icon("warn"),
+ *   title: "Dangerous",
  *   body: ["rm -rf /tmp/work"],
  *   accent: "warning",
  *   timeoutMs: 30_000,
@@ -243,7 +252,8 @@ function buildSections(opts: {
  * ```ts
  * const result = await showOverlay(ui, {
  *   mode: "sudo",
- *   title: "🔐 ROOT COMMAND REQUEST",
+ *   icon: icon("lock"),
+ *   title: "Root Command Request",
  *   body: ["Intent: install package", "Command: apt install foo"],
  *   accent: "error",
  * });

package/src/icon-catalog.ts

@@ -1,165 +1,21 @@
 /**
- * icon-catalog.ts — semantic icon catalog, treated like an l10n message table.
+ * icon-catalog.ts — re-export shim.
  *
- * 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 `/pix`
- * settings command (in pix-data), persisted to `~/.pi/agent/pix.json`
- * (`pretty.icons`), 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 /pix settings 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: "/" },
-	afk: { nerd: "\u{F0310}", unicode: `\u2328${VS}`, ascii: "kbd" },
-
-	// ── 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" },
-
-	// ── shared status glyphs (checklists, panels, markers) ────────────────
-	// nerd/unicode keep the historical literal so mixed-glyph rows stay
-	// aligned; ascii mode swaps in tofu-free tokens. `⚡` (energetic
-	// warning/killed/denied) intentionally stays a local literal — it is not
-	// part of this set.
-	"status.ok": { nerd: "\u2713", unicode: `\u2713${VS}`, ascii: "ok" },
-	"status.error": { nerd: "\u2717", unicode: `\u2717${VS}`, ascii: "x" },
-	// `⚠` is East-Asian wide (2 cells); consumers that place it in an aligned
-	// marker column must normalize width via `padIcon` (pix-pretty/utils).
-	"status.warn": { nerd: "\u26A0", unicode: `\u26A0${VS}`, ascii: "!" },
-	"status.pending": { nerd: "\u25CB", unicode: `\u25CB${VS}`, ascii: "o" },
-	"status.running": { nerd: "\u25D0", unicode: `\u25D0${VS}`, ascii: "*" },
-	"status.active": { nerd: "\u25CF", unicode: `\u25CF${VS}`, ascii: "*" },
-	"status.done": { nerd: "\u25CF", unicode: `\u25CF${VS}`, ascii: "x" },
-	"status.blocked": { nerd: "\u2298", unicode: `\u2298${VS}`, ascii: "!" },
-
-	// ── 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: "*" },
-
-	// ── subagent widget (pix-subagent) ────────────────────────────────────
-	agent: { nerd: "\u{F0BA0}", unicode: `\u2699${VS}`, ascii: "@" },
-	turns: { nerd: "\u{F006A}", unicode: `\u21BB${VS}`, ascii: "~" },
-	tools: { nerd: "\u{F1064}", unicode: `\u2692${VS}`, ascii: "T" },
-	tokens: { nerd: "\u{F027F}", unicode: `\u25A4${VS}`, ascii: "tk" },
-} as const;
-
-/** Every valid semantic icon key. */
-export type IconKey = keyof typeof CATALOG;
-
-/** All catalog keys (useful for /pix 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 pix.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 the /pix command, which writes pix.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).
+ * The semantic icon catalog now lives in `@xynogen/pix-runtime` (a lower layer)
+ * so that pix-runtime's own UI — the `/pix` settings overlay — can resolve
+ * icons without a circular dependency on pix-pretty. This file re-exports the
+ * whole surface unchanged, so every existing `@xynogen/pix-pretty/icon-catalog`
+ * import keeps working.
  */
-export function icon(key: IconKey): string {
-	const entry = CATALOG[key];
-	return entry ? entry[activeMode] : "";
-}
 
-/** Resolve a key for an explicit mode (used by /pix previews + tests). */
-export function iconFor(key: IconKey, mode: IconMode): string {
-	const entry = CATALOG[key];
-	return entry ? entry[mode] : "";
-}
+export {
+	getIconMode,
+	ICON_KEYS,
+	ICON_MODES,
+	type IconKey,
+	type IconMode,
+	icon,
+	iconFor,
+	onIconModeChange,
+	setIconMode,
+} from "@xynogen/pix-runtime/icon-catalog";

package/src/modal-frame.ts

@@ -77,6 +77,15 @@ export interface FrameOptions {
 	fg?: (s: string) => string;
 	/** Optional pre-styled string rendered as the first content row (tab bar etc.) */
 	top?: string;
+	/**
+	 * Plain title text embedded into the top border, e.g. `╭─ pix settings ─────╮`.
+	 * Styled with `titleColor` (falls back to `color`). Kept as plain text so the
+	 * frame owns the spacing/dashes; pass an already-short string (it's truncated
+	 * to fit). Distinct from `top`, which is a full pinned content row.
+	 */
+	title?: string;
+	/** Color function for the embedded `title` text. Defaults to `color`. */
+	titleColor?: (s: string) => string;
 	/**
 	 * Wrap over-wide content instead of cutting its tail. Default true.
 	 *
@@ -140,6 +149,44 @@ export function fitModalLines(lines: string[], inner: number, wrap = true): FitR
 	return { rows, truncated };
 }
 
+// ── Column layout ───────────────────────────────────────────────────────────
+
+export interface JoinColumnsOptions {
+	/** Left column width in cells. Rows are truncated/padded to exactly this. */
+	leftWidth: number;
+	/** Right column width in cells. Rows are truncated to this (no right-pad). */
+	rightWidth: number;
+	/** Spaces between the columns when no `sep` is given. Default 2. */
+	gap?: number;
+	/**
+	 * Pre-styled separator string placed between the columns (e.g. a themed
+	 * `" │ "`). Its own visible width is used as-is — pass `gap` OR `sep`, not
+	 * both. When omitted the columns are separated by `gap` spaces.
+	 */
+	sep?: string;
+}
+
+/**
+ * Stitch two column bodies into side-by-side rows (a list + preview pane, say).
+ * Left cells are truncated then space-padded to `leftWidth` by *visible* width
+ * (ANSI-aware), so styled text aligns; right cells are only truncated. The
+ * result has `max(left.length, right.length)` rows — the shorter column is
+ * padded with blanks. Pure: no wrapping, no color; callers style the cells and
+ * the optional `sep`.
+ */
+export function joinColumns(left: string[], right: string[], opts: JoinColumnsOptions): string[] {
+	const divider = opts.sep ?? " ".repeat(Math.max(0, opts.gap ?? 2));
+	const height = Math.max(left.length, right.length);
+	const rows: string[] = [];
+	for (let i = 0; i < height; i++) {
+		const l = truncateToWidth(left[i] ?? "", opts.leftWidth);
+		const lPad = l + " ".repeat(Math.max(0, opts.leftWidth - visibleWidth(l)));
+		const r = truncateToWidth(right[i] ?? "", opts.rightWidth);
+		rows.push(`${lPad}${divider}${r}`);
+	}
+	return rows;
+}
+
 /**
  * Render a rounded modal box.
  *
@@ -165,6 +212,20 @@ export function frameLines(opts: FrameOptions): string[] {
 	const inner = width - CHROME;
 	const dashes = "─".repeat(width - 2);
 	const wrap = opts.wrap ?? true;
+
+	// Top border: bare `╭───╮`, or a titled `╭─ Title ──╮` when `title` is set.
+	// The title sits after one lead dash with a padding space on each side; the
+	// remaining run fills with dashes so the border stays exactly `width` wide.
+	const topBorder = ((): string => {
+		// Full width = ╭ + lead dash + " " + label + " " + tail dashes + ╮.
+		// Fixed chrome around the label is 5 cols (2 corners, 1 lead dash, 2 pads).
+		const span = width - 5;
+		if (!opts.title || span < 3) return color(`╭${dashes}╮`);
+		const paint = opts.titleColor ?? color;
+		const label = truncateToWidth(opts.title, span - 1, ELLIPSIS); // keep ≥1 tail dash
+		const tail = "─".repeat(Math.max(1, span - visibleWidth(label)));
+		return `${color("╭─ ")}${paint(label)}${color(` ${tail}╮`)}`;
+	})();
 	// Expand before framing so a long command wraps instead of losing its tail.
 	const { rows: lines } = fitModalLines(opts.lines, inner, wrap);
 
@@ -196,7 +257,7 @@ export function frameLines(opts: FrameOptions): string[] {
 		return bg(`${color("│")} ${body} ${color("│")}`);
 	};
 
-	const out: string[] = [bg(color(`╭${dashes}╮`))];
+	const out: string[] = [bg(topBorder)];
 	if (top !== undefined) out.push(row(top));
 	for (const line of lines) out.push(row(line));
 	out.push(bg(color(`╰${dashes}╯`)));
@@ -475,7 +536,16 @@ export function frameModal(opts: ModalFrameOptions): ModalFrameResult {
 			wrap,
 		).rows.slice(0, Math.max(1, cap - 2));
 		return {
-			lines: frameLines({ width, lines: diag, color, bg, fg, wrap: false }),
+			lines: frameLines({
+				width,
+				lines: diag,
+				color,
+				bg,
+				fg,
+				title: opts.title,
+				titleColor: opts.titleColor,
+				wrap: false,
+			}),
 			bodyOffset: 0,
 			maxBodyOffset: 0,
 			visibleBodyLines: 0,
@@ -520,7 +590,17 @@ export function frameModal(opts: ModalFrameOptions): ModalFrameResult {
 
 	return {
 		// Already fitted above — pass wrap:false so rows are not re-expanded.
-		lines: frameLines({ width, lines, color, bg, fg, top, wrap: false }),
+		lines: frameLines({
+			width,
+			lines,
+			color,
+			bg,
+			fg,
+			top,
+			title: opts.title,
+			titleColor: opts.titleColor,
+			wrap: false,
+		}),
 		bodyOffset: offset,
 		maxBodyOffset,
 		visibleBodyLines,