@pie-players/pie-assessment-toolkit 0.3.73 → 0.3.75

package/dist/services/tts/math-aware-text-processing.js

@@ -1,5 +1,6 @@
+import { flatQuerySelector, flatTreeChildNodes, flatTreeParentElement, rangeIntersectsComposedNode, } from "./flat-tree.js";
 import { canonicalizeMathML } from "./mathml-sanitization.js";
-import { collectVisibleTextAndMap, isNodeExcludedFromSpeech, normalizeTextForSpeech, shouldInsertWordBoundarySpace, } from "./text-processing.js";
+import { collectVisibleTextAndMap, isNodeExcludedFromSpeech, normalizeTextForSpeech, rangeHoldsSpeakableElement, shouldInsertWordBoundarySpace, } from "./text-processing.js";
 const createAccumulator = (options) => ({
     chars: [],
     map: new Map(),
@@ -21,7 +22,7 @@ const getDataMathML = (element) => {
     return value && value.trim() ? value : null;
 };
 const findAssistiveMathML = (element) => {
-    const assistive = element.querySelector("mjx-assistive-mml math");
+    const assistive = flatQuerySelector(element, "mjx-assistive-mml math");
     return assistive?.outerHTML || null;
 };
 const findCanonicalMathML = (element) => {
@@ -44,7 +45,6 @@ const findCanonicalMathML = (element) => {
     }
     return null;
 };
-const isMathContainer = (element) => Boolean(findCanonicalMathML(element));
 const TEXT_CHUNK_SOURCE_TAGS = new Set([
     "P",
     "H1",
@@ -73,7 +73,7 @@ const TEXT_CHUNK_SOURCE_ROLES = new Set([
     "rowheader",
 ]);
 const resolveTextChunkSourceElement = (textNode, root) => {
-    let current = textNode.parentElement;
+    let current = flatTreeParentElement(textNode);
     let best = null;
     while (current && current !== root) {
         const role = (current.getAttribute("role") || "").toLowerCase();
@@ -83,12 +83,12 @@ const resolveTextChunkSourceElement = (textNode, root) => {
             best = current;
             break;
         }
-        current = current.parentElement;
+        current = flatTreeParentElement(current);
     }
     return best || root;
 };
 const hasMathCandidate = (element) => Boolean(typeof element.querySelector === "function" &&
-    element.querySelector("math, [data-mathml], .MathJax, mjx-container, mjx-assistive-mml")) ||
+    flatQuerySelector(element, "math, [data-mathml], .MathJax, mjx-container, mjx-assistive-mml")) ||
     element.tagName?.toLowerCase() === "math" ||
     element.hasAttribute?.("data-mathml") ||
     isMathJaxElement(element);
@@ -122,10 +122,11 @@ const shouldInsertBoundarySpace = (acc, nextCharacter) => {
     // visible-text collector, instead of an ASCII-only heuristic.
     return shouldInsertWordBoundarySpace(previous, nextCharacter, acc.options);
 };
-const appendTextNode = (acc, textNode) => {
+/** `start` and `end` bound the part of the node appended, for a selection. */
+const appendTextNode = (acc, textNode, start = 0, end = (textNode.textContent || "").length) => {
     const raw = textNode.textContent || "";
     let appendedNonWhitespaceInNode = false;
-    for (let i = 0; i < raw.length; i++) {
+    for (let i = start; i < end; i++) {
         const character = raw[i];
         const isWhitespace = /\s/.test(character);
         if (acc.inLeadingWhitespace) {
@@ -223,6 +224,49 @@ const textFallbackFromMathML = (mathml) => {
     visit(parsed.documentElement);
     return normalizeTextForSpeech(parts.join(" "));
 };
+// MathJax CHTML paints its glyphs from CSS, so a typeset equation's only text
+// nodes are the source MathML it keeps, clipped, in mjx-assistive-mml. Mapping
+// the fallback text onto them places a catalog word inside its equation, where
+// the rendered-math resolver finds the glyph. Any divergence between the two
+// texts leaves the fallback unmapped.
+const mapFallbackToAssistiveMath = (element, fallbackText) => {
+    const map = new Map();
+    const sourceMath = isMathJaxElement(element)
+        ? flatQuerySelector(element, "mjx-assistive-mml math")
+        : null;
+    if (!sourceMath)
+        return map;
+    const characters = [];
+    const visit = (node) => {
+        if (node.nodeType === 3) {
+            const text = node.textContent || "";
+            for (let offset = 0; offset < text.length; offset++) {
+                if (!/\s/.test(text[offset])) {
+                    characters.push({ node: node, offset });
+                }
+            }
+            return;
+        }
+        if (node.nodeType !== 1 || isAnnotationElement(node))
+            return;
+        for (const child of flatTreeChildNodes(node)) {
+            visit(child);
+        }
+    };
+    visit(sourceMath);
+    let next = 0;
+    for (let index = 0; index < fallbackText.length; index++) {
+        if (/\s/.test(fallbackText[index]))
+            continue;
+        const mapping = characters[next];
+        if (mapping?.node.textContent?.[mapping.offset] !== fallbackText[index]) {
+            return new Map();
+        }
+        map.set(index, mapping);
+        next++;
+    }
+    return next === characters.length ? map : new Map();
+};
 const collectVisibleMathFallback = (element, canonicalMathML, options) => {
     const mathAcc = createAccumulator(options);
     const visit = (node) => {
@@ -239,7 +283,7 @@ const collectVisibleMathFallback = (element, canonicalMathML, options) => {
             isAnnotationElement(childElement)) {
             return;
         }
-        for (const child of Array.from(childElement.childNodes)) {
+        for (const child of flatTreeChildNodes(childElement)) {
             visit(child);
         }
     };
@@ -255,7 +299,7 @@ const collectVisibleMathFallback = (element, canonicalMathML, options) => {
     }
     return {
         text: fallbackText,
-        map: new Map(),
+        map: mapFallbackToAssistiveMath(element, fallbackText),
     };
 };
 const trimTrailingWhitespace = (acc) => {
@@ -265,7 +309,7 @@ const trimTrailingWhitespace = (acc) => {
         acc.map.delete(acc.position);
     }
 };
-const collectMathAware = (root, options) => {
+const collectMathAware = (root, options, range) => {
     const acc = createAccumulator(options);
     const chunks = [];
     let textChunkStart = 0;
@@ -286,22 +330,28 @@ const collectMathAware = (root, options) => {
     const processNode = (node) => {
         if (isNodeExcludedFromSpeech(node, root))
             return;
-        if (node.nodeType === Node.TEXT_NODE) {
+        if (range && !rangeIntersectsComposedNode(range, node))
+            return;
+        if (node.nodeType === 3) {
             const sourceElement = resolveTextChunkSourceElement(node, root);
             if (textChunkSourceElement && sourceElement !== textChunkSourceElement) {
                 flushTextChunk();
             }
             textChunkSourceElement = sourceElement;
-            appendTextNode(acc, node);
+            const textNode = node;
+            appendTextNode(acc, textNode, range?.startContainer === textNode ? range.startOffset : undefined, range?.endContainer === textNode ? range.endOffset : undefined);
             return;
         }
-        if (node.nodeType !== Node.ELEMENT_NODE)
+        if (node.nodeType !== 1)
             return;
         const element = node;
         if (isAssistiveMathElement(element))
             return;
         const canonicalMathML = findCanonicalMathML(element);
-        if (canonicalMathML) {
+        // An equation is spoken as math only when the selection holds all of it;
+        // a part of one reads as the text selected.
+        if (canonicalMathML &&
+            (!range || rangeHoldsSpeakableElement(range, element, root))) {
             flushTextChunk();
             const collected = collectVisibleMathFallback(element, canonicalMathML, options);
             appendCollectedText(acc, collected);
@@ -316,11 +366,11 @@ const collectMathAware = (root, options) => {
             containsMathMarkup = true;
             return;
         }
-        for (const child of Array.from(element.childNodes)) {
+        for (const child of flatTreeChildNodes(element)) {
             processNode(child);
         }
     };
-    for (const child of Array.from(root.childNodes)) {
+    for (const child of flatTreeChildNodes(root)) {
         processNode(child);
     }
     trimTrailingWhitespace(acc);
@@ -336,7 +386,13 @@ const collectMathAware = (root, options) => {
         containsMathMarkup,
     };
 };
-export const collectMathAwareTextAndMap = (element, options) => {
+/**
+ * With `range`, only the part of `element` the range selects: text it selects
+ * and equations it holds whole.
+ */
+export const collectMathAwareTextAndMap = (element, options, range) => {
+    if (range)
+        return collectMathAware(element, options, range);
     if (!hasMathCandidate(element)) {
         const { text, map } = collectVisibleTextAndMap(element, options);
         return {

package/dist/services/tts/math-control-names.d.ts

@@ -0,0 +1,21 @@
+import { type ResolveMathSpeechOptions, type SREMathSpeechOptions } from "./math-speech.js";
+export interface MathControlNamesOptions {
+    /**
+     * The host's math speech options. Names take only `engineOptions`, where
+     * SRE's locale tables load from: their domain and style are fixed.
+     */
+    getMathSpeech?: () => SREMathSpeechOptions | undefined;
+    /** The host's `content-language`, read when an expression is named. */
+    getContentLanguage?: () => string | null | undefined;
+    loadSre?: ResolveMathSpeechOptions["loadSre"];
+}
+/**
+ * Labels each typeset expression inside a control under `root`, open shadow
+ * roots included, with SRE's speech, as MathJax adds it and again whenever
+ * MathJax replaces it. An `aria-label` on the role-less `mjx-container` puts
+ * that speech in the name of the control around it, among the control's other
+ * text. English reads ClearSpeak, other languages MathSpeak, in the language of
+ * the content. The label replaces the elements' own; it stays when SRE cannot
+ * speak the math. Returns the function that stops observing.
+ */
+export declare function observeMathControlNames(root: Element, options?: MathControlNamesOptions): () => void;

package/dist/services/tts/math-control-names.js

@@ -0,0 +1,142 @@
+import { resolveContentLanguage } from "../../runtime/content-language.js";
+import { flatQuerySelector, flatTreeClosest, walkFlatTree, } from "./flat-tree.js";
+import { resolveMathSpeechFromChunks, } from "./math-speech.js";
+import { canonicalizeMathML } from "./mathml-sanitization.js";
+/**
+ * Elements that take their accessible name from their content. Browsers leave
+ * MathML out of that name, so a choice labelled with math is named from its
+ * bare symbols ("4 12" for 4 over 12). The elements' renderer labels the math
+ * in the same set of controls with its own English speech.
+ */
+const CONTROLS = [
+    "a[href]",
+    "button",
+    "label",
+    "summary",
+    ...[
+        "button",
+        "checkbox",
+        "combobox",
+        "link",
+        "menuitem",
+        "menuitemcheckbox",
+        "menuitemradio",
+        "option",
+        "radio",
+        "switch",
+        "tab",
+        "treeitem",
+    ].map((role) => `[role="${role}"]`),
+].join(", ");
+const TOKENS = new Set(["mi", "mn", "mtext"]);
+const isToken = (element) => TOKENS.has(element.localName) ||
+    (element.localName === "mrow" &&
+        element.children.length === 1 &&
+        TOKENS.has(element.children[0].localName));
+/**
+ * ClearSpeak's fraction preference for a name. "4 over 12" keeps the numerals
+ * as written, where the default says "four fourths" for 4 over 4 (WCAG 2.5.3:
+ * a name does not put words in place of the formula). "Over" between longer
+ * parts is ambiguous, so an expression holding such a fraction reads every
+ * fraction by numerator and denominator.
+ */
+const fractionStyle = (math) => Array.from(math.getElementsByTagName("mfrac")).every((fraction) => Array.from(fraction.children).every(isToken))
+    ? "Fraction_Over"
+    : "Fraction_General";
+const isEnglish = (language) => !language || language.toLowerCase().split("-")[0] === "en";
+/**
+ * Labels each typeset expression inside a control under `root`, open shadow
+ * roots included, with SRE's speech, as MathJax adds it and again whenever
+ * MathJax replaces it. An `aria-label` on the role-less `mjx-container` puts
+ * that speech in the name of the control around it, among the control's other
+ * text. English reads ClearSpeak, other languages MathSpeak, in the language of
+ * the content. The label replaces the elements' own; it stays when SRE cannot
+ * speak the math. Returns the function that stops observing.
+ */
+export function observeMathControlNames(root, options = {}) {
+    if (typeof MutationObserver === "undefined")
+        return () => { };
+    const speech = new Map();
+    let stopped = false;
+    const speak = async (mathml, math, language) => {
+        const result = await resolveMathSpeechFromChunks([{ type: "math", mathml, fallbackText: "" }], {
+            language,
+            loadSre: options.loadSre,
+            mathSpeech: {
+                ...(isEnglish(language) ? { style: fractionStyle(math) } : {}),
+                engineOptions: options.getMathSpeech?.()?.engineOptions,
+            },
+        });
+        return result.usedMathSpeech ? result.speechText : null;
+    };
+    const name = (container) => {
+        if (!flatTreeClosest(container, CONTROLS))
+            return;
+        const math = flatQuerySelector(container, "math");
+        const mathml = math && canonicalizeMathML(math.outerHTML);
+        if (!math || !mathml)
+            return;
+        const language = resolveContentLanguage(container, {
+            contentLanguage: options.getContentLanguage?.(),
+        });
+        const key = `${language ?? ""}\u0000${mathml}`;
+        let pending = speech.get(key);
+        if (!pending) {
+            pending = speak(mathml, math, language);
+            speech.set(key, pending);
+        }
+        void pending.then((label) => {
+            if (stopped || !label || !container.isConnected)
+                return;
+            if (container.getAttribute("aria-label") !== label) {
+                container.setAttribute("aria-label", label);
+            }
+        });
+    };
+    // A shadow root is a tree of its own, which an observer on `root` does not
+    // see into, so each one found is observed as well. One attached after its
+    // host was visited is not found until something is added around the host.
+    const observed = new WeakSet();
+    const observeTree = (tree) => {
+        if (observed.has(tree))
+            return;
+        observed.add(tree);
+        observer.observe(tree, { childList: true, subtree: true });
+    };
+    const visit = (node) => {
+        if (node.nodeType !== 1)
+            return;
+        const element = node;
+        const container = flatTreeClosest(element, "mjx-container");
+        if (container) {
+            name(container);
+            return;
+        }
+        if (element.shadowRoot)
+            observeTree(element.shadowRoot);
+        walkFlatTree(element, (descendant) => {
+            if (descendant.nodeType !== 1)
+                return "skip";
+            const found = descendant;
+            if (found.localName === "mjx-container") {
+                name(found);
+                return "skip";
+            }
+            if (found.shadowRoot)
+                observeTree(found.shadowRoot);
+            return undefined;
+        });
+    };
+    const observer = new MutationObserver((records) => {
+        for (const record of records) {
+            for (const node of record.addedNodes)
+                visit(node);
+        }
+    });
+    observeTree(root);
+    visit(root);
+    return () => {
+        stopped = true;
+        observer.disconnect();
+    };
+}

package/dist/services/tts/math-speech.d.ts

@@ -25,7 +25,11 @@ export interface SREMathSpeechOptions {
     domain?: string;
     /** Raw SRE style/preference string. ClearSpeak preferences are ":"-joined. */
     style?: string;
-    /** Extra SRE setupEngine options for hosts that need a newly exposed SRE knob. */
+    /**
+     * Extra SRE setupEngine options for hosts that need a newly exposed SRE knob.
+     * In a browser, SRE's locale tables load from the host's bundle unless `json`
+     * (a base URL or path) or `custom` (a loader) names another source.
+     */
     engineOptions?: Record<string, unknown>;
 }
 export interface ResolvedMathSpeech {
@@ -39,6 +43,17 @@ export interface ResolvedMathSpeech {
      */
     ssml?: string;
 }
+/**
+ * Loads the speech-rule-engine once per page. A failed load is dropped, so the
+ * next call tries again; meanwhile math reads as its visible text. The first
+ * failure warns, later ones log at debug.
+ */
+export declare const createSreLoader: (importEngine: () => Promise<SpeechRuleEngineApi>) => ((engineOptions?: Record<string, unknown>) => Promise<SpeechRuleEngineApi>);
+/**
+ * One speech-rule-engine load for a whole read: its equations share the
+ * attempt, so a failed load costs a read one attempt.
+ */
+export declare const createReadSreLoad: (mathSpeech?: SREMathSpeechOptions) => (() => Promise<SpeechRuleEngineApi>);
 export declare const normalizeSREMathSpeechOptions: (options: unknown) => SREMathSpeechOptions | undefined;
 export declare const resolveMathSpeechFromChunks: (chunks: MathAwareSpeechChunk[], options?: ResolveMathSpeechOptions) => Promise<ResolvedMathSpeech>;
 export {};

package/dist/services/tts/math-speech.js

@@ -1,19 +1,53 @@
+import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
+import { setSreStartupLocaleSource, sreLocaleSource } from "./sre-locales.js";
 import { normalizeTextForSpeech } from "./text-processing.js";
-let sreLoadPromise = null;
+// Debug lines need PIE_TTS_DEBUG=1 or globalThis.__PIE_TTS_DEBUG__ = true.
+const logger = createPieLogger("tts-math-speech", isTtsDebugEnabled);
 let sreOperationQueue = Promise.resolve();
 const normalizeLocale = (language) => (language || "en").split("-")[0].toLowerCase() || "en";
-const defaultLoadSre = async () => {
-    if (!sreLoadPromise) {
-        sreLoadPromise = import("speech-rule-engine").then((module) => {
-            const candidate = module.default ||
-                module;
-            if (!candidate || typeof candidate.toSpeech !== "function") {
-                throw new Error("speech-rule-engine did not expose toSpeech");
-            }
-            return candidate;
-        });
+/**
+ * Loads the speech-rule-engine once per page. A failed load is dropped, so the
+ * next call tries again; meanwhile math reads as its visible text. The first
+ * failure warns, later ones log at debug.
+ */
+export const createSreLoader = (importEngine) => {
+    let load = null;
+    let warned = false;
+    return (engineOptions) => {
+        if (!load) {
+            setSreStartupLocaleSource(engineOptions);
+            const attempt = importEngine();
+            load = attempt;
+            attempt.catch((error) => {
+                if (load === attempt)
+                    load = null;
+                if (warned) {
+                    logger.debug("speech-rule-engine failed to load again", error);
+                    return;
+                }
+                warned = true;
+                logger.warn("speech-rule-engine failed to load; math reads as its visible text until a later read loads it.", error);
+            });
+        }
+        return load;
+    };
+};
+const defaultLoadSre = createSreLoader(() => import("./sre-engine.js").then(({ default: candidate }) => {
+    if (!candidate || typeof candidate.toSpeech !== "function") {
+        throw new Error("speech-rule-engine did not expose toSpeech");
     }
-    return sreLoadPromise;
+    return candidate;
+}));
+/**
+ * One speech-rule-engine load for a whole read: its equations share the
+ * attempt, so a failed load costs a read one attempt.
+ */
+export const createReadSreLoad = (mathSpeech) => {
+    let attempt = null;
+    return () => {
+        attempt ??= defaultLoadSre(normalizeSREMathSpeechOptions(mathSpeech)?.engineOptions);
+        return attempt;
+    };
 };
 // SRE's ClearSpeak rule set is English-only; MathSpeak is localized to many more
 // locales. Use ClearSpeak for English (highest-quality math prose) and MathSpeak
@@ -41,13 +75,15 @@ export const normalizeSREMathSpeechOptions = (options) => {
 const setupSre = async (sre, language, markup, mathSpeech) => {
     const locale = normalizeLocale(language);
     const normalizedMathSpeech = normalizeSREMathSpeechOptions(mathSpeech);
+    const engineOptions = normalizedMathSpeech?.engineOptions || {};
     await sre.setupEngine?.({
-        ...(normalizedMathSpeech?.engineOptions || {}),
+        ...sreLocaleSource(engineOptions),
+        ...engineOptions,
         locale,
         domain: normalizedMathSpeech?.domain || domainForLocale(locale),
-        ...(normalizedMathSpeech?.style
-            ? { style: normalizedMathSpeech.style }
-            : {}),
+        // SRE keeps a style it was given until it is given another, so a call
+        // without one resets it: math control names set ClearSpeak preferences.
+        style: normalizedMathSpeech?.style || "default",
         modality: "speech",
         markup,
     });
@@ -78,7 +114,7 @@ const generateMathSsml = async (sre, mathml, language, mathSpeech) => {
         return ssml.includes("<speak") ? ssml : null;
     }
     catch (error) {
-        console.debug("[TTSService] Math SSML generation failed; using plain", {
+        logger.debug("math SSML generation failed; using plain", {
             message: error instanceof Error ? error.message : String(error),
         });
         return null;
@@ -97,7 +133,7 @@ export const resolveMathSpeechFromChunks = async (chunks, options = {}) => {
     let sre = null;
     let usedMathSpeech = false;
     let usedFallback = false;
-    const loadSre = options.loadSre || defaultLoadSre;
+    const loadSre = options.loadSre || createReadSreLoad(options.mathSpeech);
     const speechParts = [];
     for (const chunk of chunks) {
         if (chunk.type === "text") {
@@ -119,7 +155,7 @@ export const resolveMathSpeechFromChunks = async (chunks, options = {}) => {
         }
         catch (error) {
             usedFallback = true;
-            console.debug("[TTSService] Math speech generation failed; using visible fallback", {
+            logger.debug("math speech generation failed; using visible fallback", {
                 message: error instanceof Error ? error.message : String(error),
             });
             speechParts.push(chunk.fallbackText);

package/dist/services/tts/provider-options.d.ts

@@ -0,0 +1,41 @@
+import type { TTSConfig, TTSProviderOptions } from "@pie-players/pie-tts";
+import type { SREMathSpeechOptions } from "./math-speech.js";
+import type { BoundarySpacingMode } from "./text-processing.js";
+/**
+ * The provider options the toolkit reads, on top of the ones every provider
+ * receives. Hosts configure them as free-form options, so readers still check
+ * each value at runtime.
+ */
+export interface ToolkitTTSProviderOptions extends TTSProviderOptions {
+    /** Highlight words or sentences while reading. Defaults by provider capability. */
+    highlightMode?: "word" | "sentence";
+    /** Locale for text processing; the toolkit sets it per speak. */
+    locale?: string;
+    /** Speech-rule-engine options for math speech. */
+    mathSpeech?: SREMathSpeechOptions;
+    /** Sentence and word segmentation of the browser provider. */
+    segmenter?: {
+        /** `regexOnly` segments without `Intl.Segmenter`. */
+        mode?: "regexOnly";
+        locale?: string;
+    };
+    /** Pauses at structural boundaries: `baseMs` scaled by a strength unit, clamped. */
+    structuralPauses?: {
+        baseMs?: number | string;
+        units?: {
+            minor?: number | string;
+            section?: number | string;
+            major?: number | string;
+        };
+        minMs?: number | string;
+        maxMs?: number | string;
+    };
+    textNormalization?: {
+        boundarySpacingMode?: BoundarySpacingMode;
+        locale?: string;
+    };
+}
+/** A provider configuration as the toolkit reads it. */
+export interface ToolkitTTSConfig extends TTSConfig {
+    providerOptions?: ToolkitTTSProviderOptions;
+}

package/dist/services/tts/provider-options.js

@@ -0,0 +1 @@
+export {};

package/dist/services/tts/sre-engine.d.ts

@@ -0,0 +1,7 @@
+import * as speechRuleEngine from "speech-rule-engine";
+declare const sre: {
+    setupEngine: typeof speechRuleEngine.setupEngine;
+    engineReady: typeof speechRuleEngine.engineReady;
+    toSpeech: typeof speechRuleEngine.toSpeech;
+};
+export default sre;

package/dist/services/tts/sre-engine.js

@@ -0,0 +1,11 @@
+import * as speechRuleEngine from "speech-rule-engine";
+import { sreStartupLocaleSource } from "./sre-locales.js";
+const sre = speechRuleEngine.default ?? speechRuleEngine;
+// SRE starts itself up while this module's import of it evaluates, then loads
+// `base` and `en` a few microtasks later from whatever locale source is set by
+// then. In a bundle this call runs synchronously after that evaluation, so it
+// lands first; configuring SRE after awaiting an `import()` of it lands after
+// those loads. Bun drains microtasks between evaluating a CommonJS module and
+// its importer, so there SRE reads `base` from its own package directory.
+void sre.setupEngine(sreStartupLocaleSource());
+export default sre;

package/dist/services/tts/sre-locales.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The `setupEngine` options naming where SRE reads locale tables from: the
+ * host's `json` (a base URL or path) or `custom` (a loader) when its
+ * `engineOptions` set either, otherwise the packaged tables wherever SRE would
+ * fetch them. SRE prefers `custom` over `json`, so the packaged loader is left
+ * out whenever the host names a source.
+ */
+export declare const sreLocaleSource: (engineOptions?: Record<string, unknown>) => Record<string, unknown>;
+/**
+ * Sets the source SRE loads its start-up locales from; see `./sre-engine.ts`.
+ * Only a call made before that module first loads has any effect.
+ */
+export declare const setSreStartupLocaleSource: (engineOptions?: Record<string, unknown>) => void;
+export declare const sreStartupLocaleSource: () => Record<string, unknown>;

package/dist/services/tts/sre-locales.js

@@ -0,0 +1,57 @@
+// SRE loads each locale's rule tables at runtime, from a public CDN unless it is
+// handed a source. An import per table lets the host's bundler emit each as a
+// lazy chunk served from the host's own origin, but a build that inlines every
+// `import()` into one file carries every table listed here, at 0.2 to 0.4 MB
+// each. So only `base`, which every locale builds on, and the `en` and `es`
+// locales are packaged; any other locale needs a source from the host's
+// `engineOptions`. No `with { type: "json" }`: bundlers infer JSON from the
+// extension, while Vite's dev server and Bun's bundler turn a table into
+// JavaScript and keep the attribute, which a browser then rejects.
+const SRE_LOCALE_TABLES = {
+    base: () => import("speech-rule-engine/lib/mathmaps/base.json"),
+    en: () => import("speech-rule-engine/lib/mathmaps/en.json"),
+    es: () => import("speech-rule-engine/lib/mathmaps/es.json"),
+};
+// SRE's `custom` loader contract: called with a locale name, resolving to that
+// locale's table as a JSON string or an already-parsed object. SRE falls back
+// to English when a table fails to load.
+const loadPackagedSreLocale = async (locale) => {
+    if (!Object.hasOwn(SRE_LOCALE_TABLES, locale)) {
+        throw new Error(`no speech-rule-engine locale table is packaged for "${locale}"; name a source with mathSpeech.engineOptions.json or .custom`);
+    }
+    return (await SRE_LOCALE_TABLES[locale]()).default;
+};
+// SRE's own test for fetching tables over HTTP (`common/system_external.js`).
+// Elsewhere it reads them from its package directory, which Node's ESM loader
+// could not replace with the imports above: it requires the attribute.
+const sreFetchesTables = () => (typeof window !== "undefined" && typeof window.document !== "undefined") ||
+    typeof globalThis
+        .DedicatedWorkerGlobalScope !== "undefined";
+/**
+ * The `setupEngine` options naming where SRE reads locale tables from: the
+ * host's `json` (a base URL or path) or `custom` (a loader) when its
+ * `engineOptions` set either, otherwise the packaged tables wherever SRE would
+ * fetch them. SRE prefers `custom` over `json`, so the packaged loader is left
+ * out whenever the host names a source.
+ */
+export const sreLocaleSource = (engineOptions = {}) => {
+    const { json, custom } = engineOptions;
+    if (json || custom) {
+        return { ...(json ? { json } : {}), ...(custom ? { custom } : {}) };
+    }
+    return sreFetchesTables() ? { custom: loadPackagedSreLocale } : {};
+};
+// Resolved on first read: a call at module scope would keep the table imports
+// in every bundle that includes this module, math speech used or not.
+let startupLocaleSource;
+/**
+ * Sets the source SRE loads its start-up locales from; see `./sre-engine.ts`.
+ * Only a call made before that module first loads has any effect.
+ */
+export const setSreStartupLocaleSource = (engineOptions) => {
+    startupLocaleSource = sreLocaleSource(engineOptions);
+};
+export const sreStartupLocaleSource = () => {
+    startupLocaleSource ??= sreLocaleSource();
+    return startupLocaleSource;
+};