@mulmoclaude/markdown-utils 1.4.0 → 2.0.0

package/dist/markdown/mathRender.d.ts

@@ -6,6 +6,20 @@ 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
@@ -24,5 +38,9 @@ export declare function adoptFormula(markup: string): {
  *  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. */
-export declare function renderMathNodes(root: Element | Document | null | undefined, labels?: MathRenderLabels): Promise<void>;
+ *  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

@@ -49,6 +49,35 @@
 // 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 = {
@@ -106,11 +135,12 @@ async function buildTypesetter() {
         OutputJax: new SVG({ fontCache: "none" }),
     });
     return {
-        render: (tex, display) => {
+        render: (tex, display, harden) => {
             const node = doc.convert(tex, { display });
             if (!(node instanceof LiteElement))
                 throw new Error("MathJax returned an unexpected node type");
-            return sanitizeMathSvg(adaptor.outerHTML(node));
+            // Baseline, host policy, baseline. Never the host policy alone.
+            return sanitizeMathSvg(harden(sanitizeMathSvg(adaptor.outerHTML(node))));
         },
     };
 }
@@ -170,14 +200,14 @@ function placeLoadError(nodes, err, labels) {
 function pendingNodes(root) {
     return Array.from(root.querySelectorAll("[data-math-pending]"));
 }
-function renderOne(node, typesetter, labels) {
+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));
+        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
@@ -199,8 +229,12 @@ function renderOne(node, typesetter, labels) {
  *  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. */
-export async function renderMathNodes(root, labels = DEFAULT_LABELS) {
+ *  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);
@@ -220,5 +254,5 @@ export async function renderMathNodes(root, labels = DEFAULT_LABELS) {
         return;
     }
     for (const node of nodes)
-        renderOne(node, typesetter, labels);
+        renderOne(node, typesetter, labels, harden);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmoclaude/markdown-utils",
-  "version": "1.4.0",
+  "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",