@zenodinh/pi-render 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,199 @@
+/**
+ * artifacts.test.ts — the artifacts seam: renderDiagram / warmup / status (engines.ts) and the cache
+ * (cache.ts), driven through fake engines and temp cache directories only (T-25).
+ *
+ * The first describe block is the predecessor's cache test ported unchanged (AC-4 parity); the second
+ * is this ticket's behavior spec: one engine run per repeated fence, a missing binary reported without a
+ * spawn, and a bounded store that never fails a render.
+ *
+ * shape: none — test module, no runtime unit for DSG-1's trigger table to select a shape for.
+ */
+
+import { existsSync, mkdtempSync, readdirSync, readFileSync, truncateSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+	type CacheMeta,
+	createArtifactCache,
+	evictIfNeeded,
+	getRenderedEntry,
+	putRenderedEntry,
+	putRenderedSource,
+} from "./cache.ts";
+import { type DiagramResult, type Engine, renderDiagram, status, warmup } from "./engines.ts";
+import type { LocalSpawn } from "./local-binary.ts";
+
+// recorded-from: generated 1x1 RGBA PNG fixture, 2026-10-03
+const PNG_BYTES = Buffer.from(
+	"89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000d49444154789c63300e5df51f0004230232e7bf98d60000000049454e44ae426082",
+	"hex",
+);
+
+let dir: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), "pretty-cache-"));
+});
+
+function meta(createdAt: string): CacheMeta {
+	return { source: "plantuml", mode: "image", mime: "image/png", rows: 4, widthCells: 40, createdAt };
+}
+
+describe("render cache", () => {
+	it("round-trips pairs, misses cleanly, and evicts oldest-first past the byte cap", () => {
+		putRenderedEntry("aaa", PNG_BYTES, meta("2026-10-02T00:00:00.000Z"), { cacheDir: dir });
+		putRenderedEntry("bbb", PNG_BYTES, meta("2026-10-02T00:01:00.000Z"), { cacheDir: dir });
+
+		const hit = getRenderedEntry("aaa", { cacheDir: dir });
+		expect(hit?.png.equals(PNG_BYTES)).toBe(true);
+		expect(hit?.meta).toEqual(meta("2026-10-02T00:00:00.000Z"));
+		expect(getRenderedEntry("missing", { cacheDir: dir })).toBeUndefined();
+		expect(existsSync(join(dir, "aaa.png.tmp"))).toBe(false);
+		expect(existsSync(join(dir, "aaa.meta.json.tmp"))).toBe(false);
+
+		// The saved source rides the same key, written atomically and evicted with
+		// its pair.
+		const sourcePath = putRenderedSource("aaa", "@startuml\nA -> B\n@enduml\n", "puml", { cacheDir: dir });
+		expect(sourcePath).toBe(join(dir, "aaa.src.puml"));
+		expect(readFileSync(sourcePath as string, "utf8")).toBe("@startuml\nA -> B\n@enduml\n");
+
+		// Seed 30 backdated entries whose PNGs are 10 MiB each (sparse): 300 MiB
+		// crosses the 256 MiB cap, so the oldest must leave while recent pairs stay.
+		for (let i = 0; i < 30; i++) {
+			const key = `seed${i.toString().padStart(2, "0")}`;
+			writeFileSync(
+				join(dir, `${key}.meta.json`),
+				JSON.stringify(meta(`2026-10-01T00:${String(i).padStart(2, "0")}:00.000Z`)),
+			);
+			const png = join(dir, `${key}.png`);
+			writeFileSync(png, Buffer.alloc(0));
+			truncateSync(png, 10 * 1024 * 1024);
+		}
+		writeFileSync(join(dir, "seed00.src.puml"), "stale source");
+
+		evictIfNeeded({ cacheDir: dir });
+
+		expect(existsSync(join(dir, "seed00.png"))).toBe(false);
+		expect(existsSync(join(dir, "seed00.meta.json"))).toBe(false);
+		expect(existsSync(join(dir, "seed00.src.puml"))).toBe(false);
+		expect(existsSync(join(dir, "seed29.meta.json"))).toBe(true);
+		expect(existsSync(join(dir, "aaa.png"))).toBe(true);
+		expect(existsSync(join(dir, "aaa.src.puml"))).toBe(true);
+	});
+});
+
+describe("artifact render seam", () => {
+	// spec: renderDiagram("dot", source, …) twice with the same source, mode and width runs the engine
+	//   once and returns the identical artifact — a repeated fence is a file read, not a render.
+	// fails_when: duplicate engine runs (every re-render of an answer re-spawns/re-renders).
+	it("AC-1 a repeated fence runs its engine exactly once and returns identical output", () => {
+		let calls = 0;
+		// invented: the counting engine is the whole fixture — there is no upstream payload to record.
+		const fakeViz: Engine = {
+			id: "viz",
+			warmup: async () => {},
+			status: () => true,
+			render: (source) => {
+				calls += 1;
+				return { kind: "svg", svg: `<svg>${source}</svg>` };
+			},
+		};
+		const cache = createArtifactCache({ cacheDir: dir });
+		const options = { cache, engines: { viz: fakeViz } };
+
+		const first: DiagramResult = renderDiagram("dot", "digraph { a -> b }", options);
+		const second: DiagramResult = renderDiagram("dot", "digraph { a -> b }", options);
+
+		expect(calls).toBe(1);
+		expect(second.kind).toBe("svg");
+		expect(second).toEqual(first);
+	});
+
+	// spec: on a machine whose plantuml candidate list holds no file, status() reports the form
+	//   unavailable and renderDiagram throws the install hint — the caller then keeps the raw fence.
+	// fails_when: a spawn is attempted for a binary that is known to be missing, or the render crashes.
+	it("AC-2 a missing plantuml binary reports unavailable and attempts no spawn", () => {
+		const spawned: string[] = [];
+		const spawn: LocalSpawn = (cmd) => {
+			spawned.push(cmd);
+			return { status: 0, signal: null, stdout: Buffer.alloc(0), stderr: Buffer.alloc(0) };
+		};
+		// invented: an empty candidate list on linux — the machine-independent "not installed" state.
+		const missing = { platform: "linux" as const, exists: () => false };
+
+		expect(status(missing).plantuml).toBe(false);
+		expect(() =>
+			renderDiagram("plantuml", "@startuml\nA -> B\n@enduml\n", {
+				cache: createArtifactCache({ cacheDir: dir }),
+				prereqs: missing,
+				spawn,
+			}),
+		).toThrow(/apt install plantuml/);
+		expect(spawned).toEqual([]);
+	});
+
+	// spec: a cache holding more entries than the 2048 cap loses its oldest entries on eviction.
+	// fails_when: the store grows without limit.
+	it("AC-3 eviction shrinks an over-cap store to the cap, oldest first", () => {
+		const total = 2050;
+		for (let i = 0; i < total; i++) {
+			const key = `e${i.toString().padStart(4, "0")}`;
+			writeFileSync(join(dir, `${key}.png`), Buffer.from("x"));
+			writeFileSync(
+				join(dir, `${key}.meta.json`),
+				JSON.stringify(meta(new Date(Date.UTC(2026, 9, 1, 0, 0, i)).toISOString())),
+			);
+		}
+
+		evictIfNeeded({ cacheDir: dir });
+
+		const entries = readdirSync(dir).filter((name) => name.endsWith(".meta.json"));
+		expect(entries.length).toBeLessThanOrEqual(2048);
+		expect(existsSync(join(dir, "e0000.meta.json"))).toBe(false);
+		expect(existsSync(join(dir, "e2049.meta.json"))).toBe(true);
+	});
+
+	// spec: an unusable cache directory (here: a path below a regular file) is a lost optimization, not a
+	//   failed artifact — the render still returns its result and eviction still returns quietly.
+	// fails_when: a cache write or eviction error propagates into the render path.
+	it("AC-3 a failing store never fails the render or throws from eviction", () => {
+		const blocker = join(dir, "blocker");
+		writeFileSync(blocker, "");
+		const cache = createArtifactCache({ cacheDir: join(blocker, "cache") });
+		// invented: the counting engine is the whole fixture — no upstream payload to record.
+		const fakeViz: Engine = {
+			id: "viz",
+			warmup: async () => {},
+			status: () => true,
+			render: () => ({ kind: "svg", svg: "<svg/>" }),
+		};
+
+		const result = renderDiagram("dot", "digraph { a -> b }", { cache, engines: { viz: fakeViz } });
+
+		expect(result.kind).toBe("svg");
+		expect(() => cache.evict()).not.toThrow();
+	});
+
+	// spec: warmup() is what lets the synchronous render seam call an asynchronous engine: after it, the
+	//   three wasm engines report ready.
+	// fails_when: an engine is called cold, or a warm-up failure is thrown instead of reported.
+	it("warmup reports the wasm engines ready", async () => {
+		const warmed = await warmup();
+
+		expect(warmed.resvg).toBe(true);
+		expect(warmed.viz).toBe(true);
+		expect(warmed.canvaskit).toBe(true);
+	});
+
+	// spec: a warmed viz engine turns a DOT fence into SVG through the same seam a fence uses.
+	// fails_when: the ported engine call cannot render, or the result kind drifts from vector.
+	it("a warmed viz engine renders a dot fence to SVG", async () => {
+		await warmup();
+
+		const result = renderDiagram("dot", "digraph { a -> b }", { cache: createArtifactCache({ cacheDir: dir }) });
+
+		expect(result.kind).toBe("svg");
+		if (result.kind === "svg") expect(result.svg).toContain("<svg");
+	});
+});

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

@@ -0,0 +1,234 @@
+// ported from pi-pretty-tui/src/features/canvas/cache.ts — survives because: the hash-keyed atomic pair
+// is what makes a repeated fence free, and the two caps keep that promise bounded.
+
+/**
+ * Disk cache for rendered diagrams: hash-keyed artifact + meta pairs under
+ * `~/.pi/agent/pi-render/cache`, bounded so repeat renders stay free without the store growing without
+ * limit.
+ *
+ * Why pairs and why atomic: the artifact IS the render result and the meta is its
+ * provenance (source form, mode, dimensions, creation time) — eviction orders
+ * by meta.createdAt. Every write lands via tmp+rename so a concurrent reader
+ * sees the old or the new complete file, never a partial one.
+ *
+ * shape: closure returning an object literal — trigger #4, one bound directory plus the store methods,
+ * so no class, subclassing, or instanceof.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Logger } from "../../../core/types/log.ts";
+
+export interface CacheMeta {
+	source: string;
+	mode: string;
+	mime: string;
+	rows: number;
+	widthCells: number;
+	createdAt: string;
+}
+
+export interface CacheOptions {
+	cacheDir?: string;
+	/** Diagnostics sink; absent means eviction failures are swallowed unwritten. */
+	log?: Logger;
+}
+
+const CACHE_DIR_NAME = "cache";
+const SCOPE = "content.artifacts";
+const META_SUFFIX = ".meta.json";
+const PNG_SUFFIX = ".png";
+const VECTOR_SUFFIX = ".svg";
+const SOURCE_INFIX = ".src.";
+const MAX_BYTES = 256 * 1024 * 1024;
+const MAX_ENTRIES = 2048;
+
+/**
+ * shape: none — one env lookup beside the cache dir name; `PI_CODING_AGENT_DIR` mirrors the host's
+ * agent-directory override, and the tree is the one `settings.json` already lives in.
+ */
+function resolveCacheDir(opts?: CacheOptions): string | undefined {
+	if (opts?.cacheDir) return opts.cacheDir;
+	const agentDir = process.env.PI_CODING_AGENT_DIR || (process.env.HOME ? join(process.env.HOME, ".pi/agent") : "");
+	return agentDir ? join(agentDir, "pi-render", CACHE_DIR_NAME) : undefined;
+}
+
+function writeAtomic(path: string, data: Buffer): void {
+	const temporary = `${path}.tmp`;
+	writeFileSync(temporary, data);
+	renameSync(temporary, path);
+}
+
+/** shape: none — one hash over a fixed tuple; the key format is the whole contract. */
+export function renderCacheKey(form: string, source: string, mode: string, widthCells: number): string {
+	return createHash("sha256").update(`${form}\0${source}\0${mode}\0${widthCells}`).digest("hex");
+}
+
+/** The directory the render cache lives in; exported so callers can point a viewer at it. */
+export function resolveRenderedCacheDir(opts?: CacheOptions): string | undefined {
+	return resolveCacheDir(opts);
+}
+
+/** shape: none — the vector is the artifact the card opens; existence is the hit. */
+export function putRenderedVector(key: string, svg: string, meta: CacheMeta, opts: CacheOptions = {}): void {
+	const dir = resolveCacheDir(opts);
+	if (!dir) return;
+	mkdirSync(dir, { recursive: true });
+	writeAtomic(join(dir, `${key}${VECTOR_SUFFIX}`), Buffer.from(svg));
+	writeAtomic(join(dir, `${key}${META_SUFFIX}`), Buffer.from(`${JSON.stringify(meta, null, 2)}\n`));
+}
+
+/** shape: none — one existence check; the path is what the card opens. */
+export function getRenderedVectorPath(key: string, opts: CacheOptions = {}): string | undefined {
+	const dir = resolveCacheDir(opts);
+	if (!dir) return undefined;
+	const path = join(dir, `${key}${VECTOR_SUFFIX}`);
+	return existsSync(path) ? path : undefined;
+}
+
+/** shape: none — one atomic write; the source is kept for copy/reuse, never read back. */
+export function putRenderedSource(
+	key: string,
+	source: string,
+	extension: string,
+	opts: CacheOptions = {},
+): string | undefined {
+	const dir = resolveCacheDir(opts);
+	if (!dir) return undefined;
+	mkdirSync(dir, { recursive: true });
+	const path = join(dir, `${key}${SOURCE_INFIX}${extension}`);
+	writeAtomic(path, Buffer.from(source));
+	return path;
+}
+
+/** boundary: a persisted meta file is untrusted JSON and narrows here before any field is read. */
+function isCacheMeta(value: unknown): value is CacheMeta {
+	if (typeof value !== "object" || value === null) return false;
+	if (
+		!(
+			"source" in value &&
+			"mode" in value &&
+			"mime" in value &&
+			"rows" in value &&
+			"widthCells" in value &&
+			"createdAt" in value
+		)
+	) {
+		return false;
+	}
+	return (
+		typeof value.source === "string" &&
+		typeof value.mode === "string" &&
+		typeof value.mime === "string" &&
+		typeof value.rows === "number" &&
+		typeof value.widthCells === "number" &&
+		typeof value.createdAt === "string"
+	);
+}
+
+/** shape: none — one atomic pair write; Command does not apply (not queued or replayable). */
+export function putRenderedEntry(key: string, png: Buffer, meta: CacheMeta, opts: CacheOptions = {}): void {
+	const dir = resolveCacheDir(opts);
+	if (!dir) return;
+	mkdirSync(dir, { recursive: true });
+	writeAtomic(join(dir, `${key}${PNG_SUFFIX}`), png);
+	writeAtomic(join(dir, `${key}${META_SUFFIX}`), Buffer.from(`${JSON.stringify(meta, null, 2)}\n`));
+}
+
+/** shape: none — one guarded read pair; returns undefined on any miss. */
+export function getRenderedEntry(key: string, opts: CacheOptions = {}): { png: Buffer; meta: CacheMeta } | undefined {
+	const dir = resolveCacheDir(opts);
+	if (!dir) return undefined;
+	try {
+		const raw: unknown = JSON.parse(readFileSync(join(dir, `${key}${META_SUFFIX}`), "utf8"));
+		if (!isCacheMeta(raw)) return undefined;
+		return { png: readFileSync(join(dir, `${key}${PNG_SUFFIX}`)), meta: raw };
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * shape: none — a bounded sweep; eviction is cleanup, never a render outcome.
+ * Two caps (bytes and entry count) both order by meta.createdAt ascending; an
+ * unreadable meta sorts first so the least trustworthy entry leaves earliest.
+ * Every failure is logged and swallowed — a full disk must not fail a render.
+ */
+export function evictIfNeeded(opts: CacheOptions = {}): void {
+	const dir = resolveCacheDir(opts);
+	if (!dir || !existsSync(dir)) return;
+	try {
+		const entries = new Map<string, { bytes: number; createdAt: string; files: string[] }>();
+		for (const name of readdirSync(dir)) {
+			const base = name.endsWith(META_SUFFIX)
+				? name.slice(0, -META_SUFFIX.length)
+				: name.endsWith(PNG_SUFFIX)
+					? name.slice(0, -PNG_SUFFIX.length)
+					: name.endsWith(VECTOR_SUFFIX)
+						? name.slice(0, -VECTOR_SUFFIX.length)
+						: name.includes(SOURCE_INFIX)
+							? name.slice(0, name.indexOf(SOURCE_INFIX))
+							: undefined;
+			if (base === undefined) continue;
+			const entry = entries.get(base) ?? { bytes: 0, createdAt: "", files: [] };
+			entry.files.push(name);
+			entry.bytes += statSync(join(dir, name)).size;
+			entries.set(base, entry);
+		}
+		for (const [base, entry] of entries) {
+			try {
+				const raw: unknown = JSON.parse(readFileSync(join(dir, `${base}${META_SUFFIX}`), "utf8"));
+				if (isCacheMeta(raw)) entry.createdAt = raw.createdAt;
+			} catch {
+				// An unreadable meta keeps the empty sort key: evicted first.
+			}
+		}
+
+		let totalBytes = 0;
+		for (const entry of entries.values()) totalBytes += entry.bytes;
+		let count = entries.size;
+		if (totalBytes <= MAX_BYTES && count <= MAX_ENTRIES) return;
+
+		const oldestFirst = [...entries.entries()].sort((a, b) => (a[1].createdAt < b[1].createdAt ? -1 : 1));
+		for (const [, entry] of oldestFirst) {
+			if (totalBytes <= MAX_BYTES && count <= MAX_ENTRIES) break;
+			for (const file of entry.files) rmSync(join(dir, file), { force: true });
+			totalBytes -= entry.bytes;
+			count -= 1;
+		}
+	} catch (error) {
+		opts.log?.logLine(SCOPE, `cache eviction failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * The artifacts-internal cache surface: content-hash keyed through `renderCacheKey`, one instance bound
+ * to a directory. T-26 reads artifact paths from it; T-28 injects the one production instance.
+ */
+export interface ArtifactCache {
+	/** The cached raster pair, or undefined on any miss. */
+	get(key: string): { png: Buffer; meta: CacheMeta } | undefined;
+	/** One atomic raster pair write. */
+	put(key: string, png: Buffer, meta: CacheMeta): void;
+	/** One atomic vector write — the artifact a vector card opens. */
+	putVector(key: string, svg: string, meta: CacheMeta): void;
+	/** Absolute vector path, or undefined when absent. */
+	vectorPath(key: string): string | undefined;
+	/** Saves the fence source beside its artifact; returns the absolute path. */
+	putSource(key: string, source: string, extension: string): string | undefined;
+	/** Bounded sweep; never throws. */
+	evict(): void;
+}
+
+/** shape: none — one delegating literal over the ported free functions; no state of its own. */
+export function createArtifactCache(opts: CacheOptions = {}): ArtifactCache {
+	return {
+		get: (key) => getRenderedEntry(key, opts),
+		put: (key, png, meta) => putRenderedEntry(key, png, meta, opts),
+		putVector: (key, svg, meta) => putRenderedVector(key, svg, meta, opts),
+		vectorPath: (key) => getRenderedVectorPath(key, opts),
+		putSource: (key, source, extension) => putRenderedSource(key, source, extension, opts),
+		evict: () => evictIfNeeded(opts),
+	};
+}

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

@@ -0,0 +1,216 @@
+/**
+ * cards.test.ts — the artifacts seam: createArtifactServer() (server.ts) and the card renderer
+ * (cards.ts). The server tests start a REAL server on an ephemeral port and issue real HTTP requests;
+ * the card tests drive the renderer with the marker paint double, so a wrong paint role is visible.
+ *
+ * shape: none — test module, no runtime unit for DSG-1's trigger table to select a shape for.
+ */
+
+import { once } from "node:events";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { connect } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { markerPaint } from "../../../../test/fakes/index.ts";
+import { createLogger } from "../../../core/log.ts";
+import { artifactTitle, imageLineMetadata, renderArtifactCard } from "./cards.ts";
+import { type ArtifactListen, type ArtifactServer, createArtifactServer } from "./server.ts";
+
+// recorded-from: generated 1x1 RGBA PNG fixture, 2026-10-03 (the predecessor's emit.test.ts fixture)
+const PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGMwDl31HwAEIwIy57+Y1gAAAABJRU5ErkJggg==";
+// invented: a tiny real SVG whose body and extension pin the served content-type.
+const SVG_BODY = '<svg xmlns="http://www.w3.org/2000/svg"><title>demo</title></svg>';
+
+let dir: string;
+let artifactPath: string;
+
+beforeAll(() => {
+	dir = mkdtempSync(join(tmpdir(), "pi-render-cards-"));
+	artifactPath = join(dir, "diagram.svg");
+	writeFileSync(artifactPath, SVG_BODY);
+});
+
+afterAll(() => {
+	rmSync(dir, { recursive: true, force: true });
+});
+
+async function started(): Promise<{ server: ArtifactServer; url: string }> {
+	const server = createArtifactServer();
+	const state = await server.start();
+	if (!state.ok) throw new Error(`server did not start: ${state.reason}`);
+	return { server, url: state.url };
+}
+
+describe("createArtifactServer", () => {
+	it("AC-1 binds 127.0.0.1 on an ephemeral port", async () => {
+		const { server, url } = await started();
+		try {
+			const address = new URL(url);
+			// fails_when: the bind is on another interface, or the port is not ephemeral.
+			expect(address.hostname).toBe("127.0.0.1");
+			expect(Number(address.port)).toBeGreaterThan(0);
+			expect(url.startsWith("http://127.0.0.1:")).toBe(true);
+			// A real request to that loopback address proves the listener answers there.
+			expect((await fetch(`${url}/a/nothing-carded`)).status).toBe(404);
+		} finally {
+			await server.stop();
+		}
+	});
+
+	it("AC-2 serves a carded path and 404s everything else with no listing", async () => {
+		const { server, url } = await started();
+		try {
+			const carded = server.urlFor(artifactPath);
+			expect(carded).toBeDefined();
+			expect(carded?.startsWith("http://127.0.0.1:")).toBe(true);
+			// One carded file keeps one opaque id, so the link is stable across re-renders.
+			expect(server.urlFor(artifactPath)).toBe(carded);
+
+			const ok = await fetch(carded as string);
+			expect(ok.status).toBe(200);
+			expect(ok.headers.get("content-type")).toBe("image/svg+xml");
+			expect(await ok.text()).toBe(SVG_BODY);
+
+			// fails_when: anything not carded is served — a listing, a request-named path, or a probe.
+			expect((await fetch(`${url}/`)).status).toBe(404);
+			expect((await fetch(`${url}/a/`)).status).toBe(404);
+			expect((await fetch(`${url}/a/unknown-id`)).status).toBe(404);
+			expect((await fetch(`${url}${artifactPath}`)).status).toBe(404);
+			expect((await fetch(`${url}/etc/passwd`)).status).toBe(404);
+		} finally {
+			await server.stop();
+		}
+	});
+
+	it("AC-3 a failed bind reports degraded state and renders the card on a file:// link", async () => {
+		const log = createLogger();
+		// invented: the injected listen is the whole fixture — a bind failure without an occupied port.
+		const listen: ArtifactListen = async () => {
+			throw new Error("EADDRINUSE: address already in use");
+		};
+		const server = createArtifactServer({ log, listen });
+
+		const state = await server.start();
+		expect(state.ok).toBe(false);
+		if (state.ok) return;
+		expect(state.reason).toContain("EADDRINUSE");
+
+		// invented: a short path so the degraded file:// target still fits the card line (the card only
+		// builds the URL; the served-path tests above use the real artifact).
+		const path = "/tmp/pi-render-degraded.svg";
+		const paint = markerPaint();
+		const spec = { typeLabel: "svg", title: "demo", path, width: 64 };
+		// fails_when: the failed bind breaks the card instead of degrading only the Open link.
+		const card = renderArtifactCard(server, spec, paint);
+		renderArtifactCard(server, spec, paint);
+		expect(card).toContain("demo");
+		expect(card).toContain("[Open (⌘click)](file:///tmp/pi-render-degraded.svg)");
+
+		// The cause is named exactly once, on the first click — not on every re-render.
+		const degraded = log.drain().filter((entry) => entry.message.includes("Open link degraded"));
+		expect(degraded).toHaveLength(1);
+	});
+
+	it("drops an idle request past the budget and logs the reason", async () => {
+		const log = createLogger();
+		const server = createArtifactServer({ log, requestTimeoutMs: 50 });
+		const state = await server.start();
+		if (!state.ok) throw new Error(state.reason);
+		const port = Number(new URL(state.url).port);
+		const socket = connect(port, "127.0.0.1");
+		await once(socket, "connect");
+		try {
+			// Nothing is sent: the server's own budget must close the socket.
+			await Promise.race([
+				once(socket, "close"),
+				new Promise((_, reject) => setTimeout(() => reject(new Error("socket was not dropped")), 2000)),
+			]);
+			const messages = log.drain().map((entry) => entry.message);
+			expect(messages.some((message) => message.includes("request dropped after 50ms"))).toBe(true);
+		} finally {
+			socket.destroy();
+			await server.stop();
+		}
+	});
+
+	it("stop() releases the port so the loopback URL stops answering", async () => {
+		const first = await started();
+		const url = first.url;
+		await first.server.stop();
+		// fails_when: stop() leaves the listener bound.
+		await expect(fetch(`${url}/a/x`)).rejects.toThrow();
+		const second = await started();
+		await second.server.stop();
+	});
+});
+
+describe("renderArtifactCard", () => {
+	it("renders the box with the server's Open link as the title-line action", async () => {
+		const { server } = await started();
+		try {
+			const paint = markerPaint();
+			const openUrl = server.urlFor(artifactPath) as string;
+			const out = renderArtifactCard(server, { typeLabel: "svg", title: "demo", path: artifactPath, width: 64 }, paint);
+
+			// Golden geometry at 64 columns: header run 56, content 60, bottom run 62; the frame carries
+			// the rule role and every text row the quote role. The temp path varies in length, so its
+			// pinned 60-column chunks are rebuilt here; the widths and row counts are literals.
+			const link = `[Open (⌘click)](${openUrl})`;
+			const titlePad = " ".repeat(60 - visibleWidth("demo") - visibleWidth(link));
+			const copyPad = " ".repeat(60 - visibleWidth("Copy path (⌥C)"));
+			const pathRows: string[] = [];
+			for (let at = 0; at < artifactPath.length; at += 60) pathRows.push(artifactPath.slice(at, at + 60));
+			const golden = [
+				paint.rule(`╭─ svg ${"─".repeat(56)}╮`),
+				`${paint.rule("│")} ${paint.quote("demo")}${titlePad}${link} ${paint.rule("│")}`,
+				`${paint.rule("│")} ${paint.quote("Copy path (⌥C)")}${copyPad} ${paint.rule("│")}`,
+				...pathRows.map(
+					(chunk) =>
+						`${paint.rule("│")} ${paint.quote(chunk)}${" ".repeat(60 - visibleWidth(chunk))} ${paint.rule("│")}`,
+				),
+				paint.rule(`╰${"─".repeat(62)}╯`),
+			].join("  \n");
+			// fails_when: the card geometry, the Open link, or the paint roles drift.
+			expect(out).toBe(`${golden}\n`);
+			// The field bug class: a line whose RAW width exceeds the card gets host-wrapped, breaking the link.
+			for (const line of out.split("\n")) expect(visibleWidth(line.trimEnd())).toBeLessThanOrEqual(64);
+		} finally {
+			await server.stop();
+		}
+	});
+
+	it("degrades the link to the plain label when the target cannot fit the line", async () => {
+		const log = createLogger();
+		const server = createArtifactServer({ log, listen: async () => Promise.reject(new Error("down")) });
+		await server.start();
+		// invented: a path long enough that its file:// URL outgrows the 60-column content line.
+		const longPath = `/${"x".repeat(120)}.svg`;
+		const out = renderArtifactCard(server, { typeLabel: "svg", title: "t", path: longPath, width: 64 }, markerPaint());
+		const titleLine = out.split("  \n")[1] ?? "";
+		// fails_when: an unfittable link is emitted anyway and the host wraps it into literal brackets.
+		expect(titleLine).toContain("Open (⌘click)");
+		expect(titleLine).not.toContain("](file://");
+		expect(visibleWidth(titleLine.trimEnd())).toBeLessThanOrEqual(64);
+	});
+});
+
+describe("artifactTitle", () => {
+	it("takes the artifact's own name where the source carries one, and the form otherwise", () => {
+		// invented: fence sources pinning the four title sources and the fallback.
+		expect(artifactTitle("plantuml", '@startuml "Payments"\nA -> B\n@enduml')).toBe("Payments");
+		expect(artifactTitle("plantuml", "@startuml\ntitle Order flow\nA -> B\n@enduml")).toBe("Order flow");
+		expect(artifactTitle("svg", "<svg><title>Logo</title></svg>")).toBe("Logo");
+		expect(artifactTitle("html", "<h1>Report</h1>")).toBe("Report");
+		expect(artifactTitle("dot", "digraph { a -> b }")).toBe("dot");
+	});
+});
+
+describe("imageLineMetadata", () => {
+	it("reports a PNG's transcript row count and one row for unparseable bytes", () => {
+		// The 1x1 PNG at the default 60-cell width fits as 30 rows (8x16 cell ratio).
+		expect(imageLineMetadata(PNG_BASE64)).toEqual({ rows: 30 });
+		expect(imageLineMetadata("not-a-png")).toEqual({ rows: 1 });
+	});
+});