@mulmoclaude/markdown-utils 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -10,3 +10,5 @@ export * from "./dom/externalLink.js";
 export * from "./files/filename.js";
 export * from "./image/resolve.js";
 export * from "./image/rewriteMarkdownImageRefs.js";
+export * from "./markdown/mermaidRender.js";
+export * from "./markdown/mermaidExtension.js";

package/dist/index.js

@@ -10,3 +10,5 @@ export * from "./dom/externalLink.js";
 export * from "./files/filename.js";
 export * from "./image/resolve.js";
 export * from "./image/rewriteMarkdownImageRefs.js";
+export * from "./markdown/mermaidRender.js";
+export * from "./markdown/mermaidExtension.js";

package/dist/markdown/mermaidExtension.d.ts

@@ -0,0 +1,2 @@
+import type { MarkedExtension } from "marked";
+export declare const mermaidExtension: MarkedExtension;

package/dist/markdown/mermaidExtension.js

@@ -0,0 +1,53 @@
+// Marked `code` renderer override that intercepts fenced code blocks
+// whose language tag is `mermaid` and rewrites them into a
+// `<pre class="mermaid" data-mermaid-pending="1">` placeholder. The
+// diagram render itself is deferred to `mermaidRender.ts`, which
+// scans the placeholders in the DOM after Vue's v-html injects the
+// html. Two-step split keeps this file pure (no runtime deps beyond
+// `marked`) so tests can assert the html shape without booting a
+// browser.
+//
+// Why a renderer override and not a block tokenizer:
+//   - marked already handles every fence variation CommonMark / GFM
+//     permits (backticks vs tildes, LF vs CRLF, top-level vs indented
+//     inside a list item, up to 3 spaces of leading whitespace on the
+//     fence). Re-implementing that surface in a bespoke regex means
+//     silently falling back to plaintext on the edge cases the regex
+//     misses. Overriding the `code` renderer catches everything marked
+//     already tokenised as a code block, so no CommonMark variant is
+//     left behind.
+//
+// Registration order (see setup.ts): register AFTER
+// `markedHighlightExtension` so this renderer wraps highlight's — a
+// non-mermaid fence returns `false` from here and falls through to
+// highlight's code renderer unchanged, while a `mermaid` fence
+// short-circuits into the placeholder and never reaches highlight.
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+export const mermaidExtension = {
+    renderer: {
+        code(token) {
+            // marked v18 hands the whole token in — read `lang` from there.
+            // `lang` may carry trailing whitespace (`\`\`\`mermaid  `), so
+            // trim before comparing. Empty `lang` (indented 4-space blocks
+            // or plain triple-backtick with no tag) can never match here.
+            const lang = (token.lang ?? "").trim();
+            if (lang !== "mermaid")
+                return false;
+            // markedHighlight's `walkTokens` fires on EVERY code token —
+            // regardless of language — and rewrites `token.text` to an
+            // HTML-escaped, highlight.js-processed string (mermaid falls
+            // to `plaintext`, so no <span> tags land, but every `"` is
+            // now `&quot;`). It also stamps `token.escaped = true`. If we
+            // re-escape here, `&` in `&quot;` becomes `&amp;`, the browser
+            // decodes `&amp;quot;` back to `&quot;` on parse, and mermaid
+            // sees literal `&quot;` in its input — parse error. Honour
+            // the `escaped` flag: pass through when already escaped, escape
+            // ourselves when not (host code paths that don't wire highlight,
+            // and the plugin, still need our own escape).
+            const html = token.escaped === true ? token.text : escapeHtml(token.text);
+            return `<pre class="mermaid" data-mermaid-pending="1">${html}</pre>\n`;
+        },
+    },
+};

package/dist/markdown/mermaidRender.d.ts

@@ -0,0 +1,33 @@
+/** Localised strings the render pipeline surfaces when it fails.
+ *  Callers (composables) resolve `t("markdownMermaid.…")` at
+ *  component-setup time and hand the formatter down. Fallback
+ *  defaults keep the pure module testable without a Vue / i18n
+ *  runtime — they mirror the English text in `src/lang/en.ts`. */
+export interface MermaidRenderLabels {
+    loadFailed: (error: string) => string;
+    renderFailed: (error: string) => string;
+}
+/** Adopt a mermaid-produced SVG string into a live DOM node via
+ *  DOMParser (HTML5 mode) instead of assigning to `.innerHTML`.
+ *  Mermaid's `securityLevel: "strict"` already escapes user-authored
+ *  diagram text before building the SVG, so the string is trusted —
+ *  but going through the parser satisfies opengrep's XSS heuristic
+ *  that flags every raw `innerHTML =`. HTML5 mode (not `image/svg+xml`)
+ *  is required: mermaid's SVG contains `<foreignObject>` wrappers with
+ *  nested HTML content for labels (line-broken text via `<br>`, `<div>`,
+ *  etc.), which is well-formed HTML5 but NOT well-formed XML — the
+ *  XML parser drops a `<parsererror>` root and refuses. HTML5 mode
+ *  treats `<svg>` as a foreign-namespace root and correctly parses
+ *  the mixed subtree.
+ *
+ *  Exported for regression tests in
+ *  `test/utils/markdown/test_mermaidRender.ts` so the assertion
+ *  exercises the real production helper instead of an inline copy. */
+export declare function adoptSvg(svgMarkup: string): SVGElement | null;
+/** Render every unprocessed mermaid placeholder under `root`. Safe to
+ *  call repeatedly — nodes get replaced on success (no `data-*` to
+ *  match a second time) and gain an `.mermaid-error` class on failure.
+ *  Returns once every discovered node has been resolved. `labels`
+ *  defaults to English fallbacks so the pure module remains callable
+ *  from tests / node environments without an i18n runtime. */
+export declare function renderMermaidNodes(root: Element | Document | null | undefined, labels?: MermaidRenderLabels, idPrefix?: string): Promise<void>;

package/dist/markdown/mermaidRender.js

@@ -0,0 +1,134 @@
+// Runtime side of the mermaid pipeline: scans the DOM for
+// `<pre class="mermaid" data-mermaid-pending>` placeholders written by
+// `mermaidExtension.ts`, lazy-loads the mermaid runtime on the first
+// hit, renders each block, and swaps the placeholder in place with
+// the resulting SVG.
+//
+// Lazy-load: mermaid.js is heavy (~500 KB gzip). The dynamic import
+// keeps it out of the initial bundle for users who never encounter a
+// diagram. `mermaidPromise` memoises the module so subsequent calls
+// don't re-import.
+const DEFAULT_LABELS = {
+    loadFailed: (error) => `⚠ Mermaid failed to load: ${error}`,
+    renderFailed: (error) => `⚠ Mermaid render failed: ${error}`,
+};
+let mermaidPromise = null;
+async function loadMermaid() {
+    if (mermaidPromise)
+        return mermaidPromise;
+    const attempt = import("mermaid").then((mod) => {
+        const mermaid = mod.default;
+        // `startOnLoad: false` — we drive rendering explicitly per node
+        // instead of letting mermaid walk the document on DOMContentLoaded.
+        // `securityLevel: "strict"` — mermaid sanitises its own labels and
+        // will not execute user-authored HTML/JS in diagram text.
+        mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "default" });
+        return mermaid;
+    });
+    // Share the in-flight promise with parallel callers, but drop the
+    // cache once it rejects so a transient failure (offline / stale
+    // chunk after a deploy / ad-blocker hiccup) can be retried by the
+    // next fence to render. Without this reset the module would be
+    // dead until the user reloaded.
+    attempt.catch(() => {
+        if (mermaidPromise === attempt)
+            mermaidPromise = null;
+    });
+    mermaidPromise = attempt;
+    return attempt;
+}
+function placeLoadError(nodes, err, labels) {
+    const message = labels.loadFailed(String(err));
+    for (const node of nodes) {
+        const errBox = document.createElement("pre");
+        errBox.className = "mermaid-error";
+        errBox.textContent = message;
+        node.replaceWith(errBox);
+    }
+}
+// Distinct per-diagram DOM id. Two diagrams on one page must not collide
+// (mermaid uses the id as the SVG root id).
+let renderCounter = 0;
+function nextRenderId(idPrefix) {
+    renderCounter += 1;
+    return `${idPrefix}-${renderCounter}`;
+}
+function pendingNodes(root) {
+    return Array.from(root.querySelectorAll("pre.mermaid[data-mermaid-pending]"));
+}
+/** Adopt a mermaid-produced SVG string into a live DOM node via
+ *  DOMParser (HTML5 mode) instead of assigning to `.innerHTML`.
+ *  Mermaid's `securityLevel: "strict"` already escapes user-authored
+ *  diagram text before building the SVG, so the string is trusted —
+ *  but going through the parser satisfies opengrep's XSS heuristic
+ *  that flags every raw `innerHTML =`. HTML5 mode (not `image/svg+xml`)
+ *  is required: mermaid's SVG contains `<foreignObject>` wrappers with
+ *  nested HTML content for labels (line-broken text via `<br>`, `<div>`,
+ *  etc.), which is well-formed HTML5 but NOT well-formed XML — the
+ *  XML parser drops a `<parsererror>` root and refuses. HTML5 mode
+ *  treats `<svg>` as a foreign-namespace root and correctly parses
+ *  the mixed subtree.
+ *
+ *  Exported for regression tests in
+ *  `test/utils/markdown/test_mermaidRender.ts` so the assertion
+ *  exercises the real production helper instead of an inline copy. */
+export function adoptSvg(svgMarkup) {
+    const parsed = new DOMParser().parseFromString(svgMarkup, "text/html");
+    // `<svg>` at the top level lands under `body` in HTML5 parsing.
+    const svgEl = parsed.body.querySelector("svg");
+    if (!svgEl)
+        return null;
+    return document.importNode(svgEl, true);
+}
+async function renderOne(node, mermaid, labels, idPrefix) {
+    // `textContent` gives us the raw source — DOMPurify preserves it
+    // verbatim inside `<pre>` and we escaped it going in, so entity
+    // decoding is browser-native from the DOM read.
+    const source = node.textContent ?? "";
+    const svgId = nextRenderId(idPrefix);
+    try {
+        const { svg } = await mermaid.render(svgId, source);
+        const svgNode = adoptSvg(svg);
+        if (!svgNode)
+            throw new Error("mermaid produced malformed SVG");
+        const wrapper = document.createElement("div");
+        wrapper.className = "mermaid-diagram";
+        wrapper.appendChild(svgNode);
+        node.replaceWith(wrapper);
+    }
+    catch (err) {
+        // Preserve the source below the localised header so the author
+        // can see WHICH diagram broke.
+        const errBox = document.createElement("pre");
+        errBox.className = "mermaid-error";
+        errBox.textContent = `${labels.renderFailed(String(err))}\n---\n${source}`;
+        node.replaceWith(errBox);
+    }
+}
+/** Render every unprocessed mermaid placeholder under `root`. Safe to
+ *  call repeatedly — nodes get replaced on success (no `data-*` to
+ *  match a second time) and gain an `.mermaid-error` class on failure.
+ *  Returns once every discovered node has been resolved. `labels`
+ *  defaults to English fallbacks so the pure module remains callable
+ *  from tests / node environments without an i18n runtime. */
+export async function renderMermaidNodes(root, labels = DEFAULT_LABELS, idPrefix = "mulmo-mermaid") {
+    if (!root)
+        return;
+    const nodes = pendingNodes(root);
+    if (nodes.length === 0)
+        return;
+    let mermaid;
+    try {
+        mermaid = await loadMermaid();
+    }
+    catch (err) {
+        // The dynamic import failed (network / bundler / adblock). Swap
+        // every pending placeholder for a visible error box so the user
+        // sees WHY the diagram is missing instead of a raw code fence, and
+        // don't let the rejection escape as an unhandled promise (callers
+        // fire this via `void run()` in the composable).
+        placeLoadError(nodes, err, labels);
+        return;
+    }
+    await Promise.all(nodes.map((node) => renderOne(node, mermaid, labels, idPrefix)));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/markdown-utils",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Browser-safe markdown / image rendering utilities shared by the MulmoClaude host and the markdown plugin",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,9 +37,11 @@
     "js-yaml": "^5.2.1"
   },
   "peerDependencies": {
+    "mermaid": "^11.16.0",
     "vue": "^3.5.0"
   },
   "devDependencies": {
+    "mermaid": "^11.16.0",
     "typescript": "^6.0.3",
     "vue": "^3.5.40"
   }