@mulmoclaude/markdown-utils 1.0.0 → 1.2.0

package/dist/image/resolve.d.ts

@@ -0,0 +1,16 @@
+/** Override the workspace file-server URL (e.g. MulmoTerminal). */
+export declare function setFilesRawUrl(url: string): void;
+/** Convert an imageData value to a displayable URL.
+ *  Handles data URIs, paths under `artifacts/images/` (resolved via
+ *  the static mount), and everything else (resolved via the workspace
+ *  file server). */
+export declare function resolveImageSrc(imageData: string): string;
+/** Same as `resolveImageSrc` but appends the current cache-bust token
+ *  so the browser re-fetches when the file has been overwritten in
+ *  place (e.g. the canvas plugin rewrote it).
+ *
+ *  Use this from display-only consumers (Preview, thumbnail list).
+ *  Avoid inside the canvas View's own `backgroundImage` — changing
+ *  that URL mid-session makes `vue-drawing-canvas` re-fetch on every
+ *  redraw, which races with stroke painting and blanks the canvas. */
+export declare function resolveImageSrcFresh(imageData: string): string;

package/dist/image/resolve.js

@@ -0,0 +1,47 @@
+import { getImageBump } from "./cacheBust";
+// Host-configurable base URL for the workspace file server (workspace-
+// relative image paths that aren't under the `artifacts/images/` static
+// mount resolve through here). Defaults to MulmoClaude's route; other
+// hosts call `setFilesRawUrl` at startup.
+let filesRawUrl = "/api/files/raw";
+/** Override the workspace file-server URL (e.g. MulmoTerminal). */
+export function setFilesRawUrl(url) {
+    filesRawUrl = url;
+}
+// Files saved by `saveImage()` (Gemini, canvas, image edit) all live
+// under this prefix — see server/utils/files/image-store.ts and
+// server/workspace/paths.ts (WORKSPACE_DIRS.images). Express mounts a
+// static handler for the corresponding URL so these paths route
+// directly to the file without going through /api/files/raw.
+const IMAGES_DIR_PREFIX = "artifacts/images/";
+/** Convert an imageData value to a displayable URL.
+ *  Handles data URIs, paths under `artifacts/images/` (resolved via
+ *  the static mount), and everything else (resolved via the workspace
+ *  file server). */
+export function resolveImageSrc(imageData) {
+    if (imageData.startsWith("data:"))
+        return imageData;
+    if (imageData.startsWith(IMAGES_DIR_PREFIX))
+        return `/${imageData}`;
+    return `${filesRawUrl}?path=${encodeURIComponent(imageData)}`;
+}
+/** Same as `resolveImageSrc` but appends the current cache-bust token
+ *  so the browser re-fetches when the file has been overwritten in
+ *  place (e.g. the canvas plugin rewrote it).
+ *
+ *  Use this from display-only consumers (Preview, thumbnail list).
+ *  Avoid inside the canvas View's own `backgroundImage` — changing
+ *  that URL mid-session makes `vue-drawing-canvas` re-fetch on every
+ *  redraw, which races with stroke painting and blanks the canvas. */
+export function resolveImageSrcFresh(imageData) {
+    if (imageData.startsWith("data:"))
+        return imageData;
+    const base = resolveImageSrc(imageData);
+    const bump = getImageBump(imageData);
+    if (bump <= 0)
+        return base;
+    // Both URL forms append a cache-bust param. The static mount form
+    // uses `?v=`, the API form already has `?path=` so we use `&v=`.
+    const sep = base.includes("?") ? "&" : "?";
+    return `${base}${sep}v=${bump}`;
+}

package/dist/image/rewriteMarkdownImageRefs.d.ts

@@ -0,0 +1,22 @@
+export declare function rewriteImgSrcAttrsInHtml(html: string, basePath: string): string;
+/**
+ * Rewrite `![alt](path)` image refs in markdown text so workspace-
+ * relative paths render through `/api/files/raw`.
+ *
+ * @param markdown Markdown source text.
+ * @param basePath The workspace-relative directory of the markdown
+ *   file (e.g. `"wiki/pages"` for `wiki/pages/foo.md`). Omit or pass
+ *   `""` when resolving refs against the workspace root.
+ *
+ * Also rewrites the `src` attribute of raw `<img>` tags inside HTML
+ * blocks / inline HTML so a page mixing both syntaxes resolves the
+ * same way. Markdown image syntax inside code blocks / inline code
+ * spans is left alone.
+ *
+ * Absolute URLs, data URIs, and existing API paths pass through
+ * untouched. Refs that would escape the workspace root (more `..`
+ * than `basePath` depth) also pass through untouched — they would
+ * 404 regardless, and passing through lets the user see the broken
+ * ref instead of silently re-pointing it.
+ */
+export declare function rewriteMarkdownImageRefs(markdown: string, basePath?: string): string;

package/dist/image/rewriteMarkdownImageRefs.js

@@ -0,0 +1,243 @@
+import { marked } from "marked";
+import { resolveImageSrc } from "./resolve";
+import { transformResolvableUrlsInHtml } from "./htmlSrcAttrs";
+// Pre-`marked` pass that rewrites workspace-relative image references
+// in markdown source so they render through the backend file server.
+//
+// Without this, a page like `![chart](../images/foo.png)` produces
+// `<img src="../images/foo.png">`, which the browser resolves against
+// the SPA page URL (e.g. `/chat/…foo.png`) and 404s. After this
+// pass, the src becomes `/api/files/raw?path=images/foo.png` which
+// the workspace file server serves.
+//
+// Uses marked's tokenizer to find image refs rather than a raw regex
+// over the source. The regex approach had two problems:
+//   - URLs containing `)` (e.g. `Foo_(bar).png`) were truncated at
+//     the first close paren.
+//   - `![x](y)` inside fenced code blocks or inline code spans was
+//     rewritten even though it's not meant to render as an image.
+// The lexer handles both correctly.
+//
+// Callers that know the markdown file's directory (`basePath`) get
+// correct resolution for `./` and `../` relative refs. Callers that
+// omit `basePath` only resolve refs that are already workspace-rooted
+// (no leading `./` or `../`); relative-with-traversal refs without
+// context would be ambiguous, so they pass through untouched rather
+// than silently pointing at the wrong file.
+//
+// Used by:
+//
+//   - `src/plugins/wiki/View.vue`
+//   - `src/components/FilesView.vue` (when previewing a .md file)
+//   - `src/plugins/markdown/View.vue` (via post-`marked` HTML rewriter)
+function shouldSkip(url) {
+    if (url.startsWith("data:"))
+        return true;
+    if (url.startsWith("http://") || url.startsWith("https://"))
+        return true;
+    // Already an API route — nothing to do.
+    if (url.startsWith("/api/"))
+        return true;
+    return false;
+}
+/**
+ * Resolve `url` relative to `basePath` using posix segment arithmetic.
+ * Returns the resolved workspace-relative path, or `null` if the URL
+ * escapes the workspace root (more `..` than `basePath` depth).
+ *
+ * Pure string operation — does not touch the filesystem or use Node's
+ * `path` module (this file runs in the browser).
+ */
+function resolveWorkspacePath(basePath, url) {
+    // Absolute-within-workspace (e.g. "/images/foo.png") — reset base.
+    const isAbsolute = url.startsWith("/");
+    const baseSegs = isAbsolute ? [] : basePath.split("/").filter((seg) => seg !== "" && seg !== ".");
+    const segs = [...baseSegs];
+    const urlSegs = (isAbsolute ? url.slice(1) : url).split("/");
+    for (const seg of urlSegs) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (segs.length === 0)
+                return null;
+            segs.pop();
+            continue;
+        }
+        segs.push(seg);
+    }
+    if (segs.length === 0)
+        return null;
+    return segs.join("/");
+}
+// Extract the alt-text span `[...]` from an image ref `![alt](url...)`.
+// CommonMark allows balanced nested brackets inside alt (`![x [y]](z)`),
+// which a greedy regex would get wrong — scan with a depth counter and
+// return the slice between the outermost brackets.
+function extractBracketedAlt(raw) {
+    if (!raw.startsWith("!["))
+        return null;
+    let depth = 1;
+    for (let i = 2; i < raw.length; i++) {
+        const char = raw[i];
+        if (char === "[")
+            depth++;
+        else if (char === "]") {
+            depth--;
+            if (depth === 0)
+                return raw.slice(2, i);
+        }
+    }
+    return null;
+}
+function rewriteImageToken(token, basePath) {
+    const href = (token.href ?? "").trim();
+    if (href === "" || shouldSkip(href))
+        return null;
+    const resolved = resolveWorkspacePath(basePath, href);
+    if (resolved === null)
+        return null;
+    const newHref = resolveImageSrc(resolved);
+    // Preserve alt text verbatim — read from the raw so any special
+    // characters (brackets, entities) survive unmodified.
+    const alt = extractBracketedAlt(token.raw) ?? token.text ?? "";
+    if (token.title) {
+        // Escape backslashes BEFORE quotes so a title containing `\` (or one
+        // ending in `\`) can't break out of the quoted title delimiter.
+        const escapedTitle = token.title.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        return `![${alt}](${newHref} "${escapedTitle}")`;
+    }
+    return `![${alt}](${newHref})`;
+}
+// Rewrite URL-bearing attributes of every recognised tag inside an
+// HTML fragment, applying the same basePath / shouldSkip /
+// resolveImageSrc pipeline used for `![alt](url)` markdown images.
+// Other attributes (alt, class, style, id, …) are preserved verbatim.
+//
+// Tags + attributes covered (single source of truth at
+// `htmlSrcAttrs.ts:RESOLVABLE_TAG_ATTRS`): `<img src>`, `<source src>`,
+// `<video poster|src>`, `<audio src>`. Add a row there to extend
+// coverage; both this rewriter and the server-side PDF rewriter pick
+// it up automatically (#1011 Stage B).
+//
+// Output URLs come from `resolveImageSrc`, which either returns a
+// mount-rooted path (`/artifacts/images/<file>`) or runs the input
+// through `encodeURIComponent`. `"` becomes `%22`, `'` becomes `%27`,
+// `<` / `>` are encoded — the rewritten attribute can't break out of
+// its own quotes or close the tag.
+//
+// Limitations:
+//   - `srcset` (comma-separated descriptor list) is deferred —
+//     tracked under #1011 Stage B follow-up.
+//   - SVG `<image href>` and CSS `url()` are deferred per plan
+//     §修正提案 P3-A.
+//   - A regex can't perfectly distinguish a real tag from one
+//     embedded in another attribute's value; embedded matches get
+//     rewritten too. Harmless because the rewritten URL is encoded
+//     safely.
+export function rewriteImgSrcAttrsInHtml(html, basePath) {
+    return transformResolvableUrlsInHtml(html, (url) => {
+        if (shouldSkip(url))
+            return null;
+        const resolved = resolveWorkspacePath(basePath, url);
+        if (resolved === null)
+            return null;
+        return resolveImageSrc(resolved);
+    });
+}
+function isSkippable(token) {
+    return token.type === "code" || token.type === "codespan";
+}
+function getContainerChildren(token) {
+    const container = token;
+    if (Array.isArray(container.tokens) && container.tokens.length > 0) {
+        return container.tokens;
+    }
+    if (Array.isArray(container.items) && container.items.length > 0) {
+        return container.items;
+    }
+    return null;
+}
+// Render a container's children back into the output, preserving any
+// structural glue the parent carries outside the children's combined
+// raw span (list markers, blockquote prefixes, trailing newlines).
+// Returns true if the container was rendered via its children, false
+// if the caller should fall back to emitting the parent's raw.
+function renderContainerChildren(raw, children, basePath, out) {
+    const joined = children.map((token) => token.raw ?? "").join("");
+    if (joined === "")
+        return false;
+    const idx = raw.indexOf(joined);
+    if (idx < 0)
+        return false;
+    if (idx > 0)
+        out.push(raw.slice(0, idx));
+    for (const child of children)
+        renderToken(child, basePath, out);
+    const tail = raw.slice(idx + joined.length);
+    if (tail)
+        out.push(tail);
+    return true;
+}
+// Recursively render a token back to markdown, rewriting image refs
+// in-place. Code / codespan tokens are emitted verbatim so image-ref
+// syntax inside them stays literal. HTML tokens get a separate pass
+// (`rewriteImgSrcAttrsInHtml`) so raw `<img>` tags route through the
+// same basePath + shouldSkip pipeline as the markdown image syntax.
+// Token-tree recursion uses the lexer's structural knowledge and never
+// crosses a skip boundary — unlike the earlier `indexOf` splice which
+// could rewrite a code-block literal when the same ref appeared in
+// real markdown.
+function renderToken(token, basePath, out) {
+    if (isSkippable(token)) {
+        out.push(token.raw);
+        return;
+    }
+    if (token.type === "image") {
+        const replacement = rewriteImageToken(token, basePath);
+        out.push(replacement ?? token.raw);
+        return;
+    }
+    if (token.type === "html") {
+        // Block / inline HTML — rewrite raw <img> tags inside before
+        // emitting. Markdown image syntax (![alt](url)) is handled by the
+        // image-token branch above; this branch covers the HTML-fallback
+        // path (#1011 Stage A). Fall back to verbatim raw if `raw` is
+        // unexpectedly missing — defensive against future marked changes.
+        const raw = token.raw ?? "";
+        out.push(rewriteImgSrcAttrsInHtml(raw, basePath));
+        return;
+    }
+    const raw = token.raw ?? "";
+    const children = getContainerChildren(token);
+    if (children && renderContainerChildren(raw, children, basePath, out)) {
+        return;
+    }
+    out.push(raw);
+}
+/**
+ * Rewrite `![alt](path)` image refs in markdown text so workspace-
+ * relative paths render through `/api/files/raw`.
+ *
+ * @param markdown Markdown source text.
+ * @param basePath The workspace-relative directory of the markdown
+ *   file (e.g. `"wiki/pages"` for `wiki/pages/foo.md`). Omit or pass
+ *   `""` when resolving refs against the workspace root.
+ *
+ * Also rewrites the `src` attribute of raw `<img>` tags inside HTML
+ * blocks / inline HTML so a page mixing both syntaxes resolves the
+ * same way. Markdown image syntax inside code blocks / inline code
+ * spans is left alone.
+ *
+ * Absolute URLs, data URIs, and existing API paths pass through
+ * untouched. Refs that would escape the workspace root (more `..`
+ * than `basePath` depth) also pass through untouched — they would
+ * 404 regardless, and passing through lets the user see the broken
+ * ref instead of silently re-pointing it.
+ */
+export function rewriteMarkdownImageRefs(markdown, basePath = "") {
+    const tokens = marked.lexer(markdown);
+    const parts = [];
+    for (const token of tokens)
+        renderToken(token, basePath, parts);
+    return parts.join("");
+}

package/dist/index.d.ts

@@ -8,3 +8,7 @@ export * from "./image/cacheBust.js";
 export * from "./image/htmlSrcAttrs.js";
 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

@@ -8,3 +8,7 @@ export * from "./image/cacheBust.js";
 export * from "./image/htmlSrcAttrs.js";
 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.0.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",
@@ -33,12 +33,15 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
+    "marked": "^18.0.6",
     "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"
   }