@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/commands/canvas.ts

@@ -0,0 +1,57 @@
+// ported from pi-pretty-tui/src/features/canvas/index.ts:90-100 — survives because: the predecessor's
+// /canvas registerCommand shape — a thin handler that opens the artifact through an injected seam and
+// notifies instead of throwing when it cannot — is exactly the command contract pi-render needs. Its
+// shortcuts, cmux routing, warmup and cache-dir plumbing stay behind (registration-adjacent chrome).
+
+/**
+ * canvas.ts — the package's one command: /canvas opens the artifact browser, or reports its status.
+ *
+ * Boundary: `ctx` arrives from the host and is read as core/types/host.ts declares it — nothing here
+ * narrows or re-declares a host shape. The injected `deps.registry` is the command's ONLY channel to
+ * the rest of the package (SA §7), and it is read-only: /canvas reports module state and never writes
+ * it, so a disabled module's command cannot act anyway.
+ *
+ * Why `canvasView` is injected: `index.ts` (T-28) is the only file that composes lanes, so the real
+ * browser arrives as a parameter; this module never imports a renderer and its tests drive a fake view.
+ *
+ * shape: none — trigger #1 dispatch object does not apply: one command, two guards (host mode, module
+ * enabled) resolved in sequence, no per-kind handler table.
+ */
+
+import type { CommandContext, ExtensionApi, Registry } from "../core/types.ts";
+
+/**
+ * The content lane's artifacts module key (SA §6). A literal, not an import: `commands/` may not
+ * reach into a renderer lane for its constant (SA §1 rule 3).
+ */
+const ARTIFACTS_KEY = "content.artifacts";
+
+/** What /canvas needs from its callers: module state to report, and the view to open. */
+export interface CommandsDeps {
+	/** Registry the command reads, e.g. isEnabled("content.artifacts"). Required; never written here. */
+	readonly registry: Registry;
+	/** Opens the artifact browser. Required; index.ts injects the real view, tests a fake one. */
+	readonly canvasView: (ctx: CommandContext) => Promise<void>;
+}
+
+/** shape: none — one interpolated line; a status table would restate the same registry read. */
+function summarize(mode: CommandContext["mode"], enabled: boolean): string {
+	if (!enabled) return "canvas: content.artifacts is disabled — enable it to open the artifact browser";
+	return `canvas: content.artifacts is enabled — the artifact browser needs a TUI host (mode: ${mode})`;
+}
+
+/** shape: none — one guarded registration; the handler below is this module's only command. */
+export function installCommands(pi: ExtensionApi, deps: CommandsDeps): void {
+	pi.registerCommand("canvas", {
+		description: "canvas: open the artifact browser, or report its status",
+		handler: async (_args, ctx) => {
+			const enabled = deps.registry.isEnabled(ARTIFACTS_KEY);
+			// A non-TUI host cannot draw the view and a disabled module has nothing to open: both report.
+			if (ctx.mode !== "tui" || !enabled) {
+				ctx.ui.notify(summarize(ctx.mode, enabled));
+				return;
+			}
+			await deps.canvasView(ctx);
+		},
+	});
+}

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

@@ -0,0 +1,266 @@
+/**
+ * code-theme.test.ts — the spec of createCodeTheme at its seam, with a counting engine double.
+ *
+ * Spec: createCodeTheme(bindEngine, {registry, log}) resolves `codeTheme` to a bundled name (unknown →
+ * dracula-soft + one log line), highlights once per theme+lang+code, never hands the engine an empty or
+ * over-80k block, and returns plain source lines when the engine or the bind throws.
+ */
+
+import { describe, expect, it } from "vitest";
+import { type BindHighlightEngine, CODE_THEME_MODULE, type CodeThemeName, createCodeTheme } from "./code-theme.ts";
+
+// invented: the engine is faked, so the block only has to be two stable lines.
+const CODE = "const a = 1;\nlet b = 2;";
+
+/** One engine invocation: the theme it was bound to, plus the block it was asked for. */
+interface EngineCall {
+	theme: CodeThemeName;
+	code: string;
+	lang: string;
+}
+
+/**
+ * Engine double that counts: it records every call and stamps its bound theme into the lines, so the
+ * resolved theme is visible in the output rather than only in the bind argument.
+ */
+function countingEngine(options: { throwOnBind?: boolean; throwOnCall?: boolean } = {}): {
+	bind: BindHighlightEngine;
+	calls: EngineCall[];
+} {
+	const calls: EngineCall[] = [];
+	const bind: BindHighlightEngine = (theme) => {
+		if (options.throwOnBind) throw new Error("bind failed");
+		return (code, lang) => {
+			calls.push({ theme, code, lang });
+			if (options.throwOnCall) throw new Error("engine failed");
+			return code.split("\n").map((line) => `«${theme}»${line}`);
+		};
+	};
+	return { bind, calls };
+}
+
+/** Logger double: logOnce's once-per-key rule plus the readout, so "exactly one line" is observable. */
+function logDouble(): {
+	logOnce(key: string, scope: string, message: string): void;
+	entries: Array<{ key: string; scope: string; message: string }>;
+	attempts: number;
+} {
+	const entries: Array<{ key: string; scope: string; message: string }> = [];
+	const seen = new Set<string>();
+	const double = {
+		entries,
+		attempts: 0,
+		logOnce(key: string, scope: string, message: string): void {
+			double.attempts += 1;
+			if (seen.has(key)) return;
+			seen.add(key);
+			entries.push({ key, scope, message });
+		},
+	};
+	return double;
+}
+
+/**
+ * Settings double over the injected contract. invented: the slice is contracted as
+ * `Record<string, unknown>`, so any bag is a legal stored document; `set` models the registry's
+ * "a write lands on the next read".
+ */
+function registryDouble(initial: Record<string, unknown> = {}): {
+	getSettings(key: string): Record<string, unknown>;
+	set(patch: Record<string, unknown>): void;
+} {
+	const slices = new Map<string, Record<string, unknown>>([["codetheme", { ...initial }]]);
+	return {
+		getSettings: (key) => slices.get(key) ?? {},
+		set: (patch) => slices.set("codetheme", { ...(slices.get("codetheme") ?? {}), ...patch }),
+	};
+}
+
+describe("createCodeTheme — theme resolution", () => {
+	it("AC-1: an unknown codeTheme renders the default theme and logs exactly one line", async () => {
+		const engine = countingEngine();
+		const log = logDouble();
+		// invented: the setting is persisted JSON, so an out-of-set name is the exact input AC-1 names.
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "nope" }), log });
+
+		const first = await theme.highlight(CODE, "ts");
+		const second = await theme.highlight(CODE, "ts");
+		const joined = theme.highlightSync(CODE, "ts");
+
+		// fails_when: a crash, empty output, or one log line per call.
+		expect(first).toEqual(["«dracula-soft»const a = 1;", "«dracula-soft»let b = 2;"]);
+		expect([second, joined]).toEqual([first, first.join("\n")]);
+		expect(engine.calls.map((call) => call.theme)).toEqual(["dracula-soft"]);
+		expect(log.entries.map((entry) => entry.key)).toEqual(["theme:nope"]);
+		expect(log.entries[0]?.message).toContain("dracula-soft");
+		expect(log.attempts).toBe(3);
+	});
+
+	it("AC-1: a bundled non-default theme is rendered without a log line", async () => {
+		const engine = countingEngine();
+		const log = logDouble();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "one-dark-pro" }), log });
+
+		// fails_when: the setting is ignored and the default theme always renders.
+		expect(await theme.highlight(CODE, "ts")).toEqual(["«one-dark-pro»const a = 1;", "«one-dark-pro»let b = 2;"]);
+		expect(log.entries).toEqual([]);
+	});
+
+	it("AC-1: an absent setting reads the default theme silently", async () => {
+		const engine = countingEngine();
+		const log = logDouble();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble(), log });
+
+		// fails_when: a fresh install logs a fallback line on every render.
+		expect(await theme.highlight(CODE, "ts")).toEqual(["«dracula-soft»const a = 1;", "«dracula-soft»let b = 2;"]);
+		expect(log.entries).toEqual([]);
+	});
+
+	it("AC-1: the descriptor is exported for T-28, and the injected registry has no write route", async () => {
+		// The injected registry shape is read-only (getSettings only), so a registration here cannot compile.
+		expect(CODE_THEME_MODULE).toEqual({
+			key: "codetheme",
+			name: "Code theme",
+			defaultEnabled: true,
+			settings: [
+				{ name: "codeTheme", kind: "enum", values: ["dracula-soft", "one-dark-pro"], default: "dracula-soft" },
+			],
+		});
+	});
+});
+
+describe("createCodeTheme — cache", () => {
+	it("AC-2: the same theme+lang+code highlights once", async () => {
+		const engine = countingEngine();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+
+		const first = await theme.highlight(CODE, "ts");
+		const second = await theme.highlight(CODE, "ts");
+
+		// fails_when: every call re-highlights (the #21 defect class).
+		expect(second).toEqual(first);
+		expect(engine.calls).toHaveLength(1);
+	});
+
+	it("AC-2: lang and theme are part of the key", async () => {
+		const engine = countingEngine();
+		const registry = registryDouble({ codeTheme: "dracula-soft" });
+		const theme = createCodeTheme(engine.bind, { registry });
+
+		await theme.highlight(CODE, "ts");
+		await theme.highlight(CODE, "py");
+		registry.set({ codeTheme: "one-dark-pro" });
+		await theme.highlight(CODE, "ts");
+
+		// fails_when: the key ignores lang or theme and serves the previous theme's colours.
+		expect(engine.calls.map((call) => `${call.theme}:${call.lang}`)).toEqual([
+			"dracula-soft:ts",
+			"dracula-soft:py",
+			"one-dark-pro:ts",
+		]);
+	});
+
+	it("AC-2: highlightSync shares the cache with highlight", async () => {
+		const engine = countingEngine();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+
+		await theme.highlight(CODE, "ts");
+		const joined = theme.highlightSync(CODE, "ts");
+
+		// fails_when: the panel path keeps a second cache and highlights the same block again.
+		expect(joined).toBe("«dracula-soft»const a = 1;\n«dracula-soft»let b = 2;");
+		expect(engine.calls).toHaveLength(1);
+	});
+
+	it("AC-2: the cache is bounded at 128 entries and a hit counts as recent use", async () => {
+		const engine = countingEngine();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+
+		for (let i = 0; i < 128; i += 1) await theme.highlight(`line ${i}`, "ts");
+		await theme.highlight("line 0", "ts");
+		await theme.highlight("line 128", "ts");
+		expect(engine.calls).toHaveLength(129); // the 129th entry evicted the oldest untouched one
+
+		// fails_when: the cache grows without bound, or a hit does not count as recent use.
+		expect(await theme.highlight("line 0", "ts")).toEqual(["«dracula-soft»line 0"]);
+		expect(engine.calls).toHaveLength(129);
+		expect(await theme.highlight("line 1", "ts")).toEqual(["«dracula-soft»line 1"]);
+		expect(engine.calls).toHaveLength(130);
+	});
+});
+
+describe("createCodeTheme — what never reaches the engine", () => {
+	it("AC-3: a block past 80k characters returns its own plain lines", async () => {
+		const engine = countingEngine();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+		// invented: one character past the ported 80_000 gate (P render.ts:86).
+		const over = `x${"y".repeat(80_000)}`;
+
+		// fails_when: a blob this size enters shiki.
+		expect(await theme.highlight(over, "ts")).toEqual([over]);
+		expect(engine.calls).toEqual([]);
+
+		// the gate is strict: exactly 80_000 characters reach the engine.
+		await theme.highlight("y".repeat(80_000), "ts");
+		expect(engine.calls).toHaveLength(1);
+	});
+
+	it("AC-3: empty code returns one empty line", async () => {
+		const engine = countingEngine();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+
+		// fails_when: an empty block enters shiki, or the panel path emits a stray newline.
+		expect(await theme.highlight("", "ts")).toEqual([""]);
+		expect(theme.highlightSync("", "ts")).toBe("");
+		expect(engine.calls).toEqual([]);
+	});
+});
+
+describe("createCodeTheme — degradation", () => {
+	it("AC-4: a throwing engine returns plain lines and nothing escapes", async () => {
+		const engine = countingEngine({ throwOnCall: true });
+		const log = logDouble();
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }), log });
+
+		// fails_when: a shiki failure kills a render.
+		await expect(theme.highlight(CODE, "ts")).resolves.toEqual(["const a = 1;", "let b = 2;"]);
+		expect(theme.highlightSync(CODE, "ts")).toBe("const a = 1;\nlet b = 2;");
+		expect(log.entries.map((entry) => entry.key)).toEqual(["fail:ts"]);
+	});
+
+	it("AC-4: a throwing engine bind degrades the same way", async () => {
+		const engine = countingEngine({ throwOnBind: true });
+		const theme = createCodeTheme(engine.bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+
+		// fails_when: a bind failure (shiki not loaded yet, a bad theme) escapes into the render path.
+		await expect(theme.highlight(CODE, "ts")).resolves.toEqual(["const a = 1;", "let b = 2;"]);
+	});
+
+	it("AC-4: an engine with no registry and no logger still highlights and still degrades", async () => {
+		const engine = countingEngine();
+		const theme = createCodeTheme(engine.bind);
+
+		// fails_when: the optional collaborators are required, so a bare construction throws.
+		expect(await theme.highlight(CODE, "ts")).toEqual(["«dracula-soft»const a = 1;", "«dracula-soft»let b = 2;"]);
+	});
+});
+
+describe("createCodeTheme — contrast normalization (P render.ts:112-140)", () => {
+	it("drops a foreground below the readability floor and keeps the rest", async () => {
+		// invented: RGB triples chosen around the 72 luminance floor (20 below, 80 just above) and the
+		// indexed-black form P treated as dark.
+		const DIM = "\u001b[38;2;20;20;20m";
+		const INDEXED = "\u001b[38;5;0m";
+		const READABLE = "\u001b[38;2;80;80;80m";
+		const RESET = "\u001b[0m";
+		const bind: BindHighlightEngine = () => () => [
+			`${DIM}dim${RESET}`,
+			`${INDEXED}indexed${RESET}`,
+			`${READABLE}readable${RESET}`,
+		];
+		const theme = createCodeTheme(bind, { registry: registryDouble({ codeTheme: "dracula-soft" }) });
+
+		// fails_when: an unreadable near-black token survives to the terminal.
+		expect(await theme.highlight("x", "ts")).toEqual([`dim${RESET}`, `indexed${RESET}`, `${READABLE}readable${RESET}`]);
+	});
+});

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;
+	};
+}