Add validateTex API for fast side-effect-free TeX syntax checking

[OlgaRedozubova]

[v2.0.41] Add validateTex API for fast side-effect-free TeX syntax checking

Summary

Adds a new opt-in MathpixMarkdownModel.validateTex(latex, { display? }) method that checks whether a TeX expression parses, without producing SVG output and without touching the rendering pipeline's equation counter, labels, or ids.

This PR provides the validation primitive; how to use it is up to the consumer.

Motivation

forLatex: true skips MathJax conversion entirely (mdPluginRaw.ts:174-191) — tokens carry raw markup. The trade-off: no syntactic check on formula contents in that mode, since MathJax never runs.

Reusing the existing MathJax.TexConvert path for validation is not acceptable because (a) it runs the full SVG output jax (wasted work for a validity check) and (b) it commits state to the shared parseOptions.tags — allCounter, allLabels, allIds — which would corrupt the next render.

What's in the PR

Public API

MathpixMarkdownModel.validateTex(latex: string, options?: { display?: boolean }): TexValidationResult;

type TexValidationResult =
  | { valid: true }
  | { valid: false; error: TexValidationError };

class TexValidationError extends Error {
  readonly code?: string;   // TexError.id (e.g. 'MissingArgFor', 'BadMath')
  readonly latex: string;   // the input formula that failed
}

Usage:

const result = MathpixMarkdownModel.validateTex('\\frac{1}{2');
if (!result.valid) {
  console.error(`[${result.error.code ?? 'unknown'}] ${result.error.message}`);
  console.error(`Formula: ${result.error.latex}`);
}

Implementation

• Dedicated isolated MTeX instance (mathjax.ts) with tags: 'none'. Shares MmlFactory with the rendering input jax (stateless, safe to share). No MathDocument needed.
• Direct TexParser invocation (mathjax/index.ts) bypasses MathItem/MathDocument, output jax, the math-node wrapping step, finishEquation, and the six post-filter tree walks (cleanSubSup, setInherited, moveLimits, cleanStretchy, cleanAttributes, combineRelations). Only the parser runs.
• Stateless across calls: parseOptions.clear() + tags.reset(0) at the start of each call. Repeated identical inputs always produce the same result; no "duplicate label" leakage.
• Never throws on bad input. TexError is wrapped in TexValidationError with code set; unexpected non-TexError exceptions (rare; would indicate a MathJax internal bug) are also wrapped with code unset. Batch callers processing thousands of formulas always get a return value.
• Discriminated union result so TypeScript narrows the type in the !result.valid branch without an extra guard.
• Object.setPrototypeOf in the TexValidationError constructor to restore the prototype chain (required because the TypeScript target is ES5, where super(Error) breaks instanceof).

Guarantees (covered by unit tests)

• getLastEquationNumber() is unchanged after validateTex calls (valid auto-numbered equations, invalid formulas, batches of 10+ calls).
• Rendering \label{eq:a} + \eqref{eq:a} produces identical HTML whether or not the same formula was validated beforehand.
• Two markdownToHTML calls produce the same output whether or not validateTex is invoked between them.
• Two consecutive validateTex calls with the same \label{...} both succeed.

Performance characteristics

• Without calling validateTex: zero runtime cost. One-time init cost is one extra MTeX instance, ~100-300 KB (shares MmlFactory and configuration packages with the rendering input jax).
• With validateTex per formula: adds TeX-parsing cost to a previously-cheap path. Per-formula cost is dominated by formula complexity:
  • simple (\frac{1}{2}): ~50-200 µs
  • mid (display equation, longer polynomial): ~0.3-1 ms
  • complex (align blocks, nested matrices): ~1-5 ms
• For 1000 formulas, expect ~500 ms total at typical complexity. Per-call memory is transient (MML tree, immediately GC'd); no accumulation.

Files

Source

• src/mathjax/mathjax.ts — new validateTex: TeX<any, any, any> instance, MmlFactory wiring
• src/mathjax/index.ts — TexValidationError class, TexValidationResult type, MathJax.ValidateTex function
• src/mathpix-markdown-model/index.ts — public method exposure (validateTex = MathJax.ValidateTex)

Tests

• tests/_validateTex.js — 13 unit tests covering return value, side-effect invariants, statelessness, cross-render isolation

Docs

• pr-specs/2026-05-validate-tex-api.md — design spec (goal, non-goals, architecture, edge cases, risk/rollback)
• doc/changelog.md — new entry for v2.0.41
• README.md — new "Validating TeX formulas" section with example, return-value shape, options table, and guarantees

Release

• package.json / package-lock.json — version bump to 2.0.41

Test plan

• npm test reports 3491 passing (3478 existing + 13 new)
• Confirm no regression in existing tabular / labels / refs / nonumbers test files
• Smoke-test in a consuming app: validate a known-broken formula, observe the new error shape (result.error.code, result.error.latex)
• Verify instanceof TexValidationError works in both the test environment and in a downstream TypeScript consumer

Risk / rollback

Risk: Low

• Purely additive — no existing render path is modified.
• Validation runs against an isolated MathJax instance; no shared mutable state with the render pipeline.
• Opt-in: nothing calls validateTex automatically; consumers who don't use it experience zero behavior change.

Risk areas to watch

• MathJax internals (TexParser, ParseOptions.clear, Tags.reset, Tags.startEquation) are not public API. A future MathJax upgrade may change signatures. Integration is documented in the spec so the breakage point is locatable.
• The { inputData: {} } as any stub passed to tags.startEquation is sufficient today because only math.inputData.recompile is read (Tags.js:197-201). May need updating if MathJax tightens the MathItem shape used by startEquation.

Rollback: revert PR. No data migrations, no API contracts broken.