@zenodinh/pi-render 0.1.2 → 0.1.4

package/README.md

@@ -4,10 +4,13 @@ A render-only presentation layer for **pi**: styled tool rows and a richer answe
 canvas, with zero tool-name registrations. pi-render draws; the host and its peers
 execute.
 
-It registers one row renderer resolver and one markdown transformer, draws eight
-built-in tool rows collapsed to a single line, and renders tables, code/JSON
-panels, diagram fences, and images inside assistant answers. It adds no tool
-schema, no prompt text, and no execution wrapper.
+It registers one row renderer resolver and one markdown transformer — and no
+commands at all — draws eight built-in tool rows collapsed to a single line, and
+renders tables, code/JSON panels, diagram fences, and images inside assistant
+answers. It adds no tool schema, no prompt text, and no execution wrapper.
+
+It is on by default: install it and styled output appears, with nothing to
+configure and nothing to invoke.
 
 Replaces [pi-pretty-tui](https://github.com/zenodinh/pi-pretty-tui), fixing
 [#21](https://github.com/zenodinh/pi-pretty-tui/issues/21) (expand freeze) and
@@ -52,8 +55,19 @@ Every tool row renders collapsed to one line, with errors summarized on that lin
 `ctrl+o` — or a click — expands the row; expanding a call again reuses the cached
 render, so there is no re-parse and no freeze.
 
-`/canvas` reports the canvas surfaces and the artifact cache, and opens the
-artifact browser in a TUI host. In a non-TUI host it prints a summary instead.
+Nothing to invoke: pi-render registers no commands, so the `/canvas` status
+command is gone. The artifact surfaces it reported on are unchanged — the engines
+and the cache still warm at boot, and diagram fences still render as cards.
+
+### Turning a module off
+
+Every module is on by default. A module can still be disabled through the one
+settings document, `~/.pi/agent/pi-render/settings.json`; only that module's
+surface falls back to the host's own rendering, and the others are unaffected:
+
+```json
+{ "version": 1, "modules": { "content.table": { "enabled": false } } }
+```
 
 ## What you get, and what changes
 

package/index.ts

@@ -1,29 +1,35 @@
 /**
  * index.ts — the composition root: the package's only file that calls pi.*.
  *
- * Why one file: every lane ends in a plain value (a resolver, a transformer, a command), so boot is a
+ * Why one file: every lane ends in a plain value (a resolver, a transformer, a surface), so boot is a
  * table of contents — build the registry, compose the two tables, register once per seam, and warm the
  * engines the synchronous seams call. Each lane installs in its own try/catch: a broken lane costs
- * itself, never the session (SA §2). The predecessor's ordering lore does not port — with zero
- * registrations there is no inter-extension race left to sequence around.
+ * itself, never the session (SA §2). One ordering constraint survives the predecessor's ordering lore:
+ * both live seams register synchronously, before the first await, because the host evaluates
+ * getMarkdownTransformers() when it constructs a restored message and stores that list on the component
+ * — a transformer registered after our engine warm-up is invisible to every message restored before it
+ * (issue #13).
+ *
+ * The command surface is empty on purpose (Req 2): the whole host surface is one tool resolver, one
+ * markdown transformer and one `session_start` hook — nothing for the user to invoke.
  *
  * Boundary: the host arrives as the parameter. Nothing here parses markdown, draws a row or decides
- * module state; the one adapter this file owns is the artifacts fence pass, which no lane supplies.
+ * module state; the one adapter this file owns is the artifacts pass — the fence walk and the local
+ * `.html` link walk — which no lane supplies.
  *
  * shape: none — wiring only: `piRender` is the runtime unit, and every install below is straight-line.
  */
 
 import { readFileSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { basename, isAbsolute, resolve } from "node:path";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
-import { installCommands } from "./src/commands/canvas.ts";
 import { CODE_THEME_MODULE, createCodeTheme, createShikiEngine } from "./src/core/code-theme.ts";
 import { createLogger } from "./src/core/log.ts";
 import { createContentPaint, createRowPaint } from "./src/core/paint.ts";
 import { createRegistry } from "./src/core/registry.ts";
 import { createSettingsStore } from "./src/core/settings.ts";
 import type {
-	CommandContext,
+	CodeTheme,
 	ContentPaint,
 	ExtensionApi,
 	Logger,
@@ -37,7 +43,6 @@ import {
 	type DiagramForm,
 	type EngineStatus,
 	renderDiagram,
-	status,
 	warmup,
 } from "./src/renderers/content/artifacts/engines.ts";
 import { type ArtifactServer, createArtifactServer } from "./src/renderers/content/artifacts/server.ts";
@@ -45,6 +50,7 @@ import { createCodePanel, mapFencedBlocks, panelWidth } from "./src/renderers/co
 import { createImageCardSurface } from "./src/renderers/content/image-card.ts";
 import { type ContentSurfaces, createContentTransformer } from "./src/renderers/content/index.ts";
 import { createJsonPanel } from "./src/renderers/content/json-panel.ts";
+import { mapHtmlLinkCards } from "./src/renderers/content/link-paragraph.ts";
 import { table } from "./src/renderers/content/table.ts";
 import { createMasterResolver, type SpecEntry } from "./src/renderers/tool/index.ts";
 import { bashRow } from "./src/renderers/tool/specs/bash.ts";
@@ -107,7 +113,7 @@ function uniqueModules(descriptors: readonly ModuleDescriptor[]): ModuleDescript
 }
 
 // ---------------------------------------------------------------------------
-// The artifacts fence pass — the one adapter this file owns (SA §6)
+// The artifacts pass — the one adapter this file owns (SA §6)
 // ---------------------------------------------------------------------------
 
 /** Raster width the cache key is computed from; pi-tui's own image width (P transformer.ts:68). */
@@ -122,12 +128,25 @@ function isArtifactForm(lang: string): lang is DiagramForm {
 // ported from pi-pretty-tui/src/features/canvas/transformer.ts:134-226 — survives because: fence → card
 // with a raw fence on failure is the whole artifacts surface; its settings gate and inline pixels do not.
 /**
- * shape: closure returning an object literal — trigger #4, one stateless Surface over the captured cache,
- * server and log.
+ * The artifacts lane's late-bound collaborators. The surface must exist when the transformer registers
+ * (before piRender's first await, see `piRender`), but the cache and server can only be built in the
+ * awaited artifacts lane, so the surface reads this holder per render: while a slot is still empty the
+ * whole pass is a no-op and every fence stays byte-identical.
+ */
+interface ArtifactsHolder {
+	cache?: ArtifactCache;
+	server?: ArtifactServer;
+}
+
+/**
+ * shape: closure returning an object literal — trigger #4, one stateless Surface over the late-bound
+ * holder and the log.
  */
-function createArtifactsSurface(cache: ArtifactCache, server: ArtifactServer, log: Logger): Surface {
+function createArtifactsSurface(holder: ArtifactsHolder, log: Logger): Surface {
 	/** One fence to one card, or undefined so the raw fence stays byte-identical. */
 	const card = (form: DiagramForm, source: string, width: number, paint: ContentPaint): string | undefined => {
+		const { cache, server } = holder;
+		if (cache === undefined || server === undefined) return undefined;
 		try {
 			const key = renderCacheKey(form, source, ARTIFACT_MODE, ARTIFACT_WIDTH_CELLS);
 			const result = renderDiagram(form, source, {
@@ -152,11 +171,26 @@ function createArtifactsSurface(cache: ArtifactCache, server: ArtifactServer, lo
 
 	return {
 		rewrite(markdown, ctx, paint) {
+			const { cache, server } = holder;
+			// Cold holder: the artifacts lane has not built its cache or bound its server yet. Return the input
+			// by reference so the fence walk never runs and every fence stays byte-identical.
+			if (cache === undefined || server === undefined) return markdown;
 			const width = panelWidth(ctx.availableWidth);
-			const { text, changed } = mapFencedBlocks(markdown, (lang, code) =>
+			const fenced = mapFencedBlocks(markdown, (lang, code) =>
 				isArtifactForm(lang) ? card(lang, code, width, paint) : undefined,
 			);
-			return changed ? text : markdown;
+			// The fence walk may have replaced a whole block, so the link walk runs on its output and the
+			// message itself is what it falls back to when neither pass matched.
+			const fencedText = fenced.changed ? fenced.text : markdown;
+			// A local `.html` named only by a link needs no inline bytes: the pass gates on existence and
+			// the server streams the file on click, so the render path never reads it.
+			const links = mapHtmlLinkCards(fencedText, {
+				projectDir: PROJECT_DIR,
+				log,
+				card: ({ path }) =>
+					renderArtifactCard(server, { typeLabel: "html", title: basename(path), path, width }, paint),
+			});
+			return links.changed ? links.text : fencedText;
 		},
 	};
 }
@@ -171,6 +205,43 @@ function readLinkedFile(href: string): string | undefined {
 	}
 }
 
+// ---------------------------------------------------------------------------
+// The lazy code theme — the seam between the synchronous transformer and the awaited engine
+// ---------------------------------------------------------------------------
+
+/**
+ * The host evaluates getMarkdownTransformers() when it constructs a restored message and stores the
+ * result on the component, so the transformer must register before piRender's first await — but
+ * createShikiEngine() is itself an await and the panel seam is synchronous. This holder bridges the
+ * two: the surfaces read `theme` on every render, and the content warm-up lane installs the real theme
+ * once shiki resolves. A cold render passes the source through unchanged, which is exactly the code
+ * panel's own degrade contract (bodyLines uses highlightSync's output as-is), so no async ever reaches
+ * the render path and nothing here throws.
+ */
+interface LazyCodeTheme {
+	/** The surfaces' theme: the real CodeTheme once warm, a plain passthrough while cold. */
+	readonly theme: CodeTheme;
+	/** Installs the warmed theme; the content warm-up lane calls this exactly once. */
+	warm(theme: CodeTheme): void;
+}
+
+// shape: closure returning an object literal — trigger #4, one mutable engine slot behind two delegates.
+function createLazyCodeTheme(): LazyCodeTheme {
+	let engine: CodeTheme | undefined;
+	return {
+		theme: {
+			// Cold: plain source lines are createCodeTheme's own no-engine fallback; this never rejects.
+			highlight: (code, lang) =>
+				engine === undefined ? Promise.resolve(code.split("\n")) : engine.highlight(code, lang),
+			// Cold: the exact string the panel's catch branch produces, so a cold panel reads as a plain one.
+			highlightSync: (code, lang) => (engine === undefined ? code : engine.highlightSync(code, lang)),
+		},
+		warm(next) {
+			engine = next;
+		},
+	};
+}
+
 // ---------------------------------------------------------------------------
 // Lanes — one install per seam, each settled on its own
 // ---------------------------------------------------------------------------
@@ -181,26 +252,31 @@ function installRows(pi: ExtensionApi, registry: Registry, log: Logger): void {
 }
 
 /**
- * The artifacts lane: warm the engines the synchronous fence pass calls, bind the one server, then hand
- * the pass back. A failed bind degrades every card to a file:// link, so only a throw costs this slot.
+ * The artifacts lane: warm the engines the synchronous fence pass calls, bind the one server, then fill
+ * the holder the already-registered surface reads. A failed bind degrades every card to a file:// link,
+ * and a throw costs only this slot — the transformer is registered before this lane runs.
  */
-async function installArtifacts(log: Logger, deps: BootDeps): Promise<Surface> {
+async function installArtifacts(log: Logger, deps: BootDeps, holder: ArtifactsHolder): Promise<void> {
 	await (deps.warmArtifactEngines ?? warmup)(log);
 	const server = (deps.createArtifactServer ?? ((logger: Logger) => createArtifactServer({ log: logger })))(log);
 	await server.start();
-	return createArtifactsSurface(createArtifactCache({ cacheDir: deps.cacheDir, log }), server, log);
+	holder.cache = createArtifactCache({ cacheDir: deps.cacheDir, log });
+	holder.server = server;
 }
 
-/** Region 2: code theme, five surfaces, one transformer — the only registerMarkdownTransformer call. */
-async function installContent(
+/**
+ * Region 2's synchronous half: five surfaces over lazy holders, then the one registerMarkdownTransformer
+ * call. It runs before piRender's first await, so the host's restored-message construction sees the
+ * transformer (see `piRender`); the shiki theme and the artifact cache/server stay cold until the
+ * awaited lanes fill them.
+ */
+function registerContentSeam(
 	pi: ExtensionApi,
 	registry: Registry,
 	log: Logger,
-	artifacts: Surface | undefined,
-): Promise<void> {
-	// The panel seam is synchronous while every engine start-up is not, so the highlight core is warmed
-	// here, before this registration can be reached.
-	const codeTheme = createCodeTheme(await createShikiEngine(log), { registry, log });
+	codeTheme: CodeTheme,
+	artifacts: ArtifactsHolder,
+): void {
 	const surfaces: ContentSurfaces = {
 		table,
 		codePanel: createCodePanel(codeTheme),
@@ -209,7 +285,7 @@ async function installContent(
 			projectDir: PROJECT_DIR,
 			log: (line) => log.logLine(SCOPE, line),
 		}),
-		artifacts,
+		artifacts: createArtifactsSurface(artifacts, log),
 	};
 	// The host's markdown theme is live per call, so its closures are captured once, here.
 	pi.registerMarkdownTransformer(
@@ -217,18 +293,9 @@ async function installContent(
 	);
 }
 
-/** The /canvas view: what the artifact engines can draw this session. The browser pane is T-32's. */
-function canvasView(ctx: CommandContext): Promise<void> {
-	const ready = Object.entries(status())
-		.filter(([, on]) => on)
-		.map(([id]) => id);
-	ctx.ui.notify(`canvas: artifact engines ready — ${ready.join(", ") || "none"}`);
-	return Promise.resolve();
-}
-
-/** Region 9: the one command, which reaches the rest of the package through the registry alone (SA §7). */
-function installCanvasCommand(pi: ExtensionApi, registry: Registry): void {
-	installCommands(pi, { registry, canvasView });
+/** Region 2's awaited half: fill the lazy theme once shiki resolves; renders before then already returned. */
+async function warmCodeTheme(registry: Registry, log: Logger, lazy: LazyCodeTheme): Promise<void> {
+	lazy.warm(createCodeTheme(await createShikiEngine(log), { registry, log }));
 }
 
 /** shape: none — one guarded call; a lane reports itself and boot carries on. */
@@ -241,6 +308,18 @@ async function settle<T>(lane: string, log: Logger, install: () => T | Promise<T
 	}
 }
 
+/**
+ * The synchronous twin of {@link settle} for the two lanes that must register before piRender's first
+ * await: a throw is logged and contained exactly as in settle, but nothing yields the event loop.
+ */
+function settleSync(lane: string, log: Logger, install: () => void): void {
+	try {
+		install();
+	} catch (error) {
+		log.logOnce(`boot:${lane}`, SCOPE, `${lane} lane failed: ${messageOf(error)}`);
+	}
+}
+
 /** shape: none — one message extraction for a caught value of unknown type. */
 function messageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
@@ -268,11 +347,21 @@ export default async function piRender(pi: ExtensionApi, deps: BootDeps = {}): P
 	const registry = createRegistry(createSettingsStore({ path: deps.settingsPath, logger: log }), log);
 	for (const descriptor of MODULES) registry.defineModule(descriptor);
 
-	// Lane by lane: the artifacts pass resolves before content, because the transformer dispatches it.
-	await settle("rows", log, () => installRows(pi, registry, log));
-	const artifacts = await settle("artifacts", log, () => installArtifacts(log, deps));
-	await settle("content", log, () => installContent(pi, registry, log, artifacts));
-	await settle("commands", log, () => installCanvasCommand(pi, registry));
+	// Both live seams register synchronously, before piRender's first await. The host evaluates
+	// getMarkdownTransformers() when it constructs a restored message (session rejoin builds
+	// AssistantMessageComponent while our engines are still warming) and stores that list on the
+	// component, so a transformer registered after an await is invisible to every message restored in
+	// the window — its tables render host-default for the whole session (issue #13). The rows table is
+	// synchronous already; the content seam takes lazy holders for the shiki theme and the artifact
+	// cache/server, which the awaited lanes below fill in.
+	const codeTheme = createLazyCodeTheme();
+	const artifacts: ArtifactsHolder = {};
+	settleSync("rows", log, () => installRows(pi, registry, log));
+	settleSync("content", log, () => registerContentSeam(pi, registry, log, codeTheme.theme, artifacts));
+
+	// The fallible, environment-bound lanes run next and only fill the holders above.
+	await settle("artifacts", log, () => installArtifacts(log, deps, artifacts));
+	await settle("content-warm", log, () => warmCodeTheme(registry, log, codeTheme));
 
 	// Collapse-first reading model (owner decision): every tool row starts on one line.
 	// The host exposes this on the per-event UI context (ctx.ui), not on the pi API — only

package/package.json

@@ -67,5 +67,5 @@
 		"typescript": "^7.0.2",
 		"vitest": "^5.0.3"
 	},
-	"version": "0.1.2"
+	"version": "0.1.4"
 }

package/src/core/paint.ts

@@ -5,7 +5,7 @@
  * here); both theme inputs are structural, so a plain-object fixture drives either factory with no
  * host import.
  *
- * shape: none — dispatch object does not apply: no discriminator, each role is one token lookup. The
+ * shape: none — dispatch object does not apply: no discriminator, every role is a token lookup. The
  * two closure factories below declare their own shape.
  *
  * ported from pi-pretty-tui/src/config.ts:71-100 — survives because: "read the theme token, degrade to
@@ -25,6 +25,21 @@ function fgOrPlain(theme: HostTheme, key: string, text: string): string {
 	}
 }
 
+/**
+ * The match ink: the theme's `searchMatchText`, or `accent` when that ink is the line's own body ink.
+ *
+ * The `system` theme resolves both tokens into its `neutral` family (its bundled palettes do the same),
+ * so a match painted with `searchMatchText` is invisible inside the line it belongs to. Styling the
+ * same text with both tokens compares the two inks directly; a collision — including a `searchMatchText`
+ * that is absent or throws, where `fgOrPlain` degrades it to plain — falls to `accent`, which every
+ * theme keeps distinct from body text. Never throws: each lookup already ends in plain text.
+ */
+function matchOrAccent(theme: HostTheme, text: string): string {
+	const own = fgOrPlain(theme, "searchMatchText", text);
+	const body = fgOrPlain(theme, "toolOutput", text);
+	return own === body ? fgOrPlain(theme, "accent", text) : own;
+}
+
 /** Region-2 closures read the live theme proxy; a missing or throwing token falls to the next link. */
 function tryStyle(fn: ((text: string) => string) | undefined, text: string): string | undefined {
 	try {
@@ -45,7 +60,7 @@ export function createRowPaint(theme: HostTheme): RowPaint {
 		error: (text) => fgOrPlain(theme, "error", text),
 		warning: (text) => fgOrPlain(theme, "warning", text),
 		gutter: (text) => fgOrPlain(theme, "muted", text),
-		match: (text) => fgOrPlain(theme, "searchMatchText", text),
+		match: (text) => matchOrAccent(theme, text),
 		diffAdded: (text) => fgOrPlain(theme, "toolDiffAdded", text),
 		diffRemoved: (text) => fgOrPlain(theme, "toolDiffRemoved", text),
 		diffContext: (text) => fgOrPlain(theme, "toolDiffContext", text),

package/src/core/types/host.ts

@@ -130,31 +130,19 @@ export interface TransformContext {
 	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.
+ *
+ * The command seam and its handler context are deliberately absent (Req 2): pi-render registers no
+ * command, and a declaration it never calls is a claim it does not make. A future settings panel
+ * re-declares both here, in one place (PRD Q1).
  */
 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;
 }

package/src/core/types.ts

@@ -14,7 +14,6 @@ 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,

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

@@ -18,15 +18,13 @@
 import { pathToFileURL } from "node:url";
 import { calculateImageRows, getImageDimensions, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { ContentPaint } from "../../../core/types/paint.ts";
+import { blockWidth } from "../code-panel.ts";
 import type { ArtifactServer } from "./server.ts";
 
 const OPEN_LABEL = "Open (⌘click)";
 const COPY_LABEL = "Copy path (⌥C)";
 /** The rendered link occupies brackets around the label. */
 const OPEN_WIDTH = visibleWidth(OPEN_LABEL) + 2;
-/** Cards read best narrow; the offered width is clamped into these bounds. */
-const CARD_MIN_WIDTH = 24;
-const CARD_MAX_WIDTH = 64;
 /** pi-tui's default image width; the reference for a raster artifact's transcript row count. */
 const DEFAULT_WIDTH_CELLS = 60;
 
@@ -70,9 +68,15 @@ export function artifactTitle(form: string, source: string): string {
 	return form;
 }
 
-/** shape: none — one box; every line's visible width is arithmetically bounded. */
+/**
+ * shape: none — one box; every line's DRAWN width is arithmetically bounded.
+ *
+ * Drawn, not raw: the host paints a markdown link as its label, so the pad filling the line to the
+ * right edge charges OPEN_LABEL's cells. `linkFits` and `titleBudget` still measure the RAW link —
+ * that is the width the host's wrap sees when it decides whether the token survives.
+ */
 function renderCard(spec: ArtifactCardSpec & { openUrl: string; pathLabel: string }, paint: ContentPaint): string {
-	const width = Math.max(CARD_MIN_WIDTH, Math.min(Math.floor(spec.width), CARD_MAX_WIDTH));
+	const width = blockWidth(spec.width);
 	const inner = width - 2;
 	const contentWidth = Math.max(OPEN_WIDTH + 2, inner - 2);
 	const label = spec.typeLabel.toLowerCase();
@@ -89,7 +93,10 @@ function renderCard(spec: ArtifactCardSpec & { openUrl: string; pathLabel: strin
 	const titleBudget = contentWidth - (linkFits ? visibleWidth(link) : visibleWidth(OPEN_LABEL)) - 1;
 	const titleFitted = clampWidth(title, Math.max(1, titleBudget));
 	const actionText = linkFits ? link : OPEN_LABEL;
-	const titlePad = " ".repeat(Math.max(1, contentWidth - visibleWidth(titleFitted) - visibleWidth(actionText)));
+	// Charge the DRAWN affordance, not the markdown: the host draws `[label](url)` as its label, so a
+	// pad built on the raw link width stopped (raw link − label) cells short of the frame's right edge
+	// — the title row was the one ragged line of the box (issue #8).
+	const titlePad = " ".repeat(Math.max(1, contentWidth - visibleWidth(titleFitted) - visibleWidth(OPEN_LABEL)));
 	// No escape codes inside the brackets: anything there breaks the link token.
 	const titleLine = `${paint.rule("│")} ${paint.quote(titleFitted)}${titlePad}${actionText} ${paint.rule("│")}`;
 	const copyPad = " ".repeat(Math.max(0, contentWidth - visibleWidth(COPY_LABEL)));

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

@@ -1,15 +1,17 @@
 // ported from pi-pretty-tui/src/features/canvas/code-panel.ts — survives because: the bordered panel
-// with a language header, the content-hugging width, the ANSI-aware truncation and the sync highlight
-// path are the owner's reading surface for a fence; only the color source changed (paint roles plus the
-// injected CodeTheme instead of module-level globals and hardcoded escapes).
+// with a language header, the ANSI-aware body wrap and the sync highlight path are the owner's reading
+// surface for a fence (the content-hugging width does not survive: FIX-12 replaced it with the shared
+// reading column); only the color source changed (paint roles plus the injected CodeTheme instead of
+// module-level globals and hardcoded escapes).
 
 /**
  * code-panel.ts — a fenced block becomes a bordered, themed panel; the JSON pane reuses the same frame,
- * the same fence scan and the same markdown embedding.
+ * the same fence scan, the same block-width clamp (24–140, the owner's revised reading column) and the
+ * same markdown embedding.
  *
  * Boundary: markdown is untrusted and is scanned line-by-line, never handed to a parser; the CodeTheme
  * is injected, so no renderer imports shiki. Width math is pi-tui's own ANSI-aware visibleWidth /
- * truncateToWidth — the one host utility the panel needs, and what keeps columns aligned when truecolor
+ * wrapTextWithAnsi — the host utilities the panel needs, and what keeps columns aligned when truecolor
  * escapes sit inside the content (CJK included). A failing highlighter degrades to plain source; the
  * panel never throws.
  *
@@ -17,30 +19,51 @@
  * declares its own shape below.
  */
 
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import type { CodeTheme, ContentPaint } from "../../core/types.ts";
 import type { Surface } from "./types.ts";
 
-/** The panel is never narrower than this, so a one-word snippet still reads as a block (P code-panel.ts:20). */
-const MIN_PANEL_WIDTH = 24;
-/** A body row is `│ text │`, so the text budget is width-4 (P code-panel.ts:75). */
-const ROW_CHROME = 4;
+/** The floor of the reading column, so a narrow terminal still reads a block as a block. */
+const BLOCK_MIN_WIDTH = 24;
+/** The ceiling of the reading column. Raised 64 → 140 by the owner (2026-10-07): 64 cells were too
+ *  narrow for a table cell, and 140/190 ≈ 74% keeps the proportion the original reference width set
+ *  (64/80 ≈ 80%), so a wide terminal or a two-way split still reads as one column. */
+const BLOCK_MAX_WIDTH = 140;
+/** A body row is `│␣␣text␣␣│` — two blank cells each side so the frame never touches the code — so the
+ *  text budget is width-6 (P code-panel.ts:75). */
+const ROW_CHROME = 6;
 /** Languages left as raw fences: mermaid is the host's own renderer, and the four diagram forms
  *  belong to the artifact pass that runs AFTER surfaces (SA §6) — consuming them here would
  *  regress every diagram to a plain panel. */
 const RAW_FENCES = new Set(["mermaid", "plantuml", "svg", "dot", "html"]);
 
-/** The offered transcript width, clamped to the panel minimum (P transformer.ts:319-320). */
-// shape: none — one clamp, no branch on a discriminator.
-export function panelWidth(availableWidth: number): number {
-	return Math.max(MIN_PANEL_WIDTH, Math.floor(availableWidth) || 80);
+/**
+ * The reading column: the one width every framed block shares (GLOSSARY "reading column"). The offered
+ * transcript width is clamped into [BLOCK_MIN_WIDTH, BLOCK_MAX_WIDTH], so at 140 columns and above a
+ * block holds 140 cells, and below 140 it takes the FULL offered width — a narrow terminal is never
+ * under-filled. Zero or a non-numeric offer falls back to 80 columns.
+ *
+ * shape: none — one clamp, no branch on a discriminator.
+ */
+export function blockWidth(availableWidth: number): number {
+	const offered = Math.floor(availableWidth) || 80;
+	return Math.min(BLOCK_MAX_WIDTH, Math.max(BLOCK_MIN_WIDTH, offered));
 }
 
-/** Highlighted body lines, truncated by visible width; a throwing theme degrades to the plain source. */
-// shape: none — one guarded call plus a one-line fallback; no discriminator.
-function bodyLines(code: string, lang: string, width: number, codeTheme: CodeTheme): string[] {
+/**
+ * The composition root's historical name for {@link blockWidth} (index.ts imports it and is outside
+ * FIX-12's file set). Same function, same clamp — kept so the root keeps compiling.
+ */
+export const panelWidth = blockWidth;
+
+/**
+ * Highlighted body lines, wrapped to `textWidth` visible cells; a line past the budget continues on the
+ * next row (ANSI-aware) rather than being cut. A throwing theme degrades to the plain source.
+ *
+ * shape: none — one guarded call plus a one-line fallback; no discriminator.
+ */
+function bodyLines(code: string, lang: string, textWidth: number, codeTheme: CodeTheme): string[] {
 	const source = code.replace(/\n+$/, "");
-	const budget = Math.max(8, width - ROW_CHROME);
 	let lines: string[];
 	try {
 		lines = codeTheme.highlightSync(source, lang).split("\n");
@@ -48,11 +71,15 @@ function bodyLines(code: string, lang: string, width: number, codeTheme: CodeThe
 		// A cold core or an unloadable grammar: the panel degrades, the answer render never dies.
 		lines = source.split("\n");
 	}
-	return lines.map((line) => truncateToWidth(line, budget));
+	return lines.flatMap((line) => wrapTextWithAnsi(line, textWidth));
 }
 
 /**
- * One framed block: header label, hugged width, padded rows. Shared by the code and JSON panels.
+ * One framed block at the shared reading column: header label and body rows, all `blockWidth(width)`
+ * cells wide. Each body row is `│␣␣text␣␣pad␣␣│`, i.e. the line begins two cells inside the opening
+ * border and its own padding fills the rest of a `panelSize - 6` text budget, so the frame never crowds
+ * the code. A line wider than that budget was already wrapped by {@link bodyLines}, so the panel shows
+ * the whole line over further rows and pads the last. Shared by the code and JSON panels.
  *
  * shape: none — one box; every row's visible width is arithmetically bounded to the panel width.
  */
@@ -63,22 +90,17 @@ export function renderPanel(
 	paint: ContentPaint,
 	codeTheme: CodeTheme,
 ): string[] {
-	const maxWidth = Math.max(MIN_PANEL_WIDTH, Math.floor(width));
+	const panelSize = blockWidth(width);
+	const textWidth = Math.max(8, panelSize - ROW_CHROME);
 	const label = lang.toLowerCase() || "code";
-	const body = bodyLines(code, lang, maxWidth, codeTheme);
-	const contentWidth = Math.max(1, ...body.map((line) => visibleWidth(line)));
-	const prefix = `─ ${label} `;
-	const panelSize = Math.min(
-		maxWidth,
-		Math.max(MIN_PANEL_WIDTH, Math.max(contentWidth + ROW_CHROME, visibleWidth(prefix) + ROW_CHROME)),
-	);
+	const body = bodyLines(code, lang, textWidth, codeTheme);
 	const inner = panelSize - 2;
-	const textWidth = Math.max(8, panelSize - ROW_CHROME);
+	const prefix = `─ ${label} `;
 	const dashes = Math.max(0, inner - visibleWidth(prefix));
 	const rows: string[] = [paint.codeBlockBorder(`╭${prefix}${"─".repeat(dashes)}╮`)];
 	for (const line of body) {
 		const pad = " ".repeat(Math.max(0, textWidth - visibleWidth(line)));
-		rows.push(`${paint.codeBlockBorder("│")} ${line}${pad} ${paint.codeBlockBorder("│")}`);
+		rows.push(`${paint.codeBlockBorder("│")}  ${line}${pad}  ${paint.codeBlockBorder("│")}`);
 	}
 	rows.push(paint.codeBlockBorder(`╰${"─".repeat(inner)}╯`));
 	return rows;
@@ -151,7 +173,7 @@ export function mapFencedBlocks(
 export function createCodePanel(codeTheme: CodeTheme): Surface {
 	return {
 		rewrite(markdown, ctx, paint) {
-			const width = panelWidth(ctx.availableWidth);
+			const width = blockWidth(ctx.availableWidth);
 			const { text, changed } = mapFencedBlocks(markdown, (lang, code) =>
 				lang && !RAW_FENCES.has(lang) ? toMarkdownRows(renderPanel(code, lang, width, paint, codeTheme)) : undefined,
 			);

package/src/renderers/content/index.ts

@@ -1,10 +1,13 @@
 /**
- * index.ts — the markdown transformer: final-assistant gate, per-surface registry check, dispatch,
- * identity return.
+ * index.ts — the markdown transformer: final-assistant gate, per-surface registry check, per-surface
+ * isolation, dispatch, identity return, and one keyed line for every skip.
  *
  * 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.
+ * allocates per message. A disabled surface is skipped; a surface that throws is isolated to itself and
+ * the message keeps every other rewrite; the input string returns by reference whenever no surface
+ * changed it — the host's own caching reads that reference. What the pass cannot do, it names: a closed
+ * gate and a table that comes out unboxed each leave one line keyed on the reason, so a live report
+ * reads its own cause instead of a screenshot.
  *
  * shape: closure returning a function — trigger #4, the factory captures its injected collaborators
  * (registry, surfaces, paint, log) and holds no state to classify.
@@ -12,7 +15,8 @@
  * 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.
+ * code do not port: each surface owns one rewrite here, and the registry owns every toggle. Its single
+ * try/catch around the whole pass does not port either: a failure belongs to the surface that threw.
  */
 
 import type { TransformContext } from "../../core/types/host.ts";
@@ -28,7 +32,16 @@ const ARTIFACTS_KEY = "artifacts";
 const SURFACE_ORDER: readonly SurfaceKey[] = ["table", "codePanel", "jsonPanel", "imageCard"];
 
 const SCOPE = "content";
-const LOG_KEY = "content:transform";
+
+/**
+ * What this file calls a table: a row holding a pipe, then a delimiter row of dashes, colons and pipes.
+ * It is the shape the table surface parses (T-22), spelled for the raw markdown the transformer receives,
+ * so prose that merely quotes a pipe — or an already-boxed frame — never matches.
+ */
+const TABLE_SHAPE = /\|[^\n]*\n\|[ :-]*-[-| :]*\|/;
+
+/** The tee in the table box's top rule (T-22): present in an output exactly when a table was boxed. */
+const TABLE_BOX_RULE = "┬";
 
 /** The surface table T-28 composes: one entry per SurfaceKey, plus the optional fence pass. */
 export type ContentSurfaces = Record<SurfaceKey, Surface> & {
@@ -40,7 +53,7 @@ export type ContentSurfaces = Record<SurfaceKey, Surface> & {
 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. */
+	/** Keyed diagnostics: one line per surface failure, gate skip and declined table — a healthy input logs nothing. Required. */
 	log: Logger;
 }
 
@@ -54,26 +67,62 @@ export function createContentTransformer(
 	const { paint, log } = deps;
 	const artifacts = surfaces.artifacts;
 
-	/** One dispatch step: an absent or disabled slot is skipped, otherwise it rewrites the current text. */
+	/**
+	 * One dispatch step: an absent or disabled slot is skipped, otherwise it rewrites the current text.
+	 * Per-surface isolation lives here — a surface that throws logs one line keyed on its own name and
+	 * returns the text it was handed, so the failure costs that surface alone and never the message.
+	 */
 	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;
+		try {
+			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;
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			log.logOnce(`content:fail:${key}`, SCOPE, `${key} failed: ${detail}`);
+			return input;
+		}
 	};
 
 	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)}`);
+		// The predecessor's gate, unchanged: only a settled assistant message is rewritten. The key carries
+		// the messageType alone (three possible values), so a whole session reports each gate reason once.
+		if (ctx.messageType !== "assistant" || ctx.isStreaming) {
+			if (TABLE_SHAPE.test(markdown)) {
+				log.logOnce(
+					`content:gate:${ctx.messageType}`,
+					SCOPE,
+					`table-shaped content skipped: messageType=${ctx.messageType} isStreaming=${ctx.isStreaming}`,
+				);
+			}
 			return markdown;
 		}
+
+		let out = markdown;
+		// The step that last changed the text: the surface a table should have come from, named by the
+		// decline line below. Undefined means every surface passed its input straight through.
+		let lastTouched: string | undefined;
+		for (const key of SURFACE_ORDER) {
+			const step = run(`content.${key}`, surfaces[key], out, ctx);
+			if (step !== out) lastTouched = `content.${key}`;
+			out = step;
+		}
+		const fenced = run(`content.${ARTIFACTS_KEY}`, artifacts, out, ctx);
+		if (fenced !== out) lastTouched = `content.${ARTIFACTS_KEY}`;
+		out = fenced;
+
+		// A table that reaches the end of the pass without a box rule was declined by every surface that saw
+		// it — the one case where the pipeline succeeded and the box still did not draw. The key carries the
+		// input length, so a channel that keeps repeating one table declines once.
+		if (TABLE_SHAPE.test(markdown) && !out.includes(TABLE_BOX_RULE)) {
+			log.logOnce(
+				`content:decline:table:${markdown.length}`,
+				SCOPE,
+				`table-shaped content left unboxed: last surface that touched the text=${lastTouched ?? "none"}`,
+			);
+		}
+		return out;
 	};
 }

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

@@ -15,16 +15,16 @@
  */
 
 import type { CodeTheme, ContentPaint, Logger } from "../../core/types.ts";
-import { mapFencedBlocks, panelWidth, renderPanel, toMarkdownRows } from "./code-panel.ts";
+import { blockWidth, mapFencedBlocks, renderPanel, toMarkdownRows } from "./code-panel.ts";
+import { hrefExtension, isLocalRef, standaloneLinkHref } from "./link-paragraph.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 extensions the pane claims; `hrefExtension` tests one at a time, so the table spells them out. */
+const JSON_EXTENSIONS = ["json", "jsonc", "jsonl"] as const;
 
 /** The collaborators the pane reads through: the file reader and the optional diagnostics sink. */
 export interface JsonPanelDeps {
@@ -34,12 +34,6 @@ export interface JsonPanelDeps {
 	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(
@@ -82,13 +76,11 @@ function mapJsonFileLinks(
 	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() === "");
+		// A standalone link paragraph, recognised once in link-paragraph.ts: the same rule the artifact
+		// pass applies to a local `.html` link.
+		const href = standaloneLinkHref(lines, i);
 		const pane =
-			href !== undefined && alone && isLocalRef(href) && JSON_EXTENSION.test(href.replace(/[?#].*$/, ""))
+			href !== undefined && isLocalRef(href) && JSON_EXTENSIONS.some((extension) => hrefExtension(href, extension))
 				? jsonFilePane(href, width, paint, codeTheme, deps)
 				: undefined;
 		if (pane === undefined) {
@@ -105,7 +97,7 @@ function mapJsonFileLinks(
 export function createJsonPanel(codeTheme: CodeTheme, deps: JsonPanelDeps): Surface {
 	return {
 		rewrite(markdown, ctx, paint) {
-			const width = panelWidth(ctx.availableWidth);
+			const width = blockWidth(ctx.availableWidth);
 			const fences = mapFencedBlocks(markdown, (lang, code) =>
 				JSON_LANGS.has(lang) ? toMarkdownRows(renderPanel(code, "json", width, paint, codeTheme)) : undefined,
 			);

package/src/renderers/content/link-paragraph.ts

@@ -0,0 +1,153 @@
+// ported from pi-pretty-tui/src/features/canvas/transformer.ts:110-112 (isLocalRef) and :270-275
+// (LINK_ONLY) — survives because: "a paragraph that is nothing but a link to a local file names that
+// file" is the recognition the JSON pane and the artifact link pass both need, and it is what lets a
+// large .html page be carded without its bytes ever entering the message. Promoted out of json-panel.ts
+// when the second consumer arrived; carries no registration claim and reads no file.
+
+/**
+ * link-paragraph.ts — what a link paragraph is, and the pass that cards a local `.html` one.
+ *
+ * Boundary: markdown is untrusted, so it is walked line by line and never parsed; this module reads no
+ * file — `fileExists` is one injected existence check per candidate, and the card itself is drawn by
+ * the caller. A missing file keeps the raw link and reports one keyed line through the injected sink; a
+ * remote href, a bare fragment, or another extension is left byte-identical. Nothing here throws and
+ * nothing here writes stdout or stderr.
+ *
+ * shape: none — pure recognition helpers plus one line walk over injected collaborators; there is no
+ * discriminator to dispatch on and no resource to hold.
+ */
+
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import type { Logger } from "../../core/types/log.ts";
+
+/** Diagnostics scope for the pass; the artifacts surface owns its keyed lines. */
+const SCOPE = "content.artifacts";
+
+/** The one extension this pass cards (owner decision 2026-10-07); `.svg`/`.dot`/`.puml` by path are a follow-up. */
+const HTML_EXTENSION = "html";
+
+/** A paragraph that is nothing but a link, captured as its href (P transformer.ts:270-275). */
+const LINK_ONLY = /^\[[^\]]*\]\(([^)\s]+)\)$/;
+
+/**
+ * The href of a paragraph that is nothing but a markdown link, or `undefined` when the line is
+ * anything else.
+ *
+ * A line qualifies only when the whole line — ignoring leading and trailing whitespace — is one link;
+ * a link that shares its line with prose is not a link paragraph.
+ */
+// shape: none — one anchored match, no branch on a discriminator.
+export function linkOnlyHref(line: string): string | undefined {
+	return LINK_ONLY.exec(line.trim())?.[1];
+}
+
+/**
+ * True when the href names a local file: it carries no URI scheme (`https:`, `data:`, `mailto:`), is
+ * not protocol-relative (`//host/path`), and is not a bare fragment (`#section`) (P transformer.ts:110-112).
+ */
+// shape: none — one classification, no branch on a discriminator.
+export function isLocalRef(href: string): boolean {
+	return !/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith("//") && !href.startsWith("#");
+}
+
+/** The part of an href that names a file: a query and a fragment address a location inside that file. */
+// shape: none — one string cut, no state.
+function withoutQuery(href: string): string {
+	return href.replace(/[?#].*$/, "");
+}
+
+/**
+ * True when the file part of the href ends in the named extension. The comparison is case-insensitive
+ * and ignores any query or fragment, so `hrefExtension("Guide.HTML#page=3", "html")` is true while
+ * `hrefExtension("guide.htm", "html")` is false.
+ *
+ * `extension` is written without its leading dot — `"html"`, `"jsonl"`.
+ */
+// shape: none — one string test, no branch on a discriminator.
+export function hrefExtension(href: string, extension: string): boolean {
+	return withoutQuery(href).toLowerCase().endsWith(`.${extension.toLowerCase()}`);
+}
+
+/**
+ * The href of a standalone link paragraph — a link-only line that its blank neighbours set off — or
+ * `undefined` when the line is blank, prose, or part of a paragraph.
+ *
+ * `lines` is the message split on "\n" and `index` is the line being tested; the first and last lines of
+ * a message are standalone when their only existing neighbour is blank.
+ */
+// shape: none — one link match plus one neighbour test; no discriminator.
+export function standaloneLinkHref(lines: readonly string[], index: number): string | undefined {
+	if ((lines[index] ?? "").trim() === "") return undefined;
+	if ((lines[index - 1] ?? "").trim() !== "") return undefined;
+	if ((lines[index + 1] ?? "").trim() !== "") return undefined;
+	return linkOnlyHref(lines[index] ?? "");
+}
+
+/** One standalone link the pass decided to card. */
+export interface HtmlLinkMatch {
+	/** The href exactly as the message wrote it — the value a diagnostic names. */
+	readonly href: string;
+	/** The file the href resolves to, absolute; a relative href resolves against the project directory. */
+	readonly path: string;
+}
+
+/** Draws one match into transcript markdown; the composition root passes `renderArtifactCard`. */
+export type HtmlLinkCard = (match: HtmlLinkMatch) => string;
+
+/** What the pass reads through: where relative hrefs start, how existence is checked, how to report. */
+export interface HtmlLinkPassDeps {
+	/** Base for a relative href — the launch directory, the same rule the JSON pane's reader uses. */
+	projectDir: string;
+	/** Builds the card for one existing file; called once per match, never for a miss. */
+	card: HtmlLinkCard;
+	/** Existence gate, called at most once per candidate. Defaults to node's `existsSync`. */
+	fileExists?: (absPath: string) => boolean;
+	/** Keyed diagnostics for a link that names a missing file. Optional; absent is silent. */
+	log?: Pick<Logger, "logOnce">;
+}
+
+/** The pass's outcome: the rewritten markdown, and whether anything changed. */
+export interface HtmlLinkPass {
+	/** The message with every carded link replaced; the message itself when `changed` is false. */
+	readonly text: string;
+	/** True when at least one line became a card. */
+	readonly changed: boolean;
+}
+
+/**
+ * Rewrites every standalone link paragraph that names an existing local `.html` file into a card, and
+ * returns the message itself when none matched.
+ *
+ * A local `.html` link whose file is missing keeps its raw line and reports one keyed line, because a
+ * card whose Open link 404s is worse than the link the model wrote. The render path reads no file: per
+ * candidate there is one `fileExists` call, no size cap and no engine call — the server streams the
+ * bytes on click.
+ *
+ * shape: none — one line walk with a single injected card callback, mirroring `mapFencedBlocks`; no
+ * dispatch on a value.
+ */
+export function mapHtmlLinkCards(markdown: string, deps: HtmlLinkPassDeps): HtmlLinkPass {
+	const exists = deps.fileExists ?? existsSync;
+	const lines = markdown.split("\n");
+	const out: string[] = [];
+	let changed = false;
+	for (let index = 0; index < lines.length; index += 1) {
+		const line = lines[index] ?? "";
+		const href = standaloneLinkHref(lines, index);
+		if (href === undefined || !isLocalRef(href) || !hrefExtension(href, HTML_EXTENSION)) {
+			out.push(line);
+			continue;
+		}
+		const file = withoutQuery(href);
+		const path = isAbsolute(file) ? file : resolve(deps.projectDir, file);
+		if (!exists(path)) {
+			deps.log?.logOnce(`artifact:html-link:${href}`, SCOPE, `could not card ${href} — no file at ${path}`);
+			out.push(line);
+			continue;
+		}
+		out.push(deps.card({ href, path }));
+		changed = true;
+	}
+	return { text: changed ? out.join("\n") : markdown, changed };
+}

package/src/renderers/content/table.ts

@@ -17,6 +17,7 @@
 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 { blockWidth } from "./code-panel.ts";
 import type { Surface } from "./types.ts";
 
 type InlineToken = { type?: string; text?: string; raw?: string; tokens?: InlineToken[] };
@@ -157,7 +158,9 @@ export const table: Surface = { rewrite };
 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));
+	// The shared reading column (FIX-12): the solver and every cell wrap against this one width, never
+	// the raw offered width, so a table's edges line up with the panels and cards above it.
+	const width = blockWidth(ctx.availableWidth);
 	// Unchanged tokens are spliced back by their own raw text; only table blocks are rebuilt.
 	const parts: string[] = [];
 	let changed = false;

package/src/renderers/tool/runtime.ts

@@ -6,8 +6,10 @@
  * runtime.ts — a declarative RowSpec in, host tool renderers out: parse once, project per invocation.
  *
  * Boundary: one runtime per row, created by the master resolver. It owns the protocol every spec would
- * otherwise re-implement — memo, args gate, never-throw degradation, async decorate. Host shapes arrive
- * as parameters (ctx, theme) and stay structural, so a unit test needs no pi runtime.
+ * otherwise re-implement — memo, args gate, never-throw degradation, async decorate, and the collapsed
+ * summary handoff: the result slot stores its one line in ctx.state and the call slot appends it, so a
+ * collapsed row is one line even though the host stacks two components. Host shapes arrive as parameters
+ * (ctx, theme) and stay structural, so a unit test needs no pi runtime.
  *
  * shape: closure returning an object literal — trigger #4: the per-row memo/token live behind the
  * renderCall/renderResult methods, with no subclassing.
@@ -32,6 +34,8 @@ const LOG_SCOPE = "tool.row";
 const MEMO_KEY = "piRender.memo";
 const TOKEN_KEY = "piRender.token";
 const DECORATED_KEY = "piRender.decorated";
+/** The collapsed result line the call slot appends, written by renderResult and read by renderCall. */
+const SUMMARY_KEY = "piRender.summary";
 /** A session reaches 1,400+ rows, so cross-row parsed models are bounded by count and by size. */
 const CACHE_MAX_ENTRIES = 512;
 const CACHE_MAX_CHARS = 16_000_000;
@@ -71,6 +75,12 @@ function writeMemo(ctx: RenderContext, src: ResultContent | undefined, len: numb
 	ctx.state[MEMO_KEY] = { src, len, model };
 }
 
+/** The collapsed summary the result slot has settled, or undefined when it has not run yet. */
+function readSummary(ctx: RenderContext): string | undefined {
+	const value: unknown = ctx.state[SUMMARY_KEY];
+	return typeof value === "string" ? value : undefined;
+}
+
 /** The engine's text verbatim, collapsed to one line: the degradation contract's body. */
 function textOf(result: ToolResult): string {
 	const content = result.content;
@@ -165,6 +175,23 @@ function textFor(ctx: RenderContext, body: string): UiComponent {
 	};
 }
 
+/**
+ * The collapsed result slot's component: it draws no lines. The host stacks the call slot and the result
+ * slot inside one Box, and the Box concatenates each child's lines (pi-tui box.js render), so an empty
+ * array adds nothing — the call line above is the whole collapsed row. Stateless, so one shared instance
+ * serves every row and every frame.
+ *
+ * shape: object literal — trigger #7, a fixed two-method UiComponent with no state of its own.
+ */
+const EMPTY_COMPONENT: UiComponent = {
+	render(_width: number): string[] {
+		return [];
+	},
+	invalidate(): void {
+		// The host tracks staleness; this component caches no frame.
+	},
+};
+
 function nextToken(ctx: RenderContext): number {
 	const current = ctx.state[TOKEN_KEY];
 	const next = typeof current === "number" ? current + 1 : 1;
@@ -238,7 +265,10 @@ export function createRowRenderers(spec: RowSpec, deps: { paint: RowPaintFactory
 			const paint = deps.paint(theme);
 			// A partial argument set is not a title: buildCall sees {} until the host says argsComplete.
 			const model = spec.buildCall(ctx.argsComplete === true ? args : {}, ctx);
-			return textFor(ctx, paint.title(model.title));
+			const title = paint.title(model.title);
+			// Collapsed rows are one line: the summary the result slot settled rides this title line.
+			const summary = ctx.expanded === true ? undefined : readSummary(ctx);
+			return textFor(ctx, summary === undefined ? title : `${title} · ${summary}`);
 		} catch (err) {
 			logFailure(deps.log, ctx, err);
 			return textFor(ctx, "");
@@ -254,8 +284,17 @@ export function createRowRenderers(spec: RowSpec, deps: { paint: RowPaintFactory
 		try {
 			const paint = deps.paint(theme);
 			const model = modelFor(result, ctx);
-			const body = model === UNKNOWN ? rawBody(result, paint) : spec.project(model, viewOf(options, ctx), paint);
-			return textFor(ctx, body);
+			// A degraded row keeps today's one raw line and settles no summary for the call slot to adopt.
+			if (model === UNKNOWN) return textFor(ctx, rawBody(result, paint));
+			const body = spec.project(model, viewOf(options, ctx), paint);
+			if (options.expanded) return textFor(ctx, body);
+			// Collapsed: hand the one-line summary to the call slot through the shared state bag and draw no
+			// line here. Redraw only when it changed — an unchanged summary is not a new frame.
+			if (readSummary(ctx) !== body) {
+				ctx.state[SUMMARY_KEY] = body;
+				ctx.invalidate?.();
+			}
+			return EMPTY_COMPONENT;
 		} catch (err) {
 			// The paint may itself be the thrower, so the degraded row is built without it.
 			logFailure(deps.log, ctx, err);

package/src/renderers/tool/specs/search.ts

@@ -303,23 +303,31 @@ function annotation(value: string | undefined, paint: RowPaint): string {
 }
 
 function project(m: SearchModel, view: RowView, paint: RowPaint): string {
-	const tail = m.notices.length ? `\n${paint.warning(`[${m.notices.join(". ")}]`)}` : "";
+	const notice = m.notices.length ? paint.warning(`[${m.notices.join(". ")}]`) : "";
+	// A collapsed row is exactly one line (FIX-09): the notice joins the summary inline, never its own
+	// line. An expanded row keeps it as a trailer under the body.
+	const trailer = notice === "" ? "" : `\n${notice}`;
 	switch (m.kind) {
 		case "empty":
-			return `${paint.muted(`0 ${m.noun}`)}${tail}`;
+			return inline(`${paint.muted(`0 ${m.noun}`)}`, notice);
 		case "files": {
 			const count = m.files.length;
-			const label = `${count} file${count === 1 ? "" : "s"}`;
-			if (!view.expanded) return `${paint.muted(label)}${tail}`;
-			return `${paint.muted(label)}\n${renderFiles(m.files, paint)}${tail}`;
+			const label = `${paint.muted(`${count} file${count === 1 ? "" : "s"}`)}`;
+			if (!view.expanded) return inline(label, notice);
+			return `${label}\n${renderFiles(m.files, paint)}${trailer}`;
 		}
 		case "matches": {
 			const fileCount = m.blocks.length;
-			const label = `${m.matchCount} match${m.matchCount === 1 ? "" : "es"} in ${fileCount} file${
-				fileCount === 1 ? "" : "s"
-			}`;
-			if (!view.expanded) return `${paint.muted(label)}${tail}`;
-			return `${paint.muted(label)}\n${renderBlocks(m.blocks, m.highlight, paint)}${tail}`;
+			const label = `${paint.muted(
+				`${m.matchCount} match${m.matchCount === 1 ? "" : "es"} in ${fileCount} file${fileCount === 1 ? "" : "s"}`,
+			)}`;
+			if (!view.expanded) return inline(label, notice);
+			return `${label}\n${renderBlocks(m.blocks, m.highlight, paint)}${trailer}`;
 		}
 	}
 }
+
+/** Joins a notice onto a collapsed summary with a separator, so the row stays one line. */
+function inline(label: string, notice: string): string {
+	return notice === "" ? label : `${label} · ${notice}`;
+}

package/src/renderers/tool/types.ts

@@ -38,7 +38,12 @@ export interface RowSpec<M = unknown> {
 	buildCall(args: Record<string, unknown>, ctx: RenderContext): CallModel;
 	/** Parses the result once per result, memoized in ctx.state. Required; returns "unknown" when unrecognized. */
 	build(result: ToolResult, ctx: RenderContext): M | "unknown";
-	/** Draws the collapsed-line body; re-runs on every frame, so it stays allocation-light. Required. */
+	/**
+	 * Draws the row body for the current view. While `view.expanded` is false it MUST return exactly
+	 * one line (notices joined inline with " · ") — the runtime hands that line to the call slot so a
+	 * collapsed invocation occupies one transcript line; expanded, it returns the summary header plus
+	 * the body. Re-runs on every frame, so it stays allocation-light. Required.
+	 */
 	project(m: M, view: RowView, paint: RowPaint): string;
 	/** Enriches M, e.g. with a resolved link target, then asks the host to redraw. Optional. */
 	decorate?(m: M, ctx: RenderContext): Promise<Partial<M>>;

package/src/commands/canvas.ts

@@ -1,57 +0,0 @@
-// ported from pi-pretty-tui/src/features/canvas/index.ts:90-100 — survives because: the predecessor's
-// /canvas registerCommand shape — a thin handler that opens the artifact through an injected seam and
-// notifies instead of throwing when it cannot — is exactly the command contract pi-render needs. Its
-// shortcuts, cmux routing, warmup and cache-dir plumbing stay behind (registration-adjacent chrome).
-
-/**
- * canvas.ts — the package's one command: /canvas opens the artifact browser, or reports its status.
- *
- * Boundary: `ctx` arrives from the host and is read as core/types/host.ts declares it — nothing here
- * narrows or re-declares a host shape. The injected `deps.registry` is the command's ONLY channel to
- * the rest of the package (SA §7), and it is read-only: /canvas reports module state and never writes
- * it, so a disabled module's command cannot act anyway.
- *
- * Why `canvasView` is injected: `index.ts` (T-28) is the only file that composes lanes, so the real
- * browser arrives as a parameter; this module never imports a renderer and its tests drive a fake view.
- *
- * shape: none — trigger #1 dispatch object does not apply: one command, two guards (host mode, module
- * enabled) resolved in sequence, no per-kind handler table.
- */
-
-import type { CommandContext, ExtensionApi, Registry } from "../core/types.ts";
-
-/**
- * The content lane's artifacts module key (SA §6). A literal, not an import: `commands/` may not
- * reach into a renderer lane for its constant (SA §1 rule 3).
- */
-const ARTIFACTS_KEY = "content.artifacts";
-
-/** What /canvas needs from its callers: module state to report, and the view to open. */
-export interface CommandsDeps {
-	/** Registry the command reads, e.g. isEnabled("content.artifacts"). Required; never written here. */
-	readonly registry: Registry;
-	/** Opens the artifact browser. Required; index.ts injects the real view, tests a fake one. */
-	readonly canvasView: (ctx: CommandContext) => Promise<void>;
-}
-
-/** shape: none — one interpolated line; a status table would restate the same registry read. */
-function summarize(mode: CommandContext["mode"], enabled: boolean): string {
-	if (!enabled) return "canvas: content.artifacts is disabled — enable it to open the artifact browser";
-	return `canvas: content.artifacts is enabled — the artifact browser needs a TUI host (mode: ${mode})`;
-}
-
-/** shape: none — one guarded registration; the handler below is this module's only command. */
-export function installCommands(pi: ExtensionApi, deps: CommandsDeps): void {
-	pi.registerCommand("canvas", {
-		description: "canvas: open the artifact browser, or report its status",
-		handler: async (_args, ctx) => {
-			const enabled = deps.registry.isEnabled(ARTIFACTS_KEY);
-			// A non-TUI host cannot draw the view and a disabled module has nothing to open: both report.
-			if (ctx.mode !== "tui" || !enabled) {
-				ctx.ui.notify(summarize(ctx.mode, enabled));
-				return;
-			}
-			await deps.canvasView(ctx);
-		},
-	});
-}