@zenodinh/pi-render 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,252 @@
+// ported from pi-pretty-tui/src/features/canvas/images.ts:24-33 (resolve, read, every miss
+// `undefined`), card.ts:46-101 (the boxed path card) and transformer.ts:106-108 (isLocalRef) —
+// survives because: "a local reference becomes a card and any miss leaves the model's own text in
+// place" is the rule all three carried. The registration-era halves do not port: no pixels, no base64,
+// no canvaskit conversion, no artifact URL and no Open link — pi-render draws no pixels and owns no
+// server (T-26).
+
+/**
+ * image-card.ts — the surface that turns a local image reference into a card: path and dimensions,
+ * never pixels.
+ *
+ * Boundary: untrusted markdown in, and the only fallible step is the local header read — a missing,
+ * unreadable, or non-image target leaves the reference byte-identical and never throws, so a broken
+ * image reference can never take an answer down.
+ *
+ * shape: closure returning an object literal — trigger #4, the probe and the log sink are captured per
+ * surface instance; no subclassing and no instanceof.
+ */
+
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { basename, extname, isAbsolute, resolve } from "node:path";
+import type { TransformContext } from "../../core/types/host.ts";
+import type { ContentPaint } from "../../core/types/paint.ts";
+import type { Surface } from "./types.ts";
+
+/** Dimensions read from a local image header; a format we do not walk yields neither field. */
+export interface ImageFacts {
+	/** Pixel width. Absent when the header read did not produce it. */
+	width?: number;
+	/** Pixel height. Absent when the header read did not produce it. */
+	height?: number;
+}
+
+/**
+ * The local-probe seam: one absolute path in, `undefined` when no image is readable there — the
+ * reference then stays raw — otherwise the facts, where an empty object still cards (a real image
+ * whose dimensions this probe did not read).
+ */
+export type ImageProbe = (absPath: string) => ImageFacts | undefined;
+
+export interface ImageCardDeps {
+	/** Base for relative references; the transform context carries no cwd. Defaults to process.cwd(). */
+	projectDir?: string;
+	/** Dimension reader. Defaults to one bounded header read of the file itself. */
+	probe?: ImageProbe;
+	/** Diagnostics, at most one call per miss; the composition root injects the shared logger. */
+	log?: (line: string) => void;
+}
+
+/** Cards read best narrow — they do not sprawl across the transcript (the predecessor's 64). */
+const CARD_MAX_WIDTH = 64;
+/** Below this a path cannot be shown at all, so the card wins over the offered width. */
+const CARD_MIN_WIDTH = 24;
+/** One bounded read: JPEG's frame marker can sit behind up to 64 KiB of EXIF. */
+const HEAD_BYTES = 64 * 1024;
+
+/** A malformed header can hold nonsense; only two positive integers become card dimensions. */
+function dims(width: number, height: number): ImageFacts | undefined {
+	if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) return undefined;
+	return { width, height };
+}
+
+/** PNG: the IHDR chunk is first by spec, so both dimensions sit at fixed offsets. */
+function pngFacts(head: Buffer): ImageFacts | undefined {
+	if (head.length < 24 || head.toString("latin1", 12, 16) !== "IHDR") return undefined;
+	return dims(head.readUInt32BE(16), head.readUInt32BE(20));
+}
+
+/** GIF: the logical screen descriptor follows the 6-byte signature. */
+function gifFacts(head: Buffer): ImageFacts | undefined {
+	if (head.length < 10) return undefined;
+	return dims(head.readUInt16LE(6), head.readUInt16LE(8));
+}
+
+/** JPEG: no fixed offset — walk the segment chain to the first SOFn, which carries the frame size. */
+function jpegFacts(head: Buffer): ImageFacts | undefined {
+	let at = 2;
+	while (at + 9 <= head.length) {
+		if (head[at] !== 0xff) return undefined;
+		const marker = head[at + 1] ?? 0;
+		// SOF0-3, SOF5-7, SOF9-11 carry the frame size; 0xc4/0xc8/0xcc are DHT/JPG/DAC.
+		if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+			return dims(head.readUInt16BE(at + 7), head.readUInt16BE(at + 5));
+		}
+		// RST/SOI/EOI/TEM carry no length field, so the walk steps over them instead of misreading one.
+		if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+			at += 2;
+			continue;
+		}
+		const length = head.readUInt16BE(at + 2);
+		if (length < 2) return undefined;
+		at += 2 + length;
+	}
+	return undefined;
+}
+
+/** shape: dispatch object — trigger #1, three signature-keyed readers, each one stateless header read. */
+const HEADERS: ReadonlyArray<readonly [string, (head: Buffer) => ImageFacts | undefined]> = [
+	["\u0089PNG", pngFacts],
+	["GIF8", gifFacts],
+	["\u00ff\u00d8\u00ff", jpegFacts],
+];
+
+/** The image signatures this module knows. `undefined` = not an image, so the reference stays raw. */
+function parseFacts(head: Buffer): ImageFacts | undefined {
+	for (const [magic, read] of HEADERS) {
+		if (head.toString("latin1", 0, magic.length) === magic) return read(head) ?? {};
+	}
+	// WebP is a RIFF container whose dimensions live in a bit-packed chunk this module does not walk;
+	// recognising it keeps the card (path alone) instead of dropping a real image reference.
+	if (head.toString("latin1", 0, 4) === "RIFF" && head.toString("latin1", 8, 12) === "WEBP") return {};
+	return undefined;
+}
+
+/** The open descriptor, or `undefined` when there is no readable file at the path. */
+function openImage(absPath: string): number | undefined {
+	try {
+		if (!statSync(absPath).isFile()) return undefined;
+		return openSync(absPath, "r");
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * The default probe: one stat plus one bounded header read — the pixels are never read, and a miss
+ * resolves to `undefined` so it can never become an exception in the render path.
+ */
+function readFacts(absPath: string): ImageFacts | undefined {
+	const fd = openImage(absPath);
+	if (fd === undefined) return undefined;
+	try {
+		const head = Buffer.allocUnsafe(HEAD_BYTES);
+		const read = readSync(fd, head, 0, HEAD_BYTES, 0);
+		return parseFacts(head.subarray(0, read));
+	} catch {
+		// The file is there but its header is not readable; a card with the path alone still helps.
+		return {};
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/** A scheme, a protocol-relative URL, or an anchor is not a local path — a data: URI is a scheme. */
+function isLocalReference(href: string): boolean {
+	return !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith("//") && !href.startsWith("#");
+}
+
+/** A row wider than the box wraps onto the next row; truncation is what made the path useless. */
+function chunk(text: string, width: number): string[] {
+	const rows: string[] = [];
+	for (let at = 0; at < text.length; at += width) rows.push(text.slice(at, at + width));
+	return rows;
+}
+
+/** The box hugs the offered width but never more than a card reads well at. */
+function cardWidth(availableWidth: number): number {
+	return Math.max(CARD_MIN_WIDTH, Math.min(availableWidth, CARD_MAX_WIDTH));
+}
+
+/** shape: none — one box; every row is a constant plus a value whose width is known before painting. */
+function renderImageCard(absPath: string, facts: ImageFacts, paint: ContentPaint, width: number): string {
+	const inner = width - 2;
+	const content = Math.max(1, inner - 2);
+	const extension = extname(absPath).slice(1).toLowerCase();
+	const label = extension === "" ? "image" : extension;
+	const header = `─ ${label} `;
+	const name = basename(absPath);
+	const size = facts.width === undefined || facts.height === undefined ? "" : `${facts.width}×${facts.height}`;
+	const title = size === "" ? name : `${name} · ${size}`;
+	const rows = [...chunk(title, content), ...chunk(absPath, content)];
+	const lines = [
+		paint.rule(`╭${header}${"─".repeat(Math.max(0, inner - header.length))}╮`),
+		...rows.map((row) => `${paint.rule("│")} ${paint.quote(row.padEnd(content))} ${paint.rule("│")}`),
+		paint.rule(`╰${"─".repeat(inner)}╯`),
+	];
+	// Hard breaks keep each box row on its own line when the reference sat inside a paragraph.
+	return `${lines.join("  \n")}\n`;
+}
+
+/** A fenced block is code: the host's own markdown parser sees no image token inside it either. */
+const FENCE = /^\s*(`{3,}|~{3,})/;
+/** CommonMark image syntax; a destination holding a space or a parenthesis is left alone, not mangled. */
+const IMAGE_REF = /!\[[^\]]*\]\(([^()\s]+)(?:\s+"[^"]*")?\)/g;
+
+/** shape: none — one line pass with a fence flag; there is no discriminator to dispatch on. */
+function rewriteOutsideFences(markdown: string, rewriteLine: (line: string) => string): string {
+	const lines = markdown.split("\n");
+	let open: string | undefined;
+	let changed = false;
+	for (let at = 0; at < lines.length; at += 1) {
+		const line = lines[at];
+		if (line === undefined) continue;
+		const fence = FENCE.exec(line)?.[1];
+		if (open !== undefined) {
+			// A closing fence is at least as long as the run that opened the block.
+			if (fence?.startsWith(open)) open = undefined;
+			continue;
+		}
+		if (fence !== undefined) {
+			open = fence;
+			continue;
+		}
+		const rewritten = rewriteLine(line);
+		if (rewritten !== line) {
+			lines[at] = rewritten;
+			changed = true;
+		}
+	}
+	return changed ? lines.join("\n") : markdown;
+}
+
+/**
+ * shape: closure returning an object literal — trigger #4, the probe, the log sink and the base
+ * directory are captured once and the module holds no other state.
+ */
+export function createImageCardSurface(deps: ImageCardDeps = {}): Surface {
+	const probe = deps.probe ?? readFacts;
+	const log = deps.log ?? ((): void => {});
+	const projectDir = deps.projectDir ?? process.cwd();
+
+	/** The card for one reference, or `undefined` when the reference must stay exactly as written. */
+	const cardFor = (href: string, paint: ContentPaint, availableWidth: number): string | undefined => {
+		if (!isLocalReference(href)) return undefined;
+		const absPath = isAbsolute(href) ? href : resolve(projectDir, href);
+		let facts: ImageFacts | undefined;
+		try {
+			facts = probe(absPath);
+		} catch (error) {
+			// The probe is caller-supplied and this path never throws: one line, and the reference stays.
+			log(`image ${href}: ${error instanceof Error ? error.message : String(error)}`);
+			return undefined;
+		}
+		if (facts === undefined) {
+			log(`image ${href}: no image readable at ${absPath}`);
+			return undefined;
+		}
+		return renderImageCard(absPath, facts, paint, cardWidth(availableWidth));
+	};
+
+	return {
+		rewrite(markdown: string, ctx: TransformContext, paint: ContentPaint): string {
+			const rewriteLine = (line: string): string =>
+				line.replace(IMAGE_REF, (reference: string, href: unknown) => {
+					// The captured group is host markdown text: narrowed, never assumed.
+					if (typeof href !== "string") return reference;
+					return cardFor(href, paint, ctx.availableWidth) ?? reference;
+				});
+			return rewriteOutsideFences(markdown, rewriteLine);
+		},
+	};
+}

package/src/renderers/content/index.ts

@@ -0,0 +1,79 @@
+/**
+ * index.ts — the markdown transformer: final-assistant gate, per-surface registry check, dispatch,
+ * identity return.
+ *
+ * Boundary: the host calls this on the transcript render path, so nothing here throws and nothing
+ * allocates per message. A disabled surface is skipped, and the input string returns by reference
+ * whenever no surface changed it — the host's own caching reads that reference.
+ *
+ * shape: closure returning a function — trigger #4, the factory captures its injected collaborators
+ * (registry, surfaces, paint, log) and holds no state to classify.
+ *
+ * ported from pi-pretty-tui/src/features/canvas/transformer.ts — survives because: the final-assistant
+ * gate, the degrade-to-the-input-verbatim fallback, and mermaid staying with the host's own transformer
+ * are the host-aligned behaviors that file got right. Its parser, settings load, and per-form render
+ * code do not port: each surface owns one rewrite here, and the registry owns every toggle.
+ */
+
+import type { TransformContext } from "../../core/types/host.ts";
+import type { Logger } from "../../core/types/log.ts";
+import type { ContentPaint } from "../../core/types/paint.ts";
+import type { Registry } from "../../core/types/registry.ts";
+import type { Surface, SurfaceKey } from "./types.ts";
+
+/** Registry key of the artifacts fence pass — T-28 injects its surface when artifacts land (T-25/T-26). */
+const ARTIFACTS_KEY = "artifacts";
+
+/** Dispatch order: the four markdown surfaces, then the fence pass over their output. */
+const SURFACE_ORDER: readonly SurfaceKey[] = ["table", "codePanel", "jsonPanel", "imageCard"];
+
+const SCOPE = "content";
+const LOG_KEY = "content:transform";
+
+/** The surface table T-28 composes: one entry per SurfaceKey, plus the optional fence pass. */
+export type ContentSurfaces = Record<SurfaceKey, Surface> & {
+	/** Artifact fences (plantuml/dot/svg/html). Absent until T-28 wires it; the slot is dispatched last. */
+	artifacts?: Surface;
+};
+
+/** The transformer's injected collaborators — the region-2 paint roles, plus the keyed logger. */
+export interface ContentTransformerDeps {
+	/** Live content paint; surfaces receive it per invocation. Required. */
+	paint: ContentPaint;
+	/** Keyed diagnostics; the never-throw path logs exactly one line. Required. */
+	log: Logger;
+}
+
+// shape: closure returning a function — trigger #4, collaborators captured once, the per-message body
+// mutates no captured state.
+export function createContentTransformer(
+	registry: Registry,
+	surfaces: ContentSurfaces,
+	deps: ContentTransformerDeps,
+): (markdown: string, ctx: TransformContext) => string {
+	const { paint, log } = deps;
+	const artifacts = surfaces.artifacts;
+
+	/** One dispatch step: an absent or disabled slot is skipped, otherwise it rewrites the current text. */
+	const run = (key: string, surface: Surface | undefined, input: string, ctx: TransformContext): string => {
+		if (surface === undefined || !registry.isEnabled(key)) return input;
+		const next = surface.rewrite(input, ctx, paint);
+		// A surface signals "nothing matched" by returning its input; comparing by value also discards an
+		// equal copy, so a no-op pass keeps the reference the host handed us.
+		return next === input ? input : next;
+	};
+
+	return (markdown, ctx) => {
+		// The predecessor's gate, unchanged: only a settled assistant message is rewritten.
+		if (ctx.messageType !== "assistant" || ctx.isStreaming) return markdown;
+		try {
+			let out = markdown;
+			for (const key of SURFACE_ORDER) out = run(`content.${key}`, surfaces[key], out, ctx);
+			return run(`content.${ARTIFACTS_KEY}`, artifacts, out, ctx);
+		} catch (error) {
+			// One failing surface must not cost the answer: the original input returns untouched.
+			log.logOnce(LOG_KEY, SCOPE, `transform failed: ${error instanceof Error ? error.message : String(error)}`);
+			return markdown;
+		}
+	};
+}

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

@@ -0,0 +1,116 @@
+// ported from pi-pretty-tui/src/features/canvas/transformer.ts:262-307 (standaloneFileCard, JSON branch)
+// + json-panel.test.ts — survives because: a local JSON file the message links to is the one content
+// kind whose value is its colored lines, so it renders as a pane (40-line cap plus a way out) rather
+// than as a card; only the color source changed (paint roles plus the injected CodeTheme).
+
+/**
+ * json-panel.ts — a ```json fence or a standalone link to a local `.json`/`.jsonc`/`.jsonl` file renders
+ * through the same panel frame as a code fence, with `json` as the language.
+ *
+ * Boundary: the linked file's bytes cross a trust boundary, so they are read through an injected reader
+ * (the composition root supplies the real one; a test injects a fake) and, when unreadable, the raw link
+ * is kept and one keyed line is logged. Nothing here throws.
+ *
+ * shape: none — a factory over injected collaborators; the factory declares its own shape below.
+ */
+
+import type { CodeTheme, ContentPaint, Logger } from "../../core/types.ts";
+import { mapFencedBlocks, panelWidth, renderPanel, toMarkdownRows } from "./code-panel.ts";
+import type { Surface } from "./types.ts";
+
+/** JSON's content is what the reader wants up to here; past it the file stays one click away (P transformer.ts:265). */
+const MAX_PANE_LINES = 40;
+/** A fence spelling that still highlights as JSON (P transformer.ts:264). */
+const JSON_LANGS = new Set(["json", "jsonc", "jsonl"]);
+/** A paragraph that is nothing but a link, captured as its href (P transformer.ts:270-275). */
+const LINK_ONLY = /^\[[^\]]*\]\(([^)\s]+)\)$/;
+const JSON_EXTENSION = /\.(jsonc?|jsonl)$/i;
+
+/** The collaborators the pane reads through: the file reader and the optional diagnostics sink. */
+export interface JsonPanelDeps {
+	/** Reads the linked file; returns undefined when it cannot be read (missing, unreadable, a directory). */
+	read(href: string): string | undefined;
+	/** Once-per-key diagnostics for an unreadable link. Optional; absent is silent. */
+	log?: Pick<Logger, "logOnce">;
+}
+
+/** A scheme-bearing, protocol-relative or fragment href is not a local file (P transformer.ts:110-112). */
+// shape: none — one classification, no branch on a discriminator.
+function isLocalRef(href: string): boolean {
+	return !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith("//") && !href.startsWith("#");
+}
+
+/** The pane markdown for one readable JSON file, or undefined when the reader could not produce content. */
+// shape: none — one guarded call plus a footer choice; no discriminator.
+function jsonFilePane(
+	href: string,
+	width: number,
+	paint: ContentPaint,
+	codeTheme: CodeTheme,
+	deps: JsonPanelDeps,
+): string | undefined {
+	const content = deps.read(href);
+	if (content === undefined) {
+		deps.log?.logOnce(`read:${href}`, "json-panel", `could not read ${href} — leaving the link as-is`);
+		return undefined;
+	}
+	const all = content.replace(/\n+$/, "").split("\n");
+	const shown = all.slice(0, MAX_PANE_LINES);
+	const panel = toMarkdownRows(renderPanel(shown.join("\n"), "json", width, paint, codeTheme));
+	const hidden = all.length - shown.length;
+	// The link text is the href as given: this pane knows no artifact server (T-26 owns it), so the
+	// target stays a plain path the terminal can open.
+	const footer = hidden > 0 ? `${paint.quote(`… +${hidden} more lines`)} · [Open](${href})` : paint.quote(href);
+	return `${panel}\n\n${footer}`;
+}
+
+/**
+ * Rewrites standalone local-JSON links into panes; a link that is not exactly a standalone JSON
+ * reference keeps its raw line, and `changed` tracks whether anything matched.
+ *
+ * shape: none — one line walk with a single callback seam, no dispatch on a value.
+ */
+function mapJsonFileLinks(
+	markdown: string,
+	width: number,
+	paint: ContentPaint,
+	codeTheme: CodeTheme,
+	deps: JsonPanelDeps,
+): { 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 line = lines[i] ?? "";
+		const href = LINK_ONLY.exec(line.trim())?.[1];
+		const alone =
+			line.trim() !== "" &&
+			(i === 0 || (lines[i - 1] ?? "").trim() === "") &&
+			(i === lines.length - 1 || (lines[i + 1] ?? "").trim() === "");
+		const pane =
+			href !== undefined && alone && isLocalRef(href) && JSON_EXTENSION.test(href.replace(/[?#].*$/, ""))
+				? jsonFilePane(href, width, paint, codeTheme, deps)
+				: undefined;
+		if (pane === undefined) {
+			out.push(line);
+			continue;
+		}
+		out.push(pane);
+		changed = true;
+	}
+	return { text: out.join("\n"), changed };
+}
+
+// shape: closure returning an object literal — trigger #4, one stateless Surface over the captured theme and reader.
+export function createJsonPanel(codeTheme: CodeTheme, deps: JsonPanelDeps): Surface {
+	return {
+		rewrite(markdown, ctx, paint) {
+			const width = panelWidth(ctx.availableWidth);
+			const fences = mapFencedBlocks(markdown, (lang, code) =>
+				JSON_LANGS.has(lang) ? toMarkdownRows(renderPanel(code, "json", width, paint, codeTheme)) : undefined,
+			);
+			const links = mapJsonFileLinks(fences.text, width, paint, codeTheme, deps);
+			return fences.changed || links.changed ? links.text : markdown;
+		},
+	};
+}

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

@@ -0,0 +1,188 @@
+/**
+ * panels.test.ts — the spec of the two content Surfaces at their seam: fenced markdown in, panel
+ * markdown out. Every test drives `createCodePanel(...).rewrite` / `createJsonPanel(...).rewrite` with a
+ * plain transform context; no module internals are imported.
+ *
+ * Fixtures: the code theme is `createCodeTheme` over a deterministic engine double that stamps its bound
+ * theme into each line, so a panel names the theme it was colored for. Panels are driven with the marker
+ * paint double, so a frame escape that is not the codeBlockBorder role is visible in the golden.
+ */
+
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { describe, expect, it } from "vitest";
+import { markerPaint } from "../../../test/fakes/index.ts";
+import { type BindHighlightEngine, type CodeThemeName, createCodeTheme } from "../../core/code-theme.ts";
+import type { CodeTheme, TransformContext } from "../../core/types.ts";
+import { createCodePanel } from "./code-panel.ts";
+import { createJsonPanel, type JsonPanelDeps } from "./json-panel.ts";
+
+const ESC = String.fromCharCode(27);
+/** The codeBlockBorder role's marker pair (test/fakes/paint.ts), the only frame escape a panel may emit. */
+const border = (text: string): string => `${ESC}[38;5;211m${text}${ESC}[38;5;231m`;
+/** The quote role's marker pair, used for the JSON pane's footer. */
+const quote = (text: string): string => `${ESC}[38;5;209m${text}${ESC}[38;5;229m`;
+/** One highlighted body line as the engine double emits it. */
+const ink = (rgb: string, text: string): string => `${ESC}[38;2;${rgb}m${text}${ESC}[0m`;
+/** Panel rows embedded as markdown: one code span per row, joined by the hard break the host honors. */
+const rows = (lines: string[]): string => lines.map((line) => `\`${line}\``).join("  \n");
+
+// invented: the engine is faked, so the golden pins OUR frame and highlight wiring, not shiki's palette.
+// Colours sit above the low-contrast floor (72) so code-theme's normalization leaves them alone.
+const INK: Record<CodeThemeName, string> = { "dracula-soft": "200;100;50", "one-dark-pro": "50;200;100" };
+const THEMES = Object.entries(INK) as Array<[CodeThemeName, string]>;
+
+/** Theme double: an engine that stamps the bound theme's ink into each line. */
+function themeNamed(name: CodeThemeName): CodeTheme {
+	const engine: BindHighlightEngine = (theme) => (code) => code.split("\n").map((line) => ink(INK[theme], line));
+	return createCodeTheme(engine, { registry: { getSettings: () => ({ codeTheme: name }) } });
+}
+
+/** Markdown transform context; only availableWidth is read (core/types/host.ts). */
+// invented: the two gate fields are the completed-assistant case, which is the only case a surface sees.
+const ctx = (availableWidth: number): TransformContext => ({
+	messageType: "assistant",
+	isStreaming: false,
+	availableWidth,
+});
+
+/** Reader double over a fixed file map (the injected seam T-28 wires to the filesystem). */
+function reader(files: Record<string, string>): JsonPanelDeps {
+	return { read: (href) => files[href] };
+}
+
+describe("code panel", () => {
+	it.each(THEMES)("AC-1: a fence renders as a bordered panel in %s's ink", (name, inkRgb) => {
+		const out = createCodePanel(themeNamed(name)).rewrite("```python\nx = 1\n```\n", ctx(80), markerPaint());
+
+		const expected = `${rows([
+			border("╭─ python ─────────────╮"),
+			`${border("│")} ${ink(inkRgb, "x = 1")}${" ".repeat(15)} ${border("│")}`,
+			border("╰──────────────────────╯"),
+		])}\n`;
+		// fails_when: the frame geometry, the language header, or the theme's ink drifts.
+		expect(out).toBe(expected);
+	});
+
+	it("AC-1: a bare fence and the mermaid/artifact fences keep their raw text", () => {
+		const panel = createCodePanel(themeNamed("dracula-soft"));
+		for (const raw of ["```\nx\n```\n", "```mermaid\ngraph TD;\n```\n", "```plantuml\nA -> B\n```\n"]) {
+			// fails_when: a host-owned or artifact-bound fence is consumed into a panel.
+			expect(panel.rewrite(raw, ctx(80), markerPaint())).toBe(raw);
+		}
+	});
+
+	it("AC-1: a fence hugging its content stays under the offered width", () => {
+		const out = createCodePanel(themeNamed("dracula-soft")).rewrite("```py\nx = 1\n```\n", ctx(80), markerPaint());
+		// fails_when: the panel spans the terminal instead of hugging its content.
+		expect(visibleWidth(out.split("\n")[0] ?? "")).toBeLessThan(30);
+	});
+
+	it("AC-2: a throwing highlightSync degrades to a plain panel, no throw", () => {
+		const throwing: CodeTheme = {
+			highlight: () => Promise.reject(new Error("boom")),
+			highlightSync: () => {
+				throw new Error("boom");
+			},
+		};
+		const panel = createCodePanel(throwing);
+		let out = "";
+		// fails_when: a highlighter failure kills the answer render.
+		expect(() => {
+			out = panel.rewrite("```ts\nlet x = 1;\n```\n", ctx(40), markerPaint());
+		}).not.toThrow();
+		expect(out).toContain("let x = 1;");
+		expect(out).not.toContain(`${ESC}[38;2;`); // no engine ink survived
+	});
+
+	it("AC-2: a throwing engine behind the real CodeTheme degrades the same way", () => {
+		const engine: BindHighlightEngine = () => () => {
+			throw new Error("boom");
+		};
+		const theme = createCodeTheme(engine, { registry: { getSettings: () => ({ codeTheme: "dracula-soft" }) } });
+		const out = createCodePanel(theme).rewrite("```ts\nlet x = 1;\n```\n", ctx(40), markerPaint());
+		// fails_when: code-theme's own degrade does not reach the panel.
+		expect(out).toContain("let x = 1;");
+		expect(out).not.toContain(`${ESC}[38;2;`);
+	});
+
+	it("AC-3: box columns align when truecolor escapes sit inside CJK content", () => {
+		const cjk = "// 撤销转退款场景，根据是否超过保价时间限制判断是否进行汇率决策";
+		const out = createCodePanel(themeNamed("dracula-soft")).rewrite(
+			`\`\`\`java\n${cjk}\npublic class X {}\n\`\`\`\n`,
+			ctx(110),
+			markerPaint(),
+		);
+		const widths = new Set(
+			out
+				.split("\n")
+				.filter((line) => line !== "")
+				.map((line) => visibleWidth(line.trimEnd())),
+		);
+		// fails_when: a wide character is measured as one column, so the closing │ no longer lines up.
+		expect(widths.size).toBe(1);
+	});
+});
+
+describe("json panel", () => {
+	// recorded-from: pi-pretty-tui/src/features/canvas/json-panel.test.ts (2026-10-06) — the same two-key body.
+	const DATA = '{\n  "name": "pi-pretty-tui",\n  "version": "0.1.0"\n}\n';
+
+	it.each(THEMES)("AC-1: a local .json link renders as a json pane in %s's ink", (name, inkRgb) => {
+		const panel = createJsonPanel(themeNamed(name), reader({ "/repo/data.json": DATA }));
+		const out = panel.rewrite("[data.json](/repo/data.json)\n", ctx(80), markerPaint());
+
+		const body = ["{", '  "name": "pi-pretty-tui",', '  "version": "0.1.0"', "}"];
+		const expected = `${rows([
+			border("╭─ json ─────────────────────╮"),
+			...body.map((line) => `${border("│")} ${ink(inkRgb, line)}${" ".repeat(26 - line.length)} ${border("│")}`),
+			border("╰────────────────────────────╯"),
+		])}\n\n${quote("/repo/data.json")}\n`;
+		// fails_when: the pane frame, the header, the footer, or the theme's ink drifts.
+		expect(out).toBe(expected);
+	});
+
+	it("AC-1: a ```json fence renders through the same panel", () => {
+		const panel = createJsonPanel(themeNamed("dracula-soft"), reader({}));
+		const out = panel.rewrite("```json\n{}\n```\n", ctx(40), markerPaint());
+		// fails_when: the JSON fence is left raw or rendered without the json header.
+		expect(out).toContain("╭─ json ");
+		expect(out).toContain(ink("200;100;50", "{}"));
+	});
+
+	it("caps a long file at 40 lines and leaves one way out", () => {
+		// invented: 60 numbered lines is one past the 40-line cap plus a countable remainder.
+		const sixty = Array.from({ length: 60 }, (_, index) => `line ${index}`).join("\n");
+		const panel = createJsonPanel(themeNamed("dracula-soft"), reader({ "/repo/big.json": sixty }));
+		const out = panel.rewrite("[big.json](/repo/big.json)\n", ctx(80), markerPaint());
+
+		// fails_when: the transcript swallows the whole file, or loses the way to the rest of it.
+		expect(out).toContain("╭─ json ");
+		expect(out).toContain("… +20 more lines");
+		expect(out).toContain("[Open](/repo/big.json)");
+		expect(out).not.toContain("line 40");
+	});
+
+	it("leaves a non-JSON or unreadable link as-is", () => {
+		const panel = createJsonPanel(themeNamed("dracula-soft"), reader({}));
+		const notes = "[notes.md](/repo/notes.md)\n";
+		const missing = "[gone.json](/repo/gone.json)\n";
+		// fails_when: a markdown link is pane-ized, or a missing file breaks the answer render.
+		expect(panel.rewrite(notes, ctx(80), markerPaint())).toBe(notes);
+		expect(panel.rewrite(missing, ctx(80), markerPaint())).toBe(missing);
+	});
+
+	it("logs once when the linked file cannot be read", () => {
+		const seen: string[] = [];
+		const panel = createJsonPanel(themeNamed("dracula-soft"), {
+			read: () => undefined,
+			log: {
+				logOnce: (key) => {
+					seen.push(key);
+				},
+			},
+		});
+		panel.rewrite("[gone.json](/repo/gone.json)\n", ctx(80), markerPaint());
+		// fails_when: an unreadable link is silent.
+		expect(seen).toEqual(["read:/repo/gone.json"]);
+	});
+});