@xynogen/pix-pretty 1.8.0 → 1.10.0

package/README.md

@@ -11,7 +11,7 @@ consume. It does not register user-facing tools itself — the tool renderers
 initializes the syntax-highlight theme from Pi settings, clears the highlight
 cache, seeds the icon mode from `pix.json`, and registers two FFF slash
 commands (`/fff-health`, `/fff-rescan`) once `pix-grep` has brought the FFF
-finder online. The `/pix` settings command lives in `pix-data`.
+finder online. The `/pix` settings command lives in `pix-runtime`.
 (Activated by `pix-core`; not a standalone extension.)
 
 ### Rendering
@@ -36,7 +36,7 @@ problem on terminals without a Nerd Font, becomes a one-file edit here.
   `getIconMode()`, `setIconMode()`, `ICON_KEYS`, `ICON_MODES`.
 - **`./icon-persist`** — reads/writes the icon mode via `pix.json`
   (`pretty.icons`); `initIconMode()` applies it on load.
-- **`/pix`** (in `pix-data`) — unified settings overlay that includes the icon
+- **`/pix`** (in `pix-runtime`) — unified settings overlay that includes the icon
   mode switch. 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.
@@ -62,9 +62,9 @@ pi install npm:@xynogen/pix-pretty
 
 ## Configuration
 
-Configuration is read from **`~/.pi/agent/pix.json`** (the unified config file hosted by `@xynogen/pix-data/pix-config`). The `pretty` section of that file sets the defaults for theme, icon mode, and preview lines. Environment variables still override `pix.json` values.
+Configuration is read from **`~/.pi/agent/pix.json`** (the unified config file owned by `@xynogen/pix-runtime/config`). The `pretty` section of that file sets the defaults for theme, icon mode, and preview lines. Environment variables still override `pix.json` values.
 
-> **Note:** `pix-config.ts` and `collapse.ts` previously shipped with `pix-pretty` — they have moved to `pix-data` (`@xynogen/pix-data/pix-config` and `@xynogen/pix-data/collapse`). Update any direct imports.
+> **Note:** config and collapse helpers previously shipped with `pix-pretty`; they now live in `pix-runtime` (`@xynogen/pix-runtime/config` and `@xynogen/pix-runtime/collapse`). Update any direct imports.
 
 ### `pix.json` — `pretty` section
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-pretty",
-	"version": "1.8.0",
+	"version": "1.10.0",
 	"description": "Enhanced tool output rendering with syntax highlighting, file icons, tree views, diff rendering, and FFF search",
 	"type": "module",
 	"main": "src/index.ts",
@@ -21,6 +21,7 @@
 		"./fff": "./src/fff.ts",
 		"./types": "./src/types.ts",
 		"./utils": "./src/utils.ts",
+		"./widget-format": "./src/widget-format.ts",
 		"./resize": "./src/resize.ts",
 		"./context": "./src/tools/context.ts",
 		"./gate-overlay": "./src/gate-overlay.ts",
@@ -59,7 +60,7 @@
 	},
 	"dependencies": {
 		"@xynogen/pix-data": "^0.4.0",
-		"@xynogen/pix-runtime": "^0.3.0",
+		"@xynogen/pix-runtime": "^0.4.0",
 		"chalk": "^4.1.2",
 		"cli-highlight": "^2.1.11",
 		"@ff-labs/fff-node": "^0.5.2",

package/src/icon-catalog.test.ts

@@ -39,6 +39,32 @@ describe("icon-catalog", () => {
 		}
 	});
 
+	it("status family keeps historical nerd glyphs and gains ascii tokens", () => {
+		// nerd mode must equal the pre-catalog literals so mixed-glyph rows and
+		// existing snapshot assertions stay aligned.
+		expect(iconFor("status.ok", "nerd")).toBe("\u2713");
+		expect(iconFor("status.error", "nerd")).toBe("\u2717");
+		expect(iconFor("status.warn", "nerd")).toBe("\u26A0");
+		expect(iconFor("status.pending", "nerd")).toBe("\u25CB");
+		expect(iconFor("status.running", "nerd")).toBe("\u25D0");
+		expect(iconFor("status.active", "nerd")).toBe("\u25CF");
+		expect(iconFor("status.done", "nerd")).toBe("\u25CF");
+		expect(iconFor("status.blocked", "nerd")).toBe("\u2298");
+		// ascii mode must be tofu-free (letters/punctuation only).
+		for (const key of [
+			"status.ok",
+			"status.error",
+			"status.warn",
+			"status.pending",
+			"status.running",
+			"status.active",
+			"status.done",
+			"status.blocked",
+		] as const) {
+			expect(iconFor(key, "ascii")).toMatch(/^[\x20-\x7e]+$/);
+		}
+	});
+
 	it("unknown key fails soft to empty string", () => {
 		// @ts-expect-error exercising the runtime guard
 		expect(icon("does.not.exist")).toBe("");

package/src/icon-catalog.ts

@@ -58,6 +58,20 @@ const CATALOG = {
 	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" },
+	"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" },
 

package/src/progress.ts

@@ -14,6 +14,7 @@
  */
 
 import { frameModal, MIN_MODAL_HEIGHT, modalWidth, terminalModalHeight } from "./modal-frame.js";
+import { SPINNER } from "./widget-format.js";
 
 interface ProgressTheme {
 	fg(color: string, text: string): string;
@@ -46,7 +47,6 @@ export interface ProgressHandle {
 	close(): void;
 }
 
-const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 // 120ms: smooth enough to read as motion, slow enough to barely touch the
 // render queue. The overlay owns input so this isn't competing with echo.
 const SPINNER_INTERVAL_MS = 120;

package/src/utils.ts

@@ -230,9 +230,10 @@ export function lnum(n: number, w: number): string {
 // ---------------------------------------------------------------------------
 
 export function humanSize(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KiB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MiB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GiB`;
 }
 
 // ---------------------------------------------------------------------------

package/src/widget-format.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "bun:test";
+import {
+	describeActivity,
+	fmtTokenCount,
+	formatContext,
+	formatMs,
+	formatSpeed,
+	formatTokens,
+	formatToolUses,
+	formatTurns,
+	getSessionContextPercent,
+	getSessionContextUsage,
+	SPINNER,
+	truncateLine,
+} from "./widget-format.ts";
+
+const stripAnsi = (text: string) => text.replace(/\x1b\[[0-9;]*m/g, "");
+
+describe("widget formatters", () => {
+	test("SPINNER has frames to cycle", () => {
+		expect(SPINNER.length).toBeGreaterThan(1);
+	});
+
+	test("fmtTokenCount scales with magnitude", () => {
+		expect(fmtTokenCount(500)).toBe("500");
+		expect(fmtTokenCount(30_100)).toBe("30.1K");
+		expect(fmtTokenCount(1_000_000)).toBe("1.00M");
+	});
+
+	test("formatTokens uses ' token' / 'k token' / 'M token' variants", () => {
+		expect(stripAnsi(formatTokens(500))).toContain("500 token");
+		expect(stripAnsi(formatTokens(12_400))).toContain("12.4k token");
+		expect(stripAnsi(formatTokens(2_500_000))).toContain("2.5M token");
+	});
+
+	test("formatMs renders seconds to one decimal", () => {
+		expect(formatMs(2_100)).toBe("2.1s");
+	});
+
+	test("formatSpeed returns empty when there is no work", () => {
+		expect(formatSpeed(0, 1_000)).toBe("");
+		expect(formatSpeed(100, 0)).toBe("");
+		expect(stripAnsi(formatSpeed(200, 2_000))).toBe("100 t/s");
+	});
+
+	test("formatContext shows used/window/percent, or empty when unknown", () => {
+		expect(formatContext(null)).toBe("");
+		expect(formatContext({ tokens: null, contextWindow: null, percent: null })).toBe("");
+		expect(
+			stripAnsi(formatContext({ tokens: 30_100, contextWindow: 1_000_000, percent: 3 })),
+		).toContain("30.1K/1.00M (3%)");
+		expect(stripAnsi(formatContext({ tokens: null, contextWindow: null, percent: 42 }))).toContain(
+			"42% ctx",
+		);
+	});
+
+	test("formatTurns and formatToolUses render counts", () => {
+		expect(stripAnsi(formatTurns(3))).toContain("3");
+		expect(stripAnsi(formatTurns(3, 10))).toContain("3\u226410");
+		expect(stripAnsi(formatToolUses(5))).toContain("5");
+	});
+
+	test("truncateLine tail-anchors the latest non-empty line to len", () => {
+		expect(truncateLine("short", 32)).toBe("short");
+		expect(truncateLine("a\nb\nlatest", 32)).toBe("latest");
+		expect(truncateLine("0123456789", 4)).toBe("\u20266789");
+	});
+
+	test("describeActivity groups active tools, tails text (default 32), else thinking", () => {
+		const two = new Map<string, string>([
+			["0", "read"],
+			["1", "read"],
+		]);
+		expect(describeActivity(two)).toBe("reading 2\u00d7\u2026");
+		expect(describeActivity(new Map(), "line one\nlatest line")).toBe("latest line");
+		expect(describeActivity(new Map())).toBe("thinking\u2026");
+	});
+
+	test("describeActivity honors an explicit tailLen", () => {
+		expect(describeActivity(new Map(), "0123456789", 4)).toBe("\u20266789");
+	});
+
+	test("getSessionContextUsage reads stats and tolerates throwing sessions", () => {
+		const session = {
+			getSessionStats: () => ({
+				tokens: { input: 0, output: 0, cacheWrite: 0 },
+				contextUsage: { tokens: 10, contextWindow: 100, percent: 10 },
+			}),
+		};
+		expect(getSessionContextUsage(session)).toEqual({
+			tokens: 10,
+			contextWindow: 100,
+			percent: 10,
+		});
+		expect(getSessionContextUsage(undefined)).toBeNull();
+		const throwing = {
+			getSessionStats: () => {
+				throw new Error("no stats");
+			},
+		};
+		expect(getSessionContextUsage(throwing)).toBeNull();
+	});
+
+	test("getSessionContextPercent returns just the percent, or null", () => {
+		const session = {
+			getSessionStats: () => ({
+				tokens: { input: 0, output: 0, cacheWrite: 0 },
+				contextUsage: { tokens: 10, contextWindow: 100, percent: 42 },
+			}),
+		};
+		expect(getSessionContextPercent(session)).toBe(42);
+		expect(getSessionContextPercent(undefined)).toBeNull();
+	});
+});

package/src/widget-format.ts

@@ -0,0 +1,168 @@
+/**
+ * widget-format.ts — pure, shared live-widget formatting helpers.
+ *
+ * These are the token/context/turn/tool/speed formatters plus the session
+ * context-usage readers used by pix-subagent's agent widget and pix-commands'
+ * /btw widget. They are pure (no Theme, no Pi host) so both packages can import
+ * them from this sanctioned shared layer instead of duplicating the code.
+ *
+ * icon() is imported locally (this module lives inside pix-pretty).
+ */
+
+import { icon } from "./icon-catalog.ts";
+
+// ── Braille spinner ──────────────────────────────────────────────────────────
+
+export const SPINNER = [
+	"\u280b",
+	"\u2819",
+	"\u2839",
+	"\u2838",
+	"\u283c",
+	"\u2834",
+	"\u2826",
+	"\u2827",
+	"\u2807",
+	"\u280f",
+];
+
+// ── Session-stats shapes + readers ─────────────────────────────────────────────
+
+/** Minimal shape we read from upstream `getSessionStats()`. */
+export type SessionStatsLike = {
+	tokens: { input: number; output: number; cacheWrite: number };
+	contextUsage?: { tokens?: number | null; contextWindow?: number; percent: number | null };
+};
+export type SessionLike = { getSessionStats(): SessionStatsLike };
+
+/** Context usage snapshot: estimated used tokens, window size, percent. */
+export type ContextUsageLike = {
+	tokens: number | null;
+	contextWindow: number | null;
+	percent: number | null;
+};
+
+/** Full context usage, or null when unavailable. */
+export function getSessionContextUsage(session: SessionLike | undefined): ContextUsageLike | null {
+	if (!session) return null;
+	try {
+		const cu = session.getSessionStats().contextUsage;
+		if (!cu) return null;
+		return {
+			tokens: cu.tokens ?? null,
+			contextWindow: cu.contextWindow ?? null,
+			percent: cu.percent ?? null,
+		};
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Context-window utilization (0–100), or null when unavailable
+ * (no model contextWindow, or post-compaction before the next response).
+ */
+export function getSessionContextPercent(session: SessionLike | undefined): number | null {
+	return getSessionContextUsage(session)?.percent ?? null;
+}
+
+// ── Formatters ─────────────────────────────────────────────────────────────────
+
+export function formatTokens(count: number): string {
+	const t = icon("tokens");
+	if (count >= 1_000_000) return `${t} ${(count / 1_000_000).toFixed(1)}M token`;
+	if (count >= 1_000) return `${t} ${(count / 1_000).toFixed(1)}k token`;
+	return `${t} ${count} token`;
+}
+
+/** Compact token count: 500 → "500", 30_100 → "30.1K", 1_000_000 → "1.00M". */
+export function fmtTokenCount(n: number): string {
+	if (n < 1_000) return `${n}`;
+	if (n < 1_000_000) return `${(n / 1_000).toFixed(1)}K`;
+	return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/**
+ * Format context-window utilization: "󰉿 30.1K/1.00M (3%)".
+ * Falls back to "󰉿 3% ctx" when the window size is unknown.
+ * Returns "" when percent is null/unavailable (caller should skip the segment).
+ */
+export function formatContext(usage: ContextUsageLike | null | undefined): string {
+	if (usage?.percent == null) return "";
+	const t = icon("tokens");
+	const pct = Math.round(usage.percent);
+	if (!usage.contextWindow) return `${t} ${pct}% ctx`;
+	const used = usage.tokens ?? Math.round((usage.percent / 100) * usage.contextWindow);
+	return `${t} ${fmtTokenCount(used)}/${fmtTokenCount(usage.contextWindow)} (${pct}%)`;
+}
+
+export function formatTurns(turnCount: number, maxTurns?: number | null): string {
+	const t = icon("turns");
+	return maxTurns != null ? `${t} ${turnCount}≤${maxTurns}` : `${t} ${turnCount}`;
+}
+
+export function formatToolUses(count: number): string {
+	return `${icon("tools")} ${count}`;
+}
+
+export function formatMs(ms: number): string {
+	return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Output tokens per second over a duration. "" when either input is
+ * non-positive (no work / zero elapsed) so callers can skip the segment.
+ */
+export function formatSpeed(outputTokens: number, durationMs: number): string {
+	if (outputTokens <= 0 || durationMs <= 0) return "";
+	return `${Math.round(outputTokens / (durationMs / 1000))} t/s`;
+}
+
+// ── Activity description ─────────────────────────────────────────────────────
+
+export const TOOL_DISPLAY: Record<string, string> = {
+	read: "reading",
+	bash: "running command",
+	edit: "editing",
+	write: "writing",
+	grep: "searching",
+	find: "finding files",
+	ls: "listing",
+};
+
+/**
+ * Live tail of agent output: latest non-empty line, tail-anchored to `len`
+ * chars (keeps the moving edge, not the stale first line).
+ */
+export function truncateLine(text: string, len = 32): string {
+	const lines = text.split("\n").filter((l) => l.trim());
+	const line = (lines.at(-1) ?? "").trim();
+	if (line.length <= len) return line;
+	return `\u2026${line.slice(-len)}`;
+}
+
+/**
+ * One-line description of what an agent/job is doing: grouped active tools,
+ * else a tail (`tailLen` chars, default 32) of the streaming answer text, else
+ * "thinking…".
+ */
+export function describeActivity(
+	activeTools: Map<string, string>,
+	responseText?: string,
+	tailLen = 32,
+): string {
+	if (activeTools.size > 0) {
+		const groups = new Map<string, number>();
+		for (const toolName of activeTools.values()) {
+			const action = TOOL_DISPLAY[toolName] ?? toolName;
+			groups.set(action, (groups.get(action) ?? 0) + 1);
+		}
+		const parts: string[] = [];
+		for (const [action, count] of groups) {
+			parts.push(count > 1 ? `${action} ${count}\u00d7` : action);
+		}
+		return `${parts.join(", ")}\u2026`;
+	}
+	if (responseText?.trim()) return truncateLine(responseText, tailLen);
+	return "thinking\u2026";
+}