npm - @mulmoclaude/markdown-utils - Versions diffs - 1.3.5 → 2.0.0 - Mend

@mulmoclaude/markdown-utils 1.3.5 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/dist/dom/adoptSvg.d.ts +18 -0
package/dist/dom/adoptSvg.js +28 -0
package/dist/index.d.ts +3 -0
package/dist/index.js +3 -0
package/dist/markdown/mathExtension.d.ts +34 -0
package/dist/markdown/mathExtension.js +195 -0
package/dist/markdown/mathRender.d.ts +46 -0
package/dist/markdown/mathRender.js +258 -0
package/dist/markdown/mermaidRender.d.ts +0 -17
package/dist/markdown/mermaidRender.js +1 -24
package/package.json +9 -6

package/dist/dom/adoptSvg.d.ts ADDED Viewed

@@ -0,0 +1,18 @@
+/** Parse a markup string with DOMParser in HTML5 mode and hand back its
+ *  `<body>`, for callers that then pick nodes out of it and import them.
+ *
+ *  Parsing instead of assigning to `.innerHTML` satisfies opengrep's XSS
+ *  heuristic that flags every raw `innerHTML =`; callers are expected to
+ *  have produced or sanitised the markup themselves.
+ *
+ *  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>` and
+ *  `<math>` as foreign-namespace roots and correctly parses the mixed
+ *  subtree. */
+export declare function parseMarkupBody(markup: string): HTMLElement;
+/** Adopt an SVG markup string into a live DOM node. Returns null when
+ *  the markup has no `<svg>` root. */
+export declare function adoptSvg(svgMarkup: string): SVGElement | null;

package/dist/dom/adoptSvg.js ADDED Viewed

@@ -0,0 +1,28 @@
+// Shared by every renderer that receives markup as a *string* (mermaid
+// diagrams, MathJax formulas) and has to put it into the live DOM.
+/** Parse a markup string with DOMParser in HTML5 mode and hand back its
+ *  `<body>`, for callers that then pick nodes out of it and import them.
+ *
+ *  Parsing instead of assigning to `.innerHTML` satisfies opengrep's XSS
+ *  heuristic that flags every raw `innerHTML =`; callers are expected to
+ *  have produced or sanitised the markup themselves.
+ *
+ *  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>` and
+ *  `<math>` as foreign-namespace roots and correctly parses the mixed
+ *  subtree. */
+export function parseMarkupBody(markup) {
+    return new DOMParser().parseFromString(markup, "text/html").body;
+}
+/** Adopt an SVG markup string into a live DOM node. Returns null when
+ *  the markup has no `<svg>` root. */
+export function adoptSvg(svgMarkup) {
+    // `<svg>` at the top level lands under `body` in HTML5 parsing.
+    const svgEl = parseMarkupBody(svgMarkup).querySelector("svg");
+    if (!svgEl)
+        return null;
+    return document.importNode(svgEl, true);
+}

package/dist/index.d.ts CHANGED Viewed

@@ -12,3 +12,6 @@ export * from "./image/resolve.js";
 export * from "./image/rewriteMarkdownImageRefs.js";
 export * from "./markdown/mermaidRender.js";
 export * from "./markdown/mermaidExtension.js";
+export * from "./markdown/mathExtension.js";
+export * from "./markdown/mathRender.js";
+export * from "./dom/adoptSvg.js";

package/dist/index.js CHANGED Viewed

@@ -12,3 +12,6 @@ export * from "./image/resolve.js";
 export * from "./image/rewriteMarkdownImageRefs.js";
 export * from "./markdown/mermaidRender.js";
 export * from "./markdown/mermaidExtension.js";
+export * from "./markdown/mathExtension.js";
+export * from "./markdown/mathRender.js";
+export * from "./dom/adoptSvg.js";

package/dist/markdown/mathExtension.d.ts ADDED Viewed

@@ -0,0 +1,34 @@
+import type { MarkedExtension } from "marked";
+/** Index of the first `$` in `src` that could legally open math, or
+ *  `undefined` when there is none. Marked uses this to cut the
+ *  preceding text token, so returning a position is what gets the
+ *  tokenizer invoked there at all. */
+export declare function findMathStart(src: string): number | undefined;
+/** True when `body` passes the strict inline-`$` rules 2-5. `after` is
+ *  the character following the closing delimiter (empty at end of
+ *  input). */
+export declare function isPlausibleInlineMath(body: string, after: string): boolean;
+/** Placeholder `mathRender.ts` looks for. The TeX source rides in the
+ *  element's text content — DOMPurify preserves text verbatim, and
+ *  reading it back out of the DOM decodes the entities natively, so no
+ *  manual unescaping is needed downstream.
+ *
+ *  `block` picks the wrapper element and is independent of `display`:
+ *  a `$$…$$` sitting mid-sentence typesets in display mode but must
+ *  still emit a `<span>`, because marked has it inside a `<p>` and a
+ *  `<div>` there is invalid nesting the browser silently reflows. */
+export declare function mathPlaceholder(tex: string, opts: {
+    display: boolean;
+    block: boolean;
+}): string;
+/** Index of the first `$$` that begins a line (up to 3 leading spaces),
+ *  or `undefined`. A block-level `start()` truncates the paragraph
+ *  marked is accumulating, so pointing it at a mid-sentence `$$…$$`
+ *  would split the prose around an inline formula. Only a line-leading
+ *  `$$` can possibly satisfy the block tokenizer, so only those are
+ *  worth stopping for — mid-paragraph display math is picked up by the
+ *  inline extension instead. */
+export declare function findMathBlockStart(src: string): number | undefined;
+/** Register with `marked.use(mathExtension)`. Pair with
+ *  `renderMathNodes()` from `mathRender.js` on the injected DOM. */
+export declare const mathExtension: MarkedExtension;

package/dist/markdown/mathExtension.js ADDED Viewed

@@ -0,0 +1,195 @@
+// Marked extension that turns TeX math into placeholder elements. The
+// actual typesetting is deferred to `mathRender.ts`, which scans the
+// placeholders in the DOM after Vue's v-html injects the html — the
+// same two-step split `mermaidExtension.ts` / `mermaidRender.ts` use,
+// and for the same two reasons: this file stays pure (no runtime dep
+// beyond `marked` and the zero-dep `@mulmoclaude/common` leaf) so the
+// html shape is testable without a browser, and the MathJax runtime
+// stays out of the initial bundle.
+//
+// Why MathJax SVG and not KaTeX:
+//   - The rendered output is a self-contained `<svg>` using
+//     `currentColor` — no stylesheet and no webfont files to ship in
+//     the published npm tarball. KaTeX's html output needs
+//     `katex.min.css` plus ~60 woff2 files.
+//   - Marp decks already render math through marp-core, which uses
+//     MathJax SVG by default. Rendering the plain-markdown preview the
+//     same way keeps one document from looking like two.
+//   - KaTeX's `mathml` output survives `sanitizeMarkdownHtml` badly:
+//     DOMPurify drops `<semantics>`/`<annotation>` but keeps the
+//     annotation's TEXT, so the raw LaTeX source lands next to the
+//     formula as visible garbage.
+//
+// Delimiter rules. `$` is a currency symbol far more often than it is
+// a math delimiter, so the inline form is deliberately strict — the
+// Pandoc rule set, which is what stops `$100 と $200` from swallowing
+// the prose between two prices:
+//
+//   1. The opening `$` must not be preceded by an ASCII alphanumeric
+//      (`US$5`) or by a backslash (`\$`, an escaped literal).
+//   2. The character AFTER the opening `$` must not be whitespace.
+//   3. The character BEFORE the closing `$` must not be whitespace,
+//      and must not be a backslash.
+//   4. The character AFTER the closing `$` must not be an ASCII digit
+//      (`$5-$10`).
+//   5. The body must be non-empty, single-line, and must not consist
+//      only of digits and separators (`$1,000$`).
+//
+// Rules 2-5 are enforced in the tokenizer, where the whole match is in
+// hand. Rule 1 needs the character BEFORE the match, which a marked
+// inline tokenizer never sees — its `src` always begins at the current
+// cursor. It is enforced in `start()` instead, which scans forward
+// through the remaining source and therefore does have the preceding
+// character for every `$` except one sitting at index 0 of the
+// remainder (only reachable when the previous inline token ended
+// exactly there). Best-effort by construction; the four tokenizer
+// rules carry the rest.
+//
+// `$$…$$` is unambiguous, so display math is not subject to rules 1-4.
+import { escapeHtml } from "@mulmoclaude/common";
+const ASCII_ALNUM = /[A-Za-z0-9]/;
+const ASCII_DIGIT = /\d/;
+/** Digits, separators and currency-ish punctuation only — `$1,000$`
+ *  is a price range, not an equation. */
+const NUMERIC_ONLY = /^[\s\d.,:;%+-]*$/;
+/** Index of the first `$` in `src` that could legally open math, or
+ *  `undefined` when there is none. Marked uses this to cut the
+ *  preceding text token, so returning a position is what gets the
+ *  tokenizer invoked there at all. */
+export function findMathStart(src) {
+    let from = 0;
+    for (;;) {
+        const index = src.indexOf("$", from);
+        if (index < 0)
+            return undefined;
+        const prev = index === 0 ? "" : (src[index - 1] ?? "");
+        // Rule 1: not `US$5`, not an escaped `\$`.
+        if (prev !== "\\" && !ASCII_ALNUM.test(prev))
+            return index;
+        from = index + 1;
+    }
+}
+/** True when `body` passes the strict inline-`$` rules 2-5. `after` is
+ *  the character following the closing delimiter (empty at end of
+ *  input). */
+export function isPlausibleInlineMath(body, after) {
+    if (body.length === 0)
+        return false;
+    if (body.includes("\n"))
+        return false;
+    // Rule 2 / 3: no whitespace hugging either delimiter.
+    if (/^\s/.test(body) || /\s$/.test(body))
+        return false;
+    // Rule 3, second half: `\` before the closing `$` escapes it.
+    if (body.endsWith("\\"))
+        return false;
+    // Rule 4: `$5-$10`.
+    if (ASCII_DIGIT.test(after))
+        return false;
+    // Rule 5.
+    if (NUMERIC_ONLY.test(body))
+        return false;
+    return true;
+}
+/** Placeholder `mathRender.ts` looks for. The TeX source rides in the
+ *  element's text content — DOMPurify preserves text verbatim, and
+ *  reading it back out of the DOM decodes the entities natively, so no
+ *  manual unescaping is needed downstream.
+ *
+ *  `block` picks the wrapper element and is independent of `display`:
+ *  a `$$…$$` sitting mid-sentence typesets in display mode but must
+ *  still emit a `<span>`, because marked has it inside a `<p>` and a
+ *  `<div>` there is invalid nesting the browser silently reflows. */
+export function mathPlaceholder(tex, opts) {
+    const escaped = escapeHtml(tex);
+    const flag = opts.display ? "1" : "0";
+    const attrs = `data-math-pending="1" data-math-display="${flag}"`;
+    if (opts.block)
+        return `<div class="math-block" ${attrs}>${escaped}</div>\n`;
+    return `<span class="math-inline" ${attrs}>${escaped}</span>`;
+}
+// `$$…$$` occupying its own line(s). Registered at block level so it
+// does not end up wrapped in a paragraph with the surrounding prose.
+const BLOCK_FENCED = /^ {0,3}\$\$[ \t]*\n([\s\S]*?)\n {0,3}\$\$[ \t]*(?:\n+|$)/;
+const BLOCK_ONE_LINE = /^ {0,3}\$\$([^\n]+?)\$\$[ \t]*(?:\n+|$)/;
+/** Index of the first `$$` that begins a line (up to 3 leading spaces),
+ *  or `undefined`. A block-level `start()` truncates the paragraph
+ *  marked is accumulating, so pointing it at a mid-sentence `$$…$$`
+ *  would split the prose around an inline formula. Only a line-leading
+ *  `$$` can possibly satisfy the block tokenizer, so only those are
+ *  worth stopping for — mid-paragraph display math is picked up by the
+ *  inline extension instead. */
+export function findMathBlockStart(src) {
+    const match = /(^|\n) {0,3}\$\$/.exec(src);
+    if (!match)
+        return undefined;
+    // Point at the `$$` itself, not at the newline that precedes it.
+    return match.index + match[0].length - 2;
+}
+/** Type predicate rather than a cast: marked hands renderers a bare
+ *  `Tokens.Generic`, and both extensions here are the only producers of
+ *  these two token types, so the shape is checked once at the boundary
+ *  instead of asserted. */
+function isMathToken(token) {
+    return typeof token.text === "string" && typeof token.display === "boolean";
+}
+const mathBlock = {
+    name: "mathBlock",
+    level: "block",
+    start: findMathBlockStart,
+    tokenizer(src) {
+        const match = BLOCK_FENCED.exec(src) ?? BLOCK_ONE_LINE.exec(src);
+        const text = match?.[1]?.trim();
+        if (!match || text === undefined)
+            return undefined;
+        if (text.length === 0)
+            return undefined;
+        return { type: "mathBlock", raw: match[0], text, display: true };
+    },
+    renderer(token) {
+        if (!isMathToken(token))
+            return "";
+        return mathPlaceholder(token.text, { display: true, block: true });
+    },
+};
+// `$$…$$` inside a paragraph (display mode) and `$…$` (inline mode).
+const INLINE_DISPLAY = /^\$\$([^\n]+?)\$\$/;
+// The body alternates an escaped dollar against any other non-`$`
+// character, rather than excluding `$` outright: an escaped dollar has
+// to be consumed as ONE unit, or the first `\$` is taken for the closing
+// delimiter and a legitimate `$\text{Cost: \$5}$` is cut at the
+// backslash — where `isPlausibleInlineMath` then rejects it for ending
+// in one. The escape branch is ordered first so it wins the match.
+const INLINE_PLAIN = /^\$((?:\\\$|[^\n$])+?)\$/;
+const mathInline = {
+    name: "mathInline",
+    level: "inline",
+    start: findMathStart,
+    tokenizer(src) {
+        const display = INLINE_DISPLAY.exec(src);
+        const displayText = display?.[1]?.trim();
+        if (display && displayText !== undefined) {
+            if (displayText.length === 0)
+                return undefined;
+            return { type: "mathInline", raw: display[0], text: displayText, display: true };
+        }
+        const plain = INLINE_PLAIN.exec(src);
+        const body = plain?.[1];
+        if (!plain || body === undefined)
+            return undefined;
+        const after = src.slice(plain[0].length, plain[0].length + 1);
+        if (!isPlausibleInlineMath(body, after))
+            return undefined;
+        return { type: "mathInline", raw: plain[0], text: body, display: false };
+    },
+    renderer(token) {
+        if (!isMathToken(token))
+            return "";
+        return mathPlaceholder(token.text, { display: token.display, block: false });
+    },
+};
+/** Register with `marked.use(mathExtension)`. Pair with
+ *  `renderMathNodes()` from `mathRender.js` on the injected DOM. */
+export const mathExtension = {
+    extensions: [mathBlock, mathInline],
+};

package/dist/markdown/mathRender.d.ts ADDED Viewed

@@ -0,0 +1,46 @@
+/** Localised strings the render pipeline surfaces when it fails.
+ *  Callers (composables) resolve the keys at component-setup time and
+ *  hand the formatter down. Fallback defaults keep the pure module
+ *  testable without a Vue / i18n runtime. */
+export interface MathRenderLabels {
+    loadFailed: (error: string) => string;
+    renderFailed: (error: string) => string;
+}
+/** A host's EXTRA pass over one formula's markup, run between two
+ *  `sanitizeMathSvg` passes and never in place of one. Receives what the
+ *  baseline left (`<mjx-container>` wrapping the `<svg>`, plus the
+ *  assistive `<math>` twin) and returns a narrower version of it — what
+ *  it returns is sanitised again on the way out, so a hardener can only
+ *  ever take things away.
+ *
+ *  Two things it must keep, or the formula degrades: the `<svg>` element
+ *  itself (`adoptFormula` returns null without it, and the placeholder
+ *  becomes an error box), and — for inline math to sit on the text
+ *  baseline — the root `<svg>`'s own `style="vertical-align: …"`. A
+ *  policy that strips `style` everywhere still renders; the formula just
+ *  sits slightly high. */
+export type MathHardener = (markup: string) => string;
+/** DOMPurify pass over one formula's SVG. See the SANITISATION note at
+ *  the top of the file: this is the only thing standing between a
+ *  `\href{javascript:…}` in an arbitrary `.md` and a clickable payload
+ *  in the app's origin, because the markdown-level sanitiser has
+ *  already run by the time this markup exists. */
+export declare function sanitizeMathSvg(markup: string): string;
+/** Split one formula's sanitised markup into the picture and its
+ *  screen-reader counterpart, both imported into the live document.
+ *  `mathml` is null when MathJax produced no assistive copy. */
+export declare function adoptFormula(markup: string): {
+    svg: SVGElement;
+    mathml: Element | null;
+} | null;
+/** Typeset every unprocessed math placeholder under `root`. Safe to
+ *  call repeatedly — a rendered node loses `data-math-pending` and a
+ *  failed one is replaced by an `.math-error` box, so neither matches
+ *  a second time. `labels` defaults to English fallbacks so the pure
+ *  module remains callable from tests / node environments without an
+ *  i18n runtime. `harden` is an EXTRA pass over each formula's markup,
+ *  run between two `sanitizeMathSvg` passes rather than instead of one,
+ *  so it can only ever narrow what reaches the page (see the HOST note
+ *  at the top of the file); it defaults to leaving the sanitised markup
+ *  alone. */
+export declare function renderMathNodes(root: Element | Document | null | undefined, labels?: MathRenderLabels, harden?: MathHardener): Promise<void>;

package/dist/markdown/mathRender.js ADDED Viewed

@@ -0,0 +1,258 @@
+// Runtime side of the math pipeline: scans the DOM for the
+// `[data-math-pending]` placeholders written by `mathExtension.ts`,
+// lazy-loads MathJax on the first hit, typesets each formula to SVG,
+// and swaps the placeholder in place with the resulting `<svg>`.
+//
+// Mirrors `mermaidRender.ts` deliberately — same lazy-load-and-memoise
+// shape, same "replace the node so a second pass finds nothing"
+// idempotence, same localised error box carrying the source that broke.
+//
+// Lazy-load: `mathjax-full`'s TeX→SVG pipeline is heavy (~1 MB). The
+// dynamic import keeps it out of the initial bundle for the documents —
+// most of them — that contain no math at all.
+//
+// SVG, not CommonHTML: the output is a self-contained `<svg>` drawn in
+// `currentColor`, so it needs no stylesheet and no webfont files in the
+// published tarball, and it inherits the surrounding theme's text
+// colour for free.
+//
+// SANITISATION. This SVG is injected AFTER `sanitizeMarkdownHtml` has
+// run on the markdown, so DOMPurify never sees it on that pass — and
+// MathJax's TeX input is NOT inert: the `html` package (part of
+// `AllPackages`) implements `\href`, and `$\href{javascript:alert(1)}{x}$`
+// emits a real `<a href="javascript:…">` inside the SVG. A
+// `presentDocument` path can open any `.md` on disk, including one that
+// came with a cloned repository, so that is a live XSS vector and not a
+// theoretical one. Every formula therefore goes through DOMPurify here,
+// on its way in.
+//
+// `fontCache: "none"` is load-bearing for that, not a size preference.
+// The default (`"local"`) emits each glyph once into a `<defs>` block
+// and references it with `<use xlink:href="#…">` — and DOMPurify drops
+// every `<use>` element, which would leave a formula with correct
+// geometry and no glyphs at all. `"none"` inlines each glyph as its own
+// `<path>`, so nothing depends on an element the sanitiser removes.
+// Measured cost: ~5% more markup per formula.
+//
+// ACCESSIBILITY. MathJax's SVG carries `role="img"` and no accessible
+// name, so a screen reader meets an unlabelled graphic where the formula
+// is. `AssistiveMmlHandler` fixes that at the source: it marks the SVG
+// `aria-hidden="true"` and emits a MathML copy of the same expression
+// beside it, which assistive technology reads as maths rather than as a
+// picture or as raw LaTeX. That copy is visually hidden here with inline
+// styles rather than a class — this module ships no stylesheet and is
+// consumed by more than one host, so a host that never adopted our CSS
+// would otherwise render every formula twice.
+//
+// Sanitising rather than trimming the TeX package list is deliberate.
+// A package allow-list has to be re-audited every time MathJax adds an
+// extension; the sanitiser is a boundary that holds regardless, and it
+// keeps a legitimate `\href{https://…}` working while dropping the
+// `javascript:` one.
+//
+// A HOST MAY NEED A STRICTER POLICY THAN THE DEFAULT, which is why
+// `renderMathNodes` takes an extra pass. `sanitizeMathSvg` runs DOMPurify with
+// its defaults, and those keep `class` and `style` — while the TeX `html`
+// package puts BOTH under the author's control:
+//
+//   $\style{position:fixed;inset:0;background:#fff}{x}$  →  <g style="position: fixed; …">
+//   $\class{fixed inset-0 bg-white}{x}$                  →  <g class=" fixed inset-0 bg-white">
+//
+// Inside an `<svg>` those declarations are largely inert — CSS box
+// positioning does not apply to SVG child elements, and the root `<svg>`
+// clips its own overflow — so this is not a hole in THIS app, where the
+// markdown is a file on the user's own disk. It is a hole in the
+// invariant of a host that renders STRANGER-WRITTEN markdown on a
+// signed-in origin and has therefore banned author-controlled `class` /
+// `style` outright (mulmoserver's article renderer bans both precisely
+// because a utility-CSS framework turns a class name into positioning).
+// Such a host passes its own function.
+//
+// That function runs BETWEEN two `sanitizeMathSvg` passes, never instead of one.
+// The baseline is not a default a caller can decline: a host writing the targeted
+// transformer this feature exists for — strip `class` and `style`, keep the rest —
+// would otherwise silently re-admit the `\href{javascript:…}` the baseline is
+// there to stop (codex, #2983). And the pass AFTER it is what makes the return
+// type honest: a hardener hands back an arbitrary STRING, so nothing in the type
+// says it only removed things, and the markup it returns is what reaches the
+// document (coderabbit, #2983). Sanitising on both sides is what makes "may only
+// tighten" a property of the code rather than a sentence in a docstring — the
+// cost is one more DOMPurify pass per formula, against a MathJax typeset.
+import DOMPurify from "dompurify";
+import { parseMarkupBody } from "../dom/adoptSvg.js";
+const DEFAULT_LABELS = {
+    loadFailed: (error) => `⚠ MathJax failed to load: ${error}`,
+    renderFailed: (error) => `⚠ Math render failed: ${error}`,
+};
+/** DOMPurify pass over one formula's SVG. See the SANITISATION note at
+ *  the top of the file: this is the only thing standing between a
+ *  `\href{javascript:…}` in an arbitrary `.md` and a clickable payload
+ *  in the app's origin, because the markdown-level sanitiser has
+ *  already run by the time this markup exists. */
+export function sanitizeMathSvg(markup) {
+    return DOMPurify.sanitize(markup);
+}
+let typesetterPromise = null;
+/** The MathJax pieces this module needs, imported on demand. The return
+ *  type is inferred on purpose: annotating it would mean naming
+ *  `mathjax-full`'s deep-path types, which is exactly what the
+ *  `MathTypesetter` note above explains this module avoids — and an
+ *  alias referring back to this function is circular, which resolves to
+ *  `any` and silently unchecks every call below. */
+async function loadMathJax() {
+    const [{ mathjax }, { TeX }, { SVG }, { liteAdaptor }, { RegisterHTMLHandler }, { AllPackages }, { LiteElement }, { AssistiveMmlHandler }] = await Promise.all([
+        import("mathjax-full/js/mathjax.js"),
+        import("mathjax-full/js/input/tex.js"),
+        import("mathjax-full/js/output/svg.js"),
+        import("mathjax-full/js/adaptors/liteAdaptor.js"),
+        import("mathjax-full/js/handlers/html.js"),
+        import("mathjax-full/js/input/tex/AllPackages.js"),
+        import("mathjax-full/js/adaptors/lite/Element.js"),
+        import("mathjax-full/js/a11y/assistive-mml.js"),
+    ]);
+    return { mathjax, TeX, SVG, liteAdaptor, RegisterHTMLHandler, AllPackages, LiteElement, AssistiveMmlHandler };
+}
+/** Build the one-shot TeX→SVG renderer.
+ *
+ *  `RegisterHTMLHandler` mutates a MathJax-global handler list, so it
+ *  must run exactly once per page — memoising the whole builder in
+ *  `typesetterPromise` is what guarantees that. `AssistiveMmlHandler`
+ *  wraps that handler so every formula also carries a MathML copy of
+ *  itself; see the ACCESSIBILITY note at the top of the file.
+ *
+ *  `doc` and `adaptor` stay captured in the closure rather than being
+ *  handed back, so both calls keep the concrete types their imports
+ *  gave them and nothing downstream has to assert a node shape.
+ *  `AbstractMathDocument.convert` is nonetheless declared `any`, hence
+ *  the real `instanceof` narrowing against the lite adaptor's own node
+ *  class. */
+async function buildTypesetter() {
+    const { mathjax, TeX, SVG, liteAdaptor, RegisterHTMLHandler, AllPackages, LiteElement, AssistiveMmlHandler } = await loadMathJax();
+    const adaptor = liteAdaptor();
+    AssistiveMmlHandler(RegisterHTMLHandler(adaptor));
+    const doc = mathjax.document("", {
+        InputJax: new TeX({ packages: AllPackages }),
+        OutputJax: new SVG({ fontCache: "none" }),
+    });
+    return {
+        render: (tex, display, harden) => {
+            const node = doc.convert(tex, { display });
+            if (!(node instanceof LiteElement))
+                throw new Error("MathJax returned an unexpected node type");
+            // Baseline, host policy, baseline. Never the host policy alone.
+            return sanitizeMathSvg(harden(sanitizeMathSvg(adaptor.outerHTML(node))));
+        },
+    };
+}
+async function loadTypesetter() {
+    if (typesetterPromise)
+        return typesetterPromise;
+    const attempt = buildTypesetter();
+    // 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
+    // formula to render. Without this reset the module would be dead
+    // until the user reloaded.
+    attempt.catch(() => {
+        if (typesetterPromise === attempt)
+            typesetterPromise = null;
+    });
+    typesetterPromise = attempt;
+    return attempt;
+}
+// Visually hidden, still in the accessibility tree. The clip-rect idiom
+// rather than `display:none` / `visibility:hidden`, both of which remove
+// the node from that tree — which would defeat the whole point.
+const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;border:0;";
+/** Split one formula's sanitised markup into the picture and its
+ *  screen-reader counterpart, both imported into the live document.
+ *  `mathml` is null when MathJax produced no assistive copy. */
+export function adoptFormula(markup) {
+    const parsed = parseMarkupBody(markup);
+    const svg = parsed.querySelector("svg");
+    if (!svg)
+        return null;
+    const math = parsed.querySelector("math");
+    return {
+        svg: document.importNode(svg, true),
+        mathml: math === null ? null : document.importNode(math, true),
+    };
+}
+function hiddenMathml(mathml) {
+    const wrapper = document.createElement("span");
+    wrapper.className = "math-a11y";
+    wrapper.setAttribute("style", VISUALLY_HIDDEN);
+    wrapper.appendChild(mathml);
+    return wrapper;
+}
+function errorBox(message, className) {
+    const box = document.createElement("code");
+    box.className = className;
+    box.textContent = message;
+    return box;
+}
+function placeLoadError(nodes, err, labels) {
+    const message = labels.loadFailed(String(err));
+    for (const node of nodes) {
+        node.replaceWith(errorBox(message, "math-error"));
+    }
+}
+function pendingNodes(root) {
+    return Array.from(root.querySelectorAll("[data-math-pending]"));
+}
+function renderOne(node, typesetter, labels, harden) {
+    // `textContent` gives us the raw TeX — we escaped it going in and
+    // DOMPurify preserves text verbatim, so entity decoding is
+    // browser-native from the DOM read.
+    const source = node.textContent ?? "";
+    const display = node.dataset.mathDisplay === "1";
+    try {
+        const formula = adoptFormula(typesetter.render(source, display, harden));
+        if (!formula)
+            throw new Error("MathJax produced malformed SVG");
+        // Keep the placeholder's own element (a `<div>` for block math, a
+        // `<span>` inside a paragraph for inline) so the surrounding flow
+        // is unchanged — only its contents and the pending flag change.
+        node.replaceChildren(formula.svg);
+        if (formula.mathml)
+            node.appendChild(hiddenMathml(formula.mathml));
+        delete node.dataset.mathPending;
+    }
+    catch (err) {
+        // Preserve the source next to the localised header so the author
+        // can see WHICH formula broke.
+        node.replaceWith(errorBox(`${labels.renderFailed(String(err))} — ${source}`, "math-error"));
+    }
+}
+/** Typeset every unprocessed math placeholder under `root`. Safe to
+ *  call repeatedly — a rendered node loses `data-math-pending` and a
+ *  failed one is replaced by an `.math-error` box, so neither matches
+ *  a second time. `labels` defaults to English fallbacks so the pure
+ *  module remains callable from tests / node environments without an
+ *  i18n runtime. `harden` is an EXTRA pass over each formula's markup,
+ *  run between two `sanitizeMathSvg` passes rather than instead of one,
+ *  so it can only ever narrow what reaches the page (see the HOST note
+ *  at the top of the file); it defaults to leaving the sanitised markup
+ *  alone. */
+export async function renderMathNodes(root, labels = DEFAULT_LABELS, harden = (markup) => markup) {
+    if (!root)
+        return;
+    const nodes = pendingNodes(root);
+    if (nodes.length === 0)
+        return;
+    let typesetter;
+    try {
+        typesetter = await loadTypesetter();
+    }
+    catch (err) {
+        // The dynamic import failed (network / bundler / adblock). Swap
+        // every pending placeholder for a visible error box so the user
+        // sees WHY the formula is missing instead of raw TeX, 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;
+    }
+    for (const node of nodes)
+        renderOne(node, typesetter, labels, harden);
+}

package/dist/markdown/mermaidRender.d.ts CHANGED Viewed

@@ -7,23 +7,6 @@ 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.

package/dist/markdown/mermaidRender.js CHANGED Viewed

@@ -8,6 +8,7 @@
 // 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.
+import { adoptSvg } from "../dom/adoptSvg.js";
 const DEFAULT_LABELS = {
     loadFailed: (error) => `⚠ Mermaid failed to load: ${error}`,
     renderFailed: (error) => `⚠ Mermaid render failed: ${error}`,
@@ -56,30 +57,6 @@ function nextRenderId(idPrefix) {
 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

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/markdown-utils",
-  "version": "1.3.5",
+  "version": "2.0.0",
   "description": "Browser-safe markdown / image rendering utilities shared by the MulmoClaude host and the markdown plugin",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,18 +33,21 @@
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmoclaude/common": "^1.1.2",
+    "@mulmoclaude/common": "^1.2.0",
+    "dompurify": "^3.4.13",
     "js-yaml": "^5.2.3",
-    "marked": "^18.0.7"
+    "marked": "^18.0.11"
   },
   "peerDependencies": {
-    "mermaid": "^11.16.0",
+    "mathjax-full": "^3.2.2",
+    "mermaid": "^11.16.1",
     "vue": "^3.5.0"
   },
   "devDependencies": {
-    "mermaid": "^11.16.0",
+    "mathjax-full": "^3.2.2",
+    "mermaid": "^11.17.2",
     "typescript": "^6.0.3",
-    "vue": "^3.5.40"
+    "vue": "^3.5.41"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/markdown-utils#readme",
   "repository": {