@zenodinh/pi-render 0.0.0-stage → 0.1.2

package/src/core/code-theme.ts

@@ -0,0 +1,275 @@
+// ported from pi-pretty-tui/src/core/render.ts:48-140 — survives because: the theme fallback with one log
+// line, the LRU keyed theme+lang+code, the 80k size gate and the low-contrast fg normalization are the one
+// place a highlight decision is made.
+
+/**
+ * code-theme.ts — syntax highlighting behind two calls: rows await `highlight`, panels call `highlightSync`;
+ * one cache serves both, so a block is highlighted once per theme.
+ *
+ * Boundary: `codeTheme` arrives from the injected registry as persisted JSON and is narrowed here before it
+ * is read; diagnostics go to the injected logOnce sink. The shiki adapter below ports
+ * pi-pretty-tui/src/features/canvas/code-panel.ts:16-140 (warm sync core, JavaScript regex engine, the
+ * predecessor's grammar set) and returns shiki's own token colours — that is the highlighting; the package
+ * palette stays in paint.ts.
+ *
+ * shape: none — dispatch object / Strategy do not apply: two factories over one cache and one warm core,
+ * with no discriminator to dispatch on. Each factory declares its own shape below.
+ */
+
+import type { BundledLanguage } from "shiki";
+import type { Logger } from "./types/log.ts";
+import type { ModuleDescriptor, Registry } from "./types/registry.ts";
+import type { CodeTheme, HighlightEngine } from "./types.ts";
+
+/** Bundled theme set: the predecessor's five trimmed to the two the host themes ship (PRD EB-1). */
+const THEMES = ["dracula-soft", "one-dark-pro"] as const;
+
+/** A bundled theme name — the closed set a `codeTheme` setting is allowed to name. */
+export type CodeThemeName = (typeof THEMES)[number];
+
+const MODULE_KEY = "codetheme";
+const SETTING = "codeTheme";
+const SCOPE = "code-theme";
+const DEFAULT_THEME: CodeThemeName = "dracula-soft";
+
+/** The descriptor T-28 registers for the /render panel; exported here, never registered here. */
+export const CODE_THEME_MODULE: ModuleDescriptor = {
+	key: MODULE_KEY,
+	name: "Code theme",
+	defaultEnabled: true,
+	settings: [{ name: SETTING, kind: "enum", values: [...THEMES], default: DEFAULT_THEME }],
+};
+
+/** Bounded by entries, not bytes: one entry is at most MAX_HL_CHARS, and the cap is the predecessor's. */
+const CACHE_LIMIT = 128;
+/** Past this size highlighting costs more than it is worth (P render.ts:86). */
+const MAX_HL_CHARS = 80_000;
+/** Readability floor for a token colour over the host background (P render.ts:124). */
+const MIN_FG_LUMINANCE = 72;
+
+/** Settings read plus the diagnostics sink — the whole injected surface, so a test double is three lines. */
+export interface CodeThemeOptions {
+	/** Effective settings by module key. Optional; absent reads the default theme. */
+	registry?: Pick<Registry, "getSettings">;
+	/** Once-per-key diagnostics. Optional; absent is silent. */
+	log?: Pick<Logger, "logOnce">;
+}
+
+/** Binds the engine to one theme: production memoizes per theme over one warm core, tests count the calls. */
+export type BindHighlightEngine = (theme: CodeThemeName) => HighlightEngine;
+
+/** boundary: `codeTheme` is persisted JSON, so only a bundled name is trusted; anything else falls back. */
+function isCodeThemeName(value: unknown): value is CodeThemeName {
+	return typeof value === "string" && THEMES.some((theme) => theme === value);
+}
+
+// shape: closure returning an object literal — trigger #4, two methods over one Map, no subclassing.
+export function createCodeTheme(bindEngine: BindHighlightEngine, options: CodeThemeOptions = {}): CodeTheme {
+	const cache = new Map<string, string[]>();
+
+	/** LRU: a hit moves to the tail, the head goes once the cap is passed. */
+	const remember = (key: string, lines: string[]): string[] => {
+		cache.delete(key);
+		cache.set(key, lines);
+		if (cache.size > CACHE_LIMIT) {
+			const oldest = cache.keys().next().value;
+			if (oldest !== undefined) cache.delete(oldest);
+		}
+		return lines;
+	};
+
+	/** Read per call: a settings write lands on the next render, and an unknown name falls back exactly once. */
+	const resolveTheme = (): CodeThemeName => {
+		const stored: unknown = options.registry?.getSettings(MODULE_KEY)[SETTING];
+		if (isCodeThemeName(stored)) return stored;
+		if (stored !== undefined) {
+			options.log?.logOnce(
+				`theme:${String(stored)}`,
+				SCOPE,
+				`unknown code theme "${String(stored)}" — rendering "${DEFAULT_THEME}"`,
+			);
+		}
+		return DEFAULT_THEME;
+	};
+
+	/** Engine output behind the cache; the size gate and any engine failure fall through to plain source lines. */
+	const lines = (code: string, lang: string): string[] => {
+		if (!code) return [""];
+		if (code.length > MAX_HL_CHARS) return code.split("\n");
+		const theme = resolveTheme();
+		const key = `${theme}\0${lang}\0${code}`;
+		const hit = cache.get(key);
+		if (hit !== undefined) return remember(key, hit);
+		try {
+			return remember(key, bindEngine(theme)(code, lang).map(dropLowContrastFg));
+		} catch {
+			// Shiki fails on a grammar, a theme or a broken engine; a row degrades, it never dies.
+			options.log?.logOnce(`fail:${lang}`, SCOPE, `highlight failed for "${lang}" — rendering plain`);
+			return code.split("\n");
+		}
+	};
+
+	return {
+		/** Async for the row seam; the engine itself is synchronous. */
+		highlight: async (code, lang) => lines(code, lang),
+		/** The panel seam: the same cache and engine, joined into one block. */
+		highlightSync: (code, lang) => lines(code, lang).join("\n"),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Shiki adapter
+// ---------------------------------------------------------------------------
+
+/**
+ * The ESC byte, built rather than written: a colour literal belongs to paint.ts, and the T-29 scan keeps
+ * escape literals on that one owner.
+ */
+const ESC = String.fromCharCode(27);
+const RESET = `${ESC}[0m`;
+const SGR = new RegExp(`${ESC}\\[([0-9;]*)m`, "g");
+
+/** A fence spelling the grammars below register under a different id (P code-panel.ts:73-88). */
+const LANG_ALIASES = new Map<string, string>([
+	["ts", "typescript"],
+	["js", "javascript"],
+	["py", "python"],
+	["sh", "bash"],
+	["shell", "bash"],
+	["zsh", "bash"],
+	["yml", "yaml"],
+	["md", "markdown"],
+	["golang", "go"],
+	["c++", "cpp"],
+	["c#", "csharp"],
+	["rs", "rust"],
+]);
+
+/**
+ * The grammars worth carrying — the predecessor's set (P code-panel.ts:32-62), by shiki id. Typed against
+ * shiki's own union, so an id the bundle does not carry fails the type-check instead of at first render.
+ */
+const LANG_IDS: readonly BundledLanguage[] = [
+	"typescript",
+	"tsx",
+	"javascript",
+	"jsx",
+	"python",
+	"java",
+	"json",
+	"yaml",
+	"markdown",
+	"bash",
+	"sql",
+	"xml",
+	"html",
+	"css",
+	"go",
+	"rust",
+	"diff",
+	"toml",
+	"ini",
+	"dockerfile",
+	"csharp",
+	"cpp",
+	"kotlin",
+	"php",
+	"ruby",
+	"swift",
+	"lua",
+];
+
+/** One foreground SGR too dark to read over the host background (P render.ts:112-125). */
+function isLowContrastFg(params: string): boolean {
+	if (params === "30" || params === "90" || params === "38;5;0" || params === "38;5;8") return true;
+	if (!params.startsWith("38;2;")) return false;
+	const channels = params.slice("38;2;".length).split(";").map(Number);
+	if (channels.length !== 3 || channels.some((n) => !Number.isFinite(n))) return false;
+	const [r, g, b] = channels;
+	if (r === undefined || g === undefined || b === undefined) return false;
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b < MIN_FG_LUMINANCE;
+}
+
+/**
+ * Drops such a foreground instead of substituting one: the row then renders in the theme's own foreground,
+ * which is the readable default, and no second palette appears outside paint.ts.
+ */
+function dropLowContrastFg(line: string): string {
+	return line.replace(SGR, (sequence, params: string) => (isLowContrastFg(params) ? "" : sequence));
+}
+
+/** The SGR for one token: its colour plus the font styles shiki reports as bit flags (P code-panel.ts:106-118). */
+function tokenSgr(token: { color?: string; fontStyle?: number }): string {
+	const parts: string[] = [];
+	if (typeof token.color === "string" && /^#[0-9a-f]{6}$/i.test(token.color)) {
+		const value = Number.parseInt(token.color.slice(1), 16);
+		parts.push(`38;2;${(value >> 16) & 0xff};${(value >> 8) & 0xff};${value & 0xff}`);
+	}
+	const style = token.fontStyle ?? 0;
+	if (style & 1) parts.push("3");
+	if (style & 2) parts.push("1");
+	if (style & 4) parts.push("4");
+	return parts.length > 0 ? `${ESC}[${parts.join(";")}m` : "";
+}
+
+/** One line of tokens to one SGR string; the reset after non-blank content stops a colour bleeding onward. */
+function tokensToAnsi(tokens: readonly { content: string; color?: string; fontStyle?: number }[]): string {
+	let out = RESET;
+	for (const token of tokens) {
+		out += tokenSgr(token) + token.content + (token.content.trim() === "" ? "" : RESET);
+	}
+	return out;
+}
+
+// shape: closure returning a function — trigger #4 (one warm core plus a per-theme memo, no subclassing);
+// the core itself is built lazily, so a process that never highlights never pays for shiki.
+export async function createShikiEngine(log?: Pick<Logger, "logOnce">): Promise<BindHighlightEngine> {
+	// The bundled registries come from shiki's own entry points, not from @shikijs/langs: only `shiki` is a
+	// declared dependency of this package (package.json).
+	const [core, regex, bundledLangs, bundledThemes] = await Promise.all([
+		import("shiki/core"),
+		import("shiki/engine/javascript"),
+		import("shiki/langs"),
+		import("shiki/themes"),
+	]);
+
+	// A grammar that failed to load costs that language only; the rest of the set still highlights.
+	const registrations = await Promise.all(
+		LANG_IDS.map(async (id) => (await bundledLangs.bundledLanguages[id]().catch(() => undefined))?.default),
+	);
+	const themes = await Promise.all(THEMES.map(async (name) => (await bundledThemes.bundledThemes[name]()).default));
+	const highlighter = core.createHighlighterCoreSync({
+		themes,
+		langs: registrations.filter((registration) => registration !== undefined),
+		engine: regex.createJavaScriptRegexEngine(),
+	});
+	const known = new Set(highlighter.getLoadedLanguages());
+
+	const plain = (code: string): string[] => code.split("\n");
+
+	const highlight = (code: string, lang: string, theme: CodeThemeName): string[] => {
+		// A Map lookup, not a bare object index: `lang` is caller input, so a prototype key must not resolve.
+		const id = LANG_ALIASES.get(lang) ?? lang;
+		if (!known.has(id)) {
+			log?.logOnce(`lang:${id}`, SCOPE, `unknown language "${id}" — rendering plain`);
+			return plain(code);
+		}
+		try {
+			return highlighter.codeToTokensBase(code, { lang: id, theme }).map(tokensToAnsi);
+		} catch {
+			// A grammar the engine rejects degrades that block, exactly as the predecessor's panel did.
+			log?.logOnce(`lang:${id}`, SCOPE, `highlight failed for "${id}" — rendering plain`);
+			return plain(code);
+		}
+	};
+
+	// One bound engine per theme: the low-level call takes the theme, the seam's type does not.
+	const bound = new Map<CodeThemeName, HighlightEngine>();
+	return (theme) => {
+		const engine = bound.get(theme);
+		if (engine !== undefined) return engine;
+		const boundEngine: HighlightEngine = (code, lang) => highlight(code, lang, theme);
+		bound.set(theme, boundEngine);
+		return boundEngine;
+	};
+}

package/src/core/log.ts

@@ -0,0 +1,57 @@
+/**
+ * log.ts — keyed in-memory diagnostics: logLine for scoped lines, logOnce for once-per-key lines.
+ *
+ * Memory, not a file. The predecessor resolved an agent directory and appended to disk on every line —
+ * the owner-confirmed cause of its slow start. A bounded ring costs no boot work, no fs call, and no
+ * permission that can fail; drain() is the readout tests and the future /render panel consume.
+ *
+ * Boundary: called from the render path, so nothing here throws or writes stdout/stderr — pi owns the
+ * terminal. Both hold structurally: there is no fallible operation here to catch.
+ *
+ * shape: closure returning an object literal — trigger #4, one ring buffer plus dedup marks per logger,
+ * no subclassing or instanceof.
+ */
+import type { LogEntry, Logger } from "./types/log.ts";
+
+/** A session logs thousands; the panel reads a window, so the buffer stays bounded and the rest drops. */
+const LOG_CAP = 256;
+
+export function createLogger(): Logger {
+	// Empty until the first entry: nothing is preallocated at import or construction, and pushing below
+	// the cap keeps the index math out of the common case.
+	let ring: Array<LogEntry | undefined> = [];
+	let head = 0;
+	// Marks, not entries: a panel may drain repeatedly, and a drained key must still count as logged.
+	const seen = new Set<string>();
+
+	const record = (entry: LogEntry): void => {
+		if (ring.length < LOG_CAP) {
+			ring.push(entry);
+			return;
+		}
+		ring[head] = entry;
+		head = (head + 1) % LOG_CAP;
+	};
+
+	return {
+		logLine(scope: string, message: string): void {
+			record({ scope, message, time: Date.now() });
+		},
+		logOnce(key: string, scope: string, message: string): void {
+			if (seen.has(key)) return;
+			seen.add(key);
+			record({ scope, message, time: Date.now() });
+		},
+		drain(): LogEntry[] {
+			const out: LogEntry[] = [];
+			// Once full, head is the oldest slot, so read from it and wrap.
+			for (let i = 0; i < ring.length; i += 1) {
+				const entry = ring[(head + i) % ring.length];
+				if (entry !== undefined) out.push(entry);
+			}
+			ring = [];
+			head = 0;
+			return out;
+		},
+	};
+}

package/src/core/paint.ts

@@ -0,0 +1,64 @@
+/**
+ * paint.ts — the only color source: our role vocabulary mapped onto host theme tokens.
+ *
+ * Boundary: renderers call role methods and never emit an escape (AGENTS: every escape originates
+ * here); both theme inputs are structural, so a plain-object fixture drives either factory with no
+ * host import.
+ *
+ * shape: none — dispatch object does not apply: no discriminator, each role is one token lookup. The
+ * two closure factories below declare their own shape.
+ *
+ * ported from pi-pretty-tui/src/config.ts:71-100 — survives because: "read the theme token, degrade to
+ * default when it is absent" is what resolveBaseBackground did; its dead links (`toolBg`,
+ * `background`) are dropped — neither token exists at host 1.0.4.
+ */
+
+import type { HostTheme, MarkdownTheme } from "./types/host.ts";
+import type { ContentPaint, RowPaint } from "./types/paint.ts";
+
+/** Host `fg` throws on a token the active theme lacks (`Theme.tokenAnsi`); a row degrades, never dies. */
+function fgOrPlain(theme: HostTheme, key: string, text: string): string {
+	try {
+		return theme.fg(key, text);
+	} catch {
+		return text;
+	}
+}
+
+/** Region-2 closures read the live theme proxy; a missing or throwing token falls to the next link. */
+function tryStyle(fn: ((text: string) => string) | undefined, text: string): string | undefined {
+	try {
+		return fn?.(text);
+	} catch {
+		return undefined;
+	}
+}
+
+/** Region 1 — the tool-row factory. Reads `theme` live, so the next call paints the current theme. */
+// shape: closure returning an object literal — trigger #4, eight stateless row roles over the captured theme.
+export function createRowPaint(theme: HostTheme): RowPaint {
+	return {
+		title: (text) => fgOrPlain(theme, "toolTitle", text),
+		output: (text) => fgOrPlain(theme, "toolOutput", text),
+		muted: (text) => fgOrPlain(theme, "muted", text),
+		accent: (text) => fgOrPlain(theme, "accent", text),
+		error: (text) => fgOrPlain(theme, "error", text),
+		warning: (text) => fgOrPlain(theme, "warning", text),
+		gutter: (text) => fgOrPlain(theme, "muted", text),
+		match: (text) => fgOrPlain(theme, "searchMatchText", text),
+		diffAdded: (text) => fgOrPlain(theme, "toolDiffAdded", text),
+		diffRemoved: (text) => fgOrPlain(theme, "toolDiffRemoved", text),
+		diffContext: (text) => fgOrPlain(theme, "toolDiffContext", text),
+	};
+}
+
+/** Region 2 — the content factory. `rule` degrades hr → quoteBorder → plain; every role ends in plain. */
+// shape: closure returning an object literal — trigger #4, four stateless content roles over the captured markdown theme.
+export function createContentPaint(mdTheme: MarkdownTheme): ContentPaint {
+	return {
+		rule: (text) => tryStyle(mdTheme.hr, text) ?? tryStyle(mdTheme.quoteBorder, text) ?? text,
+		quote: (text) => tryStyle(mdTheme.quote, text) ?? text,
+		code: (text) => tryStyle(mdTheme.code, text) ?? text,
+		codeBlockBorder: (text) => tryStyle(mdTheme.codeBlockBorder, text) ?? text,
+	};
+}

package/src/core/registry.ts

@@ -0,0 +1,135 @@
+/**
+ * registry.ts — the pluggable module registry: descriptors in, enabled flags and settings out.
+ *
+ * Boundary: the /render panel writes through setSettings; renderers poll isEnabled/getSettings per
+ * invocation and never write. A write lands on the next read — the registry pushes no redraw, and the
+ * injected store plus logger are the only collaborators it touches. The stored document and the patch
+ * both arrive as untrusted JSON, so every field is narrowed here before it is trusted.
+ *
+ * shape: closure returning an object literal — trigger #4, one Map of state plus methods, no subclassing.
+ */
+
+import type { Logger } from "./types/log.ts";
+import type { ModuleDescriptor, Registry, SettingSpec } from "./types/registry.ts";
+import type { ModuleSettings, SettingsDoc, SettingsStore } from "./types/settings.ts";
+
+const SCOPE = "registry";
+
+/** One registered module with its resolved state — the Map value the isEnabled hot path reads. */
+interface ModuleEntry {
+	readonly descriptor: ModuleDescriptor;
+	enabled: boolean;
+	settings: Record<string, unknown>;
+}
+
+/** boundary: a persisted slice and a settings patch both cross as untrusted JSON and narrow here. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// shape: dispatch object — trigger #1, 3 setting kinds, validators stateless.
+const FITS: Record<SettingSpec["kind"], (value: unknown, values: string[] | undefined) => boolean> = {
+	toggle: (value) => typeof value === "boolean",
+	number: (value) => typeof value === "number" && Number.isFinite(value),
+	enum: (value, values) => typeof value === "string" && (values ?? []).includes(value),
+};
+
+function fitsSpec(spec: SettingSpec, value: unknown): boolean {
+	return FITS[spec.kind](value, spec.values);
+}
+
+function logRejected(log: Logger, key: string, name: string): void {
+	log.logOnce(`invalid:${key}:${name}`, SCOPE, `ignored invalid value for ${key}.${name}`);
+}
+
+/** Reads one module's persisted slice into resolved state; anything malformed falls back, logged once. */
+function readEntry(doc: SettingsDoc, descriptor: ModuleDescriptor, log: Logger): ModuleEntry {
+	const stored: unknown = doc.modules[descriptor.key];
+	const slice = isRecord(stored) ? stored : {};
+	const enabled = slice.enabled;
+	const bag = slice.settings;
+	const settings: Record<string, unknown> = {};
+	let malformed = stored !== undefined && !isRecord(stored);
+	malformed ||= enabled !== undefined && typeof enabled !== "boolean";
+	malformed ||= bag !== undefined && !isRecord(bag);
+
+	for (const spec of descriptor.settings) {
+		// Object.hasOwn, not a bare lookup: a declared name must not read an inherited member.
+		const value = isRecord(bag) && Object.hasOwn(bag, spec.name) ? bag[spec.name] : undefined;
+		if (value === undefined) continue;
+		if (fitsSpec(spec, value)) settings[spec.name] = value;
+		else malformed = true;
+	}
+	if (malformed)
+		log.logOnce(`stored:${descriptor.key}`, SCOPE, `malformed stored entry for ${descriptor.key} — using defaults`);
+
+	return { descriptor, enabled: typeof enabled === "boolean" ? enabled : descriptor.defaultEnabled, settings };
+}
+
+export function createRegistry(store: SettingsStore, log: Logger): Registry {
+	const modules = new Map<string, ModuleEntry>();
+	// One read at boot: no render path may touch the disk, so a later write updates this cache directly.
+	const doc = store.load();
+
+	return {
+		defineModule(descriptor: ModuleDescriptor): void {
+			if (modules.has(descriptor.key)) {
+				log.logOnce(
+					`duplicate:${descriptor.key}`,
+					SCOPE,
+					`duplicate module ${descriptor.key} ignored — first definition wins`,
+				);
+				return;
+			}
+			modules.set(descriptor.key, readEntry(doc, descriptor, log));
+		},
+
+		isEnabled(key: string): boolean {
+			return modules.get(key)?.enabled ?? false;
+		},
+
+		getSettings(key: string): Record<string, unknown> {
+			const entry = modules.get(key);
+			if (entry === undefined) return {};
+			const out: Record<string, unknown> = {};
+			for (const spec of entry.descriptor.settings) {
+				out[spec.name] = Object.hasOwn(entry.settings, spec.name) ? entry.settings[spec.name] : spec.default;
+			}
+			return out;
+		},
+
+		setSettings(key: string, patch: object): void {
+			const entry = modules.get(key);
+			if (entry === undefined) {
+				log.logOnce(`unknown:${key}`, SCOPE, `ignored settings write for unknown module ${key}`);
+				return;
+			}
+			const raw: unknown = patch;
+			if (!isRecord(raw)) {
+				log.logOnce(`patch:${key}`, SCOPE, `ignored non-object settings patch for ${key}`);
+				return;
+			}
+
+			let enabled = entry.enabled;
+			const bag: Record<string, unknown> = { ...entry.settings };
+			const enabledPatch = raw.enabled;
+			if (enabledPatch !== undefined) {
+				if (typeof enabledPatch === "boolean") enabled = enabledPatch;
+				else logRejected(log, key, "enabled");
+			}
+			for (const name of Object.keys(raw)) {
+				if (name === "enabled") continue;
+				const spec = entry.descriptor.settings.find((s) => s.name === name);
+				const value = raw[name];
+				if (spec !== undefined && fitsSpec(spec, value)) bag[name] = value;
+				else logRejected(log, key, name);
+			}
+
+			const next: ModuleSettings = { enabled, settings: bag };
+			doc.modules[key] = next;
+			entry.enabled = enabled;
+			entry.settings = bag;
+			store.save(doc);
+		},
+	};
+}

package/src/core/settings.ts

@@ -0,0 +1,119 @@
+// ported from pi-pretty-tui/src/core/state.ts — survives because: its tmp+rename write and its
+// fill-defaults read are exactly the mechanics that keep one document uncorrupted and cheap to read.
+
+/**
+ * The one persisted settings document (SA §3), at `~/.pi/agent/pi-render/settings.json`.
+ *
+ * Why cached: the predecessor re-read its document inside the render path (P render.ts:62), so every
+ * row paid a disk read. Here only the first load reads; save() refreshes the cache.
+ *
+ * Why tmp+rename: a reader opening the final path mid-write must see the old document or the new one
+ * complete — never a torn file.
+ *
+ * shape: closure returning an object literal — trigger #4, this module's one runtime unit is
+ * createSettingsStore(): a cached document plus two methods, so no class, subclassing, or instanceof.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { Logger, ModuleSettings, SettingsDoc, SettingsStore } from "./types.ts";
+
+const DOC_VERSION = 1;
+
+/** Stands in when no logger is injected, so every factory call needs no logger guard. */
+const NOOP_LOGGER: Logger = {
+	logLine: () => {},
+	logOnce: () => {},
+	drain: () => [],
+};
+
+/** shape: none — one env lookup; PI_CODING_AGENT_DIR mirrors how the host resolves its agent dir. */
+function defaultSettingsPath(): string {
+	const agentDir = process.env.PI_CODING_AGENT_DIR || join(process.env.HOME ?? "", ".pi/agent");
+	return join(agentDir, "pi-render", "settings.json");
+}
+
+/** shape: none — one type predicate over untrusted JSON. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** shape: none — one code check on an unknown catch value. */
+function isEnoent(error: unknown): boolean {
+	return isRecord(error) && error.code === "ENOENT";
+}
+
+/** shape: none — one field shape per key; a bad entry reads as the module's defaults. */
+function normalizeModule(entry: unknown): ModuleSettings {
+	if (!isRecord(entry)) return { enabled: true };
+	const enabled = typeof entry.enabled === "boolean" ? entry.enabled : true;
+	return isRecord(entry.settings) ? { enabled, settings: entry.settings } : { enabled };
+}
+
+/** shape: none — one field shape per key; a schema library does not earn a dependency for two keys. */
+function normalize(raw: Record<string, unknown>): SettingsDoc {
+	const version = typeof raw.version === "number" ? raw.version : DOC_VERSION;
+	const source = isRecord(raw.modules) ? raw.modules : {};
+	// Object.fromEntries writes own data properties, so a "__proto__" key cannot set the prototype.
+	const modules = Object.fromEntries(
+		Object.entries(source).map(([key, entry]): [string, ModuleSettings] => [key, normalizeModule(entry)]),
+	);
+	return { version, modules };
+}
+
+/**
+ * Cached load plus atomic save. `path` and `logger` are injectable so tests never touch the real
+ * agent directory and can read the malformed-doc line back.
+ */
+export function createSettingsStore(opts?: { path?: string; logger?: Logger }): SettingsStore {
+	const path = opts?.path ?? defaultSettingsPath();
+	const logger = opts?.logger ?? NOOP_LOGGER;
+	let cache: SettingsDoc | undefined;
+
+	const defaults = (): SettingsDoc => ({ version: DOC_VERSION, modules: {} });
+
+	const malformed = (why: string): SettingsDoc => {
+		logger.logOnce(`settings:${path}`, "settings", `${why} at ${path} — using defaults`);
+		return defaults();
+	};
+
+	const readFromDisk = (): SettingsDoc => {
+		let text: string;
+		try {
+			text = readFileSync(path, "utf8");
+		} catch (error) {
+			// A missing file is the normal first run, not a fault worth a line.
+			return isEnoent(error) ? defaults() : malformed("settings unreadable");
+		}
+		let raw: unknown;
+		try {
+			raw = JSON.parse(text);
+		} catch {
+			return malformed("settings malformed");
+		}
+		if (!isRecord(raw)) return malformed("settings malformed");
+		if (raw.modules !== undefined && !isRecord(raw.modules)) return malformed("settings malformed");
+		return normalize(raw);
+	};
+
+	return {
+		load(): SettingsDoc {
+			const current = cache ?? readFromDisk();
+			cache = current;
+			return current;
+		},
+
+		save(doc: SettingsDoc): void {
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				const temporary = `${path}.tmp`;
+				writeFileSync(temporary, `${JSON.stringify(doc, null, 2)}\n`);
+				renameSync(temporary, path);
+			} catch {
+				// A write failure degrades to in-memory: the panel keeps working, the disk stays old.
+				logger.logOnce(`settings:save:${path}`, "settings", `settings write failed at ${path} — kept in memory`);
+			}
+			cache = doc;
+		},
+	};
+}

package/src/core/types/code-theme.ts

@@ -0,0 +1,24 @@
+/**
+ * code-theme.ts — the highlighting contract core/code-theme (T-10) implements.
+ *
+ * Boundary: the highlighter is injected — the shiki adapter in production, a counting double in
+ * tests — so no renderer imports shiki and no test needs the wasm engine.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** The injectable highlighter: code plus a language id in, one escape-wrapped line per array entry out. */
+export type HighlightEngine = (
+	/** Source text to highlight; may be multi-line. Required. */
+	code: string,
+	/** Language id, e.g. "ts" or "bash". Required. */
+	lang: string,
+) => string[];
+
+/** Cached highlighting: an oversize input and an engine failure both yield plain, uncoloured lines. */
+export interface CodeTheme {
+	/** Highlights one block, waiting for the engine. Required; never rejects — failures degrade. */
+	highlight(code: string, lang: string): Promise<string[]>;
+	/** Highlights one block from cache or synchronous engine. Required; the render-path entry. */
+	highlightSync(code: string, lang: string): string;
+}