@zenodinh/pi-render 0.0.0-stage → 0.1.2

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/table.ts

@@ -0,0 +1,174 @@
+// ported from pi-pretty-tui/src/features/canvas/table.ts — survives because: the banded layout,
+// the column-width solver and the cell wrapping are the reading experience this requirement keeps.
+// Only the escape source changed: frame and bars go through paint.rule, inline code through
+// paint.code, and the predecessor's own bold/italic literals are dropped because no escape may
+// originate outside core/paint.ts.
+
+/**
+ * table.ts — the table surface: a markdown table becomes a banded box.
+ *
+ * Boundary: lane-local. The transformer passes markdown in and splices the returned markdown back
+ * out, so every escape in the output originates in the injected ContentPaint (T-08) — the #22 fix.
+ *
+ * shape: module-scope const object — trigger #3, one stateless Surface per process; the helpers
+ * stay module functions (no state, no discriminator to dispatch on).
+ */
+
+import { Marked, type Token, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import type { TransformContext } from "../../core/types/host.ts";
+import type { ContentPaint } from "../../core/types/paint.ts";
+import type { Surface } from "./types.ts";
+
+type InlineToken = { type?: string; text?: string; raw?: string; tokens?: InlineToken[] };
+interface CellLike {
+	text?: string;
+	tokens?: InlineToken[];
+}
+interface TableToken {
+	header: CellLike[];
+	rows: CellLike[][];
+}
+
+/** Per-cell padding plus the bars: below this a column cannot hold its own frame. */
+const MIN_COLUMN = 6;
+/** A column wider than this is a paragraph, not a table cell. */
+const MAX_COLUMN = 60;
+
+const markdownParser = new Marked();
+
+/** Marked parses untrusted markdown, so the token shape is narrowed, never asserted (BND-1). */
+function isInlineToken(value: unknown): value is InlineToken {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("tokens" in value)) return true;
+	return Array.isArray(value.tokens) && value.tokens.every(isInlineToken);
+}
+
+function isCell(value: unknown): value is CellLike {
+	if (typeof value !== "object" || value === null) return false;
+	if ("text" in value && typeof value.text !== "string") return false;
+	if (!("tokens" in value)) return true;
+	return Array.isArray(value.tokens) && value.tokens.every(isInlineToken);
+}
+
+/** Marked's Token union carries a Generic member, so `type` alone cannot narrow — the shape does. */
+function isTableToken(token: Token): token is Token & TableToken {
+	if (token.type !== "table") return false;
+	if (!("header" in token)) return false;
+	if (!(Array.isArray(token.header) && token.header.every(isCell))) return false;
+	if (!("rows" in token)) return false;
+	return Array.isArray(token.rows) && token.rows.every((row) => Array.isArray(row) && row.every(isCell));
+}
+
+/** Inline styling is a ContentPaint role or nothing — the host tokenizer's own `codespan` is code. */
+function inlineText(token: InlineToken, paint: ContentPaint): string {
+	switch (token.type) {
+		case "codespan":
+			return paint.code(token.text ?? "");
+		case "strong":
+		case "em":
+		case "link":
+			return (token.tokens ?? []).map((child) => inlineText(child, paint)).join("") || (token.text ?? "");
+		default:
+			return token.text ?? token.raw ?? "";
+	}
+}
+
+function cellText(cell: CellLike | undefined, paint: ContentPaint): string {
+	const tokens = cell?.tokens;
+	const text =
+		Array.isArray(tokens) && tokens.length > 0
+			? tokens.map((token) => inlineText(token, paint)).join("")
+			: (cell?.text ?? "");
+	// Soft wraps inside a cell are one logical line before the width solve.
+	return text.replace(/\s+/g, " ").trim();
+}
+
+function padCell(content: string, width: number): string {
+	const fit = visibleWidth(content) > width ? truncateToWidth(content, width) : content;
+	return fit + " ".repeat(Math.max(0, width - visibleWidth(fit)));
+}
+
+/** shape: none — one greedy width solve; a table is small and the rule is exact. */
+function renderTable(token: TableToken, width: number, paint: ContentPaint): string[] {
+	const header = token.header.map((cell) => cellText(cell, paint));
+	const rows = token.rows.map((row) => row.map((cell) => cellText(cell, paint)));
+	const columns = Math.max(1, header.length);
+	const natural: number[] = [];
+	for (let index = 0; index < columns; index++) {
+		const cells = [header[index] ?? "", ...rows.map((row) => row[index] ?? "")];
+		natural.push(Math.min(MAX_COLUMN, Math.max(MIN_COLUMN, ...cells.map((cell) => visibleWidth(cell)))));
+	}
+	const widths = [...natural];
+	// Width budget: per-cell padding (2 each), the column bars, and the two outer bars.
+	const total = (): number => widths.reduce((sum, column) => sum + column + 2, 0) + (columns - 1) + 2;
+	while (total() > width) {
+		const widest = widths.indexOf(Math.max(...widths));
+		if ((widths[widest] ?? 0) <= MIN_COLUMN) break;
+		widths[widest] = (widths[widest] ?? 0) - 1;
+	}
+
+	// A light box around and between everything: the frame is what keeps a wrapped cell visually
+	// inside the table instead of trailing off its right edge.
+	const ruleLine = (left: string, middle: string, right: string): string =>
+		paint.rule(`${left}${widths.map((column) => "─".repeat(column + 2)).join(middle)}${right}`);
+	const bar = paint.rule("│");
+	const physical: string[] = [];
+
+	const renderBand = (cells: string[][]): void => {
+		const height = Math.max(1, ...cells.map((wrapped) => wrapped.length));
+		for (let line = 0; line < height; line++) {
+			const parts = cells.map((wrapped, index) => ` ${padCell(wrapped[line] ?? "", widths[index] ?? MIN_COLUMN)} `);
+			physical.push(`${bar}${parts.join(bar)}${bar}`);
+		}
+	};
+
+	const wrapBand = (cells: string[]): string[][] =>
+		cells.map((cell, index) => wrapTextWithAnsi(cell, widths[index] ?? MIN_COLUMN));
+
+	physical.push(ruleLine("┌", "┬", "┐"));
+	renderBand(wrapBand(header));
+	physical.push(ruleLine("├", "┼", "┤"));
+	rows.forEach((row, index) => {
+		if (index > 0) physical.push(ruleLine("├", "┼", "┤"));
+		renderBand(wrapBand(row));
+	});
+	physical.push(ruleLine("└", "┴", "┘"));
+	return physical.map((line) => (visibleWidth(line) > width ? truncateToWidth(line, width) : line));
+}
+
+/** CommonMark code span, with a delimiter longer than any backtick run inside. */
+function codeSpan(line: string): string {
+	const content = line || "\u00a0";
+	const longestBacktickRun = Math.max(0, ...Array.from(content.matchAll(/`+/g), (match) => (match[0] ?? "").length));
+	const fence = "`".repeat(longestBacktickRun + 1);
+	const padding = content.startsWith("`") || content.endsWith("`") ? " " : "";
+	return `${fence}${padding}${content}${padding}${fence}`;
+}
+
+/** Hard breaks keep every emitted line on its own row, like the host's own diagram rows. */
+function toMarkdownRows(lines: string[]): string {
+	return `${lines.map(codeSpan).join("  \n")}\n`;
+}
+
+/** shape: module-scope const object — trigger #3, one stateless table surface per process. */
+export const table: Surface = { rewrite };
+
+/** A table block is rewritten; every other block returns by the host's own text. */
+function rewrite(markdown: string, ctx: TransformContext, paint: ContentPaint): string {
+	// Every table block contains a pipe, so a block without one never pays for a lex.
+	if (!markdown.includes("|")) return markdown;
+	const width = Math.max(24, Math.floor(ctx.availableWidth));
+	// Unchanged tokens are spliced back by their own raw text; only table blocks are rebuilt.
+	const parts: string[] = [];
+	let changed = false;
+	for (const token of markdownParser.lexer(markdown)) {
+		if (!isTableToken(token)) {
+			parts.push(token.raw);
+			continue;
+		}
+		changed = true;
+		parts.push(toMarkdownRows(renderTable(token, width, paint)));
+	}
+	// No table matched: return the input itself — joining raw text is not byte-exact (Marked eats CRLF).
+	return changed ? parts.join("") : markdown;
+}

package/src/renderers/content/types.ts

@@ -0,0 +1,20 @@
+/**
+ * renderers/content/types.ts — the content-lane contracts (a markdown surface plus its registry keys).
+ *
+ * Boundary: lane-local. Surfaces and the content transformer import these; no other lane does. The
+ * host shapes they build on live in core (types/host.ts, types/paint.ts).
+ *
+ * shape: none — declaration-only module (no runtime unit), so no DSG-1 shape trigger applies.
+ */
+
+import type { TransformContext } from "../../core/types/host.ts";
+import type { ContentPaint } from "../../core/types/paint.ts";
+
+/** Surface registry keys. The module key is "content." + the key, e.g. "content.table". */
+export type SurfaceKey = "table" | "codePanel" | "jsonPanel" | "imageCard";
+
+/** One markdown rewrite stage: the input string returns by reference whenever nothing matched. */
+export interface Surface {
+	/** Rewrites (or passes through) one block of markdown. Required; never throws on unknown input. */
+	rewrite(markdown: string, ctx: TransformContext, paint: ContentPaint): string;
+}