rapier-math 1.0.1 → 1.1.0

package/src/math/index.d.ts

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+export interface MathError {
+  code: string;
+  message: string;
+  /** Zero-based UTF-16 offset in the formula. */
+  offset: number;
+  command?: string;
+  messageTruncated?: boolean;
+  commandTruncated?: boolean;
+  /** True only when refused oversized source is not embedded in diagnostic SVG. */
+  sourceOmitted?: boolean;
+}
+export interface RenderOptions {
+  displayMode?: boolean;
+  maxWidth?: number;
+  screen?: {fontSize: number; pixelRatio: number; dark: boolean};
+}
+export interface RenderResult {
+  svg: string;
+  width: number;
+  height: number;
+  depth: number;
+  lines: number;
+  fitted: boolean;
+  errors: MathError[];
+}
+/** Parser nodes are inspectable; the internal node vocabulary can grow. */
+export interface MathNode {type: string; [field: string]: unknown}
+/** Browser nodes (including Element, Document and DocumentFragment) satisfy this
+ * structural type without requiring the DOM type library in server projects. */
+export interface MathContainer {readonly nodeType: number}
+export const version: string;
+/** Oversized source returns a bounded resource-limit diagnostic with sourceOmitted. */
+export function render(source: unknown, options?: RenderOptions): RenderResult;
+export function renderToString(source: unknown, options?: RenderOptions): string;
+export function parse(source: string): MathNode;
+export function fit(container: MathContainer): number;
+export function observe(container: MathContainer): () => void;
+declare const RapierMath: Readonly<{
+  version: typeof version; render: typeof render; renderToString: typeof renderToString;
+  parse: typeof parse; fit: typeof fit; observe: typeof observe;
+}>;
+export default RapierMath;

package/src/math/integration.d.ts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+import type {RenderOptions} from './index.js';
+export interface IntegrationOptions {
+  renderOptions?: RenderOptions;
+  /** Per document. Default 1024. Exhaustion leaves subsequent math as source. */
+  maxFormulas?: number;
+  /** Combined successful SVG code units per document. Default 16 * 1024 * 1024. */
+  maxOutputLength?: number;
+}

package/src/math/integration.mjs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+import {render} from './index.mjs';
+
+export const escapeText = text => text.replace(/[&<>"'\r]/g, char =>
+  ({'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;', '\r': '&#13;'}[char]));
+
+// One budget per document render. Rejection leaves the host's text node intact.
+export function createFormulaRenderer(options = {}) {
+  const maxFormulas = options.maxFormulas ?? 1024, maxOutputLength = options.maxOutputLength ?? 16 * 1024 * 1024;
+  for (const value of [maxFormulas, maxOutputLength])
+    if (!Number.isSafeInteger(value) || value < 0) throw new RangeError('Math integration budgets must be finite nonnegative integers.');
+  let count = 0, length = 0;
+  return (source, displayMode) => {
+    let result;
+    if (count >= maxFormulas || length >= maxOutputLength) return {errors: [{code: 'resource-limit', offset: 0,
+      message: 'The document math budget is exhausted.'}]};
+    count++;
+    try { result = render(source, {...options.renderOptions, displayMode}); }
+    catch (error) { return {errors: [{code: error.code || 'invalid-tex', message: String(error.message), offset: error.offset || 0}]}; }
+    if (result.errors.length) return {errors: result.errors};
+    if (result.svg.length > maxOutputLength - length) {
+      length = maxOutputLength;
+      return {errors: [{code: 'resource-limit', offset: 0, message: 'The document math output budget is exhausted.'}]};
+    }
+    length += result.svg.length;
+    return result;
+  };
+}

package/src/math/layout.js

@@ -13,9 +13,9 @@ function mathScale(c) {
   return c.size * (c.screen ? Math.max(scale, Math.min(1, (c.level === 1 ? 12 : 10) / c.screen.fontSize)) : scale);
 }
 
-function mathScreenStroke(c) {
+function mathScreenStroke(c, scale) {
   if (!c.screen) return 0;
-  const {fontSize, pixelRatio, dark} = c.screen, size = fontSize * mathScale(c);
+  const {fontSize, pixelRatio, dark} = c.screen, size = fontSize * (scale ?? mathScale(c));
   if (!(size > 0)) return 0;
   const small = Math.max(0, Math.min(1, (32 - size) / 16));
   const hairline = MATH_FONT.constants.FractionRuleThickness / MATH_FONT.units * size;
@@ -41,35 +41,37 @@ function mathCompose(items, width, extra = {}) {
   return mathBox(width, h, d, svg, {left, right, inkTop:Number.isFinite(inkTop)?inkTop:-h, inkBottom:Number.isFinite(inkBottom)?inkBottom:d,...glyph,...extra});
 }
 
+const MATH_STYLED_RANGES = {
+  italic: [0x1d434, 0x1d44e, null], bold: [0x1d400, 0x1d41a, 0x1d7ce],
+  'bold-italic': [0x1d468, 0x1d482, null], script: [0x1d49c, 0x1d4b6, null],
+  'bold-script': [0x1d4d0, 0x1d4ea, null], fraktur: [0x1d504, 0x1d51e, null],
+  'bold-fraktur': [0x1d56c, 0x1d586, null], 'double-struck': [0x1d538, 0x1d552, 0x1d7d8],
+  'sans-serif': [0x1d5a0, 0x1d5ba, 0x1d7e2], 'sans-serif-bold': [0x1d5d4, 0x1d5ee, 0x1d7ec],
+  'sans-serif-italic': [0x1d608, 0x1d622, null], 'sans-serif-bold-italic': [0x1d63c, 0x1d656, null],
+  monospace: [0x1d670, 0x1d68a, 0x1d7f6],
+};
+const MATH_STYLED_LEGACY = {
+  italic: {104: 0x210e},
+  script: {66:0x212c,69:0x2130,70:0x2131,72:0x210b,73:0x2110,76:0x2112,77:0x2133,82:0x211b,101:0x212f,103:0x210a,111:0x2134},
+  fraktur: {67:0x212d,72:0x210c,73:0x2111,82:0x211c,90:0x2128},
+  'double-struck': {67:0x2102,72:0x210d,78:0x2115,80:0x2119,81:0x211a,82:0x211d,90:0x2124},
+};
+const MATH_STYLED_GREEK = {bold:0x1d6a8, italic:0x1d6e2, 'bold-italic':0x1d71c, 'sans-serif-bold':0x1d756, 'sans-serif-bold-italic':0x1d790};
+const MATH_STYLED_GREEK_SPECIAL = [0x2207,0x2202,0x3f5,0x3d1,0x3f0,0x3d5,0x3f1,0x3d6];
 function mathStyledCodePoint(cp, variant) {
-  const ranges = {
-    italic: [0x1d434, 0x1d44e, null], bold: [0x1d400, 0x1d41a, 0x1d7ce],
-    'bold-italic': [0x1d468, 0x1d482, null], script: [0x1d49c, 0x1d4b6, null],
-    'bold-script': [0x1d4d0, 0x1d4ea, null], fraktur: [0x1d504, 0x1d51e, null],
-    'bold-fraktur': [0x1d56c, 0x1d586, null], 'double-struck': [0x1d538, 0x1d552, 0x1d7d8],
-    'sans-serif': [0x1d5a0, 0x1d5ba, 0x1d7e2], 'sans-serif-bold': [0x1d5d4, 0x1d5ee, 0x1d7ec],
-    'sans-serif-italic': [0x1d608, 0x1d622, null], 'sans-serif-bold-italic': [0x1d63c, 0x1d656, null],
-    monospace: [0x1d670, 0x1d68a, 0x1d7f6],
-  };
-  const legacy = {
-    italic: {104: 0x210e},
-    script: {66:0x212c,69:0x2130,70:0x2131,72:0x210b,73:0x2110,76:0x2112,77:0x2133,82:0x211b,101:0x212f,103:0x210a,111:0x2134},
-    fraktur: {67:0x212d,72:0x210c,73:0x2111,82:0x211c,90:0x2128},
-    'double-struck': {67:0x2102,72:0x210d,78:0x2115,80:0x2119,81:0x211a,82:0x211d,90:0x2124},
-  };
   if (variant === 'normal') variant = 'italic';
-  if (legacy[variant]?.[cp] !== undefined) return legacy[variant][cp];
-  const r = ranges[variant];
+  if (MATH_STYLED_LEGACY[variant]?.[cp] !== undefined) return MATH_STYLED_LEGACY[variant][cp];
+  const r = MATH_STYLED_RANGES[variant];
   if (r) {
     if (cp >= 65 && cp <= 90) return r[0] + cp - 65;
     if (cp >= 97 && cp <= 122) return r[1] + cp - 97;
     if (r[2] && cp >= 48 && cp <= 57) return r[2] + cp - 48;
   }
-  const greek = {bold:0x1d6a8, italic:0x1d6e2, 'bold-italic':0x1d71c, 'sans-serif-bold':0x1d756, 'sans-serif-bold-italic':0x1d790}[variant];
+  const greek = MATH_STYLED_GREEK[variant];
   if (greek !== undefined) {
     if (cp >= 0x391 && cp <= 0x3a9 && cp !== 0x3a2) return greek + cp - 0x391;
     if (cp >= 0x3b1 && cp <= 0x3c9) return greek + 26 + cp - 0x3b1;
-    const special = [0x2207,0x2202,0x3f5,0x3d1,0x3f0,0x3d5,0x3f1,0x3d6].indexOf(cp);
+    const special = MATH_STYLED_GREEK_SPECIAL.indexOf(cp);
     if (special === 0) return greek + 25;
     if (special > 0) return greek + 50 + special;
   }
@@ -78,19 +80,19 @@ function mathStyledCodePoint(cp, variant) {
 
 function mathGlyphIndex(id, c, extra = {}) {
   if(c.dotless)id=MATH_FONT.dotless?.[id] ?? id;
-  const alternates=MATH_FONT.scriptAlternates[id];
-  const pixels=c.screen?c.screen.fontSize*mathScale(c):Infinity,
+  const alternates=MATH_FONT.scriptAlternates[id],scale=mathScale(c);
+  const pixels=c.screen?c.screen.fontSize*scale:Infinity,
     optical=Math.max(c.level,pixels<10?2:pixels<15?1:0);
   if(optical && alternates)id=alternates[Math.min(optical,alternates.length)-1];
   if(c.flattenAccent)id=MATH_FONT.flatAccents[id] ?? id;
-  const g = MATH_FONT.glyphs[id], s = mathScale(c) / MATH_FONT.units, stroke = mathScreenStroke(c), radius = stroke / 2;
+  const g = MATH_FONT.glyph(id), s = scale / MATH_FONT.units, stroke = mathScreenStroke(c,scale), radius = stroke / 2;
   if (!g) throw Object.assign(new Error('Unsupported mathematical glyph'), {code:'unsupported-glyph'});
   if(c.budget) {
     c.budget.outlineBytes=(c.budget.outlineBytes || 0)+g[7].length+96;
     if(c.budget.outlineBytes>4*1024*1024)throw Object.assign(new Error('Mathematical outlines exceed the rendering budget'),{code:'resource-limit'});
   }
   const svg = g[7] ? '<path d="' + g[7] + '" transform="scale(' + mathNumber(s) + ' ' + mathNumber(-s) + ')"'+
-    (c.screen ? ' data-math-ink="' + mathNumber(mathScale(c)) + '"' : '') +
+    (c.screen ? ' data-math-ink="' + mathNumber(scale) + '"' : '') +
     (stroke ? ' stroke="currentColor" stroke-width="' + mathNumber(stroke / s) + '" stroke-linejoin="round" paint-order="stroke fill"' : '') + '/>' : '';
   return mathBox(g[0] * s, Math.max(0, g[4] * s + radius), Math.max(0, -g[2] * s + radius), svg,
     {left: Math.min(0,g[1]*s-radius), right: Math.max(g[0]*s,g[3]*s+radius), inkTop:-g[4]*s-radius, inkBottom:-g[2]*s+radius, italic: g[5]*s, stroke,
@@ -98,8 +100,9 @@ function mathGlyphIndex(id, c, extra = {}) {
 }
 
 function mathGlyph(value, c, extra = {}) {
-  if ([...value].length !== 1) return mathText(value, c, extra);
-  const cp = value.codePointAt(0), mapped = mathStyledCodePoint(cp, extra.variant || c.variant);
+  const cp = value.codePointAt(0);
+  if (value.length !== (cp > 0xffff ? 2 : 1)) return mathText(value, c, extra);
+  const mapped = mathStyledCodePoint(cp, extra.variant || c.variant);
   const id = MATH_FONT.chars[mapped] ?? MATH_FONT.chars[cp];
   if (id === undefined) {
     const composed = mathFallbackGlyph(value, c, extra);
@@ -134,7 +137,7 @@ function mathStretch(value, target, c, horizontal = false) {
   const shape = (glyph, advance) => {
     const b = mathGlyphIndex(glyph,c);
     if (!horizontal || b.w !== 0) return b;
-    const g = MATH_FONT.glyphs[b.glyph], unit = b.unitScale, x = -g[1] * unit;
+    const g = MATH_FONT.glyph(b.glyph), unit = b.unitScale, x = -g[1] * unit;
     const width = (advance ?? g[3] - g[1]) * unit;
     return mathCompose([[b,x,0]],width,{italic:b.italic,accent:b.accent+x});
   };
@@ -150,7 +153,7 @@ function mathStretch(value, target, c, horizontal = false) {
     // These font glyphs have straight central shafts but no MATH assembly.
     // Preserve both end shapes and widen only a narrow central strip.
     if('=⇌⇋↞↠→↔↦'.includes(value)) {
-      const g=MATH_FONT.glyphs[natural.glyph],unit=natural.unitScale,added=target-natural.w,
+      const g=MATH_FONT.glyph(natural.glyph),unit=natural.unitScale,added=target-natural.w,
         split=g[0]*(value==='↞'?0.75:value==='↠'?0.25:0.5),half=g[0]*0.05,
         left=split-half,right=split+half,delta=added/unit;
       // The two-headed arrows have their plain shaft opposite both heads.
@@ -201,7 +204,7 @@ function mathStretch(value, target, c, horizontal = false) {
     length=(full-overlap*connections.length)*unit;
   const items=[]; let pos=0, width=0;
   for (let i=0;i<pieces.length;i++) {
-    const p=pieces[i], b=mathGlyphIndex(p[0],c), g=MATH_FONT.glyphs[b.glyph];
+    const p=pieces[i], b=mathGlyphIndex(p[0],c), g=MATH_FONT.glyph(b.glyph);
     if (horizontal) items.push([b,pos,0]);
     else items.push([b,0,-pos+g[2]*unit]);
     width=Math.max(width,b.w);
@@ -273,8 +276,9 @@ function mathKern(b,corner,height) {
 }
 
 function mathContourBands(box, dy = 0) {
-  const profile = MATH_FONT.edgeProfiles[box.glyph];
-  if (!profile || !box.unitScale || box.extended) return null;
+  if (!box.unitScale || box.extended) return null;
+  const profile = MATH_FONT.profile(box.glyph);
+  if (!profile) return null;
   const bands = [], step = MATH_FONT.edgeStep, unit = box.unitScale;
   const x = box.glyphX || 0, y = (box.glyphY || 0) + dy, radius = (box.stroke || 0) / 2;
   for (let i = profile.length - 1; i > 0; i--) if (profile[i]) {
@@ -570,7 +574,7 @@ function mathLayout(n,c) {
     case 'smash': {const b=mathLayout(n.body,c);return {...b,h:n.mode==='b'?b.h:0,d:n.mode==='t'?b.d:0};}
     case 'raise': {const b=mathLayout(n.body,c),s=mathScale(c);return mathCompose([[b,0,-n.amount*s]],b.w,{class:b.class,...(n.height===undefined?{}:{h:n.height*s}),...(n.depth===undefined?{}:{d:n.depth*s})});}
     case 'rule': {const s=mathScale(c);return mathRule(n.width*s,(n.height+n.depth)*s,-n.height*s);}
-    case 'link': {const b=mathLayout(n.body,c);const url=new URL(n.href);if(!['http:','https:'].includes(url.protocol))throw Object.assign(new Error('Unsupported equation link'),{code:'unsafe-url'});b.svg='<a href="'+mathEscape(n.href)+'" target="_blank" rel="noopener noreferrer">'+b.svg+'</a>';return b;}
+    case 'link': {const b=mathLayout(n.body,c);const url=new URL(n.href);if(!['http:','https:'].includes(url.protocol))throw Object.assign(new Error('Unsupported equation link'),{code:'unsafe-url'});b.svg='<a href="'+mathEscape(n.href)+'" aria-label="'+mathEscape(n.href)+'" tabindex="0" target="_blank" rel="noopener noreferrer">'+b.svg+'</a>';return b;}
     default: throw Object.assign(new Error('Unsupported maths construct: '+n.type),{code:'unsupported-construct'});
   }
 }

package/src/math/markdown-it.d.ts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MIT
+import type MarkdownIt from 'markdown-it';
+import type {DelimiterOptions} from './delimiters.js';
+import type {IntegrationOptions} from './integration.js';
+export interface MarkdownMathOptions extends DelimiterOptions, IntegrationOptions {}
+export default function rapierMath(md: InstanceType<typeof MarkdownIt>, options?: MarkdownMathOptions): void;

package/src/math/markdown-it.mjs

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: MIT
+import {installMathRules} from './markdown-rules.mjs';
+import {createFormulaRenderer, escapeText} from './integration.mjs';
+
+export default function rapierMath(md, options = {}) {
+  installMathRules(md, options);
+  let session;
+  function withSession(renderer, render, tokens, opts, env) {
+    const previous = session, current = {render: createFormulaRenderer(options), children: new WeakSet()};
+    const visit = tokens => {
+      for (const token of tokens) {
+        if (token.children) { current.children.add(token.children); visit(token.children); }
+      }
+    };
+    visit(tokens);
+    session = current;
+    try { return render.call(renderer, tokens, opts, env); }
+    finally { session = previous; }
+  }
+  const render = md.renderer.render, renderInline = md.renderer.renderInline;
+  md.renderer.render = function(tokens, opts, env) {
+    return withSession(this, render, tokens, opts, env);
+  };
+  md.renderer.renderInline = function(tokens, opts, env) {
+    // The block renderer's inline children share its document budget. A separate
+    // inline tree, including a nested host renderInline call, owns a fresh one.
+    if (session?.children.has(tokens)) return renderInline.call(this, tokens, opts, env);
+    return withSession(this, renderInline, tokens, opts, env);
+  };
+  function formula(tokens, index, _options, env) {
+    const token = tokens[index], display = token.type === 'math_block';
+    const result = (session?.render || createFormulaRenderer(options))(token.content, display);
+    if (result.errors.length) {
+      (env.rapierMathErrors ||= []).push({source: token.content, errors: result.errors});
+      return '<code data-math-error="' + escapeText(result.errors[0].code) + '">' +
+        escapeText(token.meta?.mathSource ?? token.content) + '</code>';
+    }
+    return result.svg;
+  }
+  md.renderer.rules.math_inline = formula;
+  md.renderer.rules.math_block = (tokens, index, opts, env) => {
+    const result = formula(tokens, index, opts, env);
+    return tokens[index].block ? '<div class="math-display">' + result + '</div>\n' : result;
+  };
+}

package/src/math/markdown-rules.mjs

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: MIT
+// Original neutral adapter. The host owns Markdown structure and normalization.
+import {createMathMatcher} from './delimiters.mjs';
+
+export function installMathRules(md, {singleDollar = false, brackets = true, ruleName = 'rapier_math', inLink = false} = {}) {
+  // The host's image-alt renderer ignores unknown token types. Keep math as
+  // literal source in text-only output, while leaving escaping to that host.
+  const renderText = md.renderer.renderInlineAsText;
+  md.renderer.renderInlineAsText = function(tokens, options, env) {
+    return renderText.call(this, tokens.map(token =>
+      token.type === 'math_inline' || token.type === 'math_block'
+        ? {...token, type: 'text', content: token.meta?.mathSource ?? token.content}
+        : token), options, env);
+  };
+  const matchers = new WeakMap();
+  function match(state, at, limit) {
+    let entry = matchers.get(state);
+    if (!entry || entry.source !== state.src) {
+      entry = {source: state.src, match: createMathMatcher(state.src, {singleDollar, brackets})};
+      matchers.set(state, entry);
+    }
+    return entry.match(at, limit);
+  }
+  md.inline.ruler.before('escape', ruleName, (state, silent) => {
+    if (!inLink && state.linkLevel > 0) return false;
+    if (state.src[state.pos] !== '$' && state.src[state.pos] !== '\\') return false;
+    const span = match(state, state.pos, state.posMax);
+    if (!span) return false;
+    if (!silent) {
+      const token = state.push(span.displayMode ? 'math_block' : 'math_inline', '', 0);
+      token.markup = span.open;
+      token.content = state.src.slice(span.bodyStart, span.bodyEnd);
+      token.meta = {mathSource: state.src.slice(span.start, span.end)};
+    }
+    state.pos = span.end;
+    return true;
+  });
+  md.block.ruler.before('fence', ruleName, (state, startLine, endLine, silent) => {
+    // An indented code block belongs to the host even when it begins with dollars.
+    if (state.sCount[startLine] - state.blkIndent >= 4) return false;
+    const start = state.bMarks[startLine] + state.tShift[startLine];
+    if (state.src.slice(start, start + 2) !== '$$' && (!brackets || state.src.slice(start, start + 2) !== '\\[')) return false;
+    const span = match(state, start, state.eMarks[endLine - 1]);
+    if (!span?.displayMode) return false;
+    let last = startLine;
+    while (last < endLine && state.eMarks[last] < span.end) last++;
+    if (last >= endLine || span.bodyEnd < state.bMarks[last] + state.tShift[last] ||
+        state.src.slice(span.end, state.eMarks[last]).trim()) return false;
+    if (silent) return true;
+    const parts = [];
+    for (let line = startLine; line <= last; line++) {
+      const from = line === startLine ? span.bodyStart : state.bMarks[line] + state.tShift[line];
+      const to = line === last ? span.bodyEnd : state.eMarks[line];
+      parts.push(state.src.slice(from, to));
+    }
+    const token = state.push('math_block', 'math', 0);
+    token.block = true;
+    token.markup = span.open;
+    token.content = parts.join('\n');
+    token.meta = {mathSource: span.open + token.content + span.close};
+    token.map = [startLine, last + 1];
+    state.line = last + 1;
+    return true;
+  }, {alt: ['paragraph', 'reference', 'blockquote', 'list']});
+}

package/src/math/package-build.mjs

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 // The module has the exact classic renderer body, with module-local exports.
-import {readFile, writeFile} from 'node:fs/promises';
+import {writeFile} from 'node:fs/promises';
 import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
@@ -19,9 +19,9 @@ export function mathModule(bundle) {
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
   if (!process.argv[2]) throw new Error('usage: node src/math/package-build.mjs <module-file>');
   const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-  const {buildMath} = await import('../tools/build-math.mjs');
-  const result = await buildMath({root, updatePins: false});
-  const text = mathModule(await readFile(resolve(root, 'shell/vendor', result.bundle), 'utf8'));
+  const {assembleMath} = await import('../tools/build-math.mjs');
+  const {bytes} = await assembleMath({root});
+  const text = mathModule(bytes);
   await writeFile(resolve(process.argv[2]), text);
   console.log(JSON.stringify({file: process.argv[2], bytes: Buffer.byteLength(text)}));
 }

package/src/math/package-check.mjs

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: MIT
+// Package entry, exact authored text and hostile-content boundaries; no appearance assertions.
+import assert from 'node:assert/strict';
+import {readFile} from 'node:fs/promises';
+import {Script, createContext} from 'node:vm';
+import {mathModule} from './src/math/package-build.mjs';
+
+const read = path => readFile(new URL(path, import.meta.url), 'utf8');
+const pkg = JSON.parse(await read('./package.json'));
+const resources = JSON.parse(await read('./src/shell/math-resources.json'));
+const classicSource = await read('./' + resources.bundle);
+assert.equal(pkg.name, 'rapier-math');
+assert.equal(pkg.version, resources.version);
+assert.equal(pkg.type, 'module');
+assert.equal(pkg.license, 'SEE LICENSE IN LICENSE');
+assert.equal(Object.keys(pkg.dependencies || {}).length, 0);
+assert.equal(Object.keys(pkg.scripts || {}).length, 0);
+assert.equal(await read('./index.mjs'), mathModule(classicSource), 'exact generated module');
+const rendererLicense = await read('./LICENSE-MIT'), fontLicense = await read('./math-font-LICENSE.txt');
+for (const name of ['./LICENSE', './index.mjs', './' + resources.bundle]) {
+  const text = await read(name);
+  assert(text.includes(rendererLicense.trim()), name + ': renderer license');
+  assert(text.includes(fontLicense.trim()), name + ': complete font license');
+}
+
+// Initialize Node's lazy Web API globals before observing module purity. This
+// allocates a local Response only; no network request or renderer evaluation.
+new Response();
+const globals = Object.getOwnPropertyDescriptors(globalThis);
+const module = await import('./index.mjs');
+const afterImport = Object.getOwnPropertyDescriptors(globalThis);
+assert.deepEqual(Reflect.ownKeys(afterImport), Reflect.ownKeys(globals), 'module adds no globals');
+for (const key of Reflect.ownKeys(globals)) for (const field of Object.keys(globals[key]))
+  assert(Object.is(afterImport[key][field], globals[key][field]), 'module preserves global ' + String(key));
+assert.deepEqual(Object.keys(module).sort(), ['default', 'fit', 'observe', 'parse', 'render', 'renderToString', 'version']);
+for (const name of Object.keys(module.default)) assert.equal(module[name], module.default[name], 'named/default export ' + name);
+assert.equal(module.version, resources.version);
+assert(Object.isFrozen(module.default));
+
+const context = createContext({atob, URL});
+new Script(classicSource, {filename: resources.bundle}).runInContext(context);
+const classic = context.RapierMath;
+const plain = value => JSON.parse(JSON.stringify(value));
+const unescape = text => text.replace(/&(amp|lt|gt|quot|apos|#\d+|#x[\da-f]+);/gi, (_, entity) =>
+  entity[0] === '#' ? String.fromCodePoint(entity[1] === 'x' ? parseInt(entity.slice(2), 16) : Number(entity.slice(1))) :
+    ({amp: '&', lt: '<', gt: '>', quot: '"', apos: "'"})[entity]);
+function sourceAlternative(result, source) {
+  const label = /\baria-label="([^"]*)"/.exec(result.svg)?.[1];
+  const title = /<title>([^<]*)<\/title>/.exec(result.svg)?.[1];
+  const utf16 = /\bdata-tex-utf16="([0-9a-f]+)"/.exec(result.svg)?.[1];
+  if (utf16) assert.equal(utf16.match(/.{4}/g).map(part => String.fromCharCode(parseInt(part, 16))).join(''), source, 'exact UTF-16 alternative');
+  else { assert.equal(unescape(label), source, 'exact aria alternative'); assert.equal(unescape(title), source, 'exact title alternative'); }
+}
+function inert(svg) {
+  assert(!/<\s*(?:script|foreignObject|iframe|object|embed|image|style|animate|set)\b/i.test(svg), 'no executable or remote SVG element');
+  for (const tag of svg.match(/<[^>]+>/g) || []) {
+    const attributes = [...tag.matchAll(/\s([^\s=]+)="([^"]*)"/g)];
+    for (const [, name, value] of attributes) {
+      assert(!/^on/i.test(name), 'no event attribute');
+      if (/^(?:href|xlink:href)$/i.test(name)) assert(/^https?:\/\//i.test(unescape(value)), 'only HTTP(S) links');
+      if (!/^(?:aria-label|data-tex-utf16)$/.test(name)) assert(!/url\s*\(|javascript:|vbscript:/i.test(unescape(value)), 'no executable attribute');
+    }
+  }
+}
+
+const examples = [
+  [String.raw`\frac{-b\pm\sqrt{b^2-4ac}}{2a}`, {displayMode: true}],
+  [String.raw`\begin{aligned}a&=b+c\\d&=e+f\end{aligned}`, {displayMode: true, maxWidth: 4}],
+  [String.raw`\newcommand{\squareof}[1]{#1^2}\squareof{x}`, {screen: {fontSize: 16, pixelRatio: 2, dark: false}}],
+  [String.raw`\text{A < B & "C" 'D'} + α`, {}],
+  [String.raw`\href{https://example.com/?a=1&b=2}{x}`, {}],
+  [String.raw`\unsupported{content}`, {}],
+  ['x\u0000y\ud800z\udfff', {}],
+];
+for (const [source, options] of examples) {
+  const result = module.render(source, options);
+  assert.deepEqual(plain(result), plain(classic.render(source, options)), 'module/classic result');
+  assert.equal(module.renderToString(source, options), result.svg, 'string export agrees with render');
+  sourceAlternative(result, source); inert(result.svg);
+}
+assert.deepEqual(plain(module.parse(examples[0][0])), plain(classic.parse(examples[0][0])), 'module/classic parse');
+assert.equal(module.render(examples.at(-1)[0]).errors[0].code, 'invalid-source-character');
+assert.equal(module.render(examples.at(-2)[0]).errors[0].code, 'unsupported-command');
+
+const hostile = [
+  String.raw`\text{</title><script>alert(1)</script>}`,
+  String.raw`\href{javascript:alert(1)}{x}`,
+  String.raw`\href{data:text/html,test}{x}`,
+  String.raw`\href{https://example.com/" onload="alert(1)}{x}`,
+  String.raw`\color{url(https://example.com/payload)}x`,
+  String.raw`\def\again{\again}\again`,
+];
+for (const source of hostile) {
+  const result = module.render(source);
+  sourceAlternative(result, source); inert(result.svg);
+  assert.deepEqual(plain(result), plain(classic.render(source)), 'module/classic hostile result');
+}
+for (const source of hostile.slice(1)) assert(module.render(source).errors.length, 'unsafe or exhausted input produces a diagnostic');
+for (const source of ['x'.repeat(1_000_001), '\ud800'.repeat(1_000_001), '&'.repeat(8_000_000)]) {
+  const result = module.render(source);
+  assert.equal(result.errors[0].code, 'resource-limit');
+  assert.equal(result.errors[0].sourceOmitted, true);
+  assert(result.svg.includes('data-math-source-omitted="true"'));
+  assert(!result.svg.includes('data-tex-utf16'), 'refused source never creates a carrier');
+  assert(result.svg.length < 100_000, 'refusal diagnostic is fixed-size');
+  assert.equal(module.renderToString(source), result.svg);
+  assert.deepEqual(plain(result), plain(classic.render(source)), 'module/classic refusal result');
+  inert(result.svg);
+}
+const longCommand = '\\' + 'a'.repeat(10_000), diagnostic = module.render(longCommand);
+assert(diagnostic.errors[0].messageTruncated && diagnostic.errors[0].commandTruncated);
+sourceAlternative(diagnostic, longCommand);
+assert(diagnostic.errors[0].message.length <= 1025 && diagnostic.errors[0].command.length <= 128);
+const unicodeFailure = module.render('\\begin{' + '😀'.repeat(600) + '}x');
+assert(unicodeFailure.errors[0].message.isWellFormed(), 'diagnostic admission cannot split a source surrogate pair');
+assert.equal(module.render('x+1').errors.length, 0, 'refused input cannot poison later rendering');
+console.log(JSON.stringify({name: pkg.name, version: module.version, module: 'native ESM; no global changes',
+  rebuild: 'exact module', classicAgreement: examples.length + hostile.length, sourceAlternatives: 'exact', hostileContent: 'inert', licenses: 'complete'}));

package/src/math/package-readme.mjs

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+import {readFileSync} from 'node:fs';
+export function mathReadme(resources) {
+  return readFileSync(new URL('./README.md', import.meta.url), 'utf8')
+    .replace('rapier-math-VERSION.js', resources.bundle) +
+    '\nBuild: ' + resources.version + '. Classic payload: ' + resources.bytes +
+    ' bytes; gzip (level 9): ' + resources.gzipBytes + ' bytes.\nSHA-384: `' + resources.sha384 + '`\n';
+}

package/src/math/package-verify.mjs

@@ -15,10 +15,11 @@ const payload = await read(resources.bundle);
 assert.equal(payload.length, resources.bytes, 'payload length');
 assert.equal(hash(payload), resources.sha256, 'payload SHA-256');
 assert.equal(hash(payload, 'sha384', 'base64'), resources.sha384, 'payload SHA-384');
-for (const input of [...resources.sources, ...resources.recipe]) {
+for (const input of [...resources.sources, ...resources.recipe, ...resources.adoption]) {
   const bytes = await read('src/' + input.file);
   assert.equal(bytes.length, input.bytes, input.file + ': length');
   assert.equal(hash(bytes), input.sha256, input.file + ': SHA-256');
+  if (input.packageFile) assert.deepEqual(await read(input.packageFile), bytes, input.packageFile + ': exact adoption source');
 }
 const rendererLicense = await read('src/math/LICENSE-MIT');
 for (const file of ['LICENSE-MIT', 'math-LICENSE.txt']) assert.deepEqual(await read(file), rendererLicense, file);
@@ -34,7 +35,11 @@ assert.equal(font.licenseDeclared, resources.font.license, 'font license identit
 assert.equal(sbom.hasExtractedLicensingInfos.find(item => item.licenseId === resources.font.license)?.extractedText,
   fontLicense.toString('utf8'), 'complete extracted font license');
 const {buildMath} = await import('./src/tools/build-math.mjs');
+const {mathReadme} = await import('./src/math/package-readme.mjs');
+assert.equal((await read('README.md')).toString('utf8'), mathReadme(resources), 'generated README source');
+for (const [file, owner] of [['check.mjs', 'package-check.mjs'], ['verify.mjs', 'package-verify.mjs'], ['adoption-check.mjs', 'adoption-verify.mjs']])
+  assert.deepEqual(await read(file), await read('src/math/' + owner), file + ': exact carried owner');
 await buildMath({root: source, updatePins: false});
 assert.deepEqual(await read('src/shell/vendor/' + resources.bundle), payload, 'rebuilt payload bytes');
 console.log(JSON.stringify({file: resources.bundle, bytes: payload.length, sha256: resources.sha256,
-  sources: resources.sources.length + resources.recipe.length, rebuild: 'exact', licenses: 'complete'}));
+  sources: resources.sources.length + resources.recipe.length, adoptionFiles: resources.adoption.length, rebuild: 'exact', licenses: 'complete'}));

package/src/math/rehype.d.ts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: MIT
+import type {Root} from 'hast';
+import type {VFile} from 'vfile';
+import type {IntegrationOptions} from './integration.js';
+/** Install after sanitization. Recognizes remark-rehype math code nodes. */
+export default function rehypeRapierMath(options?: IntegrationOptions): (tree: Root, file: VFile) => void;

package/src/math/rehype.mjs

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+import {fromHtml} from 'hast-util-from-html';
+import {createFormulaRenderer} from './integration.mjs';
+
+// Run AFTER the host sanitizer. Only known math code nodes are replaced, using
+// fresh renderer output parsed into HAST. Authored raw nodes never become HTML here.
+export default function rehypeRapierMath(options = {}) {
+  return (tree, file) => {
+    const render = createFormulaRenderer(options);
+    function math(node) {
+      const names = node?.properties?.className;
+      if (node?.type !== 'element' || node.tagName !== 'code' || !Array.isArray(names) ||
+          !names.includes('language-math') || !names.some(name => name === 'math-inline' || name === 'math-display') ||
+          !Array.isArray(node.children) || !node.children.every(child => child.type === 'text' && typeof child.value === 'string')) return null;
+      return {source: node.children.map(child => child.value).join(''), display: names.includes('math-display')};
+    }
+    function visit(parent) {
+      for (let index = 0; index < (parent.children?.length || 0); index++) {
+        const node = parent.children[index];
+        const code = node.type === 'element' && node.tagName === 'pre' && node.children?.length === 1 ? node.children[0] : node;
+        const input = math(code);
+        if (!input) { visit(node); continue; }
+        const result = render(input.source, input.display);
+        if (result.errors.length) {
+          for (const error of result.errors) {
+            const message = file?.message(error.message, {place: code.position, source: 'rapier-math', ruleId: error.code});
+            if (message) { message.mathSource = input.source; message.mathOffset = error.offset; }
+          }
+          continue;
+        }
+        const svg = fromHtml(result.svg, {fragment: true}).children[0];
+        parent.children[index] = input.display ? {type: 'element', tagName: 'div', properties: {className: ['math-display']}, children: [svg]} : svg;
+      }
+    }
+    visit(tree);
+  };
+}

package/src/math/stream.d.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+export interface MarkdownSnapshot {source: string; html: string; revision: number; final: boolean}
+export interface MarkdownStream {
+  /** null means keep the previous preview; the chunk was still accepted. */
+  write(chunk: string): MarkdownSnapshot | null;
+  finish(): MarkdownSnapshot;
+  abort(): void;
+  /** Replace a message by resetting, then writing the replacement source. */
+  reset(): number;
+  readonly revision: number;
+}
+export function createMarkdownStream(renderMarkdown: (source: string) => string, options?: {
+  maxSourceLength?: number; previewEvery?: number;
+}): MarkdownStream;

package/src/math/stream.mjs

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: MIT
+// Full Markdown previews have no append-only promise. Geometric admission bounds
+// the total source passed to a synchronous host, including the final batch pass.
+export function createMarkdownStream(renderMarkdown, {maxSourceLength = 1_000_000, previewEvery = 256} = {}) {
+  if (typeof renderMarkdown !== 'function') throw new TypeError('Supply a synchronous Markdown renderer.');
+  for (const value of [maxSourceLength, previewEvery])
+    if (!Number.isSafeInteger(value) || value < 1) throw new RangeError('Stream limits must be positive finite integers.');
+  let chunks = [], length = 0, threshold = previewEvery, closed = false, revision = 0, rendering = false;
+  function open() {
+    if (closed || rendering) throw new Error(closed ? 'This stream is closed; reset it before writing.' : 'A stream renderer cannot reenter its stream.');
+  }
+  function snapshot(final) {
+    const source = chunks.join('');
+    chunks = source ? [source] : [];
+    // Failed previews consumed work too. Further chunks must still wait for the
+    // next geometric threshold; only an explicit finish retries immediately.
+    threshold = Math.max(previewEvery, length * 2);
+    rendering = true;
+    let html;
+    try {
+      html = renderMarkdown(source);
+      if (typeof html !== 'string') throw new TypeError('The Markdown renderer must return a string synchronously.');
+    } finally { rendering = false; }
+    if (final) { closed = true; chunks = []; length = 0; }
+    return {source, html, revision, final};
+  }
+  return {
+    write(chunk) {
+      open();
+      if (typeof chunk !== 'string') throw new TypeError('Decode transport bytes to strings before writing.');
+      if (chunk.length > maxSourceLength - length)
+        throw Object.assign(new RangeError('The message exceeds its source budget; this chunk was not accepted.'), {code: 'resource-limit'});
+      if (!chunk.length) return null;
+      chunks.push(chunk); length += chunk.length; revision++;
+      return length >= threshold ? snapshot(false) : null;
+    },
+    finish() { open(); revision++; return snapshot(true); },
+    abort() {
+      if (rendering) throw new Error('A stream renderer cannot abort its stream.');
+      if (closed) return;
+      chunks = []; length = 0; closed = true; revision++;
+    },
+    reset() { if (rendering) throw new Error('A stream renderer cannot reset its stream.'); chunks = []; length = 0; threshold = previewEvery; closed = false; return ++revision; },
+    get revision() { return revision; },
+  };
+}