@zenodinh/pi-render 0.1.3 → 0.1.4

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.4"
 }