@zenodinh/pi-render 0.1.3 → 0.1.5

package/index.ts

@@ -4,8 +4,11 @@
  * 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.
@@ -25,7 +28,15 @@ 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 { ContentPaint, ExtensionApi, Logger, ModuleDescriptor, Registry, Surface } from "./src/core/types.ts";
+import type {
+	CodeTheme,
+	ContentPaint,
+	ExtensionApi,
+	Logger,
+	ModuleDescriptor,
+	Registry,
+	Surface,
+} from "./src/core/types.ts";
 import { type ArtifactCache, createArtifactCache, renderCacheKey } from "./src/renderers/content/artifacts/cache.ts";
 import { artifactTitle, renderArtifactCard } from "./src/renderers/content/artifacts/cards.ts";
 import {
@@ -117,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.
  */
-function createArtifactsSurface(cache: ArtifactCache, server: ArtifactServer, log: Logger): Surface {
+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(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, {
@@ -147,6 +171,10 @@ 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 fenced = mapFencedBlocks(markdown, (lang, code) =>
 				isArtifactForm(lang) ? card(lang, code, width, paint) : undefined,
@@ -177,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
 // ---------------------------------------------------------------------------
@@ -187,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),
@@ -215,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(
@@ -223,6 +293,11 @@ async function installContent(
 	);
 }
 
+/** 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. */
 async function settle<T>(lane: string, log: Logger, install: () => T | Promise<T>): Promise<T | undefined> {
 	try {
@@ -233,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);
@@ -260,10 +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));
+	// 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.3"
+	"version": "0.1.5"
 }

package/src/core/paint.ts

@@ -48,7 +48,6 @@ function tryStyle(fn: ((text: string) => string) | undefined, text: string): str
 		return undefined;
 	}
 }
-
 /** Region 1 — the tool-row factory. Reads `theme` live, so the next call paints the current theme. */
 // shape: closure returning an object literal — trigger #4, eight stateless row roles over the captured theme.
 export function createRowPaint(theme: HostTheme): RowPaint {
@@ -67,13 +66,45 @@ export function createRowPaint(theme: HostTheme): RowPaint {
 	};
 }
 
-/** Region 2 — the content factory. `rule` degrades hr → quoteBorder → plain; every role ends in plain. */
-// shape: closure returning an object literal — trigger #4, four stateless content roles over the captured markdown theme.
-export function createContentPaint(mdTheme: MarkdownTheme): ContentPaint {
+/**
+ * How the header band fills its cell: `"reverse"` swaps the cell's ink and background (SGR reverse
+ * video), `"none"` leaves the bare header. Picked once at construction, so a side-by-side can sweep it.
+ */
+export type BandStyle = "reverse" | "none";
+
+/**
+ * SGR reverse video, on and off. The band is the ONE escape pair that originates here rather than in a
+ * theme: no background token is reachable on the content seam, so the band is built from reverse video,
+ * which needs none and therefore survives a restore that happens before any theme is known.
+ */
+const REVERSE_ON = "\x1b[7m";
+const REVERSE_OFF = "\x1b[27m";
+
+/**
+ * Region 2 — the content factory. `rule` degrades hr → quoteBorder → plain; every role ends in plain.
+ *
+ * The markdown theme's own closures supply the emphasis ink: `bold`/`italic` for inline spans, and its
+ * `code` closure (the `mdCode` token, identical to `accent` in both stock themes) for the header ink.
+ * `bandStyle` picks the header band — `"reverse"` (the default) composes reverse video over the header,
+ * `"none"` leaves it bare — so the one band reachable on this seam is a construction-time choice.
+ */
+// shape: closure returning an object literal — trigger #4, eight stateless content roles over the
+//   captured markdown theme and the band style.
+export function createContentPaint(mdTheme: MarkdownTheme, bandStyle: BandStyle = "reverse"): ContentPaint {
+	// The header ink: the theme's `code` closure under its `bold` closure. Each link is optional and
+	// degrades on its own, so a theme missing one still stamps whatever the other gives.
+	const header = (text: string): string => {
+		const inked = tryStyle(mdTheme.code, text) ?? text;
+		return tryStyle(mdTheme.bold, inked) ?? inked;
+	};
 	return {
 		rule: (text) => tryStyle(mdTheme.hr, text) ?? tryStyle(mdTheme.quoteBorder, text) ?? text,
 		quote: (text) => tryStyle(mdTheme.quote, text) ?? text,
 		code: (text) => tryStyle(mdTheme.code, text) ?? text,
 		codeBlockBorder: (text) => tryStyle(mdTheme.codeBlockBorder, text) ?? text,
+		strong: (text) => tryStyle(mdTheme.bold, text) ?? text,
+		em: (text) => tryStyle(mdTheme.italic, text) ?? text,
+		header,
+		headerBand: (text) => (bandStyle === "reverse" ? `${REVERSE_ON}${header(text)}${REVERSE_OFF}` : header(text)),
 	};
 }

package/src/core/types/host.ts

@@ -32,6 +32,10 @@ export interface MarkdownTheme {
 	code?(text: string): string;
 	/** Fenced-code-block border wrapper. Optional. */
 	codeBlockBorder?(text: string): string;
+	/** Bold wrapper for `**strong**` spans — the host markdown theme's own `bold` closure. Optional. */
+	bold?(text: string): string;
+	/** Italic wrapper for `*em*` spans — the host markdown theme's own `italic` closure. Optional. */
+	italic?(text: string): string;
 }
 
 /** The pi-tui component slice renderers return and receive. Structural host shape — no host import. */

package/src/core/types/paint.ts

@@ -51,4 +51,18 @@ export interface ContentPaint {
 	code(text: string): string;
 	/** Fenced-code-block border. Required. */
 	codeBlockBorder(text: string): string;
+	/** A `**strong**` inline span, drawn in the theme's bold. Required. */
+	strong(text: string): string;
+	/** An `*em*` inline span, drawn in the theme's italic. Required. */
+	em(text: string): string;
+	/**
+	 * One stamped header cell: the accent ink under bold. The ink is the markdown theme's `code` closure
+	 * (`mdCode`, identical to `accent` in both stock themes) and the weight its `bold` closure. Required.
+	 */
+	header(text: string): string;
+	/**
+	 * One header-band cell: {@link header} carrying the band style — reverse video by default, so the
+	 * cell's own ink becomes its background. Required.
+	 */
+	headerBand(text: string): string;
 }

package/src/renderers/content/table.ts

@@ -7,6 +7,10 @@
 /**
  * table.ts — the table surface: a markdown table becomes a banded box.
  *
+ * The header row is stamped through the header-band role — bold over the accent ink inside a band — or,
+ * when the header row is empty (`| | |`), that stamp moves onto the first column so no blank band is
+ * spent. `**strong**` and `*em*` cells route through their own roles.
+ *
  * 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.
  *
@@ -60,15 +64,22 @@ function isTableToken(token: Token): token is Token & TableToken {
 	return Array.isArray(token.rows) && token.rows.every((row) => Array.isArray(row) && row.every(isCell));
 }
 
+/** The inline text a token wraps, already styled by its own children; `token.text` is the fallback. */
+function innerText(token: InlineToken, paint: ContentPaint): string {
+	return (token.tokens ?? []).map((child) => inlineText(child, paint)).join("") || (token.text ?? "");
+}
+
 /** 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":
+			return paint.strong(innerText(token, paint));
 		case "em":
+			return paint.em(innerText(token, paint));
 		case "link":
-			return (token.tokens ?? []).map((child) => inlineText(child, paint)).join("") || (token.text ?? "");
+			return innerText(token, paint);
 		default:
 			return token.text ?? token.raw ?? "";
 	}
@@ -108,6 +119,10 @@ function renderTable(token: TableToken, width: number, paint: ContentPaint): str
 		widths[widest] = (widths[widest] ?? 0) - 1;
 	}
 
+	// An all-empty header (`| | |`) means the table carries its labels in the first column: the blank
+	// header row and its separator are dropped, and the band moves onto that first column instead.
+	const keyColumn = header.every((cell) => cell === "");
+
 	// 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 =>
@@ -115,24 +130,33 @@ function renderTable(token: TableToken, width: number, paint: ContentPaint): str
 	const bar = paint.rule("│");
 	const physical: string[] = [];
 
-	const renderBand = (cells: string[][]): void => {
-		const height = Math.max(1, ...cells.map((wrapped) => wrapped.length));
+	/** One logical row, wrapped into physical lines; `banded` picks the cells drawn through headerBand. */
+	const renderRow = (cells: string[], banded: (index: number) => boolean): void => {
+		const wrapped = cells.map((cell, index) => wrapTextWithAnsi(cell, widths[index] ?? MIN_COLUMN));
+		const height = Math.max(1, ...wrapped.map((lines) => lines.length));
 		for (let line = 0; line < height; line++) {
-			const parts = cells.map((wrapped, index) => ` ${padCell(wrapped[line] ?? "", widths[index] ?? MIN_COLUMN)} `);
+			const parts = wrapped.map((lines, index) => {
+				const padded = padCell(lines[line] ?? "", widths[index] ?? MIN_COLUMN);
+				return banded(index) ? ` ${paint.headerBand(padded)} ` : ` ${padded} `;
+			});
 			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));
-	});
+	if (keyColumn) {
+		rows.forEach((row, index) => {
+			if (index > 0) physical.push(ruleLine("├", "┼", "┤"));
+			renderRow(row, (index) => index === 0);
+		});
+	} else {
+		renderRow(header, () => true);
+		physical.push(ruleLine("├", "┼", "┤"));
+		rows.forEach((row, index) => {
+			if (index > 0) physical.push(ruleLine("├", "┼", "┤"));
+			renderRow(row, () => false);
+		});
+	}
 	physical.push(ruleLine("└", "┴", "┘"));
 	return physical.map((line) => (visibleWidth(line) > width ? truncateToWidth(line, width) : line));
 }