react-native-marcus 0.1.1 → 0.2.0

package/src/math/mathjax.ts

@@ -0,0 +1,604 @@
+/**
+ * TeX -> SVG with MathJax 4, wired up the way React Native needs.
+ *
+ * Nothing imports this module. `react-native-marcus/metro`'s `withMath()`
+ * resolves `./index.ts` -- the stub beside it -- to this file, which is how an
+ * application opts into a dependency this size. See `./index.ts`.
+ *
+ * Three things here are not the defaults:
+ *
+ * - **`liteAdaptor`**, so nothing wants a DOM. It runs the same in Hermes, in a
+ *   browser and in Node, which is what makes one renderer serve all three
+ *   platforms and draw the same glyphs on each.
+ * - **`fontCache: "none"`**, so each expression is a standalone SVG with its
+ *   glyph outlines inline. `"local"`, the default, emits `<use>` against a
+ *   `<defs>` block, which is smaller on a page full of maths and useless when
+ *   every expression is a separate attachment in someone else's view tree.
+ * - **`linebreaks: { inline: false }`**. v4 breaks long inline maths into
+ *   several `<svg>` fragments separated by `<mjx-break>`; one attachment is one
+ *   SVG, and left on, the metrics read off the first fragment are silently
+ *   wrong.
+ *
+ * Every specifier below names `mjs/` outright rather than going through
+ * MathJax's `js/*` export, and that is not cosmetic. That export maps to `mjs`
+ * for `import` and to `cjs` for `require`, so a module reached both ways --
+ * which is exactly what this file does, importing the machinery and requiring
+ * the font ranges -- is loaded twice, and the two copies each hold half of what
+ * is needed. The symptom is every `\mathbb`, `\mathcal`, `\mathfrak`,
+ * `\mathsf` and `\mathtt` coming out blank while everything else draws
+ * perfectly. `mjs/` goes through the package's `"./*": "./*"` fallback, which
+ * has no conditions to disagree about.
+ */
+import "./environment"
+
+import { mathjax } from "@mathjax/src/mjs/mathjax.js"
+import { TeX } from "@mathjax/src/mjs/input/tex.js"
+import { SVG } from "@mathjax/src/mjs/output/svg.js"
+import { liteAdaptor } from "@mathjax/src/mjs/adaptors/liteAdaptor.js"
+import { RegisterHTMLHandler } from "@mathjax/src/mjs/handlers/html.js"
+import { MathJaxNewcmFont } from "@mathjax/mathjax-newcm-font/mjs/svg.js"
+import { SerializedMmlVisitor } from "@mathjax/src/mjs/core/MmlTree/SerializedMmlVisitor.js"
+import { STATE } from "@mathjax/src/mjs/core/MathItem.js"
+import type { MmlNode } from "@mathjax/src/mjs/core/MmlTree/MmlNode.js"
+
+// Reached through the three modules that hold what is wanted rather than
+// through SRE's own entry point, which drags in a command line parser, sets
+// itself up ten milliseconds after import with a loader that cannot work here,
+// and is written with an `export * as` that neither Metro's Babel preset nor
+// Jest's will parse.
+import { setupEngine } from "speech-rule-engine/js/api/control.js"
+import { toSpeech } from "speech-rule-engine/js/api/string.js"
+import { EnginePromise } from "speech-rule-engine/js/common/engine.js"
+
+import "@mathjax/src/mjs/input/tex/base/BaseConfiguration.js"
+import "@mathjax/src/mjs/input/tex/ams/AmsConfiguration.js"
+import "@mathjax/src/mjs/input/tex/newcommand/NewcommandConfiguration.js"
+import "@mathjax/src/mjs/input/tex/boldsymbol/BoldsymbolConfiguration.js"
+
+import type { RenderedMath } from "./index"
+
+/**
+ * Every glyph range, each behind a literal `require` so a bundler can see it.
+ *
+ * MathJax 4 splits its font data into forty files it fetches on demand. The
+ * fetching has to be replaced -- no bundler can follow it -- but it cannot be
+ * skipped: `getChar` resolves a missing glyph *through* this loader, and if
+ * nothing comes of the call it puts back the placeholder it just took out, so
+ * it and `loadDynamicFileSync` hand that placeholder to each other until the
+ * stack overflows.
+ *
+ * So: a thunk per range, a synchronous loader, and the whole font in the
+ * bundle -- a few megabytes, and drawing every expression rather than a chosen
+ * subset is what they buy. `loadRanges` below runs them all before the first
+ * expression is drawn; MathJax still asks for each one the first time it wants
+ * a glyph from it, and finds the module already run.
+ */
+const RANGES: Record<string, () => unknown> = {
+  "PUA": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/PUA.js"),
+  "accents": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/accents.js"),
+  "accents-b-i": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/accents-b-i.js"),
+  "arabic": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/arabic.js"),
+  "arrows": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/arrows.js"),
+  "braille": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/braille.js"),
+  "braille-d": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/braille-d.js"),
+  "calligraphic": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/calligraphic.js"),
+  "cherokee": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/cherokee.js"),
+  "cyrillic": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/cyrillic.js"),
+  "cyrillic-ss": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/cyrillic-ss.js"),
+  "devanagari": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/devanagari.js"),
+  "double-struck": () =>
+    require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/double-struck.js"),
+  "fraktur": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/fraktur.js"),
+  "greek": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/greek.js"),
+  "greek-ss": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/greek-ss.js"),
+  "hebrew": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/hebrew.js"),
+  "latin": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/latin.js"),
+  "latin-b": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/latin-b.js"),
+  "latin-bi": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/latin-bi.js"),
+  "latin-i": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/latin-i.js"),
+  "marrows": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/marrows.js"),
+  "math": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/math.js"),
+  "monospace": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/monospace.js"),
+  "monospace-ex": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/monospace-ex.js"),
+  "monospace-l": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/monospace-l.js"),
+  "mshapes": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/mshapes.js"),
+  "phonetics": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/phonetics.js"),
+  "phonetics-ss": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/phonetics-ss.js"),
+  "sans-serif": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/sans-serif.js"),
+  "sans-serif-b": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/sans-serif-b.js"),
+  "sans-serif-bi": () =>
+    require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/sans-serif-bi.js"),
+  "sans-serif-ex": () =>
+    require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/sans-serif-ex.js"),
+  "sans-serif-i": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/sans-serif-i.js"),
+  "sans-serif-r": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/sans-serif-r.js"),
+  "script": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/script.js"),
+  "shapes": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/shapes.js"),
+  "symbols": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/symbols.js"),
+  "symbols-b-i": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/symbols-b-i.js"),
+  "variants": () => require("@mathjax/mathjax-newcm-font/mjs/svg/dynamic/variants.js"),
+}
+
+;(mathjax as unknown as { asyncLoad: unknown }).asyncLoad = (name: string) => {
+  const range = String(name).replace(/^.*\//, "").replace(/\.js$/, "")
+  const load = RANGES[range]
+
+  if (!load) {
+    throw new Error(`[react-native-marcus] font range not bundled: ${range}`)
+  }
+
+  return load()
+}
+// Synchronous, so `getChar` resolves in place rather than throwing a retry only
+// a promise-based caller could catch.
+;(mathjax as unknown as { asyncIsSynchronous: boolean }).asyncIsSynchronous = true
+
+const adaptor = liteAdaptor()
+RegisterHTMLHandler(adaptor)
+
+const font = new MathJaxNewcmFont()
+
+const doc = mathjax.document("", {
+  InputJax: new TeX({ packages: ["base", "ams", "newcommand", "boldsymbol"] }),
+  OutputJax: new SVG({
+    fontCache: "none",
+    font,
+    linebreaks: { inline: false },
+    displayOverflow: "overflow",
+  }),
+})
+
+/**
+ * Whether every range module has been run yet.
+ *
+ * MathJax pulls a range in the moment it first wants a glyph from it, which
+ * means it runs a font module from the middle of laying an expression out --
+ * and Hermes' stack does not have the room. It overflows, the expression
+ * fails, and only a second attempt succeeds, by which time the module has run.
+ * Twelve expressions across a dozen ranges cost a minute of throwing and
+ * retrying on an emulator; the same page draws in one pass once the modules
+ * have been run from here, where the stack is empty.
+ *
+ * This is deliberately *not* `font.loadDynamicFilesSync()`, which is MathJax's
+ * own way to do this and which quietly loses `\mathbb`, `\mathfrak`,
+ * `\mathsf` and `\mathtt`: it marks every range as resolved on the way past,
+ * so the four whose characters it does not manage to install can never be
+ * asked for again. Running the modules and leaving the bookkeeping alone keeps
+ * the normal path intact -- MathJax still resolves each range the first time it
+ * wants one, it just finds the module already run and does it in no time.
+ *
+ * Deferred to the first expression rather than done on import, so that an
+ * application which loads this module and draws nothing pays nothing.
+ */
+let loaded = false
+
+function loadRanges() {
+  if (loaded) {
+    return
+  }
+
+  // Set first: one range that will not load must not cost this again.
+  loaded = true
+
+  for (const load of Object.values(RANGES)) {
+    try {
+      load()
+    } catch {
+      // Left to the on-demand path, which warns through MathJax's own loader.
+    }
+  }
+}
+
+/** The opening tag, which carries the metrics and the sizing. */
+const ROOT = /<svg[^>]*>/
+/** The root's own sizing, which has to go: see `attemptRender`. */
+const SIZING = /\s(?:width|height)="[^"]*"|\sstyle="[^"]*"/g
+/** The `<svg>` element on its own, without the `<mjx-container>` around it. */
+const ELEMENT = /<svg[\s\S]*<\/svg>/
+const EX = /width="([-\d.]+)ex"[^>]*height="([-\d.]+)ex"/
+const VA = /vertical-align:\s*([-\d.]+)ex/
+/** What MathJax paints in, which a view mounted in a `Text` inherits nothing of. */
+const CURRENT_COLOR = /currentColor/g
+/**
+ * MathJax's own annotations -- `data-mml-node`, `data-latex`, `data-c` and the
+ * rest. They are for its context menu and its accessibility walker, neither of
+ * which is here, and they are a third of the bytes. They also reach the DOM
+ * through an SVG renderer that hands unknown attributes to React, which
+ * complains about every one of them.
+ */
+const ANNOTATIONS = /\sdata-[a-zA-Z0-9-]+="[^"]*"/g
+
+const available = true
+
+/**
+ * The drawing cache. Rendering is fast -- around a millisecond on a mid-range
+ * phone -- but a display redraws for all sorts of reasons that have nothing to
+ * do with its maths, and the same expression at the same size in the same
+ * colour is the same picture every time.
+ */
+const cache = new Map<string, RenderedMath | null>()
+
+/**
+ * How many goes an expression gets before it is called undrawable.
+ *
+ * One, plus one. With the ranges loaded up front nothing should have to try
+ * twice; the second go is there because the failure it covers -- a glyph
+ * resolved from inside the layout, on a stack with no room left -- leaves the
+ * range loaded on its way out, so a retry is free and always the one that
+ * works.
+ */
+const MAX_ATTEMPTS = 2
+
+/**
+ * TeX in, one standalone SVG and its box out.
+ *
+ * The box is read off the root element rather than measured: MathJax reports
+ * width, height and the depth below the baseline in `ex`, and an `ex` is half
+ * the font size by its own `exFactor`. So nothing has to be laid out to find
+ * out how much room to ask for -- which is exactly what a text layout needs to
+ * know before it can lay the line out.
+ *
+ * Returns nothing for an expression it cannot draw, rather than throwing. TeX
+ * that reaches for something the bundled fonts do not carry ends in a
+ * `RangeError`, and one bad equation should cost the equation rather than the
+ * message it is in.
+ */
+function renderMath(
+  tex: string,
+  display: boolean,
+  fontSize: number,
+  color: string | undefined,
+): RenderedMath | null {
+  const key = `${display ? "D" : "I"}${fontSize}\u0000${color ?? ""}\u0000${tex}`
+  const hit = cache.get(key)
+
+  if (hit !== undefined) {
+    return hit
+  }
+
+  loadRanges()
+
+  let rendered: RenderedMath | null = null
+
+  // See MAX_ATTEMPTS: the second go is the one that succeeds if a glyph had to
+  // be resolved from inside the layout after all.
+  for (let attempt = 0; attempt < MAX_ATTEMPTS && rendered === null; attempt++) {
+    rendered = attemptRender(tex, display, fontSize, color)
+  }
+
+  cache.set(key, rendered)
+
+  return rendered
+}
+
+function attemptRender(
+  tex: string,
+  display: boolean,
+  fontSize: number,
+  color: string | undefined,
+): RenderedMath | null {
+  try {
+    const node = doc.convert(tex, {
+      display,
+      em: fontSize,
+      ex: fontSize / 2,
+      containerWidth: 1e6,
+    })
+    // `outerHTML` wraps the picture in MathJax's own `<mjx-container>`, which is
+    // a custom element meant for a browser: an SVG renderer handed one has no
+    // idea what to do with it. Only the `<svg>` inside is wanted.
+    const svg = adaptor.outerHTML(node).match(ELEMENT)?.[0] ?? ""
+    const root = svg.match(ROOT)?.[0] ?? ""
+    const ex = EX.exec(root)
+
+    if (!ex) {
+      return null
+    }
+
+    const va = VA.exec(root)
+    const unit = fontSize / 2
+
+    return {
+      // Two things come off the root. Its `width`, `height` and
+      // `vertical-align` are stated in `ex`, and a browser resolves an `ex`
+      // from the real font's x-height while these numbers assume MathJax's own
+      // half-an-em: left in, the picture comes out a different width from the
+      // box reserved for it and the baseline shift is applied twice, once by
+      // the element and once by whatever is positioning it. The `viewBox`
+      // stays, so the picture scales to whatever size it is given. And
+      // `currentColor` inherits from nothing inside a `Text` on either
+      // platform, so the colour is painted in here rather than left to a prop
+      // the caller would have to know to pass.
+      svg: svg
+        .replace(ROOT, (tag) => tag.replace(SIZING, ""))
+        .replace(ANNOTATIONS, "")
+        .replace(CURRENT_COLOR, color ?? "currentColor"),
+      width: Number(ex[1]) * unit,
+      height: Number(ex[2]) * unit,
+      depth: va ? -Number(va[1]) * unit : 0,
+    }
+  } catch {
+    // Swallowed: only `renderMath` above knows whether a second go is worth it.
+    return null
+  }
+}
+
+/**
+ * Reading an expression out loud, which is a different problem from drawing it.
+ *
+ * The engine is MathJax's own -- SRE, which it depends on and drives in a web
+ * worker for the same purpose in a browser. There is no worker here, so it is
+ * driven directly: TeX is compiled to MathML (`STATE.COMPILED` stops one step
+ * short of typesetting, so this costs a parse and nothing else) and MathML is
+ * what SRE reads.
+ *
+ * `mathspeak` is the ruleset MathJax defaults to, and the one whose phrasing --
+ * "StartFraction a Over b EndFraction" -- screen reader users of maths on the
+ * web already know.
+ */
+
+/**
+ * Every locale SRE can speak, behind thunks a bundler can see, the way the font
+ * ranges are. `base` carries everything language-independent and is always
+ * needed.
+ *
+ * The two rulesets SRE ships that are not languages are left out: `nemeth` and
+ * `euro` are braille codes rather than speech, and a braille cell read aloud is
+ * nobody's accessible name.
+ *
+ * They are all named here because a `require` has to be written down for a
+ * bundler to find it -- and then all but the ones an application asked for are
+ * resolved away to nothing by `withMath(config, { locales })`, which is what
+ * keeps a display that reads in English from carrying the four megabytes of
+ * rules for the twelve languages it never speaks. See `../metro.ts`.
+ */
+const MAPS: Record<string, () => unknown> = {
+  base: () => require("speech-rule-engine/lib/mathmaps/base.json"),
+  af: () => require("speech-rule-engine/lib/mathmaps/af.json"),
+  ca: () => require("speech-rule-engine/lib/mathmaps/ca.json"),
+  da: () => require("speech-rule-engine/lib/mathmaps/da.json"),
+  de: () => require("speech-rule-engine/lib/mathmaps/de.json"),
+  en: () => require("speech-rule-engine/lib/mathmaps/en.json"),
+  es: () => require("speech-rule-engine/lib/mathmaps/es.json"),
+  fr: () => require("speech-rule-engine/lib/mathmaps/fr.json"),
+  hi: () => require("speech-rule-engine/lib/mathmaps/hi.json"),
+  it: () => require("speech-rule-engine/lib/mathmaps/it.json"),
+  ko: () => require("speech-rule-engine/lib/mathmaps/ko.json"),
+  nb: () => require("speech-rule-engine/lib/mathmaps/nb.json"),
+  nn: () => require("speech-rule-engine/lib/mathmaps/nn.json"),
+  sv: () => require("speech-rule-engine/lib/mathmaps/sv.json"),
+}
+
+/** What an expression is read in when the caller names no locale. */
+const DEFAULT_LOCALE = "en"
+
+/**
+ * The locales whose rules actually arrived.
+ *
+ * A locale resolved away to nothing comes back as an empty object, and once SRE
+ * has swallowed one there is no asking about it afterwards: a rule it cannot
+ * find for the locale it was asked for is answered out of the default locale's,
+ * so the expression is read out perfectly, in the wrong language. This is
+ * recorded on the way past, which is the last moment the difference is visible.
+ */
+const installed = new Set<string>()
+
+/**
+ * How SRE is set up, and how it is told to load a locale.
+ *
+ * The loader returns a *synchronous* thenable rather than a promise, and that
+ * is the whole trick to getting speech on the first render. SRE calls
+ * `loader(locale).then(install)` directly on whatever comes back, so a `then`
+ * that calls its callback in place has the rules installed before the call
+ * returns -- where a real promise would install them a microtask later, by
+ * which time the label has already been built and handed to the platform.
+ */
+function features(locale: string) {
+  return {
+    mode: "sync",
+    locale,
+    domain: "mathspeak",
+    style: "default",
+    modality: "speech",
+    custom: (name: string) => ({
+      then: (resolve: (maps: unknown) => void) => {
+        const maps = MAPS[name]?.() ?? {}
+
+        if (Object.keys(maps as object).length > 0) {
+          installed.add(name)
+        }
+
+        resolve(maps)
+      },
+    }),
+  }
+}
+
+const visitor = new SerializedMmlVisitor()
+
+/** Something every ruleset can say, used to check the engine came up. */
+const PROBE = '<math xmlns="http://www.w3.org/1998/Math/MathML"><mi>x</mi></math>'
+
+/** Whether SRE has been brought as far as its language-independent rules. */
+let started = false
+
+/**
+ * Three setups rather than one, because SRE loads in steps and each call
+ * carries it one step further: the first is the one it reserves for its own
+ * initialisation and which loads nothing, the second installs `base`, and the
+ * third installs the default locale.
+ *
+ * The third is not optional even when the default locale is not the one wanted.
+ * SRE reaches a locale by walking `base`, then the *default* locale, then the
+ * wanted one, and `select` can only make that walk synchronous for promises
+ * that already exist when it starts patching. Loading French first would create
+ * the English promise halfway through the walk, unpatched, and the walk would
+ * stop there -- English installed, French silently not, one microtask short.
+ */
+function start() {
+  if (started) {
+    return
+  }
+
+  // Set first: a setup that throws must not be attempted again on every span.
+  started = true
+
+  setupEngine(features(DEFAULT_LOCALE) as never)
+  setupEngine(features(DEFAULT_LOCALE) as never)
+  select(DEFAULT_LOCALE)
+}
+
+/**
+ * Points the engine at one locale, loading its rules if this is the first ask.
+ *
+ * Every promise SRE is holding is replaced, for the length of the call, by one
+ * that calls its callback in place. SRE walks a chain of them before it reaches
+ * the locale it was asked for -- `base` first, then the default locale, then
+ * the wanted one -- and a resolved promise still defers its callback by a
+ * microtask, which is a microtask longer than the render that wants the label.
+ * A thenable that calls back in place does not. They are all put back before
+ * anything else can see them.
+ */
+function select(locale: string) {
+  const held = { ...EnginePromise.promises }
+
+  for (const name of Object.keys(held)) {
+    EnginePromise.promises[name] = {
+      then: (resolve: (loaded: string) => void) => resolve(name),
+    } as unknown as Promise<string>
+  }
+
+  try {
+    setupEngine(features(locale) as never)
+  } finally {
+    for (const [name, promise] of Object.entries(held)) {
+      EnginePromise.promises[name] = promise
+    }
+  }
+}
+
+/** Which locale the engine is pointed at, and which locales can be spoken in. */
+let current: string | null = null
+const speakable = new Map<string, boolean>()
+
+/**
+ * Points the engine at `locale` and says whether anything can be said in it.
+ *
+ * All of this depends on internals that are not SRE's public API, so the result
+ * is checked rather than assumed: the rules have to have arrived and `PROBE`
+ * has to come out as speech. When it does not, or when any of this throws, that
+ * locale is written off and the caller falls back -- to the default locale, and
+ * from there to the TeX.
+ */
+function useLocale(locale: string): boolean {
+  const known = speakable.get(locale)
+
+  // The engine holds one locale at a time, so a locale that is already the one
+  // selected needs nothing done to it, and one already known to be unspeakable
+  // must not be selected -- it would leave the engine pointed somewhere it
+  // cannot read from.
+  if (current === locale) {
+    return known ?? false
+  }
+
+  if (known === false) {
+    return false
+  }
+
+  try {
+    start()
+    select(locale)
+    current = locale
+
+    const speaks = installed.has(locale) && toSpeech(PROBE) !== ""
+    speakable.set(locale, speaks)
+
+    return speaks
+  } catch {
+    // Left mute: a display falls back to the TeX, which is worse than speech
+    // and a great deal better than an unreadable paragraph.
+    speakable.set(locale, false)
+
+    return false
+  }
+}
+
+/** Locales already complained about, so a document warns once rather than once a span. */
+const warned = new Set<string>()
+
+function warn(locale: string) {
+  if (warned.has(locale)) {
+    return
+  }
+
+  warned.add(locale)
+
+  const spoken = Object.keys(MAPS)
+    .filter((name) => name !== "base")
+    .join(", ")
+
+  console.warn(
+    locale in MAPS
+      ? `[react-native-marcus] no speech rules for "${locale}" in this bundle. Pass ` +
+          `{ locales: ["${DEFAULT_LOCALE}", "${locale}"] } to withMath() in metro.config.js. ` +
+          `Maths is being read in "${DEFAULT_LOCALE}".`
+      : `[react-native-marcus] "${locale}" is not a locale the speech engine has. It speaks ` +
+          `${spoken}. Maths is being read in "${DEFAULT_LOCALE}".`,
+  )
+}
+
+/** The speech cache. Speaking an expression costs about as much as drawing it. */
+const speech = new Map<string, string | null>()
+
+/**
+ * TeX in, the expression as a sentence out.
+ *
+ * Returns nothing for anything it cannot say, which includes TeX that does not
+ * parse and a document where the rules never loaded.
+ */
+function speakMath(tex: string, display: boolean, locale?: string): string | null {
+  const wanted = locale ?? DEFAULT_LOCALE
+  const key = `${wanted}\u0000${display ? "D" : "I"}${tex}`
+  const hit = speech.get(key)
+
+  if (hit !== undefined) {
+    return hit
+  }
+
+  let speaks = useLocale(wanted)
+
+  // A language nobody bundled is worth saying out loud once: the expression is
+  // still read out, in the default locale, and the fix is one line of Metro
+  // config away. Silence would leave a French reader hearing English with no
+  // hint as to why. Complained about only once the fallback has answered,
+  // because an engine that cannot speak at all is not a bundling mistake and
+  // saying it is would send someone to the wrong file.
+  if (!speaks && wanted !== DEFAULT_LOCALE) {
+    speaks = useLocale(DEFAULT_LOCALE)
+
+    if (speaks) {
+      warn(wanted)
+    }
+  }
+
+  let said: string | null = null
+
+  if (speaks) {
+    try {
+      const root = doc.convert(tex, { display, end: STATE.COMPILED }) as MmlNode
+      const spoken = toSpeech(visitor.visitTree(root))
+
+      said = spoken === "" ? null : spoken
+    } catch {
+      // Unsayable, which is not a reason to lose the drawing beside it.
+    }
+  }
+
+  speech.set(key, said)
+
+  return said
+}
+
+export type { RenderedMath }
+
+export { available, renderMath, speakMath }