@xynogen/pix-data 0.2.5 → 0.3.1

package/README.md

@@ -74,7 +74,7 @@ heuristic = 0.30·coding_score + 0.60·agentic_score + 0.10·reasoning_score
 score     = round(clamp₀₁₀₀(120.6·heuristic − 10.6))   // fitted to the index
 ```
 
-3. **benchlm.ai fallback** — if the model exists in benchlm but modelgrep has
+1. **benchlm.ai fallback** — if the model exists in benchlm but modelgrep has
    no AA index and no raw benches, look up the benchlm `overallScore` (0–100)
    and use it verbatim. Match strategy (in `lookupBenchlmScore`): exact
    normalized slug, then prefix overlap either way, then take the
@@ -119,6 +119,89 @@ place if your priorities differ.
 | `lookupModelsDev` | Sync lookup by id from in-memory cache (joined on slug) |
 | `lookupBenchmark` | Sync lookup a model by id — returns score + rank + pricing |
 | `benchScoreColor` | Map a 0–100 score to a `success`/`warning`/`error`/`muted` token |
+| `pixConfig` | `@xynogen/pix-data/pix-config` — load/access the unified `pix.json` config |
+| `reloadPixConfig` | Force a fresh read of `pix.json` from disk |
+| `shouldCollapse` | `@xynogen/pix-data/collapse` — whether a tool's output card should auto-collapse |
+| `collapseDelayMs` | Configured delay (ms) before a card collapses (default 10 000) |
+| `tickCollapse` | Call in `renderResult` to schedule the timed auto-collapse for a card |
+
+## Unified config — `~/.pi/agent/pix.json`
+
+pix-data hosts the **single shared config file** consumed by every `pix-*` package. The file is auto-created with defaults on the first session that loads pix-data — you never need to create it manually.
+
+**Location:** `~/.pi/agent/pix.json`
+
+### Full schema
+
+```jsonc
+{
+  // Auto-collapse for tool output cards (pix-bash, pix-read, pix-grep, …)
+  "collapse": {
+    "enabled": true,          // master switch
+    "delayMs": 10000,         // ms before collapse fires (default 10s)
+    "tools": {
+      // per-tool overrides — set false to disable for a specific tool
+      "bash":  true,
+      "read":  true,
+      "grep":  true,
+      "edit":  true,
+      "write": true,
+      "find":  true,
+      "ls":    true,
+      "todo":  true
+    }
+  },
+
+  // Rendering options (pix-pretty)
+  "pretty": {
+    "theme": "monokai",       // syntax-highlight theme (overrides PRETTY_THEME)
+    "icons": "nerd",          // icon mode: nerd | unicode | ascii (overrides PRETTY_ICONS)
+    "maxPreviewLines": 50,    // overrides PRETTY_MAX_PREVIEW_LINES
+    "diffColors": true        // colored diff output
+  },
+
+  // Optimizer initial state (pix-optimizer)
+  "optimizer": {
+    "caveman": "off",         // off | lite | full | ultra | micro
+    "rtk":     false,
+    "toon":    false,
+    "ponytail": "off"         // off | lite | full | ultra
+  },
+
+  // Gate rules (pix-gate)
+  "gate": {
+    "disableDefaults": false,
+    "extraRules": [],          // same shape as pix-gate.json extraRules
+    "autoApprove": []          // regex strings that skip the dialog
+  }
+}
+```
+
+All sections are optional — missing keys fall back to the defaults shown above. Environment variables (e.g. `PRETTY_THEME`) still take precedence over `pix.json` values.
+
+### API — `@xynogen/pix-data/pix-config`
+
+```ts
+import { pixConfig, reloadPixConfig } from "@xynogen/pix-data/pix-config";
+
+const cfg = pixConfig();          // returns cached PixConfig (loaded once per session)
+await reloadPixConfig();          // force re-read from disk (e.g. after /config reload)
+```
+
+### API — `@xynogen/pix-data/collapse`
+
+```ts
+import { shouldCollapse, collapseDelayMs, tickCollapse } from "@xynogen/pix-data/collapse";
+
+// In a tool's renderResult:
+if (shouldCollapse("bash")) {
+  tickCollapse(card, collapseDelayMs());  // schedules timed collapse
+}
+```
+
+- `shouldCollapse(tool)` — returns `true` when `collapse.enabled` is true and the named tool is not opted out.
+- `collapseDelayMs()` — returns `collapse.delayMs` from config (default `10000`).
+- `tickCollapse(card, delayMs)` — sets a timeout that calls `card.collapse()` after the delay. Safe to call multiple times — only the first registered timeout fires.
 
 ## Install
 

package/package.json

@@ -1,9 +1,15 @@
 {
 	"name": "@xynogen/pix-data",
-	"version": "0.2.5",
+	"version": "0.3.1",
 	"description": "Pi extension — shared model data layer (models.dev + BenchLM), cached at ~/.cache/pi",
 	"type": "module",
 	"main": "src/index.ts",
+	"exports": {
+		".": "./src/index.ts",
+		"./src/*": "./src/*",
+		"./pix-config": "./src/pix-config.ts",
+		"./collapse": "./src/collapse.ts"
+	},
 	"scripts": {
 		"test": "bun test"
 	},

package/src/collapse.ts

@@ -0,0 +1,40 @@
+/**
+ * collapse.ts — auto-collapse helper for tool renderResult cards.
+ *
+ * Provides a timer-based collapse mechanism: show full output for N seconds,
+ * then collapse to a one-line dim summary. Each tool call gets its own card
+ * with its own timer, so the latest call stays expanded while older ones fold.
+ *
+ * Configuration is read from ~/.pi/agent/pix.json via pix-config.
+ */
+
+import { collapseDelayMs, shouldCollapse } from "./pix-config.js";
+
+export interface CollapseState {
+	collapsed?: boolean;
+	timer?: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * Run the collapse timer for a tool card. Call this inside `renderResult`.
+ *
+ * @param toolName — the tool name (e.g. "bash", "read") for per-tool config
+ * @param state    — the render context's `state` bag (mutable, per-card)
+ * @param invalidate — `context.invalidate()` to trigger re-render
+ * @returns `true` if the card is currently collapsed
+ */
+export function tickCollapse(
+	toolName: string,
+	state: CollapseState,
+	invalidate: () => void,
+): boolean {
+	if (!shouldCollapse(toolName)) return false;
+	if (state.collapsed) return true;
+	if (!state.timer) {
+		state.timer = setTimeout(() => {
+			state.collapsed = true;
+			invalidate();
+		}, collapseDelayMs());
+	}
+	return false;
+}

package/src/data.test.ts

@@ -100,33 +100,25 @@ describe("lookupInIndex", () => {
 	]);
 
 	it("finds exact match", () => {
-		expect(lookupInIndex("claude-sonnet-4-5", index)?.name).toBe(
-			"Claude Sonnet 4.5",
-		);
+		expect(lookupInIndex("claude-sonnet-4-5", index)?.name).toBe("Claude Sonnet 4.5");
 	});
 
 	it("strips provider prefix (provider/model)", () => {
-		expect(lookupInIndex("anthropic/claude-opus-4", index)?.name).toBe(
-			"Claude Opus 4",
-		);
+		expect(lookupInIndex("anthropic/claude-opus-4", index)?.name).toBe("Claude Opus 4");
 	});
 
 	it("strips deep prefix (cc/model)", () => {
-		expect(lookupInIndex("cc/claude-opus-4", index)?.name).toBe(
-			"Claude Opus 4",
-		);
+		expect(lookupInIndex("cc/claude-opus-4", index)?.name).toBe("Claude Opus 4");
 	});
 
 	it("strips date suffix", () => {
-		expect(lookupInIndex("claude-sonnet-4-5-20250514", index)?.name).toBe(
-			"Claude Sonnet 4.5",
-		);
+		expect(lookupInIndex("claude-sonnet-4-5-20250514", index)?.name).toBe("Claude Sonnet 4.5");
 	});
 
 	it("strips provider prefix + date suffix", () => {
-		expect(
-			lookupInIndex("anthropic/claude-sonnet-4-5-20250514", index)?.name,
-		).toBe("Claude Sonnet 4.5");
+		expect(lookupInIndex("anthropic/claude-sonnet-4-5-20250514", index)?.name).toBe(
+			"Claude Sonnet 4.5",
+		);
 	});
 
 	it("returns undefined for unknown model", () => {
@@ -183,10 +175,7 @@ describe("modelgrep adapters", () => {
 	});
 
 	it("lookupModelsDev finds hy3 via prefix + suffix strip", () => {
-		expect(
-			lookupModelsDev("openrouter", "tencent/hy3-preview:nitro")?.limit
-				?.context,
-		).toBe(256000);
+		expect(lookupModelsDev("openrouter", "tencent/hy3-preview:nitro")?.limit?.context).toBe(256000);
 	});
 
 	it("lookupModelsDev returns undefined for unknown model", () => {
@@ -251,8 +240,7 @@ describe("benchlm fallback", () => {
 
 	beforeEach(() => {
 		(modelgrep as unknown as { _mem: ModelGrepModel[] })._mem = catalog;
-		(benchlm as unknown as { _mem: typeof benchlmEntries })._mem =
-			benchlmEntries;
+		(benchlm as unknown as { _mem: typeof benchlmEntries })._mem = benchlmEntries;
 	});
 	afterEach(() => {
 		(modelgrep as unknown as { _mem: ModelGrepModel[] | null })._mem = null;
@@ -293,14 +281,11 @@ describe("modelgrep AA primary wins over benchlm", () => {
 			bench: { intelligence: 60 }, // AA index: 60/65 → 92
 		}),
 	];
-	const benchlmEntries = [
-		{ rank: 1, model: "Claude Opus 4.8", overallScore: 50 },
-	];
+	const benchlmEntries = [{ rank: 1, model: "Claude Opus 4.8", overallScore: 50 }];
 
 	beforeEach(() => {
 		(modelgrep as unknown as { _mem: ModelGrepModel[] })._mem = catalog;
-		(benchlm as unknown as { _mem: typeof benchlmEntries })._mem =
-			benchlmEntries;
+		(benchlm as unknown as { _mem: typeof benchlmEntries })._mem = benchlmEntries;
 	});
 	afterEach(() => {
 		(modelgrep as unknown as { _mem: ModelGrepModel[] | null })._mem = null;

package/src/data.ts

@@ -40,10 +40,7 @@ export interface ModelsDevModel {
 	};
 }
 
-export type ModelsDevApi = Record<
-	string,
-	{ models?: Record<string, ModelsDevModel> }
->;
+export type ModelsDevApi = Record<string, { models?: Record<string, ModelsDevModel> }>;
 
 export interface BenchmarkEntry {
 	rank: number;
@@ -158,13 +155,8 @@ export class DataSource<T> {
 			return val;
 		}
 		try {
-			const url =
-				typeof this.opts.url === "function" ? this.opts.url() : this.opts.url;
-			const raw = await this.opts.fetchRaw(
-				url,
-				this.opts.headers(),
-				this.opts.timeoutMs,
-			);
+			const url = typeof this.opts.url === "function" ? this.opts.url() : this.opts.url;
+			const raw = await this.opts.fetchRaw(url, this.opts.headers(), this.opts.timeoutMs);
 			const val = this.opts.parse(raw);
 			this._mem = val;
 			void this._writeCache(raw);
@@ -172,9 +164,7 @@ export class DataSource<T> {
 		} catch (error) {
 			const msg = error instanceof Error ? error.message : String(error);
 			if (cached !== undefined) {
-				console.warn(
-					`${this.opts.label} fetch failed, using stale cache: ${msg}`,
-				);
+				console.warn(`${this.opts.label} fetch failed, using stale cache: ${msg}`);
 				const val = this.opts.parseCache(cached.data);
 				this._mem = val;
 				return val;
@@ -184,9 +174,7 @@ export class DataSource<T> {
 		}
 	}
 
-	private async _readCache(): Promise<
-		{ ts: number; data: unknown } | undefined
-	> {
+	private async _readCache(): Promise<{ ts: number; data: unknown } | undefined> {
 		try {
 			const raw = await readFile(this.opts.cachePath, "utf8");
 			const parsed = JSON.parse(raw) as { ts: number; data: unknown };
@@ -200,10 +188,7 @@ export class DataSource<T> {
 	private async _writeCache(data: unknown): Promise<void> {
 		try {
 			await mkdir(dirname(this.opts.cachePath), { recursive: true });
-			await writeFile(
-				this.opts.cachePath,
-				JSON.stringify({ ts: Date.now(), data }),
-			);
+			await writeFile(this.opts.cachePath, JSON.stringify({ ts: Date.now(), data }));
 		} catch {
 			// Write failure is non-fatal — stale cache used on next run
 		}
@@ -217,9 +202,7 @@ function fetchWithTimeout(
 ): Promise<Response> {
 	const controller = new AbortController();
 	const timer = setTimeout(() => controller.abort(), timeoutMs);
-	return fetch(url, { signal: controller.signal, headers }).finally(() =>
-		clearTimeout(timer),
-	);
+	return fetch(url, { signal: controller.signal, headers }).finally(() => clearTimeout(timer));
 }
 
 /** Single-request raw fetch — the default DataSource fetch strategy. */
@@ -270,10 +253,7 @@ async function fetchModelGrepAll(
 
 // ── Cache dir ─────────────────────────────────────────────────────────────────
 
-export const CACHE_DIR = join(
-	process.env.XDG_CACHE_HOME || join(homedir(), ".cache"),
-	"pi",
-);
+export const CACHE_DIR = join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "pi");
 
 // ── Data sources ──────────────────────────────────────────────────────────────
 
@@ -375,9 +355,7 @@ function toModelsDevModel(g: ModelGrepModel): ModelsDevModel {
 	};
 }
 
-export function buildModelsDevIndex(
-	source: ModelGrepModel[],
-): Map<string, ModelsDevModel> {
+export function buildModelsDevIndex(source: ModelGrepModel[]): Map<string, ModelsDevModel> {
 	const index = new Map<string, ModelsDevModel>();
 	for (const g of source) {
 		const m = toModelsDevModel(g);
@@ -388,18 +366,13 @@ export function buildModelsDevIndex(
 	return index;
 }
 
-export function lookupModelsDev(
-	_provider: string,
-	id: string,
-): ModelsDevModel | undefined {
+export function lookupModelsDev(_provider: string, id: string): ModelsDevModel | undefined {
 	// Provider prefix differs between Pi routing (cc/ds/openrouter) and modelgrep
 	// (anthropic/tencent), so join on the model slug only via the normalized index.
 	return findInIndex(id, buildModelsDevIndex(modelgrep.getCached()));
 }
 
-export async function fetchModelsDevIndex(): Promise<
-	Map<string, ModelsDevModel>
-> {
+export async function fetchModelsDevIndex(): Promise<Map<string, ModelsDevModel>> {
 	return buildModelsDevIndex(await modelgrep.get());
 }
 
@@ -438,9 +411,7 @@ const clamp01to100 = (x: number) => Math.max(0, Math.min(100, x));
 // agentic-heavy (.60) since tool-call matters most, coding (.30), reasoning a
 // .10 tiebreaker. Sub-weights likewise fit — tau2 dominates the agentic group.
 function heuristicScore(
-	aa: NonNullable<
-		NonNullable<ModelGrepModel["benchmarks"]>["artificial_analysis"]
-	>,
+	aa: NonNullable<NonNullable<ModelGrepModel["benchmarks"]>["artificial_analysis"]>,
 ): number | null {
 	const coding = blend([
 		[0.6, frac(aa.coding)],
@@ -464,17 +435,13 @@ function heuristicScore(
 // Model score 0–100. Prefer AA's Intelligence Index (authoritative 9-eval
 // composite); when absent, map our heuristic onto the index scale via the
 // fitted line. Null only when nothing is benchmarked.
-function codingScore(
-	bench: NonNullable<ModelGrepModel["benchmarks"]>,
-): number | null {
+function codingScore(bench: NonNullable<ModelGrepModel["benchmarks"]>): number | null {
 	const aa = bench.artificial_analysis ?? {};
 	if (aa.intelligence != null) {
 		return Math.round((aa.intelligence / INTELLIGENCE_MAX) * 100);
 	}
 	const h = heuristicScore(aa);
-	return h == null
-		? null
-		: Math.round(clamp01to100(FALLBACK_SLOPE * h + FALLBACK_INTERCEPT));
+	return h == null ? null : Math.round(clamp01to100(FALLBACK_SLOPE * h + FALLBACK_INTERCEPT));
 }
 
 function buildBenchIndex(): Map<string, BenchmarkEntry> {
@@ -508,8 +475,7 @@ function buildBenchIndex(): Map<string, BenchmarkEntry> {
 			inputPrice: g.pricing?.input ?? null,
 			outputPrice: g.pricing?.output ?? null,
 		};
-		for (const k of [slug, normalize(slug)])
-			if (!index.has(k)) index.set(k, entry);
+		for (const k of [slug, normalize(slug)]) if (!index.has(k)) index.set(k, entry);
 	});
 	return index;
 }
@@ -544,8 +510,7 @@ function lookupBenchlmScore(
 	if (direct) candidates.push(...direct);
 	for (const [key, entries] of benchlmByNorm) {
 		if (key === norm) continue;
-		if (key.startsWith(norm) || norm.startsWith(key))
-			candidates.push(...entries);
+		if (key.startsWith(norm) || norm.startsWith(key)) candidates.push(...entries);
 	}
 	if (candidates.length === 0) return null;
 
@@ -555,10 +520,7 @@ function lookupBenchlmScore(
 		const sa = a.overallScore ?? -Infinity;
 		const sb = b.overallScore ?? -Infinity;
 		if (sa !== sb) return sb - sa;
-		return (
-			normalizeBenchlmName(a.model).length -
-			normalizeBenchlmName(b.model).length
-		);
+		return normalizeBenchlmName(a.model).length - normalizeBenchlmName(b.model).length;
 	});
 	const best = sorted[0];
 	if (!best) return null;

package/src/pix-config.ts

@@ -0,0 +1,299 @@
+/**
+ * pix-config.ts — unified config loader for ~/.pi/agent/pix.json
+ *
+ * Single source of truth for all pix-* configuration. The file is read once
+ * on first access and cached in-process. A `reloadPixConfig()` function is
+ * exposed for slash-commands that edit the file live.
+ *
+ * Design:
+ *   - Every key is explicit: absence → default, `false` → disabled.
+ *   - Env vars still win when set (backward compat), but the JSON file is the
+ *     primary config surface.
+ *   - Schema is flat-ish with namespaced top-level sections.
+ *
+ * File: ~/.pi/agent/pix.json
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface CollapseConfig {
+	/** Master toggle. `false` = never collapse any tool. Default: `true`. */
+	enabled: boolean;
+	/** Seconds before a tool card collapses. Default: `10`. */
+	delaySec: number;
+	/** Per-tool overrides. Missing key = follows `enabled`. */
+	tools: Partial<Record<string, boolean>>;
+}
+
+export interface DiffColors {
+	splitMinWidth: number;
+	splitMinCodeWidth: number;
+	bgAdd: string;
+	bgDel: string;
+	bgAddHighlight: string;
+	bgDelHighlight: string;
+	bgGutterAdd: string;
+	bgGutterDel: string;
+	fgAdd: string;
+	fgDel: string;
+}
+
+export interface PrettyConfig {
+	theme: string;
+	icons: string;
+	maxPreviewLines: number;
+	maxRenderLines: number;
+	maxHighlightChars: number;
+	cacheLimit: number;
+	diff: DiffColors;
+}
+
+export interface OptimizerConfig {
+	caveman: string;
+	rtk: string;
+	toon: string;
+	ponytail: string;
+}
+
+export interface GateRuleConfig {
+	pattern: string;
+	flags?: string;
+	severity?: string;
+	reason?: string;
+}
+
+export interface GateConfig {
+	disableDefaults: boolean;
+	autoApprove: string[];
+	extraRules: GateRuleConfig[];
+}
+
+export interface PixConfig {
+	collapse: CollapseConfig;
+	pretty: PrettyConfig;
+	optimizer: OptimizerConfig;
+	gate: GateConfig;
+}
+
+// ── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_DIFF: DiffColors = {
+	splitMinWidth: 150,
+	splitMinCodeWidth: 60,
+	bgAdd: "#163826",
+	bgDel: "#2d1919",
+	bgAddHighlight: "#234b32",
+	bgDelHighlight: "#502323",
+	bgGutterAdd: "#12201a",
+	bgGutterDel: "#261616",
+	fgAdd: "#64b478",
+	fgDel: "#c86464",
+};
+
+const DEFAULT_COLLAPSE: CollapseConfig = {
+	enabled: true,
+	delaySec: 10,
+	tools: {},
+};
+
+const DEFAULT_PRETTY: PrettyConfig = {
+	theme: "github-dark",
+	icons: "nerd",
+	maxPreviewLines: 80,
+	maxRenderLines: 150,
+	maxHighlightChars: 80_000,
+	cacheLimit: 128,
+	diff: { ...DEFAULT_DIFF },
+};
+
+const DEFAULT_OPTIMIZER: OptimizerConfig = {
+	caveman: "off",
+	rtk: "off",
+	toon: "off",
+	ponytail: "off",
+};
+
+const DEFAULT_GATE: GateConfig = {
+	disableDefaults: false,
+	autoApprove: [],
+	extraRules: [],
+};
+
+/** Full default config — used by tests and documentation. */
+export const DEFAULT_CONFIG: PixConfig = {
+	collapse: { ...DEFAULT_COLLAPSE },
+	pretty: { ...DEFAULT_PRETTY },
+	optimizer: { ...DEFAULT_OPTIMIZER },
+	gate: { ...DEFAULT_GATE },
+};
+
+// ── Loader ───────────────────────────────────────────────────────────────────
+
+let cached: PixConfig | null = null;
+
+function configPath(): string | undefined {
+	const home = process.env.HOME ?? "";
+	if (!home) return undefined;
+	return join(home, ".pi/agent", "pix.json");
+}
+
+/** Seed file written on first load so users have a reference to edit. */
+function seedConfigFile(p: string): void {
+	try {
+		mkdirSync(dirname(p), { recursive: true });
+		writeFileSync(p, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, {
+			flag: "wx", // exclusive create — no-op if file appeared between check and write
+		});
+	} catch {
+		/* race / permission — harmless */
+	}
+}
+
+function readRawConfig(): Record<string, unknown> {
+	try {
+		const p = configPath();
+		if (!p) return {};
+		if (!existsSync(p)) {
+			seedConfigFile(p);
+			return {};
+		}
+		return JSON.parse(readFileSync(p, "utf-8")) as Record<string, unknown>;
+	} catch {
+		return {};
+	}
+}
+
+// ── Merge helpers ────────────────────────────────────────────────────────────
+
+function isObj(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+function num(v: unknown, fallback: number): number {
+	return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : fallback;
+}
+
+function str(v: unknown, fallback: string): string {
+	return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+
+function bool(v: unknown, fallback: boolean): boolean {
+	return typeof v === "boolean" ? v : fallback;
+}
+
+function strArr(v: unknown): string[] {
+	if (!Array.isArray(v)) return [];
+	return v.filter((x): x is string => typeof x === "string");
+}
+
+function mergeCollapse(raw: unknown): CollapseConfig {
+	if (!isObj(raw)) return { ...DEFAULT_COLLAPSE };
+	const tools: Partial<Record<string, boolean>> = {};
+	if (isObj(raw.tools)) {
+		for (const [k, v] of Object.entries(raw.tools)) {
+			if (typeof v === "boolean") tools[k] = v;
+		}
+	}
+	return {
+		enabled: bool(raw.enabled, DEFAULT_COLLAPSE.enabled),
+		delaySec: num(raw.delaySec, DEFAULT_COLLAPSE.delaySec),
+		tools,
+	};
+}
+
+function mergeDiff(raw: unknown): DiffColors {
+	if (!isObj(raw)) return { ...DEFAULT_DIFF };
+	return {
+		splitMinWidth: num(raw.splitMinWidth, DEFAULT_DIFF.splitMinWidth),
+		splitMinCodeWidth: num(raw.splitMinCodeWidth, DEFAULT_DIFF.splitMinCodeWidth),
+		bgAdd: str(raw.bgAdd, DEFAULT_DIFF.bgAdd),
+		bgDel: str(raw.bgDel, DEFAULT_DIFF.bgDel),
+		bgAddHighlight: str(raw.bgAddHighlight, DEFAULT_DIFF.bgAddHighlight),
+		bgDelHighlight: str(raw.bgDelHighlight, DEFAULT_DIFF.bgDelHighlight),
+		bgGutterAdd: str(raw.bgGutterAdd, DEFAULT_DIFF.bgGutterAdd),
+		bgGutterDel: str(raw.bgGutterDel, DEFAULT_DIFF.bgGutterDel),
+		fgAdd: str(raw.fgAdd, DEFAULT_DIFF.fgAdd),
+		fgDel: str(raw.fgDel, DEFAULT_DIFF.fgDel),
+	};
+}
+
+function mergePretty(raw: unknown): PrettyConfig {
+	if (!isObj(raw)) return { ...DEFAULT_PRETTY };
+	return {
+		theme: str(raw.theme, DEFAULT_PRETTY.theme),
+		icons: str(raw.icons, DEFAULT_PRETTY.icons),
+		maxPreviewLines: num(raw.maxPreviewLines, DEFAULT_PRETTY.maxPreviewLines),
+		maxRenderLines: num(raw.maxRenderLines, DEFAULT_PRETTY.maxRenderLines),
+		maxHighlightChars: num(raw.maxHighlightChars, DEFAULT_PRETTY.maxHighlightChars),
+		cacheLimit: num(raw.cacheLimit, DEFAULT_PRETTY.cacheLimit),
+		diff: mergeDiff(raw.diff),
+	};
+}
+
+function mergeOptimizer(raw: unknown): OptimizerConfig {
+	if (!isObj(raw)) return { ...DEFAULT_OPTIMIZER };
+	return {
+		caveman: str(raw.caveman, DEFAULT_OPTIMIZER.caveman),
+		rtk: str(raw.rtk, DEFAULT_OPTIMIZER.rtk),
+		toon: str(raw.toon, DEFAULT_OPTIMIZER.toon),
+		ponytail: str(raw.ponytail, DEFAULT_OPTIMIZER.ponytail),
+	};
+}
+
+function mergeGateRules(raw: unknown): GateRuleConfig[] {
+	if (!Array.isArray(raw)) return [];
+	return raw.filter(
+		(r): r is GateRuleConfig =>
+			isObj(r) && typeof (r as Record<string, unknown>).pattern === "string",
+	);
+}
+
+function mergeGate(raw: unknown): GateConfig {
+	if (!isObj(raw)) return { ...DEFAULT_GATE };
+	return {
+		disableDefaults: bool(raw.disableDefaults, DEFAULT_GATE.disableDefaults),
+		autoApprove: strArr(raw.autoApprove),
+		extraRules: mergeGateRules(raw.extraRules),
+	};
+}
+
+function buildConfig(raw: Record<string, unknown>): PixConfig {
+	return {
+		collapse: mergeCollapse(raw.collapse),
+		pretty: mergePretty(raw.pretty),
+		optimizer: mergeOptimizer(raw.optimizer),
+		gate: mergeGate(raw.gate),
+	};
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/** Get the resolved pix config. Loads from disk on first call, cached after. */
+export function pixConfig(): PixConfig {
+	if (!cached) cached = buildConfig(readRawConfig());
+	return cached;
+}
+
+/** Re-read pix.json from disk. Call after editing the file live. */
+export function reloadPixConfig(): PixConfig {
+	cached = buildConfig(readRawConfig());
+	return cached;
+}
+
+/** Check if a tool should auto-collapse its output card. */
+export function shouldCollapse(toolName: string): boolean {
+	const c = pixConfig().collapse;
+	// Per-tool override wins.
+	const perTool = c.tools[toolName];
+	if (typeof perTool === "boolean") return perTool;
+	// Fall back to master toggle.
+	return c.enabled;
+}
+
+/** Get the collapse delay in milliseconds. */
+export function collapseDelayMs(): number {
+	return pixConfig().collapse.delaySec * 1000;
+}