@diegopetrucci/pi-annotate-last-message 0.1.8 → 0.1.10

package/.pi-fleet-tested-version

@@ -1 +1 @@
-0.84.2
+0.84.4

package/README.md

@@ -22,7 +22,15 @@ Run `/annotate-last-message` from an interactive pi session. The annotation wind
 - section comments for larger chunks of the message, and
 - inline notes tied to individual lines.
 
-When you submit, the extension appends a structured planning-oriented feedback prompt to the current editor buffer. It does not auto-apply changes or rewrite the previous assistant message in place.
+The message preview renders headings, lists, blockquotes, emphasis, inline code, strikethrough, links, and fenced code while preserving the original one-based source-line coordinates. Raw HTML is displayed as text. Link destinations are shown as inert text beside the label; the window never navigates to an assistant-provided URL.
+
+The window follows the active Pi theme through `ctx.ui.theme`, including Markdown colors and dark/light appearance, with readable local fallbacks when a theme token is unavailable. Opening the window does not change Pi's host theme or settings.
+
+When you submit, the extension sends a structured planning-oriented feedback prompt directly to the agent as a follow-up message. Your existing editor text is left untouched. It does not auto-apply changes or rewrite the previous assistant message in place.
+
+## Rollback
+
+There is no runtime setting or toggle for submit behavior. To roll back the rendering/theme change, reinstall the previous package version or revert this source change and rebuild/reinstall the package; no Pi theme or host setting needs to be restored.
 
 ## Requirements
 

package/index.ts

@@ -3,30 +3,72 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { openQuietGlimpse, type QuietGlimpseWindow } from "./quiet-glimpse.js";
 import { composeAnnotateLastMessagePrompt, hasAnnotateLastMessageFeedback } from "./prompt.js";
 import { findLastAssistantMessage } from "./session.js";
-import type { AnnotateLastMessageCancelPayload, AnnotateLastMessageSubmitPayload, AnnotateLastMessageWindowMessage, LastAssistantMessageData } from "./types.js";
+import type {
+	AnnotateLastMessageCancelPayload,
+	AnnotateLastMessageInlineComment,
+	AnnotateLastMessageSectionComment,
+	AnnotateLastMessageSubmitPayload,
+	AnnotateLastMessageWindowMessage,
+	LastAssistantMessageData,
+} from "./types.js";
 import { buildAnnotateLastMessageHtml } from "./ui.js";
 
+function isInlineComment(value: unknown): value is AnnotateLastMessageInlineComment {
+	return (
+		typeof value === "object" &&
+		value != null &&
+		"line" in value &&
+		typeof value.line === "number" &&
+		Number.isInteger(value.line) &&
+		value.line > 0 &&
+		"body" in value &&
+		typeof value.body === "string"
+	);
+}
+
+function isSectionComment(value: unknown): value is AnnotateLastMessageSectionComment {
+	return (
+		typeof value === "object" &&
+		value != null &&
+		"sectionId" in value &&
+		typeof value.sectionId === "string" &&
+		"body" in value &&
+		typeof value.body === "string"
+	);
+}
+
 function isSubmitPayload(value: unknown): value is AnnotateLastMessageSubmitPayload {
-	return typeof value === "object" && value != null && "type" in value && value.type === "submit";
+	return (
+		typeof value === "object" &&
+		value != null &&
+		"type" in value &&
+		value.type === "submit" &&
+		"overallComment" in value &&
+		typeof value.overallComment === "string" &&
+		"inlineComments" in value &&
+		Array.isArray(value.inlineComments) &&
+		value.inlineComments.every(isInlineComment) &&
+		"sectionComments" in value &&
+		Array.isArray(value.sectionComments) &&
+		value.sectionComments.every(isSectionComment)
+	);
 }
 
 function isCancelPayload(value: unknown): value is AnnotateLastMessageCancelPayload {
 	return typeof value === "object" && value != null && "type" in value && value.type === "cancel";
 }
 
-function appendPrompt(ctx: ExtensionCommandContext, prompt: string): void {
-	const prefix = ctx.ui.getEditorText().trim().length > 0 ? "\n\n" : "";
-	ctx.ui.pasteToEditor(`${prefix}${prompt}`);
-}
-
 export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 	let activeWindow: QuietGlimpseWindow | null = null;
+	let annotationOpening = false;
+	let annotationAttempt = 0;
 	const suppressedWindows = new WeakSet<QuietGlimpseWindow>();
 
 	function closeActiveWindow(options: { suppressResults?: boolean } = {}): void {
-		if (activeWindow == null) return;
+		annotationAttempt += 1;
 		const windowToClose = activeWindow;
 		activeWindow = null;
+		if (windowToClose == null) return;
 		if (options.suppressResults) {
 			suppressedWindows.add(windowToClose);
 		}
@@ -42,7 +84,7 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 			ctx.ui.notify("annotate-last-message requires interactive mode.", "error");
 			return;
 		}
-		if (activeWindow != null) {
+		if (annotationOpening || activeWindow != null) {
 			ctx.ui.notify("A last-message annotation window is already open.", "warning");
 			return;
 		}
@@ -54,21 +96,38 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 		}
 
 		const messageData = messageResult.data;
+		annotationOpening = true;
+		const attempt = ++annotationAttempt;
 
 		try {
-			const html = buildAnnotateLastMessageHtml(messageData);
+			const html = buildAnnotateLastMessageHtml(messageData, ctx.ui.theme);
 			const window = await openQuietGlimpse(html, {
 				width: 1440,
 				height: 980,
 				title: "annotate last message",
 			});
+			if (attempt !== annotationAttempt) {
+				suppressedWindows.add(window);
+				window.close();
+				return;
+			}
 			activeWindow = window;
+			if (window.failure != null) throw window.failure;
+			if (window.closed) throw new Error("Glimpse closed while the annotation window was starting.");
 
 			const terminalMessagePromise = new Promise<AnnotateLastMessageSubmitPayload | AnnotateLastMessageCancelPayload | null>(
 				(resolve, reject) => {
 					let settled = false;
 					let closeTimer: ReturnType<typeof setTimeout> | null = null;
 
+					const requestWindowClose = (): void => {
+						try {
+							window.close();
+						} catch {
+							// Ignore races when the native process has already exited.
+						}
+					};
+
 					const cleanup = (): void => {
 						if (closeTimer != null) {
 							clearTimeout(closeTimer);
@@ -92,6 +151,7 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 					const onMessage = (data: unknown): void => {
 						if (isSubmitPayload(data) || isCancelPayload(data)) {
 							settle(data);
+							requestWindowClose();
 						}
 					};
 
@@ -106,6 +166,7 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 					const onError = (error: Error): void => {
 						if (settled) return;
 						settled = true;
+						requestWindowClose();
 						cleanup();
 						reject(error);
 					};
@@ -113,13 +174,15 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 					window.on("message", onMessage);
 					window.on("closed", onClosed);
 					window.on("error", onError);
+					if (window.failure != null) onError(window.failure);
+					else if (window.closed) onClosed();
 				},
 			);
 
 			void (async (windowMessageSource: QuietGlimpseWindow, sourceData: LastAssistantMessageData) => {
 				try {
 					const result = await terminalMessagePromise;
-					if (suppressedWindows.has(windowMessageSource)) return;
+					if (suppressedWindows.has(windowMessageSource) || attempt !== annotationAttempt) return;
 					if (result == null) return;
 					if (result.type === "cancel") {
 						ctx.ui.notify("Annotation cancelled.", "info");
@@ -131,10 +194,10 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 					}
 
 					const prompt = composeAnnotateLastMessagePrompt(sourceData, result);
-					appendPrompt(ctx, prompt);
-					ctx.ui.notify("Appended annotation feedback to the editor.", "info");
+					pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+					ctx.ui.notify("Annotation feedback sent to the agent.", "info");
 				} catch (error) {
-					if (suppressedWindows.has(windowMessageSource)) return;
+					if (suppressedWindows.has(windowMessageSource) || attempt !== annotationAttempt) return;
 					const message = error instanceof Error ? error.message : String(error);
 					ctx.ui.notify(`Annotation failed: ${message}`, "error");
 				}
@@ -142,9 +205,12 @@ export function registerAnnotateLastMessageCommand(pi: ExtensionAPI): void {
 
 			ctx.ui.notify("Opened native annotation window.", "info");
 		} catch (error) {
+			if (attempt !== annotationAttempt) return;
 			closeActiveWindow({ suppressResults: true });
 			const message = error instanceof Error ? error.message : String(error);
 			ctx.ui.notify(`Annotation failed: ${message}`, "error");
+		} finally {
+			annotationOpening = false;
 		}
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegopetrucci/pi-annotate-last-message",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "A standalone pi extension that adds /annotate-last-message, a native Glimpse UI for annotating the latest assistant reply.",
   "keywords": [
     "pi-package",
@@ -20,6 +20,7 @@
     "prompt.ts",
     "quiet-glimpse.ts",
     "session.ts",
+    "theme.ts",
     "types.ts",
     "ui.ts",
     "web",

package/quiet-glimpse.ts

@@ -23,6 +23,8 @@ interface GlimpseProtocolMessage {
 }
 
 export interface QuietGlimpseWindow {
+	readonly closed: boolean;
+	readonly failure: Error | null;
 	on(event: "message", listener: (data: unknown) => void): this;
 	on(event: "closed", listener: () => void): this;
 	on(event: "error", listener: (error: Error) => void): this;
@@ -38,11 +40,15 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 	#closed = false;
 	#pendingHTML: string | null;
 	#stderr = "";
+	#failure: Error | null = null;
 
 	constructor(proc: ChildProcessWithoutNullStreams, initialHTML: string) {
 		super();
 		this.#proc = proc;
 		this.#pendingHTML = initialHTML;
+		// EventEmitter treats an unobserved `error` as fatal. Keep a permanent
+		// fallback while callers attach and detach their lifecycle listeners.
+		this.on("error", () => {});
 
 		proc.stdin.on("error", () => {});
 		proc.stderr.on("data", (chunk) => {
@@ -51,13 +57,15 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 
 		const rl = createInterface({ input: proc.stdout, crlfDelay: Infinity });
 		rl.on("line", (line) => {
-			let message: GlimpseProtocolMessage;
+			let parsed: unknown;
 			try {
-				message = JSON.parse(line) as GlimpseProtocolMessage;
+				parsed = JSON.parse(line);
 			} catch {
-				this.emit("error", new Error(`Malformed glimpse protocol line: ${line}`));
+				this.#reportError(new Error(`Malformed glimpse protocol line: ${line}`));
 				return;
 			}
+			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return;
+			const message = parsed as GlimpseProtocolMessage;
 
 			switch (message.type) {
 				case "ready":
@@ -77,16 +85,18 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 			}
 		});
 
-		proc.on("error", (error) => this.emit("error", error));
+		proc.on("error", (error) => this.#reportError(error));
 		proc.on("exit", (code, signal) => {
 			const stderr = this.#stderr.trim();
 			const failed = signal != null || (code != null && code !== 0);
 			if (!this.#closed && failed) {
 				const message = stderr || `Glimpse process exited abnormally (code: ${code}, signal: ${signal}).`;
-				this.emit("error", new Error(message));
+				this.#reportError(new Error(message));
 			}
 			this.#markClosed();
 		});
+		// Spawn failures can emit `error` and then `close` without `exit`.
+		proc.on("close", () => this.#markClosed());
 	}
 
 	send(js: string): void {
@@ -97,6 +107,19 @@ class QuietGlimpseWindowImpl extends EventEmitter implements QuietGlimpseWindow
 		this.#write({ type: "close" });
 	}
 
+	get closed(): boolean {
+		return this.#closed;
+	}
+
+	get failure(): Error | null {
+		return this.#failure;
+	}
+
+	#reportError(error: Error): void {
+		this.#failure ??= error;
+		this.emit("error", error);
+	}
+
 	#markClosed(): void {
 		if (this.#closed) return;
 		this.#closed = true;

package/theme.ts

@@ -0,0 +1,247 @@
+import type {
+	Theme,
+	ThemeBg,
+	ThemeColor,
+} from "@earendil-works/pi-coding-agent";
+
+/**
+ * The small public part of Pi's active theme used by the native annotation UI.
+ * The command passes ctx.ui.theme directly; no Pi theme singleton is imported.
+ */
+export type AnnotateTheme = Pick<Theme, "appearance" | "colors" | "fg" | "bg">;
+
+const DARK_FALLBACK: Readonly<Record<string, string>> = {
+	"--color-scheme": "dark",
+	"--bg": "#0d1117",
+	"--panel": "#151b23",
+	"--panel-hover": "#1f242c",
+	"--inset": "#0b1118",
+	"--border": "#30363d",
+	"--border-muted": "#21262d",
+	"--text": "#f0f6fc",
+	"--muted": "#8a8a8a",
+	"--dim": "#585858",
+	"--accent": "#f4c95d",
+	"--success": "#7ee787",
+	"--error": "#ffb3b3",
+	"--warning": "#f4c95d",
+	"--mdHeading": "#f4c95d",
+	"--mdLink": "#7dd3fc",
+	"--mdLinkUrl": "#8a8a8a",
+	"--mdCode": "#9b7bff",
+	"--mdCodeBlock": "inherit",
+	"--mdCodeBlockBorder": "#6f42c1",
+	"--mdQuote": "#8a8a8a",
+	"--mdQuoteBorder": "#6f42c1",
+	"--mdHr": "#585858",
+	"--mdListBullet": "#f4c95d",
+	"--mdBold": "inherit",
+	"--mdItalic": "inherit",
+};
+
+const LIGHT_FALLBACK: Readonly<Record<string, string>> = {
+	"--color-scheme": "light",
+	"--bg": "#f6f8fa",
+	"--panel": "#ffffff",
+	"--panel-hover": "#f3f4f6",
+	"--inset": "#f6f8fa",
+	"--border": "#d0d7de",
+	"--border-muted": "#afb8c1",
+	"--text": "#1f2328",
+	"--muted": "#57606a",
+	"--dim": "#6e7781",
+	"--accent": "#8250df",
+	"--success": "#1a7f37",
+	"--error": "#cf222e",
+	"--warning": "#9a6700",
+	"--mdHeading": "#9a6700",
+	"--mdLink": "#0969da",
+	"--mdLinkUrl": "#57606a",
+	"--mdCode": "#8250df",
+	"--mdCodeBlock": "#1a7f37",
+	"--mdCodeBlockBorder": "#6e7781",
+	"--mdQuote": "#57606a",
+	"--mdQuoteBorder": "#6e7781",
+	"--mdHr": "#8c959f",
+	"--mdListBullet": "#8250df",
+	"--mdBold": "inherit",
+	"--mdItalic": "inherit",
+};
+
+const BASIC_ANSI_COLORS: Readonly<Record<number, string>> = {
+	0: "#000000",
+	1: "#800000",
+	2: "#008000",
+	3: "#808000",
+	4: "#000080",
+	5: "#800080",
+	6: "#008080",
+	7: "#c0c0c0",
+	8: "#808080",
+	9: "#ff0000",
+	10: "#00ff00",
+	11: "#ffff00",
+	12: "#0000ff",
+	13: "#ff00ff",
+	14: "#00ffff",
+	15: "#ffffff",
+};
+
+const CUBE_LEVELS = [0, 95, 135, 175, 215, 255] as const;
+const SENTINEL = "X";
+
+const FOREGROUND_THEME_VARS: ReadonlyArray<{ token: ThemeColor; cssVar: string }> = [
+	{ token: "text", cssVar: "--text" },
+	{ token: "muted", cssVar: "--muted" },
+	{ token: "dim", cssVar: "--dim" },
+	{ token: "accent", cssVar: "--accent" },
+	{ token: "success", cssVar: "--success" },
+	{ token: "error", cssVar: "--error" },
+	{ token: "warning", cssVar: "--warning" },
+	{ token: "mdHeading", cssVar: "--mdHeading" },
+	{ token: "mdLink", cssVar: "--mdLink" },
+	{ token: "mdLinkUrl", cssVar: "--mdLinkUrl" },
+	{ token: "mdCode", cssVar: "--mdCode" },
+	{ token: "mdCodeBlock", cssVar: "--mdCodeBlock" },
+	{ token: "mdCodeBlockBorder", cssVar: "--mdCodeBlockBorder" },
+	{ token: "mdQuote", cssVar: "--mdQuote" },
+	{ token: "mdQuoteBorder", cssVar: "--mdQuoteBorder" },
+	{ token: "mdHr", cssVar: "--mdHr" },
+	{ token: "mdListBullet", cssVar: "--mdListBullet" },
+	{ token: "border", cssVar: "--border" },
+	{ token: "borderMuted", cssVar: "--border-muted" },
+];
+
+const BACKGROUND_THEME_VARS: ReadonlyArray<{ token: ThemeBg; cssVar: string }> = [
+	{ token: "customMessageBg", cssVar: "--panel" },
+	{ token: "selectedBg", cssVar: "--panel-hover" },
+	{ token: "toolPendingBg", cssVar: "--inset" },
+];
+
+function toHex(value: number): string {
+	const clamped = Math.min(255, Math.max(0, Math.round(value)));
+	return clamped.toString(16).padStart(2, "0");
+}
+
+function xterm256ToHex(index: number): string | null {
+	if (!Number.isInteger(index) || index < 0 || index > 255) return null;
+	if (index < 16) return BASIC_ANSI_COLORS[index] ?? null;
+	if (index >= 232) {
+		const value = 8 + (index - 232) * 10;
+		const hex = toHex(value);
+		return `#${hex}${hex}${hex}`;
+	}
+	const cubeIndex = index - 16;
+	const blue = cubeIndex % 6;
+	const green = Math.floor(cubeIndex / 6) % 6;
+	const red = Math.floor(cubeIndex / 36) % 6;
+	return `#${toHex(CUBE_LEVELS[red])}${toHex(CUBE_LEVELS[green])}${toHex(CUBE_LEVELS[blue])}`;
+}
+
+function colorValueToHex(value: unknown): string | null {
+	if (typeof value !== "object" || value == null) return null;
+	const color = value as { kind?: unknown; r?: unknown; g?: unknown; b?: unknown; index?: unknown };
+	if (color.kind === "rgb") {
+		const channels = [color.r, color.g, color.b];
+		if (!channels.every((channel) => typeof channel === "number" && Number.isFinite(channel) && channel >= 0 && channel <= 255)) {
+			return null;
+		}
+		return `#${toHex(color.r as number)}${toHex(color.g as number)}${toHex(color.b as number)}`;
+	}
+	if (color.kind === "indexed" && typeof color.index === "number") {
+		return xterm256ToHex(color.index);
+	}
+	// OKLCH values are intentionally handled through theme.fg/theme.bg below.
+	// Those public helpers account for Pi's configured terminal color mode.
+	return null;
+}
+
+function ansiColorToHex(value: unknown, background: boolean): string | null {
+	if (typeof value !== "string") return null;
+	const match = new RegExp(`^\\u001b\\[([0-9;]+)m`).exec(value);
+	if (!match) return null;
+	const params = match[1].split(";").map(Number);
+	const [mode, kind, first, second, third] = params;
+	const expectedMode = background ? 48 : 38;
+	if (mode !== expectedMode) {
+		if (!background && ((mode >= 30 && mode <= 37) || (mode >= 90 && mode <= 97))) {
+			return xterm256ToHex(mode >= 90 ? mode - 82 : mode - 30);
+		}
+		if (background && ((mode >= 40 && mode <= 47) || (mode >= 100 && mode <= 107))) {
+			return xterm256ToHex(mode >= 100 ? mode - 92 : mode - 40);
+		}
+		return null;
+	}
+	if (kind === 2 && params.length >= 5) {
+		const channels = [first, second, third];
+		if (!channels.every((channel) => Number.isInteger(channel) && channel >= 0 && channel <= 255)) return null;
+		return `#${toHex(first)}${toHex(second)}${toHex(third)}`;
+	}
+	if (kind === 5 && params.length >= 3) return xterm256ToHex(first);
+	return null;
+}
+
+function readThemeColor(theme: AnnotateTheme, token: ThemeColor | ThemeBg, background: boolean): string | null {
+	let colors: Readonly<Record<string, unknown>> | undefined;
+	try {
+		colors = theme.colors as Readonly<Record<string, unknown>>;
+	} catch {
+		colors = undefined;
+	}
+
+	let colorValue: unknown;
+	try {
+		colorValue = colors?.[token];
+	} catch {
+		colorValue = undefined;
+	}
+	const fromColors = colorValueToHex(colorValue);
+	if (fromColors != null) return fromColors;
+
+	try {
+		const styled = background
+			? theme.bg(token as ThemeBg, SENTINEL)
+			: theme.fg(token as ThemeColor, SENTINEL);
+		return ansiColorToHex(styled, background);
+	} catch {
+		return null;
+	}
+}
+
+function readAppearance(theme: AnnotateTheme | null | undefined): "dark" | "light" {
+	try {
+		return theme?.appearance === "light" ? "light" : "dark";
+	} catch {
+		return "dark";
+	}
+}
+
+/**
+ * Build safe CSS custom properties from the active Pi theme.
+ *
+ * Every value is either a local fallback or a validated hex color. Theme
+ * getters are isolated per token so one broken custom theme cannot make the
+ * native annotation window unreadable or prevent it from opening.
+ */
+export function getThemeCssVars(theme?: AnnotateTheme | null): Record<string, string> {
+	const vars: Record<string, string> = {
+		...(readAppearance(theme) === "light" ? LIGHT_FALLBACK : DARK_FALLBACK),
+	};
+	if (theme == null) return vars;
+
+	for (const { token, cssVar } of FOREGROUND_THEME_VARS) {
+		const color = readThemeColor(theme, token, false);
+		if (color != null) vars[cssVar] = color;
+	}
+	for (const { token, cssVar } of BACKGROUND_THEME_VARS) {
+		const color = readThemeColor(theme, token, true);
+		if (color != null) vars[cssVar] = color;
+	}
+	return vars;
+}
+
+export const __testing = {
+	ansiColorToHex,
+	colorValueToHex,
+	xterm256ToHex,
+};

package/ui.ts

@@ -2,6 +2,8 @@ import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import type { AnnotateTheme } from "./theme.js";
+import { getThemeCssVars } from "./theme.js";
 import type { LastAssistantMessageData } from "./types.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -15,9 +17,33 @@ function escapeInlineScriptSource(value: string): string {
 	return value.replace(/<\/(script)/gi, "<\\/$1");
 }
 
-export function buildAnnotateLastMessageHtml(data: LastAssistantMessageData): string {
+function buildThemeCssBlock(vars: Record<string, string>): string {
+	const declarations = Object.entries(vars)
+		.map(([key, value]) => `  ${key}: ${value};`)
+		.join("\n");
+	return `:root {\n${declarations}\n}`;
+}
+
+export function buildAnnotateLastMessageHtml(
+	data: LastAssistantMessageData,
+	theme?: AnnotateTheme,
+): string {
 	const templateHtml = readFileSync(join(webDir, "index.html"), "utf8");
+	const mdRendererJs = escapeInlineScriptSource(readFileSync(join(webDir, "md-renderer.js"), "utf8"));
 	const appJs = escapeInlineScriptSource(readFileSync(join(webDir, "app.js"), "utf8"));
 	const payload = escapeForInlineScript(JSON.stringify(data));
-	return templateHtml.replace('"__INLINE_DATA__"', payload).replace("__INLINE_JS__", appJs);
+	const themeBlock = buildThemeCssBlock(getThemeCssVars(theme));
+	const replacements = new Map([
+		['"__INLINE_DATA__"', payload],
+		["__INLINE_MD_RENDERER_JS__", mdRendererJs],
+		["__INLINE_JS__", appJs],
+		["__INLINE_THEME__", themeBlock],
+	]);
+
+	// Replace the original template in one pass so marker-like message data,
+	// theme values, or runtime source is never scanned as another placeholder.
+	return templateHtml.replace(
+		/"__INLINE_DATA__"|__INLINE_MD_RENDERER_JS__|__INLINE_JS__|__INLINE_THEME__/g,
+		(marker) => replacements.get(marker) ?? marker,
+	);
 }