@mulmoclaude/markdown-utils 1.1.0 → 1.3.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/frontmatter.d.ts

@@ -19,6 +19,18 @@ export interface ParsedMarkdown {
  *  a well-formed envelope falls back to `{ meta: {}, hasHeader: false }`
  *  so a typo in the header doesn't break rendering. */
 export declare function parseFrontmatter(raw: string): ParsedMarkdown;
+/** Split a document into its frontmatter `prefix` (the `---\n…\n---\n`
+ *  envelope, empty string when there is none) and the `body` that
+ *  follows. `prefix + body` reproduces the input exactly: `body` is
+ *  always a suffix of `raw` (see `parseFrontmatter`), so `prefix` is
+ *  the leading slice of the exact remaining length. Reach for this
+ *  instead of re-deriving the split when you need to rewrite the body
+ *  and re-attach the original header verbatim — e.g. toggling a task
+ *  checkbox without disturbing the YAML. */
+export declare function splitFrontmatter(raw: string): {
+    prefix: string;
+    body: string;
+};
 /** Serialize a meta object + body back into the canonical
  *  `---\n...\n---\n\nbody` shape. An empty `meta` returns the body
  *  alone (no envelope) — the lazy-on-write contract: don't add

package/dist/markdown/frontmatter.js

@@ -38,6 +38,19 @@ export function parseFrontmatter(raw) {
     }
     return { meta, body, hasHeader: true };
 }
+/** Split a document into its frontmatter `prefix` (the `---\n…\n---\n`
+ *  envelope, empty string when there is none) and the `body` that
+ *  follows. `prefix + body` reproduces the input exactly: `body` is
+ *  always a suffix of `raw` (see `parseFrontmatter`), so `prefix` is
+ *  the leading slice of the exact remaining length. Reach for this
+ *  instead of re-deriving the split when you need to rewrite the body
+ *  and re-attach the original header verbatim — e.g. toggling a task
+ *  checkbox without disturbing the YAML. */
+export function splitFrontmatter(raw) {
+    const { body } = parseFrontmatter(raw);
+    const prefix = raw.slice(0, raw.length - body.length);
+    return { prefix, body };
+}
 /** Serialize a meta object + body back into the canonical
  *  `---\n...\n---\n\nbody` shape. An empty `meta` returns the body
  *  alone (no envelope) — the lazy-on-write contract: don't add

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,51 @@
+// 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` and the zero-dep `@mulmoclaude/common` leaf) 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.
+import { escapeHtml } from "@mulmoclaude/common";
+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/dist/markdown/taskList.js

@@ -163,8 +163,11 @@ export function makeTasksInteractive(html) {
     // marked v18 default output:
     //   <input disabled="" type="checkbox">         (unchecked)
     //   <input checked="" disabled="" type="checkbox">  (checked)
-    // Both end with ` type="checkbox">`. Capture everything between
-    // `<input ` and `disabled=""` (typically empty or `checked="" `)
-    // and re-emit with `class="md-task"` in disabled's slot.
-    return html.replace(/<input ([^>]*)disabled="" type="checkbox">/g, '<input $1class="md-task" type="checkbox">');
+    // Match those two shapes exactly and re-emit with `class="md-task"` in
+    // disabled's slot. The middle was `[^>]*` once, which is what made this
+    // quadratic: on input full of `<input =` the engine re-scans the run for
+    // every start position looking for a `disabled=""` that never arrives.
+    // An optional literal group can't backtrack, and marked emits nothing else
+    // here — the checked/unchecked pair above is the whole surface.
+    return html.replace(/<input (checked="" )?disabled="" type="checkbox">/g, '<input $1class="md-task" type="checkbox">');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/markdown-utils",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Browser-safe markdown / image rendering utilities shared by the MulmoClaude host and the markdown plugin",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,13 +33,16 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "marked": "^18.0.6",
-    "js-yaml": "^5.2.1"
+    "@mulmoclaude/common": "^1.1.0",
+    "js-yaml": "^5.2.2",
+    "marked": "^18.0.7"
   },
   "peerDependencies": {
+    "mermaid": "^11.16.0",
     "vue": "^3.5.0"
   },
   "devDependencies": {
+    "mermaid": "^11.16.0",
     "typescript": "^6.0.3",
     "vue": "^3.5.40"
   }