@zenodinh/pi-render 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,136 @@
+// ported from pi-pretty-tui/src/features/canvas/{card,emit}.ts — survives because: the boxed card with
+// a plain-markdown Open link is what the host turns into a real clickable target, and imageLineMetadata
+// is the one place a raster artifact's row count is known (T-25's cache meta leaves rows to this step).
+// The emit.ts terminal-image emission is NOT ported: pi-render draws no inline pixels (the artifact card
+// is the transcript output), so those lines had no caller, and their iTerm2 branch carried a cursor-up
+// escape literal — the repo keeps escapes in src/core/paint.ts alone.
+
+/**
+ * cards.ts — the artifact card and the raster row count.
+ *
+ * Boundary: the Open link resolves through the ArtifactServer, which registers the path as carded and
+ * names the loopback URL; a degraded server is logged once by urlFor and the card falls back to a
+ * file:// URL, so a failed bind never reaches the render path as a throw.
+ *
+ * shape: none — no module-level state; every export is a straight-line function or one box builder.
+ */
+
+import { pathToFileURL } from "node:url";
+import { calculateImageRows, getImageDimensions, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ContentPaint } from "../../../core/types/paint.ts";
+import type { ArtifactServer } from "./server.ts";
+
+const OPEN_LABEL = "Open (⌘click)";
+const COPY_LABEL = "Copy path (⌥C)";
+/** The rendered link occupies brackets around the label. */
+const OPEN_WIDTH = visibleWidth(OPEN_LABEL) + 2;
+/** Cards read best narrow; the offered width is clamped into these bounds. */
+const CARD_MIN_WIDTH = 24;
+const CARD_MAX_WIDTH = 64;
+/** pi-tui's default image width; the reference for a raster artifact's transcript row count. */
+const DEFAULT_WIDTH_CELLS = 60;
+
+/** The artifact card's own fields; the URL is resolved from the path, never supplied by the caller. */
+export interface ArtifactCardSpec {
+	/** The fence form, e.g. "plantuml" — rendered as the card's type label. */
+	typeLabel: string;
+	/** The artifact's own name where it has one; see artifactTitle. */
+	title: string;
+	/** Absolute path of the artifact on disk; the Open link points at it. */
+	path: string;
+	/** Offered transcript width in columns. */
+	width: number;
+}
+
+/** Markdown would eat these inside a label; escaping keeps the title literal. */
+function escapeMarkdown(text: string): string {
+	return text.replace(/([\\`*_[\]#])/g, "\\$1");
+}
+
+function clampWidth(text: string, width: number): string {
+	return visibleWidth(text) > width ? truncateToWidth(text, width) : text;
+}
+
+/**
+ * The artifact names itself where it can; the caller passes the fallback (`form`) otherwise.
+ *
+ * shape: none — dispatch object does not apply: one `||` form test plus ordered title extraction.
+ */
+export function artifactTitle(form: string, source: string): string {
+	const plantumlStart = source.match(/@start\w+\s+"([^"\n]+)"/);
+	if (plantumlStart?.[1]) return plantumlStart[1].trim();
+	const plantumlTitle = source.match(/^\s*title\s+(.+)$/m);
+	if (plantumlTitle?.[1]) return plantumlTitle[1].trim();
+	if (form === "svg" || form === "html") {
+		const tag = source.match(/<title[^>]*>([^<]*)<\/title>/i);
+		if (tag?.[1]) return tag[1].trim();
+		const heading = source.match(/<h1[^>]*>([^<]+)<\/h1>/i);
+		if (heading?.[1]) return heading[1].trim();
+	}
+	return form;
+}
+
+/** shape: none — one box; every line's visible width is arithmetically bounded. */
+function renderCard(spec: ArtifactCardSpec & { openUrl: string; pathLabel: string }, paint: ContentPaint): string {
+	const width = Math.max(CARD_MIN_WIDTH, Math.min(Math.floor(spec.width), CARD_MAX_WIDTH));
+	const inner = width - 2;
+	const contentWidth = Math.max(OPEN_WIDTH + 2, inner - 2);
+	const label = spec.typeLabel.toLowerCase();
+	const prefix = `─ ${label} `;
+	const dashes = Math.max(0, inner - visibleWidth(prefix));
+	const headerLine = paint.rule(`╭${prefix}${"─".repeat(dashes)}╮`);
+
+	const title = escapeMarkdown(spec.title);
+	// A link whose raw text cannot fit the line must not be emitted: the host wraps by RAW width, would
+	// split the token mid-way and print literal brackets with the URL dropped. It then degrades to the
+	// plain label, and the path line stays the way in.
+	const link = `[${OPEN_LABEL}](${spec.openUrl})`;
+	const linkFits = visibleWidth(link) <= Math.max(4, contentWidth - 1);
+	const titleBudget = contentWidth - (linkFits ? visibleWidth(link) : visibleWidth(OPEN_LABEL)) - 1;
+	const titleFitted = clampWidth(title, Math.max(1, titleBudget));
+	const actionText = linkFits ? link : OPEN_LABEL;
+	const titlePad = " ".repeat(Math.max(1, contentWidth - visibleWidth(titleFitted) - visibleWidth(actionText)));
+	// No escape codes inside the brackets: anything there breaks the link token.
+	const titleLine = `${paint.rule("│")} ${paint.quote(titleFitted)}${titlePad}${actionText} ${paint.rule("│")}`;
+	const copyPad = " ".repeat(Math.max(0, contentWidth - visibleWidth(COPY_LABEL)));
+	const copyLine = `${paint.rule("│")} ${paint.quote(COPY_LABEL)}${copyPad} ${paint.rule("│")}`;
+
+	// The full path is shown, wrapped — truncation is what made it useless to copy.
+	const safePath = spec.pathLabel.replace(/`/g, "'");
+	const chunkWidth = Math.max(8, contentWidth);
+	const chunks: string[] = [];
+	for (let index = 0; index < safePath.length; index += chunkWidth)
+		chunks.push(safePath.slice(index, index + chunkWidth));
+	if (chunks.length === 0) chunks.push("");
+	const pathLines = chunks
+		.map((chunk) => {
+			const pad = " ".repeat(Math.max(0, contentWidth - visibleWidth(chunk)));
+			return `${paint.rule("│")} ${paint.quote(chunk)}${pad} ${paint.rule("│")}`;
+		})
+		.join("  \n");
+	const bottomLine = paint.rule(`╰${"─".repeat(inner)}╯`);
+
+	// Hard breaks keep the box adjacent; the title line carries the link.
+	return `${headerLine}  \n${titleLine}  \n${copyLine}  \n${pathLines}  \n${bottomLine}\n`;
+}
+
+/**
+ * shape: none — one URL resolution plus one box build; the degrade branch lives in urlFor, not here.
+ */
+export function renderArtifactCard(server: ArtifactServer, spec: ArtifactCardSpec, paint: ContentPaint): string {
+	// urlFor registers the path as carded and names the loopback URL; a degraded server logs once and
+	// the card falls back to a file:// link, so the session never sees the failure.
+	const openUrl = server.urlFor(spec.path) ?? pathToFileURL(spec.path).href;
+	return renderCard({ ...spec, openUrl, pathLabel: spec.path }, paint);
+}
+
+/**
+ * The transcript row count of a raster artifact: the height the host's image fit would occupy.
+ *
+ * shape: none — one parse plus one arithmetic; no dispatch.
+ */
+export function imageLineMetadata(base64: string): { rows: number } {
+	const dimensions = getImageDimensions(base64, "image/png");
+	if (!dimensions) return { rows: 1 };
+	return { rows: Math.max(1, calculateImageRows(dimensions, DEFAULT_WIDTH_CELLS)) };
+}

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