@zenodinh/pi-render 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,128 @@
+// ported from pi-pretty-tui/src/features/canvas/prereqs.ts — survives because: the spawn boundary may
+// resolve absolute paths only, so the candidate lists that feed it are the security surface itself.
+
+/**
+ * Artifacts prerequisites: what the two binary-backed forms need, and where this machine would find it.
+ *
+ * Why a candidate list instead of PATH: the spawn boundary resolves absolute paths only (no PATH
+ * lookup, no environment override), so the list is deliberately short and per-platform. Dedicated
+ * headless shells are preferred over the user's app binaries: nothing in their profile is read, and the
+ * browser starts faster.
+ *
+ * Nothing here installs anything, and nothing here spawns: a missing tool degrades to the raw fence,
+ * and the named error carries what to run — the human decides.
+ *
+ * shape: none — ordered candidate scans; each resolver is one first-hit lookup over a static list.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface PrereqProbe {
+	exists?: (path: string) => boolean;
+	platform?: NodeJS.Platform;
+}
+
+export type PrereqKind = "plantuml" | "browser";
+
+function shellDirectory(platform: NodeJS.Platform): string {
+	return platform === "darwin" ? "chrome-headless-shell-mac-arm64" : "chrome-headless-shell-linux64";
+}
+
+/**
+ * Dedicated headless shells, newest first, from the two caches that ship them
+ * (Playwright and Puppeteer — each has its own directory layout). They come
+ * before the app bundles: a stripped shell touches no user profile and starts
+ * in a fraction of the time.
+ */
+export function headlessShellCandidates(
+	platform: NodeJS.Platform,
+	roots?: { playwright?: string; puppeteer?: string },
+): string[] {
+	const playwrightRoot =
+		roots?.playwright ??
+		(platform === "darwin" ? join(homedir(), "Library/Caches/ms-playwright") : join(homedir(), ".cache/ms-playwright"));
+	const puppeteerBase = join(roots?.puppeteer ?? join(homedir(), ".cache/puppeteer"), "chrome-headless-shell");
+	const list = (root: string, matches: (name: string) => boolean, toPath: (name: string) => string): string[] => {
+		try {
+			return readdirSync(root).filter(matches).sort().reverse().map(toPath);
+		} catch {
+			return [];
+		}
+	};
+	const shellDir = shellDirectory(platform);
+	return [
+		...list(
+			playwrightRoot,
+			(name) => name.startsWith("chromium_headless_shell-"),
+			(name) => join(playwrightRoot, name, shellDir, "chrome-headless-shell"),
+		),
+		...list(
+			puppeteerBase,
+			() => true,
+			(name) => join(puppeteerBase, name, shellDir, "chrome-headless-shell"),
+		),
+	];
+}
+
+/** The ordered absolute candidates per kind and platform; first existing wins. */
+export function prereqCandidates(
+	kind: PrereqKind,
+	platform: NodeJS.Platform,
+	shells: string[] = headlessShellCandidates(platform),
+): string[] {
+	if (platform === "linux") {
+		return kind === "plantuml"
+			? ["/usr/bin/plantuml", "/usr/local/bin/plantuml", "/snap/bin/plantuml"]
+			: [...shells, "/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser", "/snap/bin/chromium"];
+	}
+	return kind === "plantuml"
+		? ["/opt/homebrew/bin/plantuml", "/usr/local/bin/plantuml"]
+		: [
+				...shells,
+				"/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+				"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+			];
+}
+
+const INSTALL_HINTS: Record<PrereqKind, Record<"darwin" | "linux", string>> = {
+	plantuml: {
+		darwin: "brew install plantuml",
+		linux: "apt install plantuml (or snap install plantuml)",
+	},
+	browser: {
+		darwin: "install Brave or Chrome, or: npx playwright install chromium-headless-shell",
+		linux: "apt install chromium, or: npx playwright install chromium-headless-shell",
+	},
+};
+
+function hintFor(kind: PrereqKind, platform: NodeJS.Platform): string {
+	return INSTALL_HINTS[kind][platform === "linux" ? "linux" : "darwin"];
+}
+
+/** shape: none — one ordered scan, first hit wins; misses leave the path empty. */
+export function resolvePrereq(
+	kind: PrereqKind,
+	probe: PrereqProbe = {},
+): { path: string; hint: string; candidates: string[] } {
+	const platform = probe.platform ?? process.platform;
+	const exists = probe.exists ?? existsSync;
+	const candidates = prereqCandidates(kind, platform);
+	return { path: candidates.find((candidate) => exists(candidate)) ?? "", hint: hintFor(kind, platform), candidates };
+}
+
+/** shape: none — the resolved absolute path, or a named error carrying the install hint. */
+export function resolvePlantuml(probe: PrereqProbe = {}): string {
+	const { path, hint, candidates } = resolvePrereq("plantuml", probe);
+	if (!path) throw new Error(`plantuml: not found — install with "${hint}" (looked in: ${candidates.join(", ")})`);
+	return path;
+}
+
+/** shape: none — an explicit test seam wins, then the same candidates as the diagnostics. */
+export function resolveBrowserPinned(explicit?: string, probe: PrereqProbe = {}): string {
+	if (explicit) return explicit;
+	const { path, hint, candidates } = resolvePrereq("browser", probe);
+	if (!path) throw new Error(`html: no pinned browser found — ${hint} (looked in: ${candidates.join(", ")})`);
+	return path;
+}

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

@@ -0,0 +1,181 @@
+// ported from pi-pretty-tui/src/features/canvas/artifact-server.ts — survives because: the loopback
+// bind plus the opaque-id registry is what lets a card's Open link reach the embedded browser without
+// ever serving a request-named path, and its degrade-to-file-link fallback keeps a failed bind off the
+// session. The predecessor's module-level singleton becomes a factory so the composition root owns one
+// instance and a test can start a real server and stop it.
+
+/**
+ * server.ts — the loopback artifact server: an ephemeral 127.0.0.1 port serving exactly the carded
+ * paths, one opaque id each, no directory listing, and a degrade path that never touches the session.
+ *
+ * Boundary: the served path comes from the carded registry, never from the request URL — the request
+ * supplies an opaque id only. A bind failure or a socket idle past the request budget is logged and
+ * dropped, never thrown.
+ *
+ * shape: closure returning an object literal — trigger #4, one bound http server plus the carded-path
+ * registry it serves from; no subclassing and no instanceof.
+ */
+
+import { readFileSync } from "node:fs";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { Logger } from "../../../core/types/log.ts";
+
+const HOST = "127.0.0.1";
+const SCOPE = "content.artifacts";
+/** SA §6: a request that takes longer than this is dropped. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000;
+
+const CONTENT_TYPES: Record<string, string> = {
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".html": "text/html; charset=utf-8",
+	".md": "text/markdown; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".log": "text/plain; charset=utf-8",
+	".puml": "text/plain; charset=utf-8",
+	".dot": "text/plain; charset=utf-8",
+	".utxt": "text/plain; charset=utf-8",
+};
+
+/** The bind outcome start() reports; a degraded server leaves every card on its file:// link. */
+export type ArtifactServerState =
+	| { readonly ok: true; readonly url: string }
+	| { readonly ok: false; readonly reason: string };
+
+export interface ArtifactServer {
+	/** Binds once on the loopback interface; a bind failure is reported, never thrown. */
+	start(): Promise<ArtifactServerState>;
+	/** Releases the port and resets the state; idempotent. */
+	stop(): Promise<void>;
+	/** Registers `path` as carded and returns its loopback URL, or undefined while degraded. */
+	urlFor(path: string): string | undefined;
+}
+
+/** The listen step — injectable so a test can drive the degraded path without an occupied port. */
+export type ArtifactListen = (server: Server) => Promise<void>;
+
+export interface ArtifactServerOptions {
+	/** Diagnostics; the degraded path names its cause exactly once through logOnce. */
+	log?: Logger;
+	/** Socket-idle budget; a request past it is dropped with one logged line. */
+	requestTimeoutMs?: number;
+	/** Test seam; production binds 127.0.0.1:0. */
+	listen?: ArtifactListen;
+}
+
+/** shape: none — one promise over the one fallible bind; the error listener keeps it from being unhandled. */
+function bindLoopback(server: Server): Promise<void> {
+	return new Promise<void>((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, HOST, () => resolve());
+	});
+}
+
+function message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+export function createArtifactServer(options: ArtifactServerOptions = {}): ArtifactServer {
+	const log = options.log;
+	const requestTimeoutMs = Math.max(1, Math.floor(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS));
+	const listen = options.listen ?? bindLoopback;
+	// path -> opaque id (dedup) and id -> path (serving). The URL carries the id, so no request can name a path.
+	const idsByPath = new Map<string, string>();
+	const pathsById = new Map<string, string>();
+	let counter = 0;
+	let server: Server | undefined;
+	let baseUrl: string | undefined;
+	let failure: string | undefined;
+
+	const register = (path: string): string => {
+		const existing = idsByPath.get(path);
+		if (existing !== undefined) return existing;
+		counter += 1;
+		const id = counter.toString(36);
+		idsByPath.set(path, id);
+		pathsById.set(id, path);
+		return id;
+	};
+
+	const contentTypeFor = (file: string): string => {
+		const extension = file.slice(file.lastIndexOf(".")).toLowerCase();
+		return CONTENT_TYPES[extension] ?? "text/plain; charset=utf-8";
+	};
+
+	/** shape: none — one guarded lookup then one guarded read; every miss is a 404, never a listing. */
+	const respond = (request: IncomingMessage, response: ServerResponse): void => {
+		let id: string | undefined;
+		try {
+			const pathname = new URL(request.url ?? "/", `http://${HOST}`).pathname;
+			if (pathname.startsWith("/a/")) id = decodeURIComponent(pathname.slice(3));
+		} catch {
+			id = undefined;
+		}
+		const file = id === undefined ? undefined : pathsById.get(id);
+		if (file === undefined) {
+			response.writeHead(404).end();
+			return;
+		}
+		try {
+			const body = readFileSync(file);
+			response.writeHead(200, {
+				"content-type": contentTypeFor(file),
+				"content-length": String(body.length),
+				"cache-control": "no-store",
+			});
+			response.end(body);
+		} catch {
+			// A carded path whose artifact is gone is a 404, not a broken response.
+			response.writeHead(404).end();
+		}
+	};
+
+	return {
+		async start(): Promise<ArtifactServerState> {
+			if (baseUrl !== undefined) return { ok: true, url: baseUrl };
+			if (failure !== undefined) return { ok: false, reason: failure };
+			try {
+				const bound = createServer(respond);
+				// An abandoned or stalled request is dropped instead of holding the socket (SA §6).
+				bound.setTimeout(requestTimeoutMs, (socket) => {
+					log?.logOnce("artifact-server:timeout", SCOPE, `request dropped after ${requestTimeoutMs}ms`);
+					socket.destroy();
+				});
+				await listen(bound);
+				const address = bound.address();
+				if (address === null || typeof address === "string") throw new Error("no port was assigned");
+				server = bound;
+				baseUrl = `http://${HOST}:${address.port}`;
+				return { ok: true, url: baseUrl };
+			} catch (error) {
+				failure = message(error);
+				log?.logOnce("artifact-server:start", SCOPE, `artifact server unavailable: ${failure}`);
+				return { ok: false, reason: failure };
+			}
+		},
+
+		async stop(): Promise<void> {
+			const bound = server;
+			server = undefined;
+			baseUrl = undefined;
+			failure = undefined;
+			if (bound === undefined) return;
+			await new Promise<void>((resolve) => {
+				bound.close(() => resolve());
+				// Keep-alive sockets the client is done with must not hold close() open.
+				bound.closeIdleConnections();
+			});
+		},
+
+		urlFor(path: string): string | undefined {
+			const id = register(path);
+			if (baseUrl === undefined) {
+				// First click on a degraded server names the cause once; the card itself already rendered.
+				log?.logOnce("artifact-server:url", SCOPE, `Open link degraded: ${failure ?? "artifact server not started"}`);
+				return undefined;
+			}
+			return `${baseUrl}/a/${encodeURIComponent(id)}`;
+		},
+	};
+}

package/src/renderers/content/code-panel.ts

@@ -0,0 +1,161 @@
+// ported from pi-pretty-tui/src/features/canvas/code-panel.ts — survives because: the bordered panel
+// with a language header, the content-hugging width, the ANSI-aware truncation and the sync highlight
+// path are the owner's reading surface for a fence; only the color source changed (paint roles plus the
+// injected CodeTheme instead of module-level globals and hardcoded escapes).
+
+/**
+ * code-panel.ts — a fenced block becomes a bordered, themed panel; the JSON pane reuses the same frame,
+ * the same fence scan and the same markdown embedding.
+ *
+ * Boundary: markdown is untrusted and is scanned line-by-line, never handed to a parser; the CodeTheme
+ * is injected, so no renderer imports shiki. Width math is pi-tui's own ANSI-aware visibleWidth /
+ * truncateToWidth — the one host utility the panel needs, and what keeps columns aligned when truecolor
+ * escapes sit inside the content (CJK included). A failing highlighter degrades to plain source; the
+ * panel never throws.
+ *
+ * shape: none — a factory plus shared pure helpers; no discriminator to dispatch on. The factory
+ * declares its own shape below.
+ */
+
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { CodeTheme, ContentPaint } from "../../core/types.ts";
+import type { Surface } from "./types.ts";
+
+/** The panel is never narrower than this, so a one-word snippet still reads as a block (P code-panel.ts:20). */
+const MIN_PANEL_WIDTH = 24;
+/** A body row is `│ text │`, so the text budget is width-4 (P code-panel.ts:75). */
+const ROW_CHROME = 4;
+/** Languages left as raw fences: mermaid is the host's own renderer, and the four diagram forms
+ *  belong to the artifact pass that runs AFTER surfaces (SA §6) — consuming them here would
+ *  regress every diagram to a plain panel. */
+const RAW_FENCES = new Set(["mermaid", "plantuml", "svg", "dot", "html"]);
+
+/** The offered transcript width, clamped to the panel minimum (P transformer.ts:319-320). */
+// shape: none — one clamp, no branch on a discriminator.
+export function panelWidth(availableWidth: number): number {
+	return Math.max(MIN_PANEL_WIDTH, Math.floor(availableWidth) || 80);
+}
+
+/** Highlighted body lines, truncated by visible width; a throwing theme degrades to the plain source. */
+// shape: none — one guarded call plus a one-line fallback; no discriminator.
+function bodyLines(code: string, lang: string, width: number, codeTheme: CodeTheme): string[] {
+	const source = code.replace(/\n+$/, "");
+	const budget = Math.max(8, width - ROW_CHROME);
+	let lines: string[];
+	try {
+		lines = codeTheme.highlightSync(source, lang).split("\n");
+	} catch {
+		// A cold core or an unloadable grammar: the panel degrades, the answer render never dies.
+		lines = source.split("\n");
+	}
+	return lines.map((line) => truncateToWidth(line, budget));
+}
+
+/**
+ * One framed block: header label, hugged width, padded rows. Shared by the code and JSON panels.
+ *
+ * shape: none — one box; every row's visible width is arithmetically bounded to the panel width.
+ */
+export function renderPanel(
+	code: string,
+	lang: string,
+	width: number,
+	paint: ContentPaint,
+	codeTheme: CodeTheme,
+): string[] {
+	const maxWidth = Math.max(MIN_PANEL_WIDTH, Math.floor(width));
+	const label = lang.toLowerCase() || "code";
+	const body = bodyLines(code, lang, maxWidth, codeTheme);
+	const contentWidth = Math.max(1, ...body.map((line) => visibleWidth(line)));
+	const prefix = `─ ${label} `;
+	const panelSize = Math.min(
+		maxWidth,
+		Math.max(MIN_PANEL_WIDTH, Math.max(contentWidth + ROW_CHROME, visibleWidth(prefix) + ROW_CHROME)),
+	);
+	const inner = panelSize - 2;
+	const textWidth = Math.max(8, panelSize - ROW_CHROME);
+	const dashes = Math.max(0, inner - visibleWidth(prefix));
+	const rows: string[] = [paint.codeBlockBorder(`╭${prefix}${"─".repeat(dashes)}╮`)];
+	for (const line of body) {
+		const pad = " ".repeat(Math.max(0, textWidth - visibleWidth(line)));
+		rows.push(`${paint.codeBlockBorder("│")} ${line}${pad} ${paint.codeBlockBorder("│")}`);
+	}
+	rows.push(paint.codeBlockBorder(`╰${"─".repeat(inner)}╯`));
+	return rows;
+}
+
+/** CommonMark code span, delimiting with one backtick more than any run inside (P transformer.ts:67-74). */
+// shape: none — one delimiter choice, no state.
+function codeSpan(line: string): string {
+	const content = line || "\u00a0";
+	const longest = Math.max(0, ...Array.from(content.matchAll(/`+/g), (match) => match[0].length));
+	const fence = "`".repeat(longest + 1);
+	const pad = content.startsWith("`") || content.endsWith("`") ? " " : "";
+	return `${fence}${pad}${content}${pad}${fence}`;
+}
+
+/** Panel rows as markdown: one code span per row joined by hard breaks, so the host keeps the frame (P transformer.ts:82-85). */
+// shape: none — one map over lines.
+export function toMarkdownRows(lines: string[]): string {
+	return lines.map(codeSpan).join("  \n");
+}
+
+/** Opens a CommonMark fenced block: up to 3 spaces, ``` or ~~~, then the language token. */
+const FENCE_OPEN = /^( {0,3})(`{3,}|~{3,})[ \t]*(\S*)/;
+
+/**
+ * Rewrites every fenced block the transform accepts; an untouched block keeps its raw lines, and
+ * `changed` is false when nothing matched so the caller can return the same string reference.
+ *
+ * shape: none — one line walk with a single callback seam, no dispatch on a value.
+ */
+export function mapFencedBlocks(
+	markdown: string,
+	transform: (lang: string, code: string) => string | undefined,
+): { text: string; changed: boolean } {
+	const lines = markdown.split("\n");
+	const out: string[] = [];
+	let changed = false;
+	for (let i = 0; i < lines.length; i += 1) {
+		const open = FENCE_OPEN.exec(lines[i] ?? "");
+		if (open === null) {
+			out.push(lines[i] ?? "");
+			continue;
+		}
+		const marker = open[2] ?? "```";
+		const lang = (open[3] ?? "").toLowerCase();
+		const close = new RegExp(`^ {0,3}${marker.charAt(0)}{${marker.length},}[ \\t]*$`);
+		let end = i + 1;
+		const body: string[] = [];
+		while (end < lines.length && !close.test(lines[end] ?? "")) {
+			body.push(lines[end] ?? "");
+			end += 1;
+		}
+		if (end >= lines.length) {
+			out.push(lines[i] ?? ""); // unterminated fence: leave it raw rather than swallow the tail
+			continue;
+		}
+		const replacement = transform(lang, body.join("\n"));
+		if (replacement === undefined) {
+			out.push(...lines.slice(i, end + 1));
+		} else {
+			out.push(replacement);
+			changed = true;
+		}
+		i = end;
+	}
+	return { text: out.join("\n"), changed };
+}
+
+// shape: closure returning an object literal — trigger #4, one stateless Surface over the captured theme.
+export function createCodePanel(codeTheme: CodeTheme): Surface {
+	return {
+		rewrite(markdown, ctx, paint) {
+			const width = panelWidth(ctx.availableWidth);
+			const { text, changed } = mapFencedBlocks(markdown, (lang, code) =>
+				lang && !RAW_FENCES.has(lang) ? toMarkdownRows(renderPanel(code, lang, width, paint, codeTheme)) : undefined,
+			);
+			return changed ? text : markdown;
+		},
+	};
+}

package/src/renderers/content/image-card.test.ts

@@ -0,0 +1,170 @@
+// Fixture provenance — every image fixture is a real file written into a temp dir, so the assertions
+// drive the surface's own default probe (the bounded header read) instead of an injected stub.
+//   pic.png  — invented: a real 3×2 PNG (73 bytes) built with zlib + CRC32 on 2026-10-06; non-square,
+//              so a width/height swap cannot pass.
+//   pic.gif  — recorded-from: macOS sips converting that 3×2 PNG to GIF on 2026-10-06 (49 bytes, GIF87a).
+//   hdr.jpeg — invented: a 33-byte JPEG header (SOI, one APP1 segment to walk over, SOF0 3×2, EOI); the
+//              reader's contract is the segment walk, not the scan data.
+//   rst.jpeg — invented: a 25-byte JPEG header with a standalone RST0 marker before SOF0 3×2 — the walk
+//              must step over a marker that carries no length field.
+//   trunc.jpeg — invented: a 10-byte JPEG header whose APP1 segment claims 32 bytes the file does not
+//              hold — the walk must give up rather than read past the end.
+//   hdr.webp — invented: a 12-byte RIFF/WEBP signature — a known image whose dimensions this module does
+//              not walk, which is the path that cards with the path alone.
+//   bad.png  — invented: the PNG header with both dimensions zeroed (33 bytes) — the shape a corrupt or
+//              truncated header produces, where the dimensions must be dropped, not trusted.
+//   cut.png  — invented: the 8-byte PNG signature alone, no IHDR.
+//   notes.txt — invented: real text behind an image reference, the not-an-image case.
+
+// shape: none — test module: every behavior is asserted only through the createImageCardSurface seam.
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { markerPaint } from "../../../test/fakes/index.ts";
+import type { TransformContext } from "../../core/types/host.ts";
+import { createImageCardSurface } from "./image-card.ts";
+
+const PNG = "iVBORw0KGgoAAAANSUhEUgAAAAMAAAACCAIAAAASFvFNAAAAEElEQVR42mP4z8AAQQxwFgBB0gX7b/EWxwAAAABJRU5ErkJggg==";
+const GIF = "R0lGODdhAwACAJEAAAAAAP8AAP///wAAACH5BAQAAAAALAAAAAADAAIAAAICjF8AOw==";
+const JPEG_HEADER = "/9j/4QAIRXhpZgAA/8AAEQgAAgADAwERAAIRAQMRAf/Z";
+const JPEG_RST_HEADER = "/9j/0P/AABEIAAIAAwMBEQACEQEDEQH/2Q==";
+const JPEG_TRUNCATED_HEADER = "/9j/4QAgRXhpZg==";
+const WEBP_HEADER = "UklGRgQAAABXRUJQ";
+const ZEROED_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAAAAAAACAIAAAAAAAAA";
+const CUT_PNG = "iVBORw0KGgo=";
+
+/** The offered width every assertion here runs at: a 64-column card, 60 columns of content. */
+const ctx: TransformContext = { messageType: "assistant", isStreaming: false, availableWidth: 100 };
+
+let dir: string;
+
+beforeAll(() => {
+	dir = mkdtempSync(join(tmpdir(), "pi-render-image-card-"));
+	writeFileSync(join(dir, "pic.png"), Buffer.from(PNG, "base64"));
+	writeFileSync(join(dir, "pic.gif"), Buffer.from(GIF, "base64"));
+	writeFileSync(join(dir, "hdr.jpeg"), Buffer.from(JPEG_HEADER, "base64"));
+	writeFileSync(join(dir, "rst.jpeg"), Buffer.from(JPEG_RST_HEADER, "base64"));
+	writeFileSync(join(dir, "trunc.jpeg"), Buffer.from(JPEG_TRUNCATED_HEADER, "base64"));
+	writeFileSync(join(dir, "hdr.webp"), Buffer.from(WEBP_HEADER, "base64"));
+	writeFileSync(join(dir, "bad.png"), Buffer.from(ZEROED_PNG, "base64"));
+	writeFileSync(join(dir, "cut.png"), Buffer.from(CUT_PNG, "base64"));
+	writeFileSync(join(dir, "notes.txt"), "not an image\n");
+});
+
+afterAll(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+describe("createImageCardSurface — image references", () => {
+	it("AC-1: an existing local image renders the golden card with its resolved path and dimensions", () => {
+		const paint = markerPaint();
+		const surface = createImageCardSurface({ projectDir: dir });
+		const path = join(dir, "pic.png");
+		const out = surface.rewrite("![shot](pic.png)", ctx, paint);
+		// Golden geometry at 64 columns: header rule run 56, content 60, bottom run 62; the frame carries
+		// the rule role and every text row the quote role — the only content role that reads as metadata.
+		// A temp path outgrows one row on some machines, so the expected path rows are its pinned
+		// 60-column chunks: the widths and the row shape are literals, only the path's length varies.
+		const pathRows: string[] = [];
+		for (let at = 0; at < path.length; at += 60) {
+			pathRows.push(`${paint.rule("│")} ${paint.quote(path.slice(at, at + 60).padEnd(60))} ${paint.rule("│")}`);
+		}
+		const golden = [
+			paint.rule(`╭─ png ${"─".repeat(56)}╮`),
+			`${paint.rule("│")} ${paint.quote(`pic.png · 3×2${" ".repeat(47)}`)} ${paint.rule("│")}`,
+			...pathRows,
+			paint.rule(`╰${"─".repeat(62)}╯`),
+		].join("  \n");
+		// fails_when: card shape drifts or dims are wrong
+		expect(out).toBe(`${golden}\n`);
+	});
+
+	it("AC-1: PNG, GIF and JPEG headers become dimensions and an unwalked format still cards", () => {
+		const paint = markerPaint();
+		const surface = createImageCardSurface({ projectDir: dir });
+		const titleRow = (ref: string): string => surface.rewrite(`![shot](${ref})`, ctx, paint).split("  \n")[1] ?? "";
+		const cases: ReadonlyArray<readonly [string, string]> = [
+			["pic.png", "pic.png · 3×2"],
+			["pic.gif", "pic.gif · 3×2"],
+			["hdr.jpeg", "hdr.jpeg · 3×2"],
+			["rst.jpeg", "rst.jpeg · 3×2"],
+		];
+		for (const [ref, title] of cases) {
+			// fails_when: a header's offsets are wrong or a width/height swap goes unnoticed
+			expect(titleRow(ref)).toContain(title);
+		}
+		// fails_when: an image format whose dimensions we do not read drops the card instead of the path
+		expect(titleRow("hdr.webp")).toContain("hdr.webp");
+		expect(titleRow("hdr.webp")).not.toContain("·");
+	});
+
+	it("AC-1: a corrupt header drops the dimensions instead of the card", () => {
+		const paint = markerPaint();
+		const surface = createImageCardSurface({ projectDir: dir });
+		const titleRow = (ref: string): string => surface.rewrite(`![shot](${ref})`, ctx, paint).split("  \n")[1] ?? "";
+		for (const ref of ["bad.png", "cut.png", "trunc.jpeg"]) {
+			// fails_when: a header we cannot trust is trusted anyway
+			expect(titleRow(ref)).toContain(ref);
+			expect(titleRow(ref)).not.toContain("·");
+		}
+	});
+
+	it("AC-2: a reference to a file that is not there stays raw with one log line", () => {
+		const log: string[] = [];
+		const surface = createImageCardSurface({ projectDir: dir, log: (line) => log.push(line) });
+		const markdown = "![shot](gone.png)";
+		// fails_when: a missing image breaks the answer render
+		expect(surface.rewrite(markdown, ctx, markerPaint())).toBe(markdown);
+		expect(log).toHaveLength(1);
+		expect(log[0]).toContain("gone.png");
+	});
+
+	it("AC-2: a local file that is not an image stays raw with one log line", () => {
+		const log: string[] = [];
+		const surface = createImageCardSurface({ projectDir: dir, log: (line) => log.push(line) });
+		const markdown = "![shot](notes.txt)";
+		// fails_when: a non-image file behind an image reference is carded
+		expect(surface.rewrite(markdown, ctx, markerPaint())).toBe(markdown);
+		expect(log).toHaveLength(1);
+		expect(log[0]).toContain("notes.txt");
+	});
+
+	it("AC-2: a probe that throws keeps the reference and logs its message", () => {
+		const log: string[] = [];
+		const surface = createImageCardSurface({
+			projectDir: dir,
+			log: (line) => log.push(line),
+			probe: () => {
+				throw new Error("disk gone");
+			},
+		});
+		const markdown = "![shot](pic.png)";
+		// fails_when: a failing probe takes the answer render down
+		expect(surface.rewrite(markdown, ctx, markerPaint())).toBe(markdown);
+		expect(log).toHaveLength(1);
+		expect(log[0]).toContain("disk gone");
+	});
+
+	it("AC-2: a remote, protocol-relative or anchored reference is left alone and never logged", () => {
+		const log: string[] = [];
+		const surface = createImageCardSurface({ projectDir: dir, log: (line) => log.push(line) });
+		const hrefs = ["https://example.test/a.png", "//example.test/a.png", "#figure", "data:image/png;base64,AAAA"];
+		for (const href of hrefs) {
+			const markdown = `![shot](${href})`;
+			// fails_when: a reference pi-render does not own is read as a local path
+			expect(surface.rewrite(markdown, ctx, markerPaint())).toBe(markdown);
+		}
+		expect(log).toEqual([]);
+	});
+
+	it("leaves a reference inside a fenced block alone and cards the one outside it", () => {
+		const surface = createImageCardSurface({ projectDir: dir });
+		const markdown = ["```md", "![shot](pic.png)", "```", "![shot](pic.png)"].join("\n");
+		const out = surface.rewrite(markdown, ctx, markerPaint());
+		// fails_when: text inside a code block is rewritten as an image reference
+		expect(out).toContain("```md\n![shot](pic.png)\n```");
+		// exactly one card, and it is the reference outside the fence
+		expect(out.match(/╭─ png /g)).toHaveLength(1);
+	});
+});