@mulmoclaude/markdown-utils 1.4.0 → 2.1.0

package/dist/markdown/mathExtension.js

@@ -32,8 +32,29 @@
 //      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$`).
+//   5. The body must be non-empty, single-line, and must be something a
+//      formula could be ABOUT: a number written the way money is
+//      (`$1,000$`, `$1.000,50$` — a price written twice) or separators
+//      with no digits at all (`$+$`) are not.
+//
+// Rule 5 used to reject EVERY digits-and-separators body, and that was
+// too wide: `1秒を $10000$ 個のステップに割る` and `答えは $1$` are the
+// ordinary way to write a number in a maths article, and both came out
+// as a literal `$10000$` / `$1$` sitting in the prose. The signature of
+// a price is its SHAPE — digits in threes, or more than one separator —
+// and the two shapes that actually
+// appear in currency prose are already dead: `$100 と $200` by rule 3
+// (whitespace before the close) and `$5-$10` by rule 4 (a digit after
+// it). What stays admitted is a body like `$5$`, which a person quoting
+// a price does not write: they write `$5`, and it is the DOUBLED
+// delimiter that makes it maths.
+//
+// The SHAPE is matched rather than a particular separator, because a
+// comma groups thousands in English and marks the decimal in most of
+// Europe, and a dot does the opposite (codex, #2985). `$1,5$` is one and
+// a half and typesets; `$1.000,50$` is a price and does not. `$1,500$`
+// is genuinely ambiguous and is read as the price — the reading rule 5
+// already had, which this narrowing keeps rather than reverses.
 //
 // 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
@@ -49,9 +70,50 @@
 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.,:;%+-]*$/;
+const DIGITS = /^\d+$/;
+/** Every character that separates the digit runs of a written number,
+ *  in any locale: `1,000.50`, `1.000,50`, `1 000,50`. Which one groups
+ *  and which one marks the decimal is exactly what cannot be known, so
+ *  none of them is read as one or the other. */
+const NUMBER_SEPARATORS = /[.,\s]/;
+const THOUSAND = 3;
+/** A bare number written the way MONEY is written rather than the way a
+ *  quantity is — `1,000`, `1.000`, `1 000`, `1.000,50`, `12,345,678`.
+ *
+ *  Read from the SHAPE, not from which separator appeared: a comma
+ *  groups thousands in English and marks the decimal in most of Europe,
+ *  and a dot does the opposite, so a rule that names one of them fails
+ *  half the world's authors either way (codex, #2985).
+ *
+ *  Two separators or more is money — a quantity does not need them. One
+ *  separator followed by exactly three digits is ambiguous, `$1,500$` as
+ *  much as `$1.500$`, and is read as money: that is the reading rule 5
+ *  already had, and the one this file is narrowing rather than
+ *  reversing. Everything else — `10000`, `1`, `1,5`, `3.14159` — is a
+ *  number, and a number in a maths article is maths.
+ *
+ *  A leading zero is NOT an exception, though it looks like one: a
+ *  three-decimal sub-unit price is how fuel is priced (`$0.100` a litre),
+ *  so `$0.100$` is as ambiguous as `$1.500$` and is read the same way
+ *  (codex, #2985). Three digits after the separator is the whole test. */
+function isMoneyShaped(body) {
+    const runs = body.split(NUMBER_SEPARATORS);
+    // Anything that is not digits-and-separators is not a written number at
+    // all — `x=1` and `\pi` land here and are maths by this rule.
+    if (!runs.every((run) => DIGITS.test(run)))
+        return false;
+    if (runs.length === 1)
+        return false;
+    if (runs.length > 2)
+        return true;
+    const [, tail] = runs;
+    if (tail === undefined)
+        return false;
+    return tail.length === THOUSAND;
+}
+/** The same set with the digits removed: a body of punctuation has
+ *  nothing to typeset. */
+const SEPARATORS_ONLY = /^[\s.,:;%+-]*$/;
 /** 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
@@ -86,8 +148,11 @@ export function isPlausibleInlineMath(body, after) {
     // Rule 4: `$5-$10`.
     if (ASCII_DIGIT.test(after))
         return false;
-    // Rule 5.
-    if (NUMERIC_ONLY.test(body))
+    // Rule 5. The shape of money is what says "price"; a plain number is
+    // just a number, and a number in a maths article is maths.
+    if (isMoneyShaped(body))
+        return false;
+    if (SEPARATORS_ONLY.test(body))
         return false;
     return true;
 }

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.1.0",
   "description": "Browser-safe markdown / image rendering utilities shared by the MulmoClaude host and the markdown plugin",
   "type": "module",
   "main": "./dist/index.js",