@zenodinh/pi-render 0.0.0-stage → 0.1.2

package/src/core/types/host.ts

@@ -0,0 +1,169 @@
+/**
+ * host.ts — the host shapes pi-render reads, composes against, and registers through.
+ *
+ * Boundary: these are STRUCTURAL declarations of shapes the pi host also declares. No host
+ * package is imported here, so a plain object literal satisfies them and a unit test needs no pi
+ * runtime; the composition root (index.ts) passes the real host in as a parameter.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ *
+ * Ported from pi-pretty-tui/src/types.ts — survives because: host-verified structural shapes keep
+ * every renderer decoupled from a host import, so unit tests need no pi runtime. The predecessor's
+ * `*Like` suffix meant "structural declaration of the host shape"; that meaning lives in these docs.
+ */
+
+/** The host theme slice paint reads. Structural host shape: any object with these two members qualifies. */
+export interface HostTheme {
+	/** Maps a theme token and text to escape-wrapped text, e.g. fg("accent", "ok"). Required. */
+	fg(key: string, text: string): string;
+	/** Wraps text in the theme's bold escape sequence. Required. */
+	bold(text: string): string;
+}
+
+/** Live markdown-theme closures the content painter wraps. Structural host shape — no host import. */
+export interface MarkdownTheme {
+	/** Horizontal-rule escape wrapper. Optional: a host without this token degrades to plain text. */
+	hr?(text: string): string;
+	/** Blockquote body wrapper. Optional. */
+	quote?(text: string): string;
+	/** Blockquote left-border wrapper. Optional. */
+	quoteBorder?(text: string): string;
+	/** Inline-code wrapper. Optional. */
+	code?(text: string): string;
+	/** Fenced-code-block border wrapper. Optional. */
+	codeBlockBorder?(text: string): string;
+}
+
+/** The pi-tui component slice renderers return and receive. Structural host shape — no host import. */
+export interface UiComponent {
+	/** Draws the current frame as lines; `width` is the terminal width in columns. Required. */
+	render(width: number): string[];
+	/** Marks the cached frame stale so the next render() redraws. Required. */
+	invalidate(): void;
+	/** Replaces the component's text. Optional: base components the runtime delegates to do not have it. */
+	setText?(v: string): void;
+}
+
+/** The text-component slice the runtime reads back. Structural host shape — no host import. */
+export interface TextComponent {
+	/** Replaces the displayed text. Required. */
+	setText(v: string): void;
+	/** Reads the displayed text back. Optional: the host's own component may not expose it. */
+	getText?(): string;
+}
+
+/** What renderCall / renderResult receive. Structural host shape — no host import; a plain object is accepted. */
+export interface RenderContext {
+	/** ONE state bag per row, shared across that row's invocations; the parse-once memo lives here. Required. */
+	state: Record<string, unknown>;
+	/** Tool arguments as the host passes them; unreadable until argsComplete is true. Optional. */
+	args?: Record<string, unknown>;
+	/** Stable id of the tool call this row draws, used as the logOnce key. Optional. */
+	toolCallId?: string;
+	/** Asks the host to redraw this row, e.g. after an async decorate() resolved. Optional. */
+	invalidate?: () => void;
+	/** The component returned on the previous invocation of the same row. Optional. */
+	lastComponent?: UiComponent;
+	/** Working directory the tool ran in, when the host reports one. Optional. */
+	cwd?: string;
+	/** True once the host has delivered the full argument set — the gate for argument-dependent output. Optional. */
+	argsComplete?: boolean;
+	/** True while the row is drawn expanded (ctrl+o or click). Optional. */
+	expanded?: boolean;
+	/** True when the tool call failed; the row collapses to an error summary. Optional. */
+	isError?: boolean;
+	/** True while the result is still streaming; the row must stay cheap. Optional. */
+	isPartial?: boolean;
+}
+
+/** One result content block; only text blocks are rendered. Structural host shape. */
+export interface ToolResultContent {
+	/** Block kind as the host labels it, e.g. "text" or "image". Required. */
+	type: string;
+	/** The block's text; absent for non-text blocks. Optional. */
+	text?: string;
+}
+
+/** The result slice renderers read. Structural host shape — the shape is narrowed, never assumed. */
+export interface ToolResult {
+	/** Result blocks in host order. Optional: a result may carry details only. */
+	content?: ToolResultContent[];
+	/** Host-supplied structured payload; opaque here and never rendered directly. Optional. */
+	details?: unknown;
+	/** True when the tool call failed. Optional. */
+	isError?: boolean;
+}
+
+/** Renderer options exactly as the host passes them — one bag per render call, no defaults invented. */
+export interface RenderResultOptions {
+	/** True while the row is drawn expanded. Required. */
+	expanded: boolean;
+	/** True while the result is still streaming. Required. */
+	isPartial: boolean;
+}
+
+/** The renderer triple the resolver returns or delegates to; renderShell stays host-owned. */
+export interface ToolRenderers {
+	/** Asks the host for its own shell frame instead of drawing one. Optional: exactly "default" or "self". */
+	renderShell?: "default" | "self";
+	/** Draws the call line. Optional: omitting it delegates this row to the next resolver. */
+	renderCall?(args: Record<string, unknown>, theme: HostTheme, ctx: RenderContext): UiComponent;
+	/** Draws the result. Optional: omitting it delegates this row to the next resolver. */
+	renderResult?(result: ToolResult, options: RenderResultOptions, theme: HostTheme, ctx: RenderContext): UiComponent;
+}
+
+/** The host resolver chain signature. Structural host shape — the host calls it, pi-render returns it. */
+export type ToolRendererResolver = (
+	/** Name of the tool being rendered, exactly as the host spells it, e.g. "bash". Required. */
+	toolName: string,
+	/** Returns what the remaining chain would draw, or undefined when the chain is exhausted. Required. */
+	next: () => ToolRenderers | undefined,
+) => ToolRenderers | undefined;
+
+/** The host markdown-transform context slice surfaces read. Structural host shape — no host import. */
+export interface TransformContext {
+	/** Which transcript stream the text belongs to. Required: "user" | "assistant" | "assistant-thinking". */
+	messageType: "user" | "assistant" | "assistant-thinking";
+	/** True while the message is still streaming in; a streaming message is not rewritten. Required. */
+	isStreaming: boolean;
+	/** Columns available to the message, in the host's character-cell units. Required; > 0. */
+	availableWidth: number;
+}
+
+/** The command-handler context slice /canvas reads. Structural host shape — no host import. */
+export interface CommandContext {
+	/** Host output mode. Required: "tui" | "rpc" | "json" | "print". */
+	mode: "tui" | "rpc" | "json" | "print";
+	/** Host notification seam for user-facing feedback. Required. */
+	ui: {
+		/** Shows one message to the user, e.g. notify("Canvas closed"). Required. */
+		notify(message: string): void;
+	};
+}
+
+/**
+ * The host surface the extension registers through. Structural host shape: the host arrives as the
+ * composition root's parameter, never as a module import, so this file stays pi-free.
+ */
+export interface ExtensionApi {
+	/** Adds one resolver to the tool-render chain. Required; called exactly once, in index.ts. */
+	registerToolRenderer(resolver: ToolRendererResolver): void;
+	/** Adds one markdown rewrite stage. Required; called exactly once, in index.ts. */
+	registerMarkdownTransformer(transformer: (markdown: string, ctx: TransformContext) => string): void;
+	/** Registers one slash command, e.g. name "canvas". Required; one call per command. */
+	registerCommand(
+		name: string,
+		options: { description?: string; handler: (args: string, ctx: CommandContext) => Promise<void> },
+	): void;
+	/** Subscribes to a host event, e.g. "session_start". Required; the per-event ctx carries ui. */
+	on(event: string, handler: (event: unknown, ctx: EventContext) => void): void;
+}
+
+/** The context a host event handler receives. Structural host shape. */
+export interface EventContext {
+	/** The host's UI surface for this event — present in interactive mode, a no-op stub otherwise. Optional. */
+	ui?: {
+		/** Collapses (false) / expands (true) every tool row. The collapse-first default rides this. Optional. */
+		setToolsExpanded?(expanded: boolean): void;
+	};
+}

package/src/core/types/log.ts

@@ -0,0 +1,28 @@
+/**
+ * log.ts — the diagnostics contract core/log (T-06) implements.
+ *
+ * Boundary: renderers call these from a render path, so the contract forbids throwing and forbids
+ * writing to stdout/stderr — pi owns both for the TUI.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** One captured diagnostic entry: the memory record a test or the /render panel reads back. */
+export interface LogEntry {
+	/** Emitting module scope, e.g. "tool.bash". Required. */
+	scope: string;
+	/** One-line diagnostic text, never multi-line. Required. */
+	message: string;
+	/** Capture time in epoch milliseconds (Date.now()). Required. */
+	time: number;
+}
+
+/** Keyed in-memory diagnostics. Structural core shape: any object with these three methods qualifies. */
+export interface Logger {
+	/** Appends one entry. Required; repeats freely, so keep it off per-frame paths. */
+	logLine(scope: string, message: string): void;
+	/** Appends at most one entry per key, e.g. key "tool:call-42". Required — the per-frame default. */
+	logOnce(key: string, scope: string, message: string): void;
+	/** Returns every captured entry and empties the buffer. Required; tests and the panel consume this. */
+	drain(): LogEntry[];
+}

package/src/core/types/paint.ts

@@ -0,0 +1,54 @@
+/**
+ * paint.ts — the painting contract: the two role sets every renderer draws through.
+ *
+ * Boundary: region 1 is the tool row, region 2 is markdown content. Renderers call role methods
+ * and never emit an escape sequence themselves (AGENTS: escapes originate in core/paint.ts).
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+import type { HostTheme } from "./host.ts";
+
+/** Region 1 — the tool-row roles. Text in, theme-derived escape-wrapped text out. */
+export interface RowPaint {
+	/** The tool name or call title, e.g. title("bash"). Required. */
+	title(text: string): string;
+	/** Tool output / result text. Required. */
+	output(text: string): string;
+	/** De-emphasized metadata such as durations and counts. Required. */
+	muted(text: string): string;
+	/** Accent for the active or highlighted element. Required. */
+	accent(text: string): string;
+	/** Error text on a failed call. Required. */
+	error(text: string): string;
+	/** Warning text for a degraded or partial result. Required. */
+	warning(text: string): string;
+	/** The row's left gutter marker. Required. */
+	gutter(text: string): string;
+	/** A matched substring highlighted inside a result line. Required. */
+	match(text: string): string;
+	/** Diff line added (+), from the host toolDiffAdded token. Required. */
+	diffAdded(text: string): string;
+	/** Diff line removed (−), from the host toolDiffRemoved token. Required. */
+	diffRemoved(text: string): string;
+	/** Diff context line, from the host toolDiffContext token. Required. */
+	diffContext(text: string): string;
+}
+
+/** Region 1 factory: the theme arrives per render call and is read live, so a theme switch repaints. */
+export type RowPaintFactory = (
+	/** The host theme as delivered on this render call. Required. */
+	theme: HostTheme,
+) => RowPaint;
+
+/** Region 2 — the markdown-content roles. */
+export interface ContentPaint {
+	/** Horizontal rule; falls back hr → quoteBorder → plain rather than throw. Required. */
+	rule(text: string): string;
+	/** Blockquote body. Required. */
+	quote(text: string): string;
+	/** Inline code. Required. */
+	code(text: string): string;
+	/** Fenced-code-block border. Required. */
+	codeBlockBorder(text: string): string;
+}

package/src/core/types/registry.ts

@@ -0,0 +1,44 @@
+/**
+ * registry.ts — the module-registry contract core/registry (T-09) implements.
+ *
+ * Boundary: index.ts is the only registration site; renderers read the registry per invocation and
+ * never write it.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** One declared setting: the /render panel renders an editor from this spec. */
+export interface SettingSpec {
+	/** Setting name inside the module's slice, e.g. "collapseAt". Required; unique per module. */
+	name: string;
+	/** Editor kind. Required: "enum" | "toggle" | "number". */
+	kind: "enum" | "toggle" | "number";
+	/** Allowed values — required when kind is "enum", ignored otherwise. Optional. */
+	values?: string[];
+	/** Value used when the document omits the key. Required; must read as `unknown` before use. */
+	default: unknown;
+}
+
+/** One pluggable module's registration. Duplicate keys keep the first and log once. */
+export interface ModuleDescriptor {
+	/** Registry key, unique module id, e.g. "row.bash". Required. */
+	key: string;
+	/** Human-readable name shown in the /render panel, e.g. "Bash row". Required. */
+	name: string;
+	/** Initial enabled state before any settings write. Required. */
+	defaultEnabled: boolean;
+	/** Settings this module exposes. Required; use [] when it exposes none. */
+	settings: SettingSpec[];
+}
+
+/** Consumers poll per invocation; a settings write lands on the next read and pushes no redraw. */
+export interface Registry {
+	/** Declares one module. Required; a repeat key keeps the first definition. */
+	defineModule(d: ModuleDescriptor): void;
+	/** Reads a module's enabled flag by key, e.g. "row.bash". Required; an unknown key reads false. */
+	isEnabled(key: string): boolean;
+	/** Reads a module's effective settings (defaults merged with stored values). Required; unknown key = {}. */
+	getSettings(key: string): Record<string, unknown>;
+	/** Merges a patch into a module's stored settings. Required; takes effect on the next read, not now. */
+	setSettings(key: string, patch: object): void;
+}

package/src/core/types/settings.ts

@@ -0,0 +1,31 @@
+/**
+ * settings.ts — the persisted-settings contract core/settings (T-07) implements.
+ *
+ * Boundary: only the store touches the disk; a render path reads the cached document it returns.
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+/** One module's persisted slice, e.g. { enabled: false, settings: { collapseAt: 3 } }. */
+export interface ModuleSettings {
+	/** Whether the module's row/surface is active. Required; a missing module key reads as enabled. */
+	enabled: boolean;
+	/** The module's own key/value bag, validated by the module that owns it. Optional; default {}. */
+	settings?: Record<string, unknown>;
+}
+
+/** The persisted document: one file for every module. A malformed value is replaced by all defaults. */
+export interface SettingsDoc {
+	/** Document schema revision, currently 1 — bumped by a migration, never by a module. Required. */
+	version: number;
+	/** Module slices keyed by registry key, e.g. "row.bash". Required; absent key = that module's defaults. */
+	modules: Record<string, ModuleSettings>;
+}
+
+/** Cached load plus atomic save. A render path never touches the disk after the first load. */
+export interface SettingsStore {
+	/** Returns the cached document, reading the file only on first call. Required. */
+	load(): SettingsDoc;
+	/** Writes the document atomically (temp file + rename). Required; a failure degrades to in-memory. */
+	save(doc: SettingsDoc): void;
+}

package/src/core/types.ts

@@ -0,0 +1,34 @@
+/**
+ * types.ts — the seam catalog barrel: every cross-lane contract, in one import path.
+ *
+ * Boundary: cross-lane contracts are declared per scope under `src/core/types/` and per lane under
+ * `src/renderers/{tool,content}/types.ts`; this file re-exports them so `core/types.ts` stays the
+ * stable import path every module and ticket names. Add a type to its scope file, never here.
+ * AC-2 scope: "a later ticket finds a missing interface" means a missing cross-lane interface in
+ * one of those files, never any interface a ticket happens to mention.
+ *
+ * shape: none — re-export barrel (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+export type { Surface, SurfaceKey } from "../renderers/content/types.ts";
+export type { CallModel, RowSpec, RowView } from "../renderers/tool/types.ts";
+export type { CodeTheme, HighlightEngine } from "./types/code-theme.ts";
+export type {
+	CommandContext,
+	ExtensionApi,
+	HostTheme,
+	MarkdownTheme,
+	RenderContext,
+	RenderResultOptions,
+	TextComponent,
+	ToolRendererResolver,
+	ToolRenderers,
+	ToolResult,
+	ToolResultContent,
+	TransformContext,
+	UiComponent,
+} from "./types/host.ts";
+export type { LogEntry, Logger } from "./types/log.ts";
+export type { ContentPaint, RowPaint, RowPaintFactory } from "./types/paint.ts";
+export type { ModuleDescriptor, Registry, SettingSpec } from "./types/registry.ts";
+export type { ModuleSettings, SettingsDoc, SettingsStore } from "./types/settings.ts";

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