@xynogen/pix-pretty 1.8.1 → 1.11.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.1",
+	"version": "1.11.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",

package/src/config.ts

@@ -20,6 +20,15 @@ const pc = config(prettySection);
 
 export const MAX_HL_CHARS = pixOrEnvInt("PRETTY_MAX_HL_CHARS", pc.maxHighlightChars, 80_000);
 
+// Per-LINE guard. MAX_HL_CHARS caps the whole block, but cli-highlight's
+// highlight.js tokenizer backtracks catastrophically on a single very long
+// line (a multi-KB JSON string value, a minified one-liner) and freezes the
+// render thread. JSON can't be hard-wrapped without splitting values mid-token
+// (which breaks highlighting), so a block containing any line past this width
+// is returned plain instead. ponytail: fixed threshold; make it a pix.json knob
+// only if a real file legitimately needs highlighted lines wider than this.
+export const MAX_HL_LINE_CHARS = envInt("PRETTY_MAX_HL_LINE_CHARS", 2_000);
+
 export const MAX_PREVIEW_LINES = pixOrEnvInt("PRETTY_MAX_PREVIEW_LINES", pc.maxPreviewLines, 80);
 
 export const CACHE_LIMIT = pixOrEnvInt("PRETTY_CACHE_LIMIT", pc.cacheLimit, 128);

package/src/highlight.test.ts

@@ -23,4 +23,14 @@ describe("active-theme syntax highlighting", () => {
 		await hlBlock("const value = 1", "typescript", theme("30;40;50"));
 		expect(_cache.size).toBe(2);
 	});
+
+	test("bails to plain (never highlights) when any line exceeds the per-line guard", async () => {
+		// Regression: a single multi-KB JSON string value made cli-highlight's
+		// tokenizer backtrack and froze the render thread. The guard returns the
+		// block unhighlighted (no ANSI, not cached) instead of tokenizing it.
+		const mega = JSON.stringify({ blurb: "x".repeat(5000) });
+		const out = await hlBlock(mega, "json", theme("10;20;30"));
+		expect(out.join("\n")).toBe(mega); // untouched, no ANSI escapes injected
+		expect(_cache.size).toBe(0); // not cached — it never went through highlight()
+	});
 });

package/src/highlight.ts

@@ -1,5 +1,5 @@
 import { normalizeShikiContrast } from "./ansi.js";
-import { CACHE_LIMIT, MAX_HL_CHARS } from "./config.js";
+import { CACHE_LIMIT, MAX_HL_CHARS, MAX_HL_LINE_CHARS } from "./config.js";
 import type { BundledLanguage, FgTheme } from "./types.js";
 
 // Engine: cli-highlight (highlight.js-backed, synchronous ANSI output).
@@ -139,6 +139,13 @@ export async function hlBlock(
 ): Promise<string[]> {
 	if (!code) return [""];
 	if (!language || code.length > MAX_HL_CHARS) return code.split("\n");
+	// A single mega-line makes highlight.js backtrack catastrophically and freezes
+	// the render thread — bail to plain before it reaches cli-highlight. Cheap
+	// scan: split is already needed for the plain fallback and the cache miss path.
+	const rawLines = code.split("\n");
+	for (const line of rawLines) {
+		if (line.length > MAX_HL_LINE_CHARS) return rawLines;
+	}
 
 	const hljsLang = toHljsLang(language);
 	if (!hljsLang) return code.split("\n");

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.test.ts

@@ -4,10 +4,12 @@ import { MAX_PREVIEW_LINES } from "./config.js";
 import type { FgTheme } from "./types.js";
 import {
 	formatCollapsedToolRow,
+	formatJson,
 	hideCollapsedToolCall,
 	pluralize,
 	renderCollapsedToolRow,
 	renderDimPreview,
+	ruleFrame,
 	setResultDetails,
 } from "./utils.js";
 
@@ -17,6 +19,23 @@ function plain(text: string): string {
 	return text.replace(ANSI, "");
 }
 
+describe("ruleFrame", () => {
+	it("wraps body with a rule top and bottom, then footer below the close", () => {
+		const out = ruleFrame(["a", "b"], ["… +3 more"], 10);
+		expect(out).toHaveLength(5);
+		expect(plain(out[0]!)).toBe("─".repeat(10)); // top rule
+		expect(out.slice(1, 3)).toEqual(["a", "b"]); // body
+		expect(plain(out[3]!)).toBe("─".repeat(10)); // bottom rule closes the block
+		expect(plain(out[4]!)).toBe("… +3 more"); // footer after the close
+	});
+
+	it("closes the block even with no footer", () => {
+		const out = ruleFrame(["only"], [], 4);
+		expect(plain(out[0]!)).toBe("────");
+		expect(plain(out.at(-1)!)).toBe("────");
+	});
+});
+
 // Minimal theme: fg() passes text through untouched.
 const theme: FgTheme = { fg: (_key, text) => text };
 
@@ -36,6 +55,55 @@ describe("pluralize", () => {
 	});
 });
 
+describe("formatJson", () => {
+	it("reindents a JSON string into a multiline block", () => {
+		expect(formatJson('{"a":1,"b":2}')).toBe('{\n  "a": 1,\n  "b": 2\n}');
+	});
+
+	it("reindents an object value", () => {
+		expect(formatJson({ a: 1 })).toBe('{\n  "a": 1\n}');
+	});
+
+	it("falls back to the raw string for non-JSON input", () => {
+		expect(formatJson("not json")).toBe("not json");
+	});
+
+	it("reindenting a mega JSON one-liner breaks it into short, still-valid lines", () => {
+		// A JSON one-liner is the pathological render case. Reindenting alone splits
+		// it into short lines; it must NOT be hard-wrapped (that would split string
+		// values mid-token) so the block stays valid JSON for syntax highlighting.
+		const obj = { results: Array.from({ length: 300 }, (_, i) => ({ i, name: `item-${i}` })) };
+		const mega = JSON.stringify(obj); // one long line
+		const out = formatJson(mega, { wrapWidth: 80, maxLines: 9999 });
+		expect(out.split("\n").length).toBeGreaterThan(300); // broken into many lines
+		expect(() => JSON.parse(out)).not.toThrow(); // still valid JSON → highlightable
+	});
+
+	it("hard-wraps a NON-JSON mega-line but leaves JSON untouched", () => {
+		// A genuine non-JSON one-liner (multi-KB plain string) still gets wrapped so
+		// the TUI never measures a single huge line.
+		const plain = "x".repeat(7806); // not JSON
+		const wrapped = formatJson(plain, { wrapWidth: 80, maxLines: 9999 });
+		const lines = wrapped.split("\n");
+		expect(Math.max(...lines.map((l) => l.length))).toBeLessThanOrEqual(80);
+		expect(wrapped.replace(/\n/g, "").length).toBe(plain.length); // lossless
+	});
+
+	it("caps line count with a `+N more` footer", () => {
+		const obj = Object.fromEntries(Array.from({ length: 200 }, (_, i) => [`k${i}`, i]));
+		const out = formatJson(obj, { maxLines: 10 });
+		const lines = out.split("\n");
+		expect(lines.length).toBe(11); // 10 + footer
+		expect(lines.at(-1)).toMatch(/^… \+\d+ more$/);
+	});
+
+	it("applies a hard char ceiling as a last-resort guard", () => {
+		const out = formatJson({ blob: "y".repeat(5000) }, { maxChars: 100, maxLines: 999 });
+		expect(out.length).toBeLessThanOrEqual(100);
+		expect(out.endsWith("…")).toBe(true);
+	});
+});
+
 describe("collapsed tool rows", () => {
 	const rowTheme = { fg: (_key: string, text: string) => text, bold: (text: string) => text };
 
@@ -119,6 +187,24 @@ describe("renderDimPreview", () => {
 		expect(out).toContain("body");
 	});
 
+	it("frames the body with a rule top and bottom, header above the top rule", () => {
+		const out = plain(renderDimPreview("a\nb", theme, { frame: true, header: "2 files" }));
+		const lines = out.split("\n");
+		// header, top rule, a, b, bottom rule
+		expect(lines[0]).toContain("2 files");
+		expect(lines[1]).toMatch(/^─+$/); // top rule
+		expect(lines.at(-1)).toMatch(/^─+$/); // bottom rule closes the block
+	});
+
+	it("frames overflow footer below the bottom rule", () => {
+		const body = Array.from({ length: MAX_PREVIEW_LINES + 2 }, (_, i) => `L${i}`);
+		const out = plain(renderDimPreview(body.join("\n"), theme, { frame: true }));
+		const lines = out.split("\n");
+		// overflow marker is the LAST line, below the closing rule
+		expect(lines.at(-1)).toContain("… 2 more lines");
+		expect(lines.at(-2)).toMatch(/^─+$/); // bottom rule sits above the footer
+	});
+
 	it("highlights matched keyword with non-dim styling", () => {
 		const raw = renderDimPreview("foo bar foo", theme, { highlight: "foo" });
 		// matched 'foo' wrapped in yellow/bold ANSI (not produced by stub fg)

package/src/utils.ts

@@ -52,6 +52,77 @@ export function pluralize(count: number, noun: string, plural?: string): string
 	return `${count} ${count === 1 ? noun : (plural ?? `${noun}s`)}`;
 }
 
+export interface FormatJsonOptions {
+	/** Hard char ceiling for the whole block; a longer block is clipped with an ellipsis. */
+	maxChars?: number;
+	/** Line ceiling; excess lines are dropped for a `… +N more` footer. Default MAX_PREVIEW_LINES. */
+	maxLines?: number;
+	/**
+	 * Fallback per-line hard-wrap for NON-JSON input only. When the value parses
+	 * as JSON, reindenting already breaks any mega-line into short lines AND the
+	 * result stays valid JSON, so callers can still syntax-highlight it — wrapping
+	 * it would split string values mid-token and defeat highlighting. This only
+	 * bites a genuine non-JSON one-liner (a multi-KB plain string) the TUI can't
+	 * wrap on its own. 0 disables.
+	 */
+	wrapWidth?: number;
+}
+
+// Hard-wrap a single line into `width`-char chunks. Preserves all characters
+// (this is wrapping, not truncation) so the data stays complete.
+function hardWrapLine(line: string, width: number): string[] {
+	if (width <= 0 || line.length <= width) return [line];
+	const out: string[] = [];
+	for (let i = 0; i < line.length; i += width) out.push(line.slice(i, i + width));
+	return out;
+}
+
+/**
+ * Pretty-print a JSON-ish value for terminal display and bound its cost.
+ *
+ * Splitting an object into short lines is itself a win: the TUI measures/wraps
+ * per line, so one huge line is the pathological case; a re-serialized object
+ * is many cheap lines even when it has more total chars.
+ *
+ * Bounds applied in order: parse+reindent → (non-JSON only) hard-wrap long
+ * lines → line cap (`… +N more`) → char cap. This shapes only the DISPLAY
+ * string; callers keep the untruncated payload for the model. The formatted
+ * JSON stays valid so callers can syntax-highlight it. Pure and host-agnostic.
+ */
+export function formatJson(value: unknown, options: FormatJsonOptions = {}): string {
+	const { maxChars, maxLines = MAX_PREVIEW_LINES, wrapWidth = 0 } = options;
+
+	let text: string;
+	let isJson = true;
+	try {
+		const parsed = typeof value === "string" ? JSON.parse(value) : value;
+		text = JSON.stringify(parsed, null, 2);
+	} catch {
+		// Not JSON (or a circular object) — fall back to a plain string, still bounded.
+		text = typeof value === "string" ? value : String(value);
+		isJson = false;
+	}
+
+	let lines = text.split("\n");
+	// Only hard-wrap non-JSON: wrapping reindented JSON would split string values
+	// mid-token and invalidate the block for downstream highlighting. JSON is
+	// already short-lined after reindent, so it never needs this guard.
+	if (wrapWidth > 0 && !isJson) lines = lines.flatMap((line) => hardWrapLine(line, wrapWidth));
+
+	if (lines.length > maxLines) {
+		const hidden = lines.length - maxLines;
+		lines = [...lines.slice(0, maxLines), `… +${hidden} more`];
+	}
+
+	let out = lines.join("\n");
+	if (maxChars !== undefined && out.length > maxChars) {
+		// Char cap is a last-resort guard (e.g. many wrapped lines under the line
+		// cap still exceeding the budget).
+		out = `${out.slice(0, Math.max(0, maxChars - 1))}…`;
+	}
+	return out;
+}
+
 export type CollapsedToolStatus = "success" | "error" | "warning";
 
 type CollapsedToolTheme = {
@@ -103,9 +174,16 @@ export function hideCollapsedToolCall(
 
 export type DimPreviewOptions = {
 	maxLines?: number;
+	/** Header line shown above the body (or above the top rule when framed).
+	 *  Pass the tool's SEMANTIC count here (e.g. `pluralize(matchCount, "match")`)
+	 *  — the same value the collapsed summary row uses — so top and collapsed
+	 *  never disagree. Do not recount the body: notices/blank lines make a body
+	 *  line-count diverge from the semantic count. */
 	header?: string;
 	/** Pattern whose matches are highlighted (green bold) inside dim lines. */
 	highlight?: string;
+	/** Wrap the body in a top/bottom rule frame (header above, overflow below), like bash/read/mcp. */
+	frame?: boolean;
 };
 
 function dimLineWithHighlight(line: string, theme: FgTheme, pattern?: string): string {
@@ -136,14 +214,25 @@ export function renderDimPreview(
 	const highlight = opts.highlight;
 	const output = normalizeLineEndings(text).trim() || "done";
 	const lines = output.split("\n");
-	const preview = lines
+	const body = lines
 		.slice(0, maxLines)
 		.map((line) => `  ${dimLineWithHighlight(line, theme, highlight)}`);
-	if (opts.header) preview.unshift(`  ${theme.fg("dim", opts.header)}`);
-	if (lines.length > maxLines) {
-		const more = pluralize(lines.length - maxLines, "more line");
-		preview.push(`  ${theme.fg("dim", `… ${more}`)}`);
+	const header = opts.header ? `  ${theme.fg("dim", opts.header)}` : undefined;
+	const overflow =
+		lines.length > maxLines
+			? `  ${theme.fg("dim", `… ${pluralize(lines.length - maxLines, "more line")}`)}`
+			: undefined;
+
+	if (opts.frame) {
+		// Same layout as bash/read/mcp: header above the top rule, body between the
+		// rules, overflow footer below the bottom rule.
+		const out = [...(header ? [header] : []), ...ruleFrame(body, overflow ? [overflow] : [])];
+		return fillToolBackground(out.join("\n"));
 	}
+
+	const preview = body;
+	if (header) preview.unshift(header);
+	if (overflow) preview.push(overflow);
 	return fillToolBackground(preview.join("\n"));
 }
 
@@ -220,6 +309,21 @@ export function rule(w: number): string {
 	return `${FG_RULE}${"─".repeat(w)}${RST}`;
 }
 
+/**
+ * Frame tool output the way bash/read/sudo do: a top rule, the body lines, a
+ * bottom rule, then any footer lines (e.g. `… +N more`) below the close. The
+ * single source of the "rule top, rule bottom" invariant so every tool's result
+ * block is framed identically — MCP and the shell tools share this.
+ */
+export function ruleFrame(
+	bodyLines: string[],
+	footerLines: string[] = [],
+	width?: number,
+): string[] {
+	const r = rule(width ?? termW());
+	return [r, ...bodyLines, r, ...footerLines];
+}
+
 export function lnum(n: number, w: number): string {
 	const v = String(n);
 	return `${FG_LNUM}${" ".repeat(Math.max(0, w - v.length))}${v}${RST}`;
@@ -230,9 +334,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";
+}