rapier-math 1.0.2 → 1.1.1

package/README.md

@@ -1,111 +1,41 @@
 # Rapier Math
 
-TeX-to-SVG maths with embedded Latin Modern outlines. Synchronous, offline and self-contained: no runtime
-dependencies, DOM, font installation or network request is needed to render a formula.
+A self-contained TeX-to-SVG renderer with Latin Modern outlines. Synchronous, no runtime downloads.
 
-## Install
+## Use
 
 ```sh
 npm install rapier-math
 ```
 
 ```js
-import {render, renderToString} from 'rapier-math';
-
-const result = render(String.raw`\frac{-b \pm \sqrt{b^2-4ac}}{2a}`, {displayMode: true});
-if (result.errors.length) console.error(result.errors);
-const svg = renderToString(String.raw`E = mc^2`);
-```
-
-ES modules work in browsers, workers and server JavaScript runtimes. The default export also provides the
-same API as named exports. Importing the module does not install a global or access the DOM.
-
-## Browser
-
-Serve `index.mjs` from this package alongside your page:
-
-```html
-<div id="equation"></div>
-<script type="module">
-  import {render, observe} from './index.mjs';
-  const result = render(String.raw`\int_0^1 x^2\,dx = \frac{1}{3}`, {displayMode: true});
-  const container = document.querySelector('#equation');
-  container.innerHTML = result.svg;
-  const stop = observe(container);
-  // Call stop() when this container is no longer observed.
-</script>
+import {renderToString} from 'rapier-math';
+const svg = renderToString(String.raw`\frac{a}{b}`);
 ```
 
-For a classic script, load `rapier-math-1.0.2.js` and call `globalThis.RapierMath.render(tex)`.
-The classic payload is 712164 bytes (441919 bytes gzip); it is the same renderer
-used by Rapier's optional maths plug-in. Its SHA-384 is `Pg2MvS4Eg4s41yUZiSPn+TCRuA4gM3JHxxbCEkuSFyHgC+t143Iv48n8P4XlkE23`.
-To serve Rapier's plug-in from your own origin, place that classic payload beside `rapier.html` or
-`rapier-document.html`, or in the reader's `plugins` directory.
-
-## API
-
-| Export | Result |
-| --- | --- |
-| `render(tex, options?)` | `{svg, width, height, depth, lines, fitted, errors}`. Dimensions are mathematical ems. |
-| `renderToString(tex, options?)` | The SVG string, including a diagnostic when rendering fails. |
-| `parse(tex)` | Parsed syntax tree; throws a structured error for unsupported or invalid input. |
-| `fit(container)` | One synchronous browser fitting pass; returns the number of selected formulas. |
-| `observe(container)` | Observe the current formulas for column, font and theme changes; returns a cleanup function. |
-| `version` | `1.0.2`. |
+For a browser script, load [dist/rapier-math.js](dist/rapier-math.js) and use
+`globalThis.RapierMath`. The native ESM entry is [dist/index.mjs](dist/index.mjs).
+Both include the font and return synchronously. Type declarations accompany the runtime files.
 
-`displayMode: true` selects display mathematics. `maxWidth` sets an optional width in mathematical ems.
-Long rows break before relations or binary operators; aligned derivations share their relation column.
-An indivisible oversized group scales uniformly to fit. `fit` and `observe` need a browser DOM;
-call `observe` again after replacing the formulas in a container.
+- [API and integration guide](docs/api.md)
+- [Runnable examples](examples/README.md)
+- [Font source and regeneration](docs/font-source.md)
 
-For a known screen, pass `screen: {fontSize: 16, pixelRatio: 2, dark: false}`. Font size is the surrounding
-text's CSS pixel size. The two numbers must be positive and finite, and `dark` must be a boolean.
-Invalid device scales return an `invalid-screen` diagnostic. Omit `screen` for resolution-independent
-output. SVGs match Latin Modern's x-height to Geist through the fonts' own metrics and inherit
-`currentColor`; explicit TeX colors retain their authored values.
+## Develop
 
-The root SVG retains exact valid XML source in `aria-label` and `title`. Source containing malformed
-XML characters is represented with Unicode escapes in those alternatives, while `data-tex-utf16` stores
-every original UTF-16 code unit as four hexadecimal digits. Rendering errors include `code`, `message`
-and `offset`, with `command` when applicable. Check `errors` before treating a result as successful.
-
-## Supported mathematics
-
-Fractions, roots, scripts, limits, matrices, arrays, aligned equations, delimiters, accents, operators,
-Greek, mathematical alphabets and symbols, text, color, size and spacing commands are supported. The parser
-also supports local TeX macros and selected chemistry and physics notation. Macro expansion and rendering
-have bounded resource limits. HTTP and HTTPS links are allowed; executable URLs and injected HTML are refused.
-
-This is a formula renderer, not a complete TeX document processor. Package loading, file input and arbitrary
-TeX extensions are not supported. Labels do not establish cross-formula references or automatic equation
-numbers. Unsupported syntax produces an explicit diagnostic. Latin Modern Math has no lowercase script
-or bold-script alphabet: those lowercase requests use ordinary-letter fallbacks. SVG text alternatives
-retain the TeX; this package does not produce semantic MathML.
-
-## Rebuild and verify
-
-The complete renderer source and font regeneration instructions are in `src/`. No package installation
-is needed to rebuild from the carried font data. Use Node 22 or later:
-
-```sh
-node verify.mjs
-node check.mjs
-node src/math/package-build.mjs index.mjs
-```
+The current runtime formats live in `dist/`; editable renderer source and its build tools live in
+`src/`. Optional adapters have one source copy in `dist/`. Examples, documentation and tests each
+have their own directory. Only the current release is kept in this checkout.
 
-`verify.mjs` checks the classic payload, source digests and complete licenses, then rebuilds the exact payload
-in `src/shell/vendor/`. `check.mjs` checks the module entry, exact source alternatives, classic/module
-agreement and hostile-content isolation. `package-build.mjs` rebuilds both the classic source output and
-the module entry. The module carries the same renderer body with module-local exports; no dynamic evaluation
-or global installation is needed.
+From a repository checkout, run `node tests/check.mjs` and `node tests/verify.mjs` to check the package and rebuild its exact bytes.
+Run `node src/tools/build-math.mjs --package .` to regenerate the classic and ESM files from source.
+Optional host checks run with `node tests/adoption.mjs` after installing the example dependencies.
 
-To regenerate the font itself, follow `src/math/FONT-SOURCE.md` and run `python src/math/build-font.py`.
-The source note uses `repo/` paths for the full Rapier checkout; this package uses `src/`.
+## License
 
-## Licenses
+The renderer and adapters are MIT-licensed. Embedded Latin Modern Math outlines and metrics are
+licensed under the GUST Font License. [LICENSE](LICENSE) contains both complete grants.
+[Component provenance](docs/math-components.json) and [source hashes](docs/math-resources.json)
+travel with the package.
 
-The renderer is MIT-licensed. Embedded Latin Modern Math 1.959 outlines and mathematical metrics use the
-GUST Font License, an instance of the LaTeX Project Public License. `LICENSE` contains both complete grants;
-`LICENSE-MIT` and `math-LICENSE.txt` reproduce the renderer license, and `math-font-LICENSE.txt` retains
-the exact font copyright, conversion notice, GUST grant and LPPL 1.3c terms. Both payloads retain the notices.
-`math-components.json` records the renderer and font as SPDX 2.3 components with the complete font grant.
+Version 1.1.1. Classic payload: 714051 bytes; gzip (level 9): 442525 bytes.

package/dist/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/dist/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/dist/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/dist/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/{index.mjs → dist/index.mjs}

@@ -2309,7 +2309,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'});
   }
 }
@@ -2768,12 +2768,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');
@@ -2869,23 +2875,27 @@ function mathSvg(box,source,error,utf16,options={}) {
   const opacity=options.screen?.dark ? .94 : 1;
   if (![width,height,depth,left,...viewBox].every(Number.isFinite)) throw new Error('Mathematical dimensions are not finite');
   const escapedSource=mathEscape(source);
-  const svg='<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-label="'+escapedSource+'"'+
+  // A group exposes authored links to accessibility APIs; an image would hide them.
+  const svg='<svg xmlns="http://www.w3.org/2000/svg" role="'+(box.svg.includes('<a ')?'group':'img')+'" aria-label="'+escapedSource+'"'+
     ' data-rapier-math="'+(options.displayMode?'display':'inline')+'" data-math-lines="'+(box.lines || 1)+'"'+
     ' data-math-natural-width="'+mathNumber(options.naturalWidth ?? width)+'"'+
     (options.screen?' data-math-screen="'+mathNumber(options.screen.fontSize)+'|'+mathNumber(options.screen.pixelRatio)+'|'+options.screen.dark+'"':'')+
     (options.maxWidth?' data-math-max-width="'+mathNumber(options.maxWidth)+'"':'')+
     (utf16?' data-tex-utf16="'+utf16+'"':'')+
+    (error?.sourceOmitted?' data-math-source-omitted="true"':'')+
     (error?' data-math-error="'+mathEscape(error.code)+'"':'')+' width="'+mathNumber(width)+'em" height="'+mathNumber(height+depth)+'em"'+
     ' viewBox="'+viewBox.map(mathNumber).join(' ')+'"'+
     ' style="font-size:'+mathNumber(mathFontRatio)+'em;max-width:100%;height:auto;vertical-align:-'+mathNumber(depth)+'em;'+
     'fill-opacity:'+opacity+';stroke-opacity:'+opacity+'" fill="currentColor">'+
     '<title>'+escapedSource+'</title>'+(error?'<desc>'+mathEscape(error.message)+'</desc>':'')+
     '<g transform="scale(1000)">'+box.svg+'</g></svg>';
+  if(svg.length>24*1024*1024)throw Object.assign(new Error('The complete formula markup exceeds its output budget.'),{code:'resource-limit'});
   return {svg,width,height,depth,lines:box.lines || 1,fitted:!!box.fitted,errors:error?[error]:[]};
 }
 
 function mathSourceAlternative(source) {
-  let alternative='',first=-1,kept=0;
+  const alternatives=[],parts=[];
+  let first=-1,kept=0;
   for(let i=0;i<source.length;i++) {
     const code=source.charCodeAt(i);
     if(code>=0xd800 && code<=0xdbff && i+1<source.length) {
@@ -2894,19 +2904,32 @@ function mathSourceAlternative(source) {
     }
     if((code>=0x20 && code<=0xd7ff) || (code>=0xe000 && code<=0xfffd) || code===9 || code===10 || code===13)continue;
     if(first<0)first=i;
-    alternative+=source.slice(kept,i)+'\\u'+code.toString(16).toUpperCase().padStart(4,'0');kept=i+1;
+    if(i>kept)parts.push(source.slice(kept,i));
+    parts.push('\\u'+code.toString(16).toUpperCase().padStart(4,'0'));kept=i+1;
+    // Flatten small batches instead of retaining one rope node per bad code unit.
+    if(parts.length>=1024) {alternatives.push(parts.join(''));parts.length=0;}
   }
   if(first<0)return {alternative:source};
-  alternative+=source.slice(kept);
+  parts.push(source.slice(kept));alternatives.push(parts.join(''));
   // Only malformed XML text needs a separate carrier; each four hex digits keep one original code unit.
-  let utf16='';
-  for(let i=0;i<source.length;i++)utf16+=source.charCodeAt(i).toString(16).padStart(4,'0');
-  return {alternative,utf16,error:{code:'invalid-source-character',offset:first,
+  const encoded=[];parts.length=0;
+  for(let i=0;i<source.length;i++) {
+    parts.push(source.charCodeAt(i).toString(16).padStart(4,'0'));
+    if(parts.length===1024) {encoded.push(parts.join(''));parts.length=0;}
+  }
+  encoded.push(parts.join(''));
+  return {alternative:alternatives.join(''),utf16:encoded.join(''),error:{code:'invalid-source-character',offset:first,
     message:'A source character cannot be embedded in SVG. The text alternative shows Unicode escapes; data-tex-utf16 keeps the original source.'}};
 }
 
 function renderMath(source,options={}) {
-  const text=String(source ?? ''),safe=mathSourceAlternative(text),context={size:1,level:0,variant:'normal',cramped:false,display:!!options?.displayMode,cache:new WeakMap(),budget:{nodes:0,outlineBytes:0}};
+  const text=String(source ?? '');
+  // Reject before scanning, escaping or parsing. Keep the diagnostic-return
+  // contract, but explicitly omit refused source instead of expanding it.
+  const safe=text.length>1000000?{alternative:'Formula source omitted: source limit exceeded.',error:{
+    code:'resource-limit',offset:0,sourceOmitted:true,
+    message:'This formula is too long to render safely. Its source was not embedded; retain the original input.'
+  }}:mathSourceAlternative(text),context={size:1,level:0,variant:'normal',cramped:false,display:!!options?.displayMode,cache:new WeakMap(),budget:{nodes:0,outlineBytes:0}};
   try {
     if(safe.error)throw safe.error;
     if(options?.screen!==undefined) {
@@ -2923,11 +2946,16 @@ function renderMath(source,options={}) {
     return mathSvg(box,safe.alternative,undefined,undefined,{displayMode:context.display,maxWidth,naturalWidth:mathInkWidth(natural)+.05,screen:context.screen});
   }
   catch (cause) {
-    const error={code:cause.code || 'invalid-tex',message:String(cause.message || cause),offset:Number.isFinite(cause.offset)?cause.offset:0};
-    if(cause.command)error.command=cause.command;
+    const message=String(cause.message || cause);
+    const error={code:cause.code || 'invalid-tex',message:message.length>1024?message.slice(0,1024).replace(/[\ud800-\udbff]$/,'')+'…':message,offset:Number.isFinite(cause.offset)?cause.offset:0};
+    if(message.length>1024)error.messageTruncated=true;
+    if(cause.sourceOmitted)error.sourceOmitted=true;
+    if(cause.command) {
+      error.command=String(cause.command).slice(0,128);
+      if(cause.command.length>128)error.commandTruncated=true;
+    }
     // A diagnostic is visible, but remains distinct from a successfully typeset formula.
-    // A hostile command can have a very long name. Keep its full diagnostic in desc/errors,
-    // while the visible notice stays finite and can render after the formula exhausted its budget.
+    // Diagnostics have an explicit bound. Exact input stays in the source alternative.
     const label=error.message.length>240?'This formula could not be rendered. The complete diagnostic is in its text description.':error.message.replace(/[^\x20-\x7e]/g,'?');
     const diagnostic={...context,variant:'roman',size:0.8,budget:{nodes:0,outlineBytes:0}};
     try {
@@ -2940,7 +2968,7 @@ function renderMath(source,options={}) {
 }
 
 const RapierMath=Object.freeze({
-  version:'1.0.2',
+  version:'1.1.1',
   parse:parseMathTex,
   render:renderMath,
   fit:mathFit,

package/dist/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/dist/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/dist/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/dist/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/dist/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']});
+}