@zenodinh/pi-render 0.0.0-stage → 0.1.0

package/src/renderers/content/artifacts/engines.ts

@@ -0,0 +1,396 @@
+// ported from pi-pretty-tui/src/features/canvas/engines.ts and adapters.ts — survives because: the engine
+// pre-warm is what lets a synchronous markdown seam call a rendered artifact, and the per-form adapters
+// are the only place where a fence becomes bytes.
+
+/**
+ * The artifacts render seam (SA §6): one cache-first render per fence form, four warmed engines, and the
+ * two binary-backed forms behind the pinned spawn boundary.
+ *
+ * Why pre-warm: the host's markdown transformer is synchronous while every engine's initialisation is
+ * asynchronous, so boot awaits warmup() once and the render pass then calls only synchronous APIs. An
+ * engine that failed to warm throws a named error, which the caller turns into the raw-fence fallback.
+ *
+ * shape: dispatch object — trigger #1, one strategy per fence form, each a stateless function.
+ */
+
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { initWasm, Resvg } from "@resvg/resvg-wasm";
+import { instance, type Viz } from "@viz-js/viz";
+import type { CanvasKit } from "canvaskit-wasm";
+import type { Logger } from "../../../core/types/log.ts";
+import { type ArtifactCache, type CacheMeta, createArtifactCache, renderCacheKey } from "./cache.ts";
+import { type LocalSpawn, type LocalSpawnResult, plantumlIncludeOffense, spawnLocal } from "./local-binary.ts";
+import { type PrereqProbe, resolveBrowserPinned, resolvePlantuml, resolvePrereq } from "./prereqs.ts";
+
+const require = createRequire(import.meta.url);
+const SCOPE = "content.artifacts";
+
+/** pi-tui's own default image width; wider fences are clamped to it (P transformer.ts:68). */
+const MAX_IMAGE_WIDTH_CELLS = 60;
+const LOCAL_TIMEOUT_MS = 5_000;
+const BROWSER_TIMEOUT_MS = 15_000;
+const VIEWPORT = "1200,800";
+const VIRTUAL_TIME_BUDGET_MS = 3_000;
+
+export type DiagramForm = "plantuml" | "svg" | "dot" | "html";
+
+export type DiagramResult =
+	| { kind: "image"; base64: string }
+	| { kind: "text"; art: string }
+	| { kind: "svg"; svg: string };
+
+export type EngineId = "plantuml" | "viz" | "resvg" | "canvaskit";
+
+/** Ready-or-not per engine; the plantuml row is a file probe, never a spawn. */
+export type EngineStatus = Record<EngineId, boolean>;
+
+/**
+ * One render backend: warmed once at boot, then called synchronously per artifact.
+ */
+export interface Engine {
+	readonly id: EngineId;
+	/** Warms what the backend needs; unavailability is reported by status(), never thrown. */
+	warmup(log?: Logger): Promise<void>;
+	/** Ready as of the last warm-up — no probe, no spawn. */
+	status(): boolean;
+	/**
+	 * One backend call; throws a named Error while not ready. `source` is the form's own text — a diagram
+	 * source for the engines behind those forms, the raster bytes base64-encoded for canvaskit.
+	 */
+	render(source: string, opts: DiagramRenderOptions): DiagramResult;
+}
+
+export interface DiagramRenderOptions {
+	workDir?: string;
+	browserPath?: string;
+	/** Test seam; production resolves through prereqs.ts's absolute candidates. */
+	plantumlPath?: string;
+	timeoutMs?: number;
+	/** PlantUML only: "text" renders `-tutxt` Unicode art instead of SVG. */
+	mode?: "image" | "text";
+	/** Cache-key component: the transformer's clamped fence width. */
+	widthCells?: number;
+	/** Injected store and engines (tests and the composition root); production uses the defaults. */
+	cache?: ArtifactCache;
+	engines?: Partial<Record<EngineId, Engine>>;
+	/** Test seams: the prereq probe and the process runner. */
+	prereqs?: PrereqProbe;
+	spawn?: LocalSpawn;
+	log?: Logger;
+}
+
+function message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * boundary: canvaskit-wasm's CJS default resolves to the module namespace under nodenext, so the
+ * callable init is narrowed here rather than trusted from the declaration.
+ */
+function isCanvasKitInit(value: unknown): value is () => Promise<CanvasKit> {
+	return typeof value === "function";
+}
+
+/** shape: closure returning an object literal — trigger #4, one warmed wasm instance per engine. */
+function resvgEngine(): Engine {
+	let warmed = false;
+	return {
+		id: "resvg",
+		async warmup(log) {
+			if (warmed) return;
+			try {
+				await initWasm(readFileSync(require.resolve("@resvg/resvg-wasm/index_bg.wasm")));
+				warmed = true;
+			} catch (error) {
+				log?.logOnce(`content.artifacts:engine:resvg`, SCOPE, `svg engine unavailable: ${message(error)}`);
+			}
+		},
+		status: () => warmed,
+		render(source) {
+			if (!warmed) throw new Error("svg engine not warmed");
+			return { kind: "image", base64: Buffer.from(new Resvg(source).render().asPng()).toString("base64") };
+		},
+	};
+}
+
+/** shape: closure returning an object literal — trigger #4, one warmed wasm instance per engine. */
+function vizEngine(): Engine {
+	let viz: Viz | null = null;
+	return {
+		id: "viz",
+		async warmup(log) {
+			if (viz) return;
+			try {
+				viz = await instance();
+			} catch (error) {
+				log?.logOnce("content.artifacts:engine:viz", SCOPE, `graphviz engine unavailable: ${message(error)}`);
+			}
+		},
+		status: () => viz !== null,
+		render(source) {
+			if (!viz) throw new Error("dot engine not warmed");
+			return { kind: "svg", svg: viz.renderString(source, { format: "svg" }) };
+		},
+	};
+}
+
+/** shape: closure returning an object literal — trigger #4, one warmed wasm instance per engine. */
+function canvasKitEngine(): Engine {
+	let kit: CanvasKit | null = null;
+	return {
+		id: "canvaskit",
+		async warmup(log) {
+			if (kit) return;
+			try {
+				const loaded: { default: unknown } = await import("canvaskit-wasm");
+				const init = loaded.default;
+				if (!isCanvasKitInit(init)) throw new Error("canvaskit-wasm exposes no init function");
+				kit = await init();
+			} catch (error) {
+				log?.logOnce("content.artifacts:engine:canvaskit", SCOPE, `image engine unavailable: ${message(error)}`);
+			}
+		},
+		status: () => kit !== null,
+		render(source) {
+			if (!kit) throw new Error("image engine not warmed");
+			const image = kit.MakeImageFromEncoded(Buffer.from(source, "base64"));
+			if (!image) throw new Error("image decode failed");
+			try {
+				const png = image.encodeToBytes();
+				if (!png) throw new Error("image encode failed");
+				return { kind: "image", base64: Buffer.from(png).toString("base64") };
+			} finally {
+				image.delete();
+			}
+		},
+	};
+}
+
+/**
+ * An injected probe wins over the warmed candidate so a test is machine-independent, and a missing
+ * binary throws its install hint here — before any spawn site is reached.
+ */
+function plantumlPath(warmed: string | undefined, opts: DiagramRenderOptions): string {
+	if (opts.plantumlPath) return opts.plantumlPath;
+	if (opts.prereqs) return resolvePlantuml(opts.prereqs);
+	return warmed ?? resolvePlantuml();
+}
+
+/** shape: closure returning an object literal — trigger #4, one resolved binary plus the spawn call. */
+function plantumlEngine(): Engine {
+	let warmed: string | undefined;
+	return {
+		id: "plantuml",
+		async warmup() {
+			warmed = resolvePrereq("plantuml").path || undefined;
+		},
+		status: () => warmed !== undefined,
+		render(source, opts) {
+			const offense = plantumlIncludeOffense(source);
+			if (offense) throw new Error(`plantuml: "${offense}" is rejected — includes can read local files`);
+			const binary = plantumlPath(warmed, opts);
+			return withWorkDir(opts.workDir, (dir) => {
+				const file = join(dir, "diagram.puml");
+				writeFileSync(file, source);
+				const textMode = opts.mode === "text";
+				const timeoutMs = opts.timeoutMs ?? LOCAL_TIMEOUT_MS;
+				const extension = textMode ? ".utxt" : ".svg";
+				// `-o` pins the directory; the FILE name is whatever plantuml chose — it uses
+				// the diagram's title when the source has one (observed 2026-10-03), and the
+				// stem-swapped input name otherwise. Guessing either name has failed twice,
+				// so the output is discovered, not predicted.
+				run(opts, "plantuml", binary, [textMode ? "-tutxt" : "-tsvg", "-o", dir, file], timeoutMs);
+				const produced = readdirSync(dir).filter((name) => name.toLowerCase().endsWith(extension));
+				if (produced.length === 0) throw new Error(`plantuml: no ${extension} output was written`);
+				const out = join(dir, produced.sort()[0] as string);
+				return textMode
+					? { kind: "text", art: readFileSync(out, "utf8") }
+					: { kind: "svg", svg: readFileSync(out, "utf8") };
+			});
+		},
+	};
+}
+
+let defaults: Record<EngineId, Engine> | undefined;
+
+/** shape: none — one lazy table; each engine holds its own warmed wasm state. */
+function defaultEngines(): Record<EngineId, Engine> {
+	defaults ??= {
+		plantuml: plantumlEngine(),
+		viz: vizEngine(),
+		resvg: resvgEngine(),
+		canvaskit: canvasKitEngine(),
+	};
+	return defaults;
+}
+
+/** shape: none — one read of the warmed flags plus one absolute-path probe for plantuml. */
+export function status(probe: PrereqProbe = {}): EngineStatus {
+	const engines = defaultEngines();
+	return {
+		plantuml: resolvePrereq("plantuml", probe).path !== "",
+		viz: engines.viz.status(),
+		resvg: engines.resvg.status(),
+		canvaskit: engines.canvaskit.status(),
+	};
+}
+
+/** shape: none — four independent warm-ups, awaited in turn; a failure is reported, never fatal. */
+export async function warmup(log?: Logger): Promise<EngineStatus> {
+	for (const engine of Object.values(defaultEngines())) await engine.warmup(log);
+	return status();
+}
+
+function spawnFailure(form: DiagramForm, cmd: string, result: LocalSpawnResult, timeoutMs: number): Error {
+	const code = (result.error as NodeJS.ErrnoException | undefined)?.code;
+	if (code === "ENOENT") return new Error(`${form}: "${cmd}" not found`);
+	if (code === "ETIMEDOUT" || result.signal === "SIGTERM") {
+		return new Error(`${form}: "${cmd}" timed out after ${timeoutMs}ms`);
+	}
+	if (result.error) return new Error(`${form}: "${cmd}" failed: ${result.error.message}`);
+	const stderr = result.stderr?.toString("utf8").trim().split("\n")[0] ?? "";
+	return new Error(`${form}: "${cmd}" exited ${result.status ?? "on signal"}${stderr ? `: ${stderr}` : ""}`);
+}
+
+function run(opts: DiagramRenderOptions, form: DiagramForm, cmd: string, args: string[], timeoutMs: number): void {
+	const result = (opts.spawn ?? spawnLocal)(cmd, args, { timeoutMs });
+	if (result.error || result.status !== 0) throw spawnFailure(form, cmd, result, timeoutMs);
+}
+
+/** A caller-provided workDir is left alone (tests inspect it); a created one is removed. */
+function withWorkDir<T>(workDir: string | undefined, fn: (dir: string) => T): T {
+	const dir = workDir ?? mkdtempSync(join(tmpdir(), "pi-render-canvas-"));
+	try {
+		return fn(dir);
+	} finally {
+		if (!workDir) rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+/**
+ * A minimal dark shell so a bare fragment screenshots legibly and without a
+ * white flash. The CSP is part of the boundary: a model-authored fragment may
+ * style itself but cannot load anything or reach the network.
+ */
+function wrapHtmlFragment(fragment: string): string {
+	return `<!doctype html>
+<html><head><meta charset="utf-8">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'">
+<style>
+:root{color-scheme:dark}
+body{margin:16px;background:#16161e;color:#e6e6ef;font:14px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}
+</style></head><body>${fragment}</body></html>`;
+}
+
+/** shape: none — one temp-dir screenshot run; the browser is a pinned absolute path, never PATH. */
+function renderHtml(source: string, opts: DiagramRenderOptions): DiagramResult {
+	return withWorkDir(opts.workDir, (dir) => {
+		const file = join(dir, "fragment.html");
+		const out = join(dir, "screenshot.png");
+		writeFileSync(file, wrapHtmlFragment(source));
+		const browser = resolveBrowserPinned(opts.browserPath, opts.prereqs);
+		const timeoutMs = opts.timeoutMs ?? BROWSER_TIMEOUT_MS;
+		run(
+			opts,
+			"html",
+			browser,
+			[
+				"--headless",
+				"--disable-gpu",
+				// No script flag here: `--blink-settings=scriptEnabled=false` makes the
+				// Playwright headless shell exit 0 without writing the screenshot
+				// (2026-10-03), and the shell's CSP already blocks scripts — `script-src`
+				// inherits `default-src 'none'`, so neither inline nor external scripts run.
+				// A throwaway profile inside the temp dir: the user's own profile is
+				// never read or locked, and the cleanup is the work dir's.
+				`--user-data-dir=${join(dir, "browser-profile")}`,
+				"--no-first-run",
+				"--disable-background-networking",
+				"--hide-scrollbars",
+				`--screenshot=${out}`,
+				`--window-size=${VIEWPORT}`,
+				`--virtual-time-budget=${VIRTUAL_TIME_BUDGET_MS}`,
+				`file://${file}`,
+			],
+			timeoutMs,
+		);
+		if (!existsSync(out)) throw new Error("html: browser produced no screenshot");
+		return { kind: "image", base64: readFileSync(out).toString("base64") };
+	});
+}
+
+// shape: dispatch object — trigger #1, one strategy per fence form, each a plain function.
+const FORM_RENDERERS: Record<DiagramForm, (source: string, opts: DiagramRenderOptions) => DiagramResult> = {
+	plantuml: (source, opts) => engineOf("plantuml", opts).render(source, opts),
+	svg: (source) => ({ kind: "svg", svg: source }),
+	dot: (source, opts) => engineOf("viz", opts).render(source, opts),
+	html: renderHtml,
+};
+
+function engineOf(id: EngineId, opts: DiagramRenderOptions): Engine {
+	return opts.engines?.[id] ?? defaultEngines()[id];
+}
+
+/** A cache hit is the artifact the last identical render wrote; an unreadable one is simply a miss. */
+function readCached(form: DiagramForm, key: string, cache: ArtifactCache): DiagramResult | undefined {
+	try {
+		if (form === "html") {
+			const entry = cache.get(key);
+			return entry === undefined ? undefined : { kind: "image", base64: entry.png.toString("base64") };
+		}
+		const path = cache.vectorPath(key);
+		return path === undefined ? undefined : { kind: "svg", svg: readFileSync(path, "utf8") };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * A write is an optimization: a full disk or an unusable directory must not cost the render that just
+ * succeeded, and eviction runs here for the same reason it exists at all.
+ */
+function writeCached(
+	form: DiagramForm,
+	key: string,
+	mode: string,
+	widthCells: number,
+	result: DiagramResult,
+	cache: ArtifactCache,
+	log: Logger | undefined,
+): void {
+	// rows belongs to the emission step (T-26); the engine seam never knows the rendered line count.
+	const meta: CacheMeta = { source: form, mode, mime: "", rows: 0, widthCells, createdAt: new Date().toISOString() };
+	try {
+		if (result.kind === "svg") cache.putVector(key, result.svg, { ...meta, mime: "image/svg+xml" });
+		else if (result.kind === "image")
+			cache.put(key, Buffer.from(result.base64, "base64"), { ...meta, mime: "image/png" });
+		else return;
+		cache.evict();
+	} catch (error) {
+		log?.logOnce(`content.artifacts:cache:${key}`, SCOPE, `artifact not cached: ${message(error)}`);
+	}
+}
+
+/**
+ * shape: none — cache-first dispatch; the dedup branch is the whole contract (a repeated fence must
+ * never run an engine twice) and every other branch is one table lookup.
+ */
+export function renderDiagram(form: DiagramForm, source: string, opts: DiagramRenderOptions = {}): DiagramResult {
+	const mode = opts.mode === "text" ? "text" : "image";
+	const widthCells = Math.max(1, Math.floor(opts.widthCells ?? MAX_IMAGE_WIDTH_CELLS));
+	const cache = opts.cache ?? createArtifactCache({ log: opts.log });
+	const key = renderCacheKey(form, source, mode, widthCells);
+
+	// Only artifacts are cached: PlantUML's text art is a view of the render, not a file (P transformer.ts:169-183).
+	if (mode === "image") {
+		const hit = readCached(form, key, cache);
+		if (hit !== undefined) return hit;
+	}
+
+	const result = FORM_RENDERERS[form](source, opts);
+	if (mode === "image") writeCached(form, key, mode, widthCells, result, cache, opts.log);
+	return result;
+}

package/src/renderers/content/artifacts/local-binary.test.ts

@@ -0,0 +1,207 @@
+/**
+ * local-binary.test.ts — the audited spawn boundary (T-25 follow-up): spawnLocal's real argv/cwd/timeout
+ * contract, cmux's absolute-candidate resolution, openInCmux's fixed argv and its no-shell guarantee, and
+ * the PlantUML include guard.
+ *
+ * Compatibility tests for the two seams nothing else exercises: the package's only `node:child_process`
+ * call site and the include guard in front of the JVM. Where behavior needs a real process it runs the
+ * Node binary this test is already running under and `/bin/echo` — never a PATH lookup, never a shell;
+ * everywhere else the seam is the injected `spawn`/`resolve`/`exists`. Each test carries a spec +
+ * fails_when line.
+ *
+ * shape: none — test module, no runtime unit for DSG-1's trigger table to select a shape for.
+ */
+
+import { existsSync, mkdtempSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+	type LocalSpawn,
+	type LocalSpawnResult,
+	openInCmux,
+	plantumlIncludeOffense,
+	resolveCmux,
+	spawnLocal,
+} from "./local-binary.ts";
+
+// invented: the canned result an exit-0 process reports; there is no upstream payload to record.
+const OK: LocalSpawnResult = { status: 0, signal: null, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
+
+const CMUX_URL = "http://127.0.0.1:7777/artifact/9f2c";
+
+/** boundary: a spawn error is `unknown` until its `code` is narrowed here — no cast, no field read blind. */
+function errorCode(result: LocalSpawnResult): unknown {
+	const error: unknown = result.error;
+	return error !== null && typeof error === "object" && "code" in error ? error.code : undefined;
+}
+
+function only<T>(items: T[]): T {
+	const first = items[0];
+	if (first === undefined) throw new Error("test fixture: expected exactly one recorded item");
+	return first;
+}
+
+interface SpawnCall {
+	cmd: string;
+	args: string[];
+	timeoutMs: number;
+}
+
+/** invented: the recording spawn is the fixture — it captures the argv/timeout and never runs a process. */
+function recorder() {
+	const calls: SpawnCall[] = [];
+	const spawn: LocalSpawn = (cmd, args, opts) => {
+		calls.push({ cmd, args, timeoutMs: opts.timeoutMs });
+		return OK;
+	};
+	return { calls, spawn };
+}
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "pi-render-local-binary-"));
+});
+
+describe("cmux resolution", () => {
+	// spec: resolveCmux scans the two absolute app-bundle candidates in order and returns the first that
+	//   exists — no PATH lookup, no environment override, undefined when neither is there.
+	// fails_when: a relative or PATH-derived candidate is launched in the user's terminal.
+	it("returns the first existing absolute candidate and undefined when none exist", () => {
+		expect(resolveCmux(() => false)).toBeUndefined();
+		expect(resolveCmux(() => true)).toBe("/Applications/cmux.app/Contents/Resources/bin/cmux");
+
+		const second = resolveCmux((candidate) => candidate !== "/Applications/cmux.app/Contents/Resources/bin/cmux");
+		expect(second).toBeDefined();
+		expect(isAbsolute(second as string)).toBe(true);
+		expect(second?.endsWith("/Applications/cmux.app/Contents/Resources/bin/cmux")).toBe(true);
+	});
+
+	// spec: with no injected binary, openInCmux resolves cmux itself; on a machine without it the call is
+	//   a named error, never a spawn.
+	// fails_when: the default resolution is skipped, or a missing cmux turns into a failed spawn attempt.
+	it("resolves cmux itself when no binary is injected", () => {
+		const { calls, spawn } = recorder();
+
+		try {
+			openInCmux(CMUX_URL, { spawn });
+		} catch (error) {
+			expect(error instanceof Error ? error.message : String(error)).toBe("cmux: CLI not found");
+			expect(calls).toEqual([]);
+			return;
+		}
+
+		const call = only(calls);
+		expect(call.cmd).toBe(resolveCmux());
+		expect(isAbsolute(call.cmd)).toBe(true);
+	});
+});
+
+describe("openInCmux — the fixed cmux argv", () => {
+	// spec: openInCmux spawns the resolved binary with exactly
+	//   `new-pane --type browser --url <url> --focus false` and the 10s default timeout.
+	// fails_when: a cmux CLI change (reordered flags, dropped --focus) silently stops opening the card.
+	it("sends the fixed argv with the default timeout", () => {
+		const binary = "/Applications/cmux.app/Contents/Resources/bin/cmux";
+		const { calls, spawn } = recorder();
+
+		expect(openInCmux(CMUX_URL, { binary, spawn })).toEqual(OK);
+
+		const call = only(calls);
+		expect(call.cmd).toBe(binary);
+		expect(call.args).toEqual(["new-pane", "--type", "browser", "--url", CMUX_URL, "--focus", "false"]);
+		expect(call.timeoutMs).toBe(10_000);
+	});
+
+	// spec: an injected resolve() wins over the candidate scan, and a caller timeout overrides the 10s one.
+	// fails_when: the seams are ignored — a test or a caller cannot point the op at its own cmux.
+	it("honors an injected resolve and a timeout override", () => {
+		const { calls, spawn } = recorder();
+
+		openInCmux(CMUX_URL, { resolve: () => "/opt/pi-render-test/bin/cmux", spawn, timeoutMs: 250 });
+
+		const call = only(calls);
+		expect(call.cmd).toBe("/opt/pi-render-test/bin/cmux");
+		expect(call.timeoutMs).toBe(250);
+	});
+
+	// spec: with no cmux resolvable the call throws the named error and no process is started.
+	// fails_when: the caller gets a raw spawn error instead of the actionable message.
+	it("throws the named error when no cmux resolves and spawns nothing", () => {
+		const { calls, spawn } = recorder();
+
+		expect(() => openInCmux(CMUX_URL, { resolve: () => undefined, spawn })).toThrow("cmux: CLI not found");
+		expect(calls).toEqual([]);
+	});
+
+	// spec: the default spawn goes straight to the binary — no shell — so shell metacharacters in the URL
+	//   stay literal arguments and execute nothing.
+	// fails_when: a shell is introduced at this boundary and a card URL can run a command.
+	it("runs argv without a shell, so metacharacters in the URL stay literal", () => {
+		const canary = join(dir, "pwned");
+		const url = `http://127.0.0.1:7777/a;touch ${canary}`;
+
+		const result = openInCmux(url, { binary: "/bin/echo", timeoutMs: 2_000 });
+
+		expect(result.status).toBe(0);
+		expect(result.stdout?.toString("utf8")).toBe(`new-pane --type browser --url ${url} --focus false\n`);
+		expect(existsSync(canary)).toBe(false);
+	});
+});
+
+describe("spawnLocal — the one process runner", () => {
+	// spec: spawnLocal runs a fixed argv with a buffer encoding and returns the exit status and stdout.
+	// fails_when: the encoding or the argv passthrough changes and every caller reads the wrong bytes.
+	it("runs a fixed argv and returns the status with buffered output", () => {
+		const result = spawnLocal(process.execPath, ["-e", "process.stdout.write('ok')"], { timeoutMs: 10_000 });
+
+		expect(result.status).toBe(0);
+		expect(result.stdout?.toString("utf8")).toBe("ok");
+	});
+
+	// spec: spawnLocal runs the process in the cwd it was given.
+	// fails_when: a caller's temp-dir cwd is ignored, so a spawn writes into the user's directory.
+	it("runs in the cwd it was given", () => {
+		const result = spawnLocal(process.execPath, ["-e", "process.stdout.write(process.cwd())"], {
+			cwd: dir,
+			timeoutMs: 10_000,
+		});
+
+		const printed = result.stdout?.toString("utf8") ?? "";
+		expect(realpathSync(printed)).toBe(realpathSync(dir));
+	});
+
+	// spec: a process outliving its timeout is killed and reported as ETIMEDOUT with SIGTERM.
+	// fails_when: a hung binary pins the render thread forever.
+	it("kills a process past its timeout and reports ETIMEDOUT", () => {
+		const result = spawnLocal(process.execPath, ["-e", "setTimeout(() => {}, 5_000)"], { timeoutMs: 300 });
+
+		expect(errorCode(result)).toBe("ETIMEDOUT");
+		expect(result.signal).toBe("SIGTERM");
+	});
+
+	// spec: a missing binary is reported as ENOENT in the result, never thrown.
+	// fails_when: the caller crashes on a machine where the binary is absent instead of degrading.
+	it("reports a missing binary as ENOENT without throwing", () => {
+		const result = spawnLocal("/nonexistent/pi-render-no-such-binary", [], { timeoutMs: 1_000 });
+
+		expect(result.status).toBeNull();
+		expect(errorCode(result)).toBe("ENOENT");
+	});
+});
+
+describe("the PlantUML include guard", () => {
+	// spec: plantumlIncludeOffense reports every include-shaped directive by name — case-insensitively,
+	//   after leading whitespace, on any line — and passes ordinary source through.
+	// fails_when: a directive variant slips past the guard and an included local file reaches the image.
+	it("reports each include directive variant and passes ordinary source", () => {
+		expect(plantumlIncludeOffense("@startuml\n!include /etc/passwd\n@enduml")).toBe("!include");
+		expect(plantumlIncludeOffense("!includeurl https://example.invalid/x.puml")).toBe("!includeurl");
+		expect(plantumlIncludeOffense("  !includesub other.puml!FOO")).toBe("!includesub");
+		expect(plantumlIncludeOffense("!include_many a.puml")).toBe("!include_many");
+		expect(plantumlIncludeOffense("IDEA\n!IMPORT x.yaml\n")).toBe("!IMPORT");
+		expect(plantumlIncludeOffense("@startuml\n!pragma layout smetana\nAlice -> Bob\n@enduml")).toBeUndefined();
+		expect(plantumlIncludeOffense("")).toBeUndefined();
+	});
+});

package/src/renderers/content/artifacts/local-binary.ts

@@ -0,0 +1,80 @@
+// ported from pi-pretty-tui/src/features/canvas/local-binary.ts — survives because: a binary cannot be
+// certified from a diff, so what survives is the bounded way to call one — absolute candidates only, no
+// shell, a timeout on every spawn, and the include guard in front of the PlantUML JVM.
+
+/**
+ * The single audited spawn boundary for the artifacts feature, and the package's only
+ * `node:child_process` site. It exists for the two forms whose engine has no Node-native replacement:
+ * the PlantUML JVM and a headless browser for HTML fences.
+ *
+ * What is bounded here, since a binary cannot be certified from a diff:
+ *   - provenance: absolute paths only, from `prereqs.ts`'s candidate lists —
+ *     no PATH lookup, no environment override;
+ *   - no shell: fixed argv straight into spawnSync, caller-supplied temp dirs;
+ *   - timeouts on every spawn;
+ *   - PlantUML sources carrying an include directive are rejected before the
+ *     spawn (includes can read local files into the rendered image);
+ *   - the HTML wrapper pins `default-src 'none'` (script-src inherits it, so
+ *     scripts cannot run, and the fragment cannot fetch), and the browser gets
+ *     a throwaway profile inside the caller's temp dir.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface LocalSpawnResult {
+	status: number | null;
+	signal?: NodeJS.Signals | null;
+	stdout?: Buffer;
+	stderr?: Buffer;
+	error?: Error | null;
+}
+
+/** The one process-runner signature: fixed argv, caller-supplied temp dirs, always a timeout. */
+export type LocalSpawn = (cmd: string, args: string[], opts: { cwd?: string; timeoutMs: number }) => LocalSpawnResult;
+
+/** shape: none — the one process runner; a seam elsewhere lets tests avoid it. */
+export function spawnLocal(cmd: string, args: string[], opts: { cwd?: string; timeoutMs: number }): LocalSpawnResult {
+	return spawnSync(cmd, args, { cwd: opts.cwd, timeout: opts.timeoutMs, encoding: "buffer" });
+}
+
+/** cmux ships its agent CLI inside the app bundle; PATH is never consulted. */
+const CMUX_CANDIDATES = [
+	"/Applications/cmux.app/Contents/Resources/bin/cmux",
+	join(homedir(), "Applications/cmux.app/Contents/Resources/bin/cmux"),
+];
+const CMUX_TIMEOUT_MS = 10_000;
+
+/** shape: none — one candidate scan; undefined means "no cmux on this machine". */
+export function resolveCmux(exists: (path: string) => boolean = existsSync): string | undefined {
+	return CMUX_CANDIDATES.find((candidate) => exists(candidate));
+}
+
+/**
+ * Opens a URL as a browser surface beside the caller's terminal (a right
+ * split; `--placement dock` exists but is disabled in practice — observed
+ * 2026-10-03). cmux routes only http(s) into its embedded browser and file://
+ * links fall to the OS handlers, which is why the card's click uses the
+ * artifact server's http URL and this CLI call is the keyboard fallback.
+ */
+export function openInCmux(
+	url: string,
+	opts: { binary?: string; resolve?: () => string | undefined; timeoutMs?: number; spawn?: LocalSpawn } = {},
+): LocalSpawnResult {
+	const binary = opts.binary ?? (opts.resolve ?? resolveCmux)();
+	if (binary === undefined) throw new Error("cmux: CLI not found");
+	const spawn = opts.spawn ?? spawnLocal;
+	return spawn(binary, ["new-pane", "--type", "browser", "--url", url, "--focus", "false"], {
+		timeoutMs: opts.timeoutMs ?? CMUX_TIMEOUT_MS,
+	});
+}
+
+const PLANTUML_INCLUDE = /^\s*!(?:include|includeurl|includesub|include_many|import)\b/im;
+
+/** shape: none — one directive scan; returns the offending token, or undefined. */
+export function plantumlIncludeOffense(source: string): string | undefined {
+	const match = source.match(PLANTUML_INCLUDE);
+	return match ? match[0].trim() : undefined;
+}