@xynogen/pix-data 0.3.0 → 0.3.2

package/README.md

@@ -154,8 +154,9 @@ pix-data hosts the **single shared config file** consumed by every `pix-*` packa
 
   // Rendering options (pix-pretty)
   "pretty": {
-    "theme": "monokai",       // syntax-highlight theme (overrides PRETTY_THEME)
+    "syntaxTheme": "monokai",       // syntax-highlight theme (overrides PRETTY_THEME)
     "icons": "nerd",          // icon mode: nerd | unicode | ascii (overrides PRETTY_ICONS)
+    "lsStyle": "grid",        // ls output layout: "grid" (horizontal) | "tree" (vertical)
     "maxPreviewLines": 50,    // overrides PRETTY_MAX_PREVIEW_LINES
     "diffColors": true        // colored diff output
   },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-data",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Pi extension — shared model data layer (models.dev + BenchLM), cached at ~/.cache/pi",
 	"type": "module",
 	"main": "src/index.ts",

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/index.ts

@@ -10,6 +10,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { benchlm, modelgrep } from "./data.ts";
+import { registerPixCommand } from "./pix-command.ts";
 
 export type {
 	BenchmarkEntry,
@@ -33,7 +34,8 @@ export {
 	modelgrep,
 } from "./data.ts";
 
-export default function (_pi: ExtensionAPI): void {
+export default function (pi: ExtensionAPI): void {
 	void modelgrep.get();
 	void benchlm.get();
+	registerPixCommand(pi);
 }

package/src/pix-command.ts

@@ -0,0 +1,298 @@
+/**
+ * pix-command.ts — the `/pix` command: unified settings overlay for pix.json.
+ *
+ * Opens an interactive overlay that surfaces every section of
+ * `~/.pi/agent/pix.json` as a browsable, editable settings panel. Each setting
+ * is a row with ←→ to cycle its value. Sections are separated by headers.
+ *
+ * Headless hosts get a notify summary instead.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { type PixConfig, pixConfig, savePixConfig } from "./pix-config.js";
+
+// ── Setting descriptors ──────────────────────────────────────────────────────
+
+interface SettingRow {
+	/** Section header — only the first row per section renders a header. */
+	section: string;
+	/** Display label. */
+	label: string;
+	/** The pix.json path: top-level key. */
+	configSection: keyof PixConfig;
+	/** The field name within the section. */
+	configKey: string;
+	/** Allowed values to cycle through. */
+	values: readonly string[];
+	/** Read the current value from config. */
+	read: (cfg: PixConfig) => string;
+}
+
+const SETTINGS: SettingRow[] = [
+	// ── Pretty ──────────────────────────────────────────────────────────────
+	{
+		section: "Pretty",
+		label: "icons",
+		configSection: "pretty",
+		configKey: "icons",
+		values: ["nerd", "unicode", "ascii"],
+		read: (c) => c.pretty.icons,
+	},
+	{
+		section: "Pretty",
+		label: "ls style",
+		configSection: "pretty",
+		configKey: "lsStyle",
+		values: ["grid", "tree"],
+		read: (c) => c.pretty.lsStyle,
+	},
+	// ── Collapse ─────────────────────────────────────────────────────────────
+	{
+		section: "Collapse",
+		label: "enabled",
+		configSection: "collapse",
+		configKey: "enabled",
+		values: ["true", "false"],
+		read: (c) => String(c.collapse.enabled),
+	},
+	{
+		section: "Collapse",
+		label: "delay (sec)",
+		configSection: "collapse",
+		configKey: "delaySec",
+		values: ["5", "10", "15", "20", "30", "60"],
+		read: (c) => String(c.collapse.delaySec),
+	},
+	// ── Optimizer ─────────────────────────────────────────────────────────────
+	{
+		section: "Optimizer",
+		label: "caveman",
+		configSection: "optimizer",
+		configKey: "caveman",
+		values: ["off", "lite", "full", "ultra", "micro"],
+		read: (c) => c.optimizer.caveman,
+	},
+	{
+		section: "Optimizer",
+		label: "rtk",
+		configSection: "optimizer",
+		configKey: "rtk",
+		values: ["off", "on"],
+		read: (c) => c.optimizer.rtk,
+	},
+	{
+		section: "Optimizer",
+		label: "toon",
+		configSection: "optimizer",
+		configKey: "toon",
+		values: ["off", "on"],
+		read: (c) => c.optimizer.toon,
+	},
+	{
+		section: "Optimizer",
+		label: "ponytail",
+		configSection: "optimizer",
+		configKey: "ponytail",
+		values: ["off", "lite", "full", "ultra"],
+		read: (c) => c.optimizer.ponytail,
+	},
+	// ── Gate ──────────────────────────────────────────────────────────────────
+	{
+		section: "Gate",
+		label: "disable defaults",
+		configSection: "gate",
+		configKey: "disableDefaults",
+		values: ["false", "true"],
+		read: (c) => String(c.gate.disableDefaults),
+	},
+];
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Coerce string values back to proper JSON types for saving. */
+function coerce(value: string): string | number | boolean {
+	if (value === "true") return true as unknown as string;
+	if (value === "false") return false as unknown as string;
+	const n = Number(value);
+	if (Number.isFinite(n) && String(n) === value) return n as unknown as string;
+	return value;
+}
+
+/** Build a plain text summary for headless hosts. */
+function buildSummary(): string {
+	const cfg = pixConfig();
+	const lines = ["pix settings (~/.pi/agent/pix.json)", ""];
+	let lastSection = "";
+	for (const row of SETTINGS) {
+		if (row.section !== lastSection) {
+			if (lastSection) lines.push("");
+			lines.push(`[${row.section}]`);
+			lastSection = row.section;
+		}
+		lines.push(`  ${row.label}: ${row.read(cfg)}`);
+	}
+	return lines.join("\n");
+}
+
+// ── Command registration ─────────────────────────────────────────────────────
+
+export function registerPixCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("pix", {
+		description: "pix: open settings (edit ~/.pi/agent/pix.json)",
+		handler: async (_args: string, ctx: ExtensionCommandContext) => {
+			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 fallback.
+			if (typeof ui.custom !== "function") {
+				ui.notify(buildSummary(), "info");
+				return;
+			}
+
+			const boxW = 52;
+
+			await ui.custom<null>(
+				(
+					tui: { requestRender(): void },
+					theme: typeof ui.theme,
+					_kb: unknown,
+					done: (v: null) => void,
+				) => {
+					let selected = 0;
+					let cfg = pixConfig();
+
+					/** Cycle the selected setting's value. */
+					const cycle = (direction: -1 | 1) => {
+						const row = SETTINGS[selected];
+						if (!row) return;
+						const vals = row.values;
+						const cur = vals.indexOf(row.read(cfg));
+						const next = (cur + direction + vals.length) % vals.length;
+						const val = vals[next];
+						if (val === undefined) return;
+
+						// Persist to pix.json.
+						cfg = savePixConfig({
+							[row.configSection]: { [row.configKey]: coerce(val) },
+						});
+					};
+
+					const move = (direction: -1 | 1) => {
+						selected = (selected + direction + SETTINGS.length) % SETTINGS.length;
+					};
+
+					return {
+						render: () => {
+							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
+							const lines: string[] = [theme.fg("accent", theme.bold("  pix settings")), ""];
+
+							let lastSection = "";
+							for (let i = 0; i < SETTINGS.length; i++) {
+								const row = SETTINGS[i]!;
+								// Section header.
+								if (row.section !== lastSection) {
+									if (lastSection) lines.push("");
+									lines.push(theme.fg("dim", `  ${row.section}`));
+									lastSection = row.section;
+								}
+
+								const sel = i === selected;
+								const cursor = sel ? theme.fg("accent", "→") : " ";
+								const label = theme.fg(sel ? "accent" : "text", row.label.padEnd(labelW));
+								const val = row.read(cfg);
+								const isDefault = val === row.values[0];
+								const value = theme.fg(isDefault ? "dim" : "success", val);
+								lines.push(`${cursor} ${label}  ${value}`);
+							}
+
+							lines.push("");
+							lines.push(theme.fg("dim", "←→ change · ↑↓ move · esc close"));
+
+							return frameLines({
+								width: boxW,
+								lines,
+								color: (s: string) => theme.fg("accent", s),
+								bg: (s: string) => theme.bg("customMessageBg", s),
+							});
+						},
+						invalidate: () => {},
+						handleInput: (data: string) => {
+							if (data === "k" || data === "\u001b[A") move(-1);
+							else if (data === "j" || data === "\u001b[B") move(1);
+							else if (data === "h" || data === "\u001b[D") cycle(-1);
+							else if (data === "l" || data === "\u001b[C" || data === " " || data === "\r")
+								cycle(1);
+							else if (data === "\u001b" || data === "q") {
+								done(null);
+								return;
+							} else return;
+							tui.requestRender();
+						},
+					};
+				},
+				{
+					overlay: true,
+					overlayOptions: { anchor: "center", width: boxW, maxHeight: "80%" },
+				},
+			);
+		},
+	});
+}
+
+// ── Inline frameLines (avoid cross-package dep on pix-pretty) ────────────────
+
+interface FrameOptions {
+	width: number;
+	lines: string[];
+	color: (s: string) => string;
+	bg?: (s: string) => string;
+}
+
+function visibleWidth(s: string): number {
+	// Strip ANSI escape sequences for width calculation.
+	return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
+
+function frameLines(opts: FrameOptions): string[] {
+	const { width, lines, color } = opts;
+	const bg = opts.bg ?? ((s: string) => s);
+	const inner = Math.max(1, width - 4); // 2 border + 2 padding
+	const dashes = "─".repeat(width - 2);
+
+	const SENTINEL = "\x00";
+	const bgOpen = bg(SENTINEL).split(SENTINEL)[0] ?? "";
+	const reassert = (s: string): string =>
+		bgOpen
+			? s.replace(/\x1b\[([0-9;]*)m/g, (seq, p: string) =>
+					p === "0" || p.split(";").includes("49") ? `${seq}${bgOpen}` : seq,
+				)
+			: s;
+
+	const row = (content: string): string => {
+		const pad = inner - visibleWidth(content);
+		const padded = pad > 0 ? content + " ".repeat(pad) : content.slice(0, inner);
+		return bg(`${color("│")} ${reassert(padded)} ${color("│")}`);
+	};
+
+	const out: string[] = [bg(color(`╭${dashes}╮`))];
+	for (const line of lines) out.push(row(line));
+	out.push(bg(color(`╰${dashes}╯`)));
+	return out;
+}

package/src/pix-config.ts

@@ -41,9 +41,13 @@ export interface DiffColors {
 	fgDel: string;
 }
 
+/** How `ls` output is rendered: `"grid"` (horizontal columns) or `"tree"` (vertical tree view). */
+export type LsStyle = "grid" | "tree";
+
 export interface PrettyConfig {
-	theme: string;
 	icons: string;
+	/** `"grid"` = horizontal columns (default), `"tree"` = vertical tree view. */
+	lsStyle: LsStyle;
 	maxPreviewLines: number;
 	maxRenderLines: number;
 	maxHighlightChars: number;
@@ -100,8 +104,8 @@ const DEFAULT_COLLAPSE: CollapseConfig = {
 };
 
 const DEFAULT_PRETTY: PrettyConfig = {
-	theme: "github-dark",
 	icons: "nerd",
+	lsStyle: "grid",
 	maxPreviewLines: 80,
 	maxRenderLines: 150,
 	maxHighlightChars: 80_000,
@@ -208,10 +212,7 @@ 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,
-		),
+		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),
@@ -223,17 +224,19 @@ function mergeDiff(raw: unknown): DiffColors {
 	};
 }
 
+function lsStyle(v: unknown): LsStyle {
+	if (v === "grid" || v === "tree") return v;
+	return DEFAULT_PRETTY.lsStyle;
+}
+
 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),
+		lsStyle: lsStyle(raw.lsStyle),
 		maxPreviewLines: num(raw.maxPreviewLines, DEFAULT_PRETTY.maxPreviewLines),
 		maxRenderLines: num(raw.maxRenderLines, DEFAULT_PRETTY.maxRenderLines),
-		maxHighlightChars: num(
-			raw.maxHighlightChars,
-			DEFAULT_PRETTY.maxHighlightChars,
-		),
+		maxHighlightChars: num(raw.maxHighlightChars, DEFAULT_PRETTY.maxHighlightChars),
 		cacheLimit: num(raw.cacheLimit, DEFAULT_PRETTY.cacheLimit),
 		diff: mergeDiff(raw.diff),
 	};
@@ -275,6 +278,20 @@ function buildConfig(raw: Record<string, unknown>): PixConfig {
 	};
 }
 
+// ── Change listeners ─────────────────────────────────────────────────────────
+
+type ConfigListener = (cfg: PixConfig) => void;
+const configListeners = new Set<ConfigListener>();
+
+/**
+ * Subscribe to config changes (fired by `savePixConfig`). Returns unsubscribe.
+ * Listeners receive the freshly-reloaded PixConfig.
+ */
+export function onPixConfigChange(cb: ConfigListener): () => void {
+	configListeners.add(cb);
+	return () => configListeners.delete(cb);
+}
+
 // ── Public API ───────────────────────────────────────────────────────────────
 
 /** Get the resolved pix config. Loads from disk on first call, cached after. */
@@ -303,3 +320,44 @@ export function shouldCollapse(toolName: string): boolean {
 export function collapseDelayMs(): number {
 	return pixConfig().collapse.delaySec * 1000;
 }
+
+/** Get the ls rendering style: `"grid"` (horizontal) or `"tree"` (vertical). */
+export function getLsStyle(): LsStyle {
+	return pixConfig().pretty.lsStyle;
+}
+
+/**
+ * Merge a partial update into pix.json and reload the in-process cache.
+ * Only the keys present in `patch` are overwritten; the rest of the file is
+ * preserved. Nested objects (e.g. `pretty`, `collapse`) are shallow-merged
+ * one level deep so callers can update a single field without wiping siblings.
+ */
+export function savePixConfig(patch: Record<string, unknown>): PixConfig {
+	const p = configPath();
+	if (!p) return pixConfig();
+	try {
+		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 = {};
+			}
+		}
+		// Shallow-merge each top-level section so partial updates don't wipe siblings.
+		for (const [key, value] of Object.entries(patch)) {
+			if (isObj(value) && isObj(existing[key])) {
+				existing[key] = { ...(existing[key] as Record<string, unknown>), ...value };
+			} else {
+				existing[key] = value;
+			}
+		}
+		writeFileSync(p, `${JSON.stringify(existing, null, 2)}\n`);
+	} catch (err) {
+		console.warn("pix-config: save failed:", err);
+	}
+	const cfg = reloadPixConfig();
+	for (const cb of configListeners) cb(cfg);
+	return cfg;
+}