rapier-math 1.0.2 → 1.1.0

package/README.md

@@ -1,111 +1,213 @@
 # 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.
+Self-contained TeX-to-SVG maths with embedded Latin Modern outlines. Rendering is synchronous and offline,
+with no core runtime dependencies, DOM, global installation or remote font request. Optional integrations
+keep the host's Markdown parser in charge.
 
-## Install
+## Start with a formula
 
 ```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});
+import {render} from 'rapier-math';
+const source = String.raw`\frac{-b\pm\sqrt{b^2-4ac}}{2a}`;
+const result = render(source, {displayMode: true});
 if (result.errors.length) console.error(result.errors);
-const svg = renderToString(String.raw`E = mc^2`);
+else console.log(result.svg);
 ```
 
-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
+Keep `source` for editing and copying. A formula API accepts TeX without Markdown delimiters.
+`String.raw` helps with JavaScript literals; JSON and transport decoding are separate layers. Never unescape
+the TeX a second time. Native ESM works in Node 22+, current browsers and module workers; no CommonJS wrapper
+is provided. Server output needs no client renderer unless fitting or further rendering is wanted.
 
-Serve `index.mjs` from this package alongside your page:
+## Markdown
 
-```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>
+```sh
+npm install markdown-it
 ```
 
-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.
+```js
+import MarkdownIt from 'markdown-it';
+import rapierMath from 'rapier-math/markdown-it';
+const md = new MarkdownIt({html: false}).use(rapierMath);
+const env = {};
+const html = md.render('Price $5. Code: `$$x$$`. Formula: \\(x^2\\).', env);
+console.log(env.rapierMathErrors || []);
+```
 
-## API
+Default delimiters are `\(...\)` (inline), `\[...\]` and `$$...$$` (display). Single `$...$` is opt-in:
+`.use(rapierMath, {singleDollar: true})`. It cannot distinguish all currency from mathematics.
 
-| Export | Result |
+| Boundary rule | Contract |
 | --- | --- |
-| `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`. |
-
-`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.
-
-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.
-
-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:
+| Escapes | An odd run of preceding backslashes escapes a delimiter; an even run does not. The body is never unescaped. |
+| Dollar runs | Only complete runs of one or two dollars are delimiters. Three or more are literal. `\$$` is an escaped pair. |
+| Single dollars | Nonempty body, no leading/trailing whitespace or CR/LF; a closer followed by an ASCII digit is rejected. |
+| Other pairs | Whitespace and newlines are allowed. The first unescaped matching closer wins. No delimiter nesting. |
+| Blocks | A display opener at the host's block start and a closer followed only by line whitespace makes a block. Otherwise it is inline content. |
+| Incomplete input | No math node is emitted until a matching closer exists. Surrounding text stays under host control. |
+| Protected source | Code spans, fences, indented code, link destinations, autolinks and HTML tags remain host syntax. Math in link labels is disabled. Math in image descriptions is retained as literal source in alt text. |
+
+Use `html: false` for untrusted Markdown. If your application enables raw HTML, retain its sanitizer and
+HTML policy. Inline HTML element contents follow the host grammar; the math adapter is not an HTML parser.
+The `rapier-math/delimiters` export offers `createMathMatcher(source, options)(start, limit?)` for authors of
+other host adapters. It indexes boundaries in a raw text region, returns exact UTF-16 offsets, and knows
+nothing about Markdown structure. Do not scan rendered HTML with it.
+
+The Rapier app explicitly keeps its established dollar-only dialect, including math in link labels.
+The shared owner corrects escaped display closers and retains outer formula whitespace. No public
+adapter or renderer imports the app's AGPL Markdown implementation.
+
+## unified / remark / rehype
+
+Use `remark-math`, `remark-rehype`, then `rehype-sanitize`, then `rapier-math/rehype`, then `rehype-stringify`.
+The complete [unified example](examples/unified.mjs) grants only the math classes on sanitized code nodes.
+The adapter replaces supported `language-math` + `math-inline`/`math-display` nodes with HAST parsed from
+fresh renderer SVG. It does not turn authored raw HTML into trusted markup or loosen the global SVG sanitizer.
+The optional `hast-util-from-html` peer is used only by this entrypoint.
+
+Choose `remarkMath({singleDollarTextMath: false})` to avoid single-dollar ambiguity. Remark owns delimiter,
+whitespace and code rules in this pipeline; its grammar is different from the markdown-it adapter and does
+not enable backslash delimiters. Unsupported formulas remain copyable code and produce VFile messages
+with `ruleId`, `mathOffset` and `mathSource`.
+
+Both rendering adapters accept `renderOptions`, `maxFormulas` (default 1024) and `maxOutputLength` (default
+16 Mi UTF-16 code units of successful SVG per document render). Rendering a cached markdown-it token tree
+again starts a fresh budget; inline children share their enclosing document's budget. Exhaustion leaves subsequent source literal with
+diagnostics. The host owns its own source, tree, prose and final HTML budgets. These are synchronous adapters.
+
+## Streaming
 
-```sh
-node verify.mjs
-node check.mjs
-node src/math/package-build.mjs index.mjs
+```js
+import {createMarkdownStream} from 'rapier-math/stream';
+const stream = createMarkdownStream(source => md.render(source, {}));
+const preview = stream.write('The answer is \\(x'); // may return null
+stream.write('^2\\).');
+const completed = stream.finish(); // {source, html, revision, final: true}
 ```
 
-`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.
+Use one stream per message. `write` accepts decoded strings and returns either a whole preview or `null`;
+`finish` always runs the same batch renderer on the complete exact source. `abort` releases pending text.
+`reset` starts a replacement and advances the revision. Cancel the old producer before reset, or reject its
+chunks using your conversation generation. No callbacks, timers, DOM mutations or shared conversation state
+are installed. See the [stream example](examples/stream.mjs).
+
+Markdown references, setext headings and fences can change earlier interpretation, so previews are
+replaceable, not committed prefixes. An open formula remains literal. Defaults: at most 1,000,000 retained
+source code units; first preview at 256 units, then only after the source has at least doubled. Including
+one `finish`, the total source sent to the host is less than three times final length, even if previews fail.
+Explicit retries of `finish` are additional host calls. There is no full-prefix
+render on every token. Late previews are consequently less frequent; show incoming chunks as text for
+immediate progress. `previewEvery` sets the first threshold, not a fixed per-chunk interval.
 
-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/`.
+Retained state is O(message length), not a claimed constant-memory Markdown parser. Stream chunks can split
+delimiters, CRLF, escapes or surrogate pairs. Final interpretation is batch-equivalent; interim previews
+may show an incomplete code unit. A rejected oversized chunk is not accepted or silently truncated; the
+caller still owns it. A failed renderer leaves accumulated source available for retry or reset.
+
+## Formula API and browser lifetime
+
+| Export | Result |
+| --- | --- |
+| `render(tex, options?)` | `{svg, width, height, depth, lines, fitted, errors}`; dimensions in mathematical ems. |
+| `renderToString(tex, options?)` | SVG, including diagnostic SVG for admitted malformed or unsupported syntax. |
+| `parse(tex)` | Inspectable AST; throws structured errors. Internal node vocabulary can grow. |
+| `fit(container)` | One synchronous DOM fitting pass, returning selected formula count. |
+| `observe(container)` | Observe current formulas; returns idempotent cleanup. |
+| `version` | The package version. Default export provides the same API. |
+
+`displayMode`, `maxWidth` in mathematical ems, and optional `screen: {fontSize, pixelRatio, dark}` configure
+rendering. Screen numbers must be positive finite values; `dark` must be boolean. Omit screen options for
+SSR and the initial hydration render. Long rows break at available relations/operators; indivisible
+oversized groups scale to fit. Fit after hydration, stop observation before replacement, then observe the
+new formulas. Stop on unmount. [Browser](examples/browser.html), [worker](examples/worker.mjs) and
+[React/SSR](examples/react.tsx) examples demonstrate these boundaries. React is not a package dependency.
+
+## Errors, source and accessibility
+
+Check `errors` before treating a formula as successful. Errors include `code`, `message`, UTF-16 `offset`
+and sometimes `command`. Render-result messages are limited to 1024 code units plus an ellipsis and command
+names to 128, with explicit `messageTruncated`/`commandTruncated` flags. Exact admitted source is retained
+independently. `parse` throws the parser's details, bounded by its source admission limit. Do not use a
+diagnostic message as a source archive.
+
+Valid XML source is kept exactly in SVG `aria-label` and `title`, including BOM, tabs and CRLF (escaped as
+character references). Invalid XML characters have visible Unicode escapes and a `data-tex-utf16` carrier:
+each four hex digits represents one original UTF-16 code unit. This includes isolated surrogates. The
+Markdown host may normalize its syntax-node content; retain the original Markdown separately. Streams
+return the exact concatenated source, including malformed UTF-16, without normalization.
+
+Source longer than 1,000,000 code units returns a bounded `resource-limit` diagnostic before source
+scanning, escaping or parsing. Its error has `sourceOmitted: true` and its SVG has
+`data-math-source-omitted="true"`; neither embeds or truncates the refused source. `renderToString` returns
+the same diagnostic SVG. Keep the original input for editing or copying. Admitted source alternatives
+remain exact. Other limits include 100,000 tokens, 50,000 parser nodes, depth 192, 4096 macro expansions, 100,000 layout
+visits, 4 Mi outline characters and 8 Mi composed SVG characters. Complete returned SVG, including source
+alternatives and diagnostics, is capped at 24 Mi UTF-16 code units. These are output/work bounds, not peak
+heap or device-memory claims. A later good render has a fresh budget.
+
+SVG labels contain raw TeX, not semantic MathML or mathematical speech. Ordinary equations are images in
+the accessibility tree. Equations containing authored HTTP(S) links use a group so the links remain exposed;
+each link is keyboard-focusable and labelled with its destination. Keep the editable source or a separate
+copy-source affordance in your host. Full semantic navigation, speech and screen-reader parity are not
+provided. A future semantic serializer needs an explicit AST-to-MathML mapping and assistive-technology
+evaluation; adding a raw TeX label does not satisfy that requirement.
+
+## Security and deployment
+
+The renderer emits local SVG outlines, never executable HTML, remote font/image fetches or loaded TeX
+extensions. Authored links permit only HTTP(S) and use `noopener noreferrer`. Insert only the returned
+SVG, never concatenate TeX or arbitrary HTML into the sink. On failure, use a text node or the framework's
+escaped text rendering. Formula safety does not sanitize surrounding Markdown.
+
+The native ESM path needs no `eval` or `unsafe-eval`. Generated SVG does contain style attributes:
+`script-src 'self'; style-src-attr 'unsafe-inline'; style-src-elem 'none'` permits same-origin external
+modules and those attributes in browsers implementing CSP3. It does **not** work under a policy forbidding
+all inline styles. `examples/browser.html` carries that policy; older browsers need their own reviewed
+style policy. No network access is needed after local module loading; use `connect-src 'none'` if suitable.
+
+With `require-trusted-types-for 'script'`, string HTML sinks and the DOMParser used by `fit`/`observe`
+require TrustedHTML. The core does not create a policy, return TrustedHTML or claim fitting support under
+that policy. Prefer server-rendered output or the structured rehype path in such applications. If the host
+uses a policy for initial insertion, narrowly scope it to freshly generated renderer output; never use a
+blanket identity policy for arbitrary strings. The browser/React examples assume string sinks are permitted.
+
+## Syntax and limits
+
+Supported: fractions, roots, scripts, limits, matrices/arrays/alignment, delimiters, accents, operators,
+Greek and mathematical alphabets, text/color/size/spacing, local macros, and selected chemistry/physics.
+Existing supported package names select built-in syntax; there is no external package/file loader.
+This is not a complete TeX document engine. No automatic numbering or cross-formula reference guarantee.
+Unsupported commands give diagnostics. Lowercase script/bold-script requests use ordinary-letter fallbacks
+where Latin Modern lacks those alphabets. All embedded licensed outlines remain present.
+
+## Package and proof
+
+Declarations accompany every public entry. Formula imports do not pull in Markdown, unified or React.
+For TypeScript, markdown-it 15 provides its own types; markdown-it 14 projects also install
+`@types/markdown-it@14`. Use the declarations for your host version.
+For a classic script, use `rapier-math-1.1.0.js` and `globalThis.RapierMath`.
+The payload includes the font: it is not a few-kilobyte renderer. Payload counts below describe this
+build, not npm tarball size or a comparison against another library.
+
+Run `node verify.mjs` and `node check.mjs` from an installed package. The carried source rebuilds the exact
+classic payload and ESM module; receipts also cover the adapters, declarations and examples. Follow
+`src/math/FONT-SOURCE.md` to regenerate font data. License and font provenance are carried with every build.
+
+Verified-claim scope: synchronous self-contained formula rendering; opt-in Markdown integrations; bounded
+replaceable previews with exact final source; structured diagnostics and explicit source fallback. This
+does not establish all-device behavior, full TeX compatibility, semantic accessibility or universal
+size/speed superiority. Test your host's sanitizer, CSP, browser lifetime and supported formula corpus.
 
 ## Licenses
 
-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.
+The renderer and neutral adapters are MIT. Latin Modern Math 1.959 outlines/metrics retain the GUST Font
+License, an instance of LPPL. `LICENSE` contains both complete grants. `LICENSE-MIT`, `math-LICENSE.txt`,
+`math-font-LICENSE.txt` and the SPDX 2.3 `math-components.json` retain renderer and font notices. Both payloads
+retain complete licenses. App-specific AGPL source is not included in this package.
+
+Build: 1.1.0. Classic payload: 714051 bytes; gzip (level 9): 442525 bytes.
+SHA-384: `dYIPrqCf4rrTcAKw1Zzzo7vujbNtk2C7Zik/tIYOaLVT0U66WOXcGNE6waFbKych`

package/adoption-check.mjs

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// Optional host checks: run from the installed package with the example peers.
+// One source-custody table; no appearance or timing assertions.
+import assert from 'node:assert/strict';
+import MarkdownIt from 'markdown-it';
+import {render} from 'rapier-math';
+import rapierMath from 'rapier-math/markdown-it';
+import {createMathMatcher} from 'rapier-math/delimiters';
+import {createMarkdownStream} from 'rapier-math/stream';
+import {processor} from './examples/unified.mjs';
+
+const md = new MarkdownIt({html: false}).use(rapierMath);
+const dollar = new MarkdownIt({html: false}).use(rapierMath, {singleDollar: true});
+const mathNodes = (host, source) => host.parse(source, {}).flatMap(token => token.children || [token])
+  .filter(token => token.type === 'math_inline' || token.type === 'math_block');
+const rows = [
+  ['escaped pair incomplete', String.raw`$$x\$$`, 0],
+  ['escaped pair then closer', String.raw`$$x\$$y$$`, 1],
+  ['even escape run', String.raw`$$x\\$$`, 1],
+  ['brackets', String.raw`A \(x+1\) B \[y\]`, 2],
+  ['escaped bracket opener', String.raw`A \\(x\\)`, 0],
+  ['currency', 'It costs $5 and $10.', 0],
+  ['code and fence', '`$$x$$`\n\n```tex\n$$y$$\n```\n\n    $$z$$\n', 0],
+  ['links', String.raw`[\(x\)](https://example.com/$$x$$)`, 0],
+  ['literal backslashes', String.raw`Path C:\\temp. \(\text{a\ b}\)`, 1],
+  ['CRLF BOM Unicode', '\ufeffπ 🐈\r\n\r\n$$\r\nx+1\r\n$$\r\n', 1],
+  ['incomplete', 'Before \\(x+1 and after', 0],
+  ['malformed UTF-16', '\ud800 and \\(x\\) and \udfff', 1],
+];
+for (const [name, source, count] of rows) {
+  assert.equal(mathNodes(md, source).length, count, name);
+  const batch = md.render(source, {});
+  // Every two-piece boundary, including CRLF, escape runs and surrogate pairs.
+  for (let split = 0; split <= source.length; split++) {
+    const stream = createMarkdownStream(text => md.render(text, {}), {previewEvery: 8});
+    stream.write(source.slice(0, split)); stream.write(source.slice(split));
+    const final = stream.finish();
+    assert.equal(final.source, source, name + ': exact transport source');
+    assert.equal(final.html, batch, name + ': final batch agreement');
+  }
+}
+for (const [source, count] of [[String.raw`$x\$y$`, 1], ['$x$5', 0], ['$ x$', 0], ['$x $', 0], ['$$$x$$$', 0]])
+  assert.equal(mathNodes(dollar, source).length, count);
+// Image descriptions are text-only host output: unknown math token types must
+// not disappear from alt text or spend a formula-render budget.
+for (const [source, alt] of [
+  [String.raw`![before $$x$$ after](image.png)`, 'before $$x$$ after'],
+  [String.raw`![before \(x\) after](image.png)`, String.raw`before \(x\) after`],
+  [String.raw`![a ![b $$x$$](inner.png) c](outer.png)`, 'a b $$x$$ c'],
+  [String.raw`![a $$\text{<>&"}$$ b](image.png)`, 'a $$\\text{&lt;&gt;&amp;&quot;}$$ b'],
+]) {
+  const host = new MarkdownIt({html: false}).use(rapierMath, {maxFormulas: 1});
+  const tokens = host.parse(source + String.raw` \(y\)`, {});
+  for (let pass = 0; pass < 2; pass++) {
+    const env = {}, html = host.renderer.render(tokens, host.options, env);
+    assert(html.includes('alt="' + alt + '"'), 'image math remains literal source');
+    assert.equal((html.match(/<svg /g) || []).length, 1, 'alt text does not spend the formula budget');
+    assert.equal(env.rapierMathErrors, undefined);
+  }
+}
+const exact = '\ufeff$$\r\n α+\\text{a\\ b} 🐈\r\n$$';
+const span = createMathMatcher(exact)(1);
+assert.equal(exact.slice(span.bodyStart, span.bodyEnd), '\r\n α+\\text{a\\ b} 🐈\r\n');
+assert.equal(createMathMatcher(String.raw`$$x\$$`)(0), null);
+
+const first = createMarkdownStream(text => text, {maxSourceLength: 8, previewEvery: 2});
+const second = createMarkdownStream(text => text);
+first.write('ab'); second.write('other'); first.abort(); first.abort();
+assert.throws(() => first.write('c'));
+first.reset(); first.write('new');
+assert.throws(() => first.write('123456'), {code: 'resource-limit'});
+assert.equal(first.finish().source, 'new');
+assert.equal(second.finish().source, 'other');
+assert.throws(() => second.finish());
+let failingHost = true, supplied = 0;
+const failing = createMarkdownStream(text => {
+  supplied += text.length;
+  if (failingHost) throw new Error('host failed');
+  return text;
+}, {previewEvery: 2});
+const failedSource = 'x'.repeat(32);
+for (const chunk of failedSource) {
+  try { failing.write(chunk); } catch (error) { assert.equal(error.message, 'host failed'); }
+}
+failingHost = false;
+assert.equal(failing.finish().source, failedSource, 'failed previews retain every accepted chunk');
+assert(supplied < 3 * failedSource.length, 'failed previews keep the repeated-work bound');
+failing.abort(); failing.reset();
+
+const hostile = String.raw`Before \(\text{</title><script>alert(1)</script>}\). <img src=x onerror=alert(1)>`;
+assert(!/<script|<img/i.test(md.render(hostile, {})));
+// Cached syntax can serve multiple outputs. Budgets belong to each render, not
+// to parsing or to an env object; every paragraph still shares one document cap.
+const formulaSource = String.raw`\(x\)`, svgCount = html => (html.match(/<svg /g) || []).length;
+for (const budgets of [{maxFormulas: 1}, {maxOutputLength: render('x').svg.length}]) {
+  const host = new MarkdownIt({html: false}).use(rapierMath, budgets);
+  for (const inline of [false, true]) {
+    const source = formulaSource + (inline ? ' ' : '\n\n') + formulaSource;
+    const tree = host.parse(source, {});
+    const tokens = inline ? tree[1].children : tree;
+    const renderer = inline ? host.renderer.renderInline : host.renderer.render;
+    for (let pass = 0; pass < 2; pass++) {
+      const env = {}, out = renderer.call(host.renderer, tokens, host.options, env);
+      assert.equal(svgCount(out), 1);
+      assert.equal(env.rapierMathErrors.length, 1);
+      assert.equal(env.rapierMathErrors[0].errors[0].code, 'resource-limit');
+      assert(out.includes(formulaSource));
+    }
+  }
+}
+const nestedHost = new MarkdownIt({html: false}).use(rapierMath, {maxFormulas: 1});
+const nestedTree = nestedHost.parse(formulaSource + ' fail', {});
+const textRule = nestedHost.renderer.rules.text;
+nestedHost.renderer.rules.text = (tokens, index, opts, env, self) => {
+  if (tokens[index].content === ' fail') throw new Error('host render failed');
+  if (tokens[index].content.includes('nested')) {
+    for (const inline of [false, true]) {
+      const nestedEnv = {};
+      assert.throws(() => inline
+        ? self.renderInline(nestedTree[1].children, opts, nestedEnv)
+        : self.render(nestedTree, opts, nestedEnv), /host render failed/);
+      assert.equal(nestedEnv.rapierMathErrors, undefined, 'nested render has its own budget');
+    }
+  }
+  return textRule(tokens, index, opts, env, self);
+};
+const outerTree = nestedHost.parse(formulaSource + ' nested ' + formulaSource, {});
+// A custom host can run the same renderer twice; a failed nested render must
+// restore the outer cap and leave subsequent root renders fresh.
+for (let pass = 0; pass < 2; pass++) {
+  const env = {}, out = nestedHost.renderer.render(outerTree, nestedHost.options, env);
+  assert.equal(svgCount(out), 1);
+  assert.equal(env.rapierMathErrors.length, 1);
+  assert.equal(env.rapierMathErrors[0].errors[0].code, 'resource-limit');
+}
+const tiny = new MarkdownIt({html: false}).use(rapierMath, {maxOutputLength: 1});
+assert(!tiny.render(String.raw`\(x\)`).includes('<svg'));
+const bad = {}, fallback = md.render(String.raw`Good \(x\). Bad \(\unknown{x}\).`, bad);
+assert.equal(bad.rapierMathErrors[0].errors[0].code, 'unsupported-command');
+assert(fallback.includes('\\unknown{x}'));
+
+const unified = await processor.process('Code `$$x$$`. Math $$x+1$$.\n\n<script>alert(1)</script>\n\n$$\\unknown{x}$$');
+assert.equal((String(unified).match(/<svg /g) || []).length, 1);
+assert(!String(unified).includes('<script'));
+assert.equal(unified.messages[0].ruleId, 'unsupported-command');
+assert(String(unified).includes('\\unknown{x}'));
+console.log(JSON.stringify({sourceCustodyRows: rows.length, splitAgreement: 'all two-piece boundaries',
+  lifetimes: 'abort, reset, replacement, rejection, interleaved messages', adapters: 'markdown-it and sanitized unified',
+  security: 'hostile source stays inert; document math budgets fall back'}));

package/check.mjs

@@ -23,6 +23,9 @@ for (const name of ['./LICENSE', './index.mjs', './' + resources.bundle]) {
   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);
@@ -93,5 +96,23 @@ for (const source of hostile) {
   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/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/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/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/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/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/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/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.