mulmocast 2.9.2 → 2.11.0

package/lib/utils/element_id.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The rule for element ids that generated markup interpolates. Pure — no Node, no
+ * filesystem — because the Node render path and the browser fragment path build the same
+ * markup and must agree on it.
+ *
+ * This enumerates what is PERMITTED rather than escaping what is not. An id drawn from this
+ * set is safe in every context the markup uses it in — an HTML attribute, a JavaScript
+ * string literal inside a `<script>` where HTML entities are not decoded, a CSS selector, a
+ * URL fragment — so a new context cannot introduce a hole the way a per-context escaper can.
+ * Escaping would also have to keep the contexts in sync: entity-escaping `<canvas id>` while
+ * the `getElementById` beside it stays raw makes the two disagree and the lookup fail.
+ *
+ * The leading character is restricted because a CSS id selector is the strictest of those
+ * contexts. Measured in a browser: `querySelector("#0")`, `"#-"`, `"#0a"` and `"#-0"` all
+ * throw, while `getElementById` accepts every one of them — so an id that works today can
+ * still be unusable the moment anything reaches for it with a selector. This set is a little
+ * narrower than CSS allows (it rejects `-a`, which is valid) in exchange for being stateable
+ * in one line.
+ */
+export declare const isSafeElementId: (id: string) => boolean;
+/**
+ * Throws unless the id is safe in every context. A caller reaching this with a bad id has a
+ * bug, not bad user input: values that come from a script have to be turned into an id
+ * before they get here.
+ */
+export declare const assertSafeElementId: (id: string) => void;

package/lib/utils/element_id.js

@@ -0,0 +1,31 @@
+import { SAFE_ELEMENT_ID } from "../types/const.js";
+/**
+ * The rule for element ids that generated markup interpolates. Pure — no Node, no
+ * filesystem — because the Node render path and the browser fragment path build the same
+ * markup and must agree on it.
+ *
+ * This enumerates what is PERMITTED rather than escaping what is not. An id drawn from this
+ * set is safe in every context the markup uses it in — an HTML attribute, a JavaScript
+ * string literal inside a `<script>` where HTML entities are not decoded, a CSS selector, a
+ * URL fragment — so a new context cannot introduce a hole the way a per-context escaper can.
+ * Escaping would also have to keep the contexts in sync: entity-escaping `<canvas id>` while
+ * the `getElementById` beside it stays raw makes the two disagree and the lookup fail.
+ *
+ * The leading character is restricted because a CSS id selector is the strictest of those
+ * contexts. Measured in a browser: `querySelector("#0")`, `"#-"`, `"#0a"` and `"#-0"` all
+ * throw, while `getElementById` accepts every one of them — so an id that works today can
+ * still be unusable the moment anything reaches for it with a selector. This set is a little
+ * narrower than CSS allows (it rejects `-a`, which is valid) in exchange for being stateable
+ * in one line.
+ */
+export const isSafeElementId = (id) => SAFE_ELEMENT_ID.test(id);
+/**
+ * Throws unless the id is safe in every context. A caller reaching this with a bad id has a
+ * bug, not bad user input: values that come from a script have to be turned into an id
+ * before they get here.
+ */
+export const assertSafeElementId = (id) => {
+    if (!isSafeElementId(id)) {
+        throw new Error(`element id must match ${SAFE_ELEMENT_ID.source}, got ${JSON.stringify(id)}. Derive it from the beat's index (beat-3, not 3 — it must not start with a digit), or sanitize the beat's id, before passing it.`);
+    }
+};

package/lib/utils/html_escape.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Escaping for JSON embedded in an inline script. Pure — no Node, no filesystem — because the
+ * Node render path and the browser fragment path embed the same values and must neutralize
+ * them the same way.
+ *
+ * HTML text and attributes are handled by escapeHtml from @mulmocast/deck; this module exists
+ * only for the inline-script context, which that helper does not cover.
+ *
+ * The lookup goes through a Map rather than an object literal so a value naming an
+ * Object.prototype member cannot resolve through the prototype chain.
+ */
+/** Neutralize the output of JSON.stringify for embedding inside an inline `<script>`. */
+export declare const escapeJsonForScript: (json: string) => string;
+export declare const neutralizeStyleTerminator: (css: string) => string;

package/lib/utils/html_escape.js

@@ -0,0 +1,30 @@
+/**
+ * Escaping for JSON embedded in an inline script. Pure — no Node, no filesystem — because the
+ * Node render path and the browser fragment path embed the same values and must neutralize
+ * them the same way.
+ *
+ * HTML text and attributes are handled by escapeHtml from @mulmocast/deck; this module exists
+ * only for the inline-script context, which that helper does not cover.
+ *
+ * The lookup goes through a Map rather than an object literal so a value naming an
+ * Object.prototype member cannot resolve through the prototype chain.
+ */
+// JSON.stringify emits these only from inside string literals, so replacing them with their
+// \u escapes leaves the parsed value identical while stopping `</script>` from terminating the
+// block the JSON is embedded in. U+2028 / U+2029 are valid JSON output but were line
+// terminators in JavaScript source before ES2019.
+const SCRIPT_JSON_ESCAPES = new Map([
+    ["<", "\\u003c"],
+    [">", "\\u003e"],
+    ["&", "\\u0026"],
+    ["\u2028", "\\u2028"],
+    ["\u2029", "\\u2029"],
+]);
+/** Neutralize the output of JSON.stringify for embedding inside an inline `<script>`. */
+export const escapeJsonForScript = (json) => json.replace(/[<>&\u2028\u2029]/g, (character) => SCRIPT_JSON_ESCAPES.get(character) ?? character);
+// A <style> element holds raw text: nothing inside it is parsed as markup except the closing
+// tag, so `</style` is the only sequence that can end it. Neutralizing just that keeps
+// author-supplied CSS working, which escaping the whole string would not. `\3c ` is the CSS
+// escape for `<`, and the matched text is carried through unchanged so a `</STYLE>` written
+// inside a CSS string keeps its casing as well as its value.
+export const neutralizeStyleTerminator = (css) => css.replace(/<\/style/gi, (terminator) => `\\3c ${terminator.slice(1)}`);

package/lib/utils/image_plugins/beat.d.ts

@@ -1,5 +1,5 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { BeatPathParams, ImageProcessorParams } from "../../types/index.js";
 export declare const imageType = "beat";
 export declare const processBeatReference: (__: ImageProcessorParams) => Promise<undefined>;
 export declare const process: (__: ImageProcessorParams) => Promise<undefined>;
-export declare const path: (__: ImageProcessorParams) => undefined;
+export declare const path: (__: BeatPathParams) => undefined;

package/lib/utils/image_plugins/bg_image_util.d.ts

@@ -5,9 +5,12 @@ import { BackgroundImage, MulmoStudioContext, ImageProcessorParams } from "../..
  * null explicitly disables background image.
  */
 export declare const resolveBackgroundImage: (beatBackgroundImage: BackgroundImage | undefined, globalBackgroundImage: BackgroundImage | undefined) => BackgroundImage | undefined;
+/** The background image comes from the script, the style from the beat; the paths and sizes `process()` needs are not read here. */
+type CombinedStyleParams = Pick<ImageProcessorParams, "context" | "textSlideStyle">;
 /**
  * Resolve combined style from background image and custom style.
  * Common pattern used by markdown, textSlide, mermaid plugins.
  */
-export declare const resolveCombinedStyle: (params: ImageProcessorParams, beatBackgroundImage: BackgroundImage | undefined, beatStyle: string | undefined) => Promise<string>;
+export declare const resolveCombinedStyle: (params: CombinedStyleParams, beatBackgroundImage: BackgroundImage | undefined, beatStyle: string | undefined) => Promise<string>;
 export declare const backgroundImageToCSS: (backgroundImage: BackgroundImage | undefined, context: MulmoStudioContext) => Promise<string>;
+export {};

package/lib/utils/image_plugins/bg_image_util.js

@@ -1,6 +1,7 @@
 import { MulmoMediaSourceMethods } from "../../methods/mulmo_media_source.js";
 import { resolveStyle } from "./utils.js";
 import { safeFetch, DEFAULT_FETCH_TIMEOUT_MS } from "../fetch.js";
+import { neutralizeStyleTerminator } from "../html_escape.js";
 /**
  * Resolve background image from beat level and global level settings.
  * Beat level takes precedence over global level.
@@ -50,7 +51,7 @@ export const resolveCombinedStyle = async (params, beatBackgroundImage, beatStyl
     const resolvedBackgroundImage = resolveBackgroundImage(beatBackgroundImage, globalBackgroundImage);
     const backgroundCSS = await backgroundImageToCSS(resolvedBackgroundImage, context);
     const style = resolveStyle(beatStyle, textSlideStyle);
-    return backgroundCSS + style;
+    return neutralizeStyleTerminator(backgroundCSS + style);
 };
 export const backgroundImageToCSS = async (backgroundImage, context) => {
     if (!backgroundImage) {

package/lib/utils/image_plugins/chart.d.ts

@@ -1,5 +1,5 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { BeatRenderParams, ImageProcessorParams } from "../../types/index.js";
 export declare const imageType = "chart";
 export declare const process: (params: ImageProcessorParams) => Promise<string | undefined>;
-export declare const path: (params: ImageProcessorParams) => string;
-export declare const html: (params: ImageProcessorParams) => Promise<string | undefined>;
+export declare const path: (params: import("../../types/type.js").BeatPathParams) => string;
+export declare const html: (params: BeatRenderParams) => Promise<string | undefined>;

package/lib/utils/image_plugins/chart.js

@@ -2,19 +2,8 @@ import { getHTMLFile } from "../file.js";
 import { renderHTMLToImage, interpolate } from "../html_render.js";
 import { parrotingImagePath, generateUniqueId } from "./utils.js";
 import { resolveCombinedStyle } from "./bg_image_util.js";
+import { chartHtml, escapedChartTemplateValues, resolveChartPlugins, stringifyChartData } from "./chart_html.js";
 export const imageType = "chart";
-/** Chart.js plugin CDN URLs keyed by chart type */
-const CHART_PLUGIN_CDNS = {
-    sankey: "https://cdn.jsdelivr.net/npm/chartjs-chart-sankey",
-    treemap: "https://cdn.jsdelivr.net/npm/chartjs-chart-treemap@3",
-};
-/** Resolve CDN script tags for Chart.js plugins based on chart type */
-const resolveChartPlugins = (chartType) => {
-    const cdn = CHART_PLUGIN_CDNS[chartType];
-    if (!cdn)
-        return "";
-    return `<script src="${cdn}"></script>`;
-};
 const processChart = async (params) => {
     const { beat, imagePath, canvasSize } = params;
     if (!beat.image || beat.image.type !== imageType)
@@ -25,10 +14,9 @@ const processChart = async (params) => {
     const combinedStyle = await resolveCombinedStyle(params, beat.image.backgroundImage, beat.image.style);
     const template = getHTMLFile("chart");
     const htmlData = interpolate(template, {
-        title: beat.image.title,
+        ...escapedChartTemplateValues(beat.image.title, beat.image.chartData),
         style: combinedStyle,
         chart_width: chart_width.toString(),
-        chart_data: JSON.stringify(beat.image.chartData),
         chart_plugins: resolveChartPlugins(chartType),
     });
     await renderHTMLToImage(htmlData, imagePath, canvasSize.width, canvasSize.height);
@@ -38,22 +26,10 @@ const dumpHtml = async (params) => {
     const { beat } = params;
     if (!beat.image || beat.image.type !== imageType)
         return;
-    const chartData = JSON.stringify(beat.image.chartData, null, 2);
-    const title = beat.image.title || "Chart";
-    const chartId = generateUniqueId("chart");
-    return `
-<div class="chart-container mb-6">
-  <h3 class="text-xl font-semibold mb-4">${title}</h3>
-  <div class="w-full" style="position: relative; height: 400px;">
-    <canvas id="${chartId}"></canvas>
-  </div>
-  <script>
-    (function() {
-      const ctx = document.getElementById('${chartId}').getContext('2d');
-      new Chart(ctx, ${chartData});
-    })();
-  </script>
-</div>`;
+    // main と同じ評価順（stringify → title 読み取り → id 生成）を保つ。引数式は本体より先に
+    // 評価されるので、stringify を wrapper 側でやらないと throw / getter の順序が入れ替わる。
+    const chartDataJson = stringifyChartData(beat.image.chartData);
+    return chartHtml(chartDataJson, beat.image.title, generateUniqueId("chart"));
 };
 export const process = processChart;
 export const path = parrotingImagePath;

package/lib/utils/image_plugins/chart_html.d.ts

@@ -0,0 +1,24 @@
+import type { MulmoChartMedia } from "../../types/index.js";
+/** Resolve CDN script tags for Chart.js plugins based on chart type */
+export declare const resolveChartPlugins: (chartType: string) => string;
+export declare const stringifyChartData: (chartData: MulmoChartMedia["chartData"]) => string;
+/** For a standalone document, where the inline script runs. */
+export declare const chartHtml: (chartDataJson: string, title: string, chartId: string) => string;
+/**
+ * For a host that injects the markup into its own page, where an injected `<script>`
+ * neither survives sanitizing nor executes via innerHTML. The config rides on the canvas
+ * instead, in the shape `@mulmocast/deck` already uses so one host runtime drives both.
+ */
+export declare const chartFragmentHtml: (chartData: MulmoChartMedia["chartData"], title: string, chartId: string) => string;
+/** `chartData` is a free record, so the type may be absent or not a string. */
+export declare const chartTypeOf: (chartData: MulmoChartMedia["chartData"]) => string;
+/** The Chart.js plugin CDNs a chart type needs, for a host that loads them once per page. */
+export declare const chartPluginCdns: (chartType: string) => string[];
+/**
+ * The two values the PNG/PDF/movie template interpolates from user data, escaped for the
+ * contexts it drops them into: `<h1>${title}</h1>` and `const chartData = ${chart_data};`.
+ */
+export declare const escapedChartTemplateValues: (title: string, chartData: MulmoChartMedia["chartData"]) => {
+    title: string;
+    chart_data: string;
+};

package/lib/utils/image_plugins/chart_html.js

@@ -0,0 +1,81 @@
+// Deep import: the package barrel pulls in every layout and all of zod, which measured
+// 551kb against 1.5kb for this file, and the browser fragment path bundles this module.
+import { escapeHtml } from "@mulmocast/deck/lib/utils.js";
+import { escapeJsonForScript } from "../html_escape.js";
+import { assertSafeElementId } from "../element_id.js";
+/**
+ * Chart.js markup and plugin resolution. Pure — no Node, no filesystem — because both the
+ * Node render path and the browser fragment path draw the same chart and must draw it the
+ * same way.
+ *
+ * The canvas id is a parameter rather than generated here: the Node path renders once to a
+ * PNG so a random id is fine, while the browser path re-renders and needs the same beat to
+ * produce the same markup, or a host diffing fragments sees every chart change identity on
+ * every render.
+ */
+/**
+ * Chart.js plugin CDN URLs keyed by chart type. A Map rather than an object literal: the
+ * chart type comes from the script, so an object lookup resolves `constructor` and
+ * `__proto__` through the prototype chain and hands back a function.
+ */
+const CHART_PLUGIN_CDNS = new Map([
+    ["sankey", "https://cdn.jsdelivr.net/npm/chartjs-chart-sankey"],
+    ["treemap", "https://cdn.jsdelivr.net/npm/chartjs-chart-treemap@3"],
+]);
+/** Resolve CDN script tags for Chart.js plugins based on chart type */
+export const resolveChartPlugins = (chartType) => {
+    const cdn = CHART_PLUGIN_CDNS.get(chartType);
+    if (!cdn)
+        return "";
+    return `<script src="${cdn}"></script>`;
+};
+export const stringifyChartData = (chartData) => JSON.stringify(chartData, null, 2);
+/** The card both paths draw: a heading and a fixed-height canvas. `trailing` is where the
+ * document path puts its driver script; the fragment path leaves it empty. */
+const chartCard = (title, canvas, trailing) => `
+<div class="chart-container mb-6">
+  <h3 class="text-xl font-semibold mb-4">${escapeHtml(title || "Chart")}</h3>
+  <div class="w-full" style="position: relative; height: 400px;">
+    ${canvas}
+  </div>${trailing}
+</div>`;
+/** For a standalone document, where the inline script runs. */
+export const chartHtml = (chartDataJson, title, chartId) => {
+    assertSafeElementId(chartId);
+    const script = `
+  <script>
+    (function() {
+      const ctx = document.getElementById('${chartId}').getContext('2d');
+      new Chart(ctx, ${escapeJsonForScript(chartDataJson)});
+    })();
+  </script>`;
+    return chartCard(title, `<canvas id="${chartId}"></canvas>`, script);
+};
+/**
+ * For a host that injects the markup into its own page, where an injected `<script>`
+ * neither survives sanitizing nor executes via innerHTML. The config rides on the canvas
+ * instead, in the shape `@mulmocast/deck` already uses so one host runtime drives both.
+ */
+export const chartFragmentHtml = (chartData, title, chartId) => {
+    assertSafeElementId(chartId);
+    const config = escapeHtml(JSON.stringify(chartData));
+    return chartCard(title, `<canvas id="${chartId}" data-chart-ready="false" data-mulmo-chart="${config}"></canvas>`, "");
+};
+/** `chartData` is a free record, so the type may be absent or not a string. */
+export const chartTypeOf = (chartData) => {
+    const type = chartData?.type;
+    return typeof type === "string" ? type : "";
+};
+/** The Chart.js plugin CDNs a chart type needs, for a host that loads them once per page. */
+export const chartPluginCdns = (chartType) => {
+    const cdn = CHART_PLUGIN_CDNS.get(chartType);
+    return cdn ? [cdn] : [];
+};
+/**
+ * The two values the PNG/PDF/movie template interpolates from user data, escaped for the
+ * contexts it drops them into: `<h1>${title}</h1>` and `const chartData = ${chart_data};`.
+ */
+export const escapedChartTemplateValues = (title, chartData) => ({
+    title: escapeHtml(title),
+    chart_data: escapeJsonForScript(JSON.stringify(chartData)),
+});

package/lib/utils/image_plugins/html_tailwind.d.ts

@@ -1,4 +1,4 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { BeatRenderParams, ImageProcessorParams } from "../../types/index.js";
 export declare const imageType = "html_tailwind";
 /**
  * Resolve image:name references to file:// absolute paths using imageRefs.
@@ -21,5 +21,5 @@ export declare const resolveRelativeImagePaths: (html: string, baseDirPath: stri
  */
 export declare const resolveRelativeModelPathsInScript: (html: string, baseDirPath: string) => string;
 export declare const process: (params: ImageProcessorParams) => Promise<string | undefined>;
-export declare const path: (params: ImageProcessorParams) => string;
-export declare const html: (params: ImageProcessorParams) => Promise<string | undefined>;
+export declare const path: (params: import("../../types/type.js").BeatPathParams) => string;
+export declare const html: (params: BeatRenderParams) => Promise<string | undefined>;

package/lib/utils/image_plugins/html_tailwind.js

@@ -6,6 +6,7 @@ import { renderHTMLToImage, interpolate, renderHTMLToFrames, renderHTMLToVideo,
 import { framesToVideo } from "../ffmpeg_utils.js";
 import { parrotingImagePath } from "./utils.js";
 import { swipeElementsToHtml, swipeElementsToScript } from "../swipe_to_html.js";
+import { htmlTailwindMarkup } from "./html_tailwind_markup.js";
 export const imageType = "html_tailwind";
 /**
  * Resolve image:name references to file:// absolute paths using imageRefs.
@@ -229,11 +230,7 @@ const dumpHtml = async (params) => {
     const { beat } = params;
     if (!beat.image || beat.image.type !== imageType)
         return;
-    const imageData = beat.image;
-    if (imageData.elements && Array.isArray(imageData.elements) && imageData.elements.length > 0) {
-        return swipeElementsToHtml(imageData.elements);
-    }
-    return joinHtml(imageData.html ?? "");
+    return htmlTailwindMarkup(beat.image);
 };
 export const process = processHtmlTailwind;
 export const path = parrotingImagePath;

package/lib/utils/image_plugins/html_tailwind_markup.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The static markup an html_tailwind beat shows. Pure — no Node, no filesystem — because the
+ * Node dump path and the browser fragment path show the same thing.
+ *
+ * Deliberately generates no `<script>`: the author's `script` FIELD, the swipe animation
+ * driver and the frame-based `animation` all need script execution, which the dump path has
+ * never emitted and which a fragment injected through `innerHTML` could not run anyway.
+ * Both paths show the beat's markup at rest.
+ *
+ * A `<script>` the author wrote inside `html` is another thing entirely: it is markup, and
+ * it passes through, because this beat type is raw author markup by design.
+ *
+ * The author's `html` is emitted as written. It is markup by design on this beat type — the
+ * schema also accepts a `script` — so escaping it would break the feature rather than
+ * protect anything the author does not already have.
+ */
+export type HtmlTailwindMarkupSource = {
+    html?: string | string[];
+    elements?: unknown;
+};
+export declare const htmlTailwindMarkup: (image: HtmlTailwindMarkupSource) => string;

package/lib/utils/image_plugins/html_tailwind_markup.js

@@ -0,0 +1,8 @@
+import { isSwipeElements, swipeElementsToHtml } from "../swipe_to_html.js";
+export const htmlTailwindMarkup = (image) => {
+    if (isSwipeElements(image.elements) && image.elements.length > 0) {
+        return swipeElementsToHtml(image.elements);
+    }
+    const html = image.html ?? "";
+    return Array.isArray(html) ? html.join("\n") : html;
+};

package/lib/utils/image_plugins/image.d.ts

@@ -1,3 +1,3 @@
 export declare const imageType = "image";
 export declare const process: (params: import("../../index.common.js").ImageProcessorParams) => Promise<string | undefined>;
-export declare const path: (params: import("../../index.common.js").ImageProcessorParams) => string | undefined;
+export declare const path: (params: import("../../index.common.js").BeatPathParams) => string | undefined;

package/lib/utils/image_plugins/index.d.ts

@@ -1,15 +1,15 @@
-import { ImageProcessorParams, MulmoBeat } from "../../types/index.js";
+import { BeatPathParams, BeatRenderParams, ImageProcessorParams, MulmoBeat } from "../../types/index.js";
 export declare const findImagePlugin: (imageType?: string) => {
     imageType: string;
     process: (params: ImageProcessorParams) => Promise<string | undefined> | void;
-    path: (params: ImageProcessorParams) => string | undefined;
-    markdown?: (params: ImageProcessorParams) => string | undefined;
-    html?: (params: ImageProcessorParams) => Promise<string | undefined>;
+    path: (params: BeatPathParams) => string | undefined;
+    markdown?: (params: BeatRenderParams) => string | undefined;
+    html?: (params: BeatRenderParams) => Promise<string | undefined>;
 } | undefined;
 export declare const getBeatPlugin: (beat: MulmoBeat) => {
     imageType: string;
     process: (params: ImageProcessorParams) => Promise<string | undefined> | void;
-    path: (params: ImageProcessorParams) => string | undefined;
-    markdown?: (params: ImageProcessorParams) => string | undefined;
-    html?: (params: ImageProcessorParams) => Promise<string | undefined>;
+    path: (params: BeatPathParams) => string | undefined;
+    markdown?: (params: BeatRenderParams) => string | undefined;
+    html?: (params: BeatRenderParams) => Promise<string | undefined>;
 };

package/lib/utils/image_plugins/markdown.d.ts

@@ -1,6 +1,6 @@
-import { ImageProcessorParams } from "../../types/index.js";
+import { BeatRenderParams, ImageProcessorParams } from "../../types/index.js";
 export declare const imageType = "markdown";
 export declare const process: (params: ImageProcessorParams) => Promise<string | undefined>;
-export declare const path: (params: ImageProcessorParams) => string;
-export declare const markdown: (params: ImageProcessorParams) => string | undefined;
-export declare const html: (params: ImageProcessorParams) => Promise<string>;
+export declare const path: (params: import("../../types/type.js").BeatPathParams) => string;
+export declare const markdown: (params: BeatRenderParams) => string | undefined;
+export declare const html: (params: BeatRenderParams) => Promise<string>;

package/lib/utils/image_plugins/markdown.js

@@ -1,10 +1,16 @@
 import { getHTMLFile } from "../file.js";
 import { renderHTMLToImage, interpolate } from "../html_render.js";
-import { parrotingImagePath } from "./utils.js";
+import { parrotingImagePath, generateUniqueId } from "./utils.js";
 import { resolveCombinedStyle } from "./bg_image_util.js";
-import { generateLayoutHtml, layoutToMarkdown, toMarkdownString, parseMarkdown } from "./markdown_layout.js";
+import { renderMarkdownContent, renderMarkdownLayout, layoutToMarkdown, toMarkdownString } from "./markdown_layout.js";
 import { resolveImageRefs, resolveMovieRefs } from "./html_tailwind.js";
 import { isObject } from "graphai";
+/**
+ * This path renders once to a PNG, so a random element id is fine. The browser path needs
+ * a stable one and supplies its own — that generator is the only thing the two callers of
+ * the shared markdown renderer differ on.
+ */
+const nodeMermaidId = () => generateUniqueId("mermaid");
 export const imageType = "markdown";
 // Type guard for object (data) format
 const isMarkdownLayout = (md) => {
@@ -23,48 +29,54 @@ const dumpMarkdown = (params) => {
     // object (data) format
     return layoutToMarkdown(md);
 };
-// Generate full HTML for rendering
+/**
+ * Full HTML for rendering, and whether it contains a diagram.
+ *
+ * The two come back together on purpose. There used to be a second detector —
+ * `containsMermaid`, a `text.includes("```mermaid")` over the raw source — deciding
+ * whether to load the mermaid runtime, while the renderer decided what to draw. Once the
+ * renderer started asking marked's lexer, the two disagreed: a ```MERMAID fence drew a
+ * diagram that no runtime was loaded for, so the PNG came out with an empty box, and an
+ * example quoted inside an outer ````markdown fence loaded the runtime for nothing.
+ *
+ * One question, one answer. The renderer already knows, so it says.
+ */
 const generateHtml = async (params) => {
     const { beat } = params;
     if (!beat.image || beat.image.type !== imageType)
-        return "";
+        return { html: "", hasMermaid: false };
     const md = beat.image.markdown;
     const combinedStyle = await resolveCombinedStyle(params, beat.image.backgroundImage, beat.image.style);
     if (isMarkdownLayout(md)) {
-        const htmlBody = await generateLayoutHtml(md);
+        const { html: htmlBody, hasMermaid } = renderMarkdownLayout(md, nodeMermaidId);
         const template = getHTMLFile("tailwind");
-        return interpolate(template, {
-            title: "Markdown Layout",
-            html_body: htmlBody,
-            custom_style: combinedStyle,
-        });
+        return {
+            html: interpolate(template, { title: "Markdown Layout", html_body: htmlBody, custom_style: combinedStyle }),
+            hasMermaid,
+        };
     }
-    const markdown = dumpMarkdown(params) ?? "";
-    const body = await parseMarkdown(markdown);
-    // Use tailwind template if mermaid is present to ensure mermaid CDN is loaded
-    if (containsMermaid(md)) {
+    const { html: body, hasMermaid } = renderMarkdownContent(dumpMarkdown(params) ?? "", nodeMermaidId);
+    // The tailwind template is what loads the mermaid CDN, so a diagram needs it.
+    if (hasMermaid) {
         const template = getHTMLFile("tailwind");
-        return interpolate(template, {
-            title: "Markdown",
-            html_body: `<div class="prose max-w-none p-6">${body}</div>`,
-            custom_style: combinedStyle,
-        });
+        return {
+            html: interpolate(template, {
+                title: "Markdown",
+                html_body: `<div class="prose max-w-none p-6">${body}</div>`,
+                custom_style: combinedStyle,
+            }),
+            hasMermaid,
+        };
     }
-    return `<html><head><style>${combinedStyle}</style></head><body>${body}</body></html>`;
-};
-// Check if markdown content contains mermaid code blocks
-const containsMermaid = (md) => {
-    const text = isMarkdownLayout(md) ? layoutToMarkdown(md) : toMarkdownString(md);
-    return text.includes("```mermaid");
+    return { html: `<html><head><style>${combinedStyle}</style></head><body>${body}</body></html>`, hasMermaid };
 };
 const processMarkdown = async (params) => {
     const { beat, imagePath, canvasSize } = params;
     if (!beat.image || beat.image.type !== imageType)
         return;
-    const rawHtml = await generateHtml(params);
+    const { html: rawHtml, hasMermaid } = await generateHtml(params);
     const resolvedImages = resolveImageRefs(rawHtml, params.imageRefs ?? {});
     const html = resolveMovieRefs(resolvedImages, params.movieRefs ?? {});
-    const hasMermaid = containsMermaid(beat.image.markdown);
     await renderHTMLToImage(html, imagePath, canvasSize.width, canvasSize.height, hasMermaid);
     return imagePath;
 };
@@ -74,11 +86,10 @@ const dumpHtml = async (params) => {
         return "";
     const md = beat.image.markdown;
     if (isMarkdownLayout(md)) {
-        return await generateLayoutHtml(md);
+        return renderMarkdownLayout(md, nodeMermaidId).html;
     }
     else {
-        const markdown = dumpMarkdown(params);
-        return await parseMarkdown(markdown ?? "");
+        return renderMarkdownContent(dumpMarkdown(params) ?? "", nodeMermaidId).html;
     }
 };
 export const process = processMarkdown;

package/lib/utils/image_plugins/markdown_layout.d.ts

@@ -1,6 +1,48 @@
 import { type MulmoMarkdownLayout } from "../../types/type.js";
-declare const toMarkdownString: (content: string | string[]) => string;
-declare const parseMarkdown: (content: string | string[]) => Promise<string>;
-export declare const generateLayoutHtml: (md: MulmoMarkdownLayout) => Promise<string>;
+/**
+ * The one markdown implementation, shared by the Node render path
+ * (`image_plugins/markdown.ts`, which turns it into a PNG) and the browser fragment path
+ * (`beat_html/markdown.ts`, which hands it to a host's DOM).
+ *
+ * Deliberately pure: no `node:*`, no filesystem, no puppeteer. That is what lets the
+ * browser side import it rather than keep a second copy — and a second copy is not
+ * hypothetical, it existed for one commit and the two immediately disagreed about which
+ * fences are diagrams. `test/beat_html/test_browser_safety.ts` bundles the browser entry
+ * with esbuild and fails if anything here reaches Node.
+ *
+ * Element ids come from a caller-supplied generator, because that is the only thing the
+ * two callers genuinely need to differ on.
+ */
+/** A markdown field is written either as one string or as lines to be joined. */
+export declare const toMarkdownString: (content: string | string[]) => string;
+/**
+ * Renders markdown, turning fenced `mermaid` blocks into mermaid markup.
+ *
+ * Asked of marked's own lexer rather than matched against the raw source. A regex over
+ * text was what both copies used, and review found four inputs it got wrong: a CRLF fence
+ * and a fence with trailing whitespace after the language were missed, while a mermaid
+ * fence quoted INSIDE an outer ````markdown fence, and one inside an indented code block,
+ * were converted — turning somebody's example of mermaid syntax into an actual diagram.
+ * marked decides what is a code block and what language it is, so all four follow from
+ * asking it.
+ *
+ * A fresh `Marked` instance per call rather than the global `marked.use`, because the
+ * renderer closes over this call's mermaid counter — a shared one would leak ids between
+ * beats.
+ */
+export declare const renderMarkdownContent: (content: string | string[], nextId: () => string) => {
+    html: string;
+    hasMermaid: boolean;
+};
+/** The object form of `markdown`, as opposed to a plain string or array of lines. */
+export declare const isMarkdownLayout: (md: unknown) => md is MulmoMarkdownLayout;
+/** Lay a markdown layout out in Tailwind: header / sidebar-left / row-2 | 2x2 | content. */
+export declare const renderMarkdownLayout: (md: MulmoMarkdownLayout, nextId: () => string) => {
+    html: string;
+    hasMermaid: boolean;
+};
+/**
+ * A layout flattened back to plain markdown, in slot order. Used by `mulmo markdown`,
+ * which wants what the beat SAYS rather than how it is laid out.
+ */
 export declare const layoutToMarkdown: (md: MulmoMarkdownLayout) => string;
-export { toMarkdownString, parseMarkdown };