rapier-math 1.0.2 → 1.1.0

package/src/math/browser.js

@@ -88,12 +88,18 @@ function mathFitElement(svg, printing = false) {
   if(screenKey!==state.screen || (target===null)!==(state.width===null) || target!==null && Math.abs(target-state.width)>.005) {
     const rendered=renderMath(source,{displayMode:display,maxWidth:(screenKey!==state.screen?width:target) || undefined,screen});
     if(!rendered.errors.length) {
+      const active=doc.activeElement,links=active && svg.contains(active)?[...svg.querySelectorAll('a')]:[];
+      const focusIndex=links.indexOf(active),focusHref=focusIndex<0?null:active.getAttribute('href');
       const replacement=new view.DOMParser().parseFromString(rendered.svg,'image/svg+xml').documentElement;
-      for(const name of ['width','height','viewBox','data-math-natural-width','data-math-max-width','data-math-lines','data-math-screen']) {
+      for(const name of ['role','width','height','viewBox','data-math-natural-width','data-math-max-width','data-math-lines','data-math-screen']) {
         if(replacement.hasAttribute(name))svg.setAttribute(name,replacement.getAttribute(name));else svg.removeAttribute(name);
       }
       svg.style.verticalAlign=replacement.style.verticalAlign;
       svg.replaceChildren(...Array.from(replacement.childNodes,node=>doc.importNode(node,true)));
+      if(focusIndex>=0 && (!doc.activeElement || doc.activeElement===doc.body)) {
+        const link=svg.querySelectorAll('a')[focusIndex];
+        if(link?.getAttribute('href')===focusHref)link.focus({preventScroll:true});
+      }
       state.natural=Number(svg.getAttribute('data-math-natural-width'));state.screen=screenKey;
       state.width=state.natural>width?width:null;
       if(state.width===null)svg.removeAttribute('data-math-max-width');

package/src/math/classic.d.ts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+import type API from './index.js';
+declare global {var RapierMath: typeof API;}
+export {};

package/src/math/delimiters.d.ts

@@ -0,0 +1,8 @@
+// SPDX-License-Identifier: MIT
+export interface DelimiterOptions {singleDollar?: boolean; brackets?: boolean}
+export interface MathSpan {
+  start: number; end: number; bodyStart: number; bodyEnd: number;
+  open: string; close: string; displayMode: boolean;
+}
+/** Index a raw, host-owned text region. Does not parse Markdown or unescape source. */
+export function createMathMatcher(source: string, options?: DelimiterOptions): (start: number, limit?: number) => MathSpan | null;

package/src/math/delimiters.mjs

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+// A boundary index for a host-owned text region, not a Markdown parser.
+export function createMathMatcher(source, {singleDollar = false, brackets = true} = {}) {
+  if (typeof source !== 'string') throw new TypeError('Math boundaries require source text.');
+  const markers = new Map(), next = Object.create(null);
+  let slashes = 0, line = 0;
+  for (let at = 0; at < source.length;) {
+    const char = source[at];
+    if (char === '\\') { slashes++; at++; continue; }
+    if (char === '\n' || char === '\r') line++;
+    if (char === '$') {
+      let end = at + 1;
+      while (source[end] === '$') end++;
+      const count = end - at;
+      if (!(slashes & 1) && (count === 2 || count === 1 && singleDollar))
+        markers.set(at, {at, marker: count === 2 ? '$$' : '$', line});
+      at = end;
+    } else {
+      if (brackets && slashes & 1 && '()[]'.includes(char))
+        markers.set(at - 1, {at: at - 1, marker: '\\' + char, line});
+      at++;
+    }
+    slashes = 0;
+  }
+  for (const entry of [...markers.values()].reverse()) {
+    const closing = entry.marker === '\\(' ? '\\)' : entry.marker === '\\[' ? '\\]' : entry.marker;
+    entry.close = next[closing];
+    next[entry.marker] = entry;
+  }
+  return function match(start, limit = source.length) {
+    const open = markers.get(start), close = open?.close;
+    if (!close || open.marker === '\\)' || open.marker === '\\]' || close.at + close.marker.length > limit) return null;
+    const bodyStart = start + open.marker.length, bodyEnd = close.at;
+    if (open.marker === '$' && (open.line !== close.line || bodyStart === bodyEnd ||
+        /\s/.test(source[bodyStart]) || /\s/.test(source[bodyEnd - 1]) || /[0-9]/.test(source[bodyEnd + 1] || ''))) return null;
+    return {start, end: bodyEnd + close.marker.length, bodyStart, bodyEnd,
+      open: open.marker, close: close.marker, displayMode: open.marker === '$$' || open.marker === '\\['};
+  };
+}

package/src/math/examples/README.md

@@ -0,0 +1,25 @@
+# Run the installed examples
+
+From a consumer directory, install `rapier-math`, then run
+`node node_modules/rapier-math/examples/formula.mjs`.
+
+For Markdown and streaming, also install `markdown-it` and run `markdown.mjs` or `stream.mjs`.
+For unified, install `unified remark-parse remark-math remark-rehype rehype-sanitize rehype-stringify hast-util-from-html`
+and run `unified.mjs`. The remark example uses remark's syntax; it does not recognize backslash delimiters.
+
+Serve the package directory over HTTP and open `examples/browser.html`. Its external module imports the
+installed ESM renderer, fits the output and releases observation before replacement and on page exit.
+Start `new Worker('./worker.mjs', {type: 'module'})` from this directory and post `{id, source}`.
+Use an id owned by the current message and ignore stale replies. Workers render SVG; they do not call `observe`.
+
+`react.tsx` is a small React 19/SSR component to copy into an existing TypeScript application. Install
+`react react-dom` and the development types `@types/react @types/react-dom`. No framework is required by the core.
+
+For streamed UTF-8, use `TextDecoderStream` or `decoder.decode(bytes, {stream: true})` and flush the decoder
+at EOF. Feed decoded strings into one stream per message. Append incoming chunks to a text node for immediate
+literal progress, and replace the whole preview when `write` returns a snapshot. Replace it with `finish()` at EOF.
+Do not concatenate transport data into HTML. On cancellation call `abort`; on replacement cancel the old producer
+before `reset`. A producer that still runs needs its own generation check before calling `write`.
+
+The examples retain the original source as the editable/copyable authority. Markdown hosts can normalize
+newlines or escapes in their syntax nodes; an HTML serialization is not an exact source archive.

package/src/math/examples/browser.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width">
+<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src-attr 'unsafe-inline'; style-src-elem 'none'; worker-src 'self'; connect-src 'none'; base-uri 'none'">
+<title>Rapier Math example</title>
+<label>TeX <textarea id="source">\frac{-b\pm\sqrt{b^2-4ac}}{2a}</textarea></label>
+<button id="render" type="button">Render</button>
+<main id="equation"></main>
+<pre id="errors"></pre>
+<script type="module" src="./browser.mjs"></script>

package/src/math/examples/browser.mjs

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+import {render, observe} from '../index.mjs';
+const container = document.querySelector('#equation');
+const source = document.querySelector('#source');
+let stop = () => {};
+function update() {
+  stop();
+  try {
+    const result = render(source.value, {displayMode: true});
+    document.querySelector('#errors').textContent = JSON.stringify(result.errors);
+    if (result.errors.length) container.replaceChildren(document.createTextNode(source.value));
+    else {
+      // Only this renderer's freshly returned SVG reaches the HTML sink.
+      container.innerHTML = result.svg;
+      stop = observe(container);
+    }
+  } catch (error) {
+    container.replaceChildren(document.createTextNode(source.value));
+    document.querySelector('#errors').textContent = error.message;
+  }
+}
+document.querySelector('#render').addEventListener('click', update);
+window.addEventListener('pagehide', () => stop());
+update();

package/src/math/examples/formula.mjs

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+import {render, renderToString} from 'rapier-math';
+
+// Works in Node/SSR: the result needs no browser JavaScript or remote font.
+const source = String.raw`\frac{-b\pm\sqrt{b^2-4ac}}{2a}`;
+const result = render(source, {displayMode: true});
+if (result.errors.length) throw new Error(JSON.stringify(result.errors));
+console.log(result.svg);
+console.log(renderToString('E=mc^2'));
+const failure = render(String.raw`\unsupported{x}`);
+console.error({source: String.raw`\unsupported{x}`, errors: failure.errors});
+// Retain the original source for editing/copying, even if admission throws.

package/src/math/examples/markdown.mjs

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: MIT
+import MarkdownIt from 'markdown-it';
+import rapierMath from 'rapier-math/markdown-it';
+
+export const md = new MarkdownIt({html: false}).use(rapierMath);
+const source = 'It costs $5 and $10. Code: `$$x$$`. Math: \\(x^2\\).\n\n$$\\frac{1}{2}$$\n';
+const env = {};
+console.log(md.render(source, env));
+console.error(env.rapierMathErrors || []);

package/src/math/examples/react.tsx

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+import {useEffect, useMemo, useRef} from 'react';
+import {render, observe} from 'rapier-math';
+
+export function Equation({source, displayMode = false}: {source: string; displayMode?: boolean}) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const result = useMemo(() => {
+    try { return render(source, {displayMode}); }
+    catch { return null; }
+  }, [source, displayMode]);
+  const svg = result && result.errors.length === 0 ? result.svg : null;
+  useEffect(() => {
+    if (ref.current && svg) return observe(ref.current);
+  }, [svg]); // Cleanup runs before replacement setup and on unmount.
+  if (!svg) return <code>{source}</code>;
+  // The server and initial client render use identical source/options. Fit only
+  // after hydration; never pass authored HTML to dangerouslySetInnerHTML.
+  return <span ref={ref} dangerouslySetInnerHTML={{__html: svg}} />;
+}

package/src/math/examples/stream.mjs

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: MIT
+import MarkdownIt from 'markdown-it';
+import rapierMath from 'rapier-math/markdown-it';
+import {createMarkdownStream} from 'rapier-math/stream';
+
+const md = new MarkdownIt({html: false}).use(rapierMath);
+const stream = createMarkdownStream(source => md.render(source, {}), {previewEvery: 16});
+for (const chunk of ['The answer is \\(', '\\frac{1}', '{2}', '\\)', '. Code: `$$x$$`.']) {
+  const preview = stream.write(chunk);
+  if (preview) console.log({phase: 'preview', ...preview});
+}
+const final = stream.finish();
+console.log({phase: 'complete', ...final});
+if (final.html !== md.render(final.source, {})) throw new Error('Batch mismatch');
+
+// One stream per message. On replacement: cancel its transport, reset, write.
+stream.reset();
+stream.write('Replacement \\(y\\).');
+console.log(stream.finish());

package/src/math/examples/unified.mjs

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+import {unified} from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMath from 'remark-math';
+import remarkRehype from 'remark-rehype';
+import rehypeSanitize, {defaultSchema} from 'rehype-sanitize';
+import rehypeRapierMath from 'rapier-math/rehype';
+import rehypeStringify from 'rehype-stringify';
+import {pathToFileURL} from 'node:url';
+
+export const processor = unified().use(remarkParse)
+  .use(remarkMath, {singleDollarTextMath: false}).use(remarkRehype)
+  .use(rehypeSanitize, {
+    ...defaultSchema,
+    attributes: {...defaultSchema.attributes, code: [
+      ...(defaultSchema.attributes.code || []).filter(rule => !(Array.isArray(rule) && rule[0] === 'className')),
+      ['className', 'language-math', 'math-inline', 'math-display'],
+    ]},
+  })
+  .use(rehypeRapierMath).use(rehypeStringify);
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const file = await processor.process('Price $5. Code `$$x$$`. Math $$x^2$$.\n\n$$\n\\frac{1}{2}\n$$');
+  console.log(String(file));
+  console.error(file.messages);
+}

package/src/math/examples/worker.mjs

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+import {render} from '../index.mjs';
+self.onmessage = ({data: {id, source}}) => {
+  try { self.postMessage({id, source, result: render(source)}); }
+  catch (error) { self.postMessage({id, source, error: {code: error.code, message: error.message}}); }
+};
+// Keep a request id per message; install a reply only if it is still current.

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

@@ -574,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'}));