@pie-players/pie-assessment-toolkit 0.3.44 → 0.3.45

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

@@ -0,0 +1,44 @@
+import type { MathAwareSpeechChunk } from "./math-aware-text-processing.js";
+interface SpeechRuleEngineApi {
+    setupEngine?: (options: Record<string, unknown>) => Promise<void> | void;
+    engineReady?: () => Promise<void>;
+    toSpeech: (mathml: string) => string;
+}
+export interface ResolveMathSpeechOptions {
+    language?: string;
+    loadSre?: () => Promise<SpeechRuleEngineApi>;
+    /**
+     * Optional SRE configuration supplied by the host. This deliberately exposes
+     * SRE's own knobs instead of adding toolkit speech rewrites.
+     */
+    mathSpeech?: SREMathSpeechOptions;
+    /**
+     * Also produce SRE's SSML rendering (markup: "ssml") for the equation, for
+     * the runtime generated-SSML path (PIE-623). Only populated when the input
+     * is a single math chunk and SRE succeeds. The plain `speechText` is always
+     * computed with markup: "none" so the plain path is unaffected.
+     */
+    produceSsml?: boolean;
+}
+export interface SREMathSpeechOptions {
+    /** SRE domain, e.g. "clearspeak" or "mathspeak". Defaults by locale. */
+    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. */
+    engineOptions?: Record<string, unknown>;
+}
+export interface ResolvedMathSpeech {
+    speechText: string;
+    usedMathSpeech: boolean;
+    usedFallback: boolean;
+    /**
+     * SRE SSML rendering of the equation (a self-contained `<speak>` document),
+     * present only when `produceSsml` was requested for a single math chunk and
+     * SRE produced trackable SSML.
+     */
+    ssml?: string;
+}
+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

@@ -0,0 +1,147 @@
+import { normalizeTextForSpeech } from "./text-processing.js";
+let sreLoadPromise = null;
+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;
+        });
+    }
+    return sreLoadPromise;
+};
+// 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
+// elsewhere, so non-English content gets locale-appropriate voicing instead of
+// silently falling back to English ClearSpeak rules.
+const domainForLocale = (locale) => locale === "en" ? "clearspeak" : "mathspeak";
+const isPlainRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const trimOption = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
+export const normalizeSREMathSpeechOptions = (options) => {
+    if (!isPlainRecord(options))
+        return undefined;
+    const domain = trimOption(options.domain);
+    const style = trimOption(options.style);
+    const engineOptions = isPlainRecord(options.engineOptions)
+        ? options.engineOptions
+        : undefined;
+    if (!domain && !style && !engineOptions)
+        return undefined;
+    return {
+        ...(domain ? { domain } : {}),
+        ...(style ? { style } : {}),
+        ...(engineOptions ? { engineOptions } : {}),
+    };
+};
+const setupSre = async (sre, language, markup, mathSpeech) => {
+    const locale = normalizeLocale(language);
+    const normalizedMathSpeech = normalizeSREMathSpeechOptions(mathSpeech);
+    await sre.setupEngine?.({
+        ...(normalizedMathSpeech?.engineOptions || {}),
+        locale,
+        domain: normalizedMathSpeech?.domain || domainForLocale(locale),
+        ...(normalizedMathSpeech?.style ? { style: normalizedMathSpeech.style } : {}),
+        modality: "speech",
+        markup,
+    });
+    await sre.engineReady?.();
+};
+const runSerializedSreOperation = async (operation) => {
+    const result = sreOperationQueue.then(operation, operation);
+    sreOperationQueue = result.then(() => undefined, () => undefined);
+    return result;
+};
+const toSpeechWithSreSettings = async (sre, mathml, language, markup, mathSpeech) => runSerializedSreOperation(async () => {
+    await setupSre(sre, language, markup, mathSpeech);
+    return sre.toSpeech(mathml);
+});
+// SRE's SSML rendering wraps the spoken words in highlight-safe structural tags
+// (`speak`, `prosody`, `say-as interpret-as="character"`, `break`), all handled
+// by `extractSpokenText`, so word-boundary offsets into the raw SSML still map
+// back to spoken tokens. SRE also prepends an XML prolog (`<?xml …?>`); AWS
+// Polly and Google Cloud TTS reject SSML that does not begin with `<speak>`, so
+// we strip the prolog here. The stripped string is the single source of truth:
+// it is both what the provider receives and what the alignment tokenizes, so
+// offsets stay consistent. We only accept output that contains a `<speak>`
+// element, so a bad/empty render degrades to plain text.
+const stripXmlProlog = (ssml) => ssml.replace(/^\s*<\?xml[^>]*\?>\s*/i, "");
+const generateMathSsml = async (sre, mathml, language, mathSpeech) => {
+    try {
+        const ssml = stripXmlProlog(await toSpeechWithSreSettings(sre, mathml, language, "ssml", mathSpeech));
+        return ssml.includes("<speak") ? ssml : null;
+    }
+    catch (error) {
+        console.debug("[TTSService] Math SSML generation failed; using plain", {
+            message: error instanceof Error ? error.message : String(error),
+        });
+        return null;
+    }
+};
+export const resolveMathSpeechFromChunks = async (chunks, options = {}) => {
+    if (!chunks.some((chunk) => chunk.type === "math")) {
+        return {
+            speechText: normalizeTextForSpeech(chunks
+                .map((chunk) => chunk.type === "text" ? chunk.text : chunk.fallbackText)
+                .join(" ")),
+            usedMathSpeech: false,
+            usedFallback: false,
+        };
+    }
+    let sre = null;
+    let usedMathSpeech = false;
+    let usedFallback = false;
+    const loadSre = options.loadSre || defaultLoadSre;
+    const speechParts = [];
+    for (const chunk of chunks) {
+        if (chunk.type === "text") {
+            speechParts.push(chunk.text);
+            continue;
+        }
+        try {
+            if (!sre) {
+                sre = await loadSre();
+            }
+            const speech = normalizeTextForSpeech(await toSpeechWithSreSettings(sre, chunk.mathml, options.language, "none", options.mathSpeech));
+            if (speech) {
+                speechParts.push(speech);
+                usedMathSpeech = true;
+                continue;
+            }
+            usedFallback = true;
+            speechParts.push(chunk.fallbackText);
+        }
+        catch (error) {
+            usedFallback = true;
+            console.debug("[TTSService] Math speech generation failed; using visible fallback", {
+                message: error instanceof Error ? error.message : String(error),
+            });
+            speechParts.push(chunk.fallbackText);
+        }
+    }
+    // Generated-SSML path: only meaningful for a single math chunk (the runtime
+    // composes one chunk per equation). Computed after the plain pass so the
+    // markup: "none" `speechText` above is unchanged. The "none" → "ssml"
+    // engine reconfiguration happens sequentially within this call.
+    const speechText = normalizeTextForSpeech(speechParts.join(" "));
+    let ssml;
+    if (options.produceSsml &&
+        sre &&
+        usedMathSpeech &&
+        chunks.length === 1 &&
+        chunks[0].type === "math") {
+        const generated = await generateMathSsml(sre, chunks[0].mathml, options.language, options.mathSpeech);
+        ssml = generated ?? undefined;
+    }
+    return {
+        speechText,
+        usedMathSpeech,
+        usedFallback,
+        ssml,
+    };
+};
+//# sourceMappingURL=math-speech.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"math-speech.js","sourceRoot":"","sources":["../../../src/services/tts/math-speech.ts"],"names":[],"mappings":"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","sourcesContent":["import type { MathAwareSpeechChunk } from \"./math-aware-text-processing.js\";\nimport { normalizeTextForSpeech } from \"./text-processing.js\";\n\ninterface SpeechRuleEngineApi {\n\tsetupEngine?: (options: Record<string, unknown>) => Promise<void> | void;\n\tengineReady?: () => Promise<void>;\n\ttoSpeech: (mathml: string) => string;\n}\n\nexport interface ResolveMathSpeechOptions {\n\tlanguage?: string;\n\tloadSre?: () => Promise<SpeechRuleEngineApi>;\n\t/**\n\t * Optional SRE configuration supplied by the host. This deliberately exposes\n\t * SRE's own knobs instead of adding toolkit speech rewrites.\n\t */\n\tmathSpeech?: SREMathSpeechOptions;\n\t/**\n\t * Also produce SRE's SSML rendering (markup: \"ssml\") for the equation, for\n\t * the runtime generated-SSML path (PIE-623). Only populated when the input\n\t * is a single math chunk and SRE succeeds. The plain `speechText` is always\n\t * computed with markup: \"none\" so the plain path is unaffected.\n\t */\n\tproduceSsml?: boolean;\n}\n\nexport interface SREMathSpeechOptions {\n\t/** SRE domain, e.g. \"clearspeak\" or \"mathspeak\". Defaults by locale. */\n\tdomain?: string;\n\t/** Raw SRE style/preference string. ClearSpeak preferences are \":\"-joined. */\n\tstyle?: string;\n\t/** Extra SRE setupEngine options for hosts that need a newly exposed SRE knob. */\n\tengineOptions?: Record<string, unknown>;\n}\n\nexport interface ResolvedMathSpeech {\n\tspeechText: string;\n\tusedMathSpeech: boolean;\n\tusedFallback: boolean;\n\t/**\n\t * SRE SSML rendering of the equation (a self-contained `<speak>` document),\n\t * present only when `produceSsml` was requested for a single math chunk and\n\t * SRE produced trackable SSML.\n\t */\n\tssml?: string;\n}\n\nlet sreLoadPromise: Promise<SpeechRuleEngineApi> | null = null;\nlet sreOperationQueue: Promise<unknown> = Promise.resolve();\n\nconst normalizeLocale = (language?: string): string =>\n\t(language || \"en\").split(\"-\")[0].toLowerCase() || \"en\";\n\nconst defaultLoadSre = async (): Promise<SpeechRuleEngineApi> => {\n\tif (!sreLoadPromise) {\n\t\tsreLoadPromise = import(\"speech-rule-engine\").then((module) => {\n\t\t\tconst candidate =\n\t\t\t\t(module as { default?: SpeechRuleEngineApi }).default ||\n\t\t\t\t(module as unknown as SpeechRuleEngineApi);\n\t\t\tif (!candidate || typeof candidate.toSpeech !== \"function\") {\n\t\t\t\tthrow new Error(\"speech-rule-engine did not expose toSpeech\");\n\t\t\t}\n\t\t\treturn candidate;\n\t\t});\n\t}\n\treturn sreLoadPromise;\n};\n\n// SRE's ClearSpeak rule set is English-only; MathSpeak is localized to many more\n// locales. Use ClearSpeak for English (highest-quality math prose) and MathSpeak\n// elsewhere, so non-English content gets locale-appropriate voicing instead of\n// silently falling back to English ClearSpeak rules.\nconst domainForLocale = (locale: string): string =>\n\tlocale === \"en\" ? \"clearspeak\" : \"mathspeak\";\n\nconst isPlainRecord = (value: unknown): value is Record<string, unknown> =>\n\t!!value && typeof value === \"object\" && !Array.isArray(value);\n\nconst trimOption = (value: unknown): string | undefined =>\n\ttypeof value === \"string\" && value.trim() ? value.trim() : undefined;\n\nexport const normalizeSREMathSpeechOptions = (\n\toptions: unknown,\n): SREMathSpeechOptions | undefined => {\n\tif (!isPlainRecord(options)) return undefined;\n\tconst domain = trimOption(options.domain);\n\tconst style = trimOption(options.style);\n\tconst engineOptions = isPlainRecord(options.engineOptions)\n\t\t? options.engineOptions\n\t\t: undefined;\n\tif (!domain && !style && !engineOptions) return undefined;\n\treturn {\n\t\t...(domain ? { domain } : {}),\n\t\t...(style ? { style } : {}),\n\t\t...(engineOptions ? { engineOptions } : {}),\n\t};\n};\n\nconst setupSre = async (\n\tsre: SpeechRuleEngineApi,\n\tlanguage: string | undefined,\n\tmarkup: \"none\" | \"ssml\",\n\tmathSpeech?: SREMathSpeechOptions,\n): Promise<void> => {\n\tconst locale = normalizeLocale(language);\n\tconst normalizedMathSpeech = normalizeSREMathSpeechOptions(mathSpeech);\n\tawait sre.setupEngine?.({\n\t\t...(normalizedMathSpeech?.engineOptions || {}),\n\t\tlocale,\n\t\tdomain: normalizedMathSpeech?.domain || domainForLocale(locale),\n\t\t...(normalizedMathSpeech?.style ? { style: normalizedMathSpeech.style } : {}),\n\t\tmodality: \"speech\",\n\t\tmarkup,\n\t});\n\tawait sre.engineReady?.();\n};\n\nconst runSerializedSreOperation = async <T>(\n\toperation: () => Promise<T>,\n): Promise<T> => {\n\tconst result = sreOperationQueue.then(operation, operation);\n\tsreOperationQueue = result.then(\n\t\t() => undefined,\n\t\t() => undefined,\n\t);\n\treturn result;\n};\n\nconst toSpeechWithSreSettings = async (\n\tsre: SpeechRuleEngineApi,\n\tmathml: string,\n\tlanguage: string | undefined,\n\tmarkup: \"none\" | \"ssml\",\n\tmathSpeech?: SREMathSpeechOptions,\n): Promise<string> =>\n\trunSerializedSreOperation(async () => {\n\t\tawait setupSre(sre, language, markup, mathSpeech);\n\t\treturn sre.toSpeech(mathml);\n\t});\n\n// SRE's SSML rendering wraps the spoken words in highlight-safe structural tags\n// (`speak`, `prosody`, `say-as interpret-as=\"character\"`, `break`), all handled\n// by `extractSpokenText`, so word-boundary offsets into the raw SSML still map\n// back to spoken tokens. SRE also prepends an XML prolog (`<?xml …?>`); AWS\n// Polly and Google Cloud TTS reject SSML that does not begin with `<speak>`, so\n// we strip the prolog here. The stripped string is the single source of truth:\n// it is both what the provider receives and what the alignment tokenizes, so\n// offsets stay consistent. We only accept output that contains a `<speak>`\n// element, so a bad/empty render degrades to plain text.\nconst stripXmlProlog = (ssml: string): string =>\n\tssml.replace(/^\\s*<\\?xml[^>]*\\?>\\s*/i, \"\");\n\nconst generateMathSsml = async (\n\tsre: SpeechRuleEngineApi,\n\tmathml: string,\n\tlanguage?: string,\n\tmathSpeech?: SREMathSpeechOptions,\n): Promise<string | null> => {\n\ttry {\n\t\tconst ssml = stripXmlProlog(\n\t\t\tawait toSpeechWithSreSettings(sre, mathml, language, \"ssml\", mathSpeech),\n\t\t);\n\t\treturn ssml.includes(\"<speak\") ? ssml : null;\n\t} catch (error) {\n\t\tconsole.debug(\"[TTSService] Math SSML generation failed; using plain\", {\n\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t});\n\t\treturn null;\n\t}\n};\n\nexport const resolveMathSpeechFromChunks = async (\n\tchunks: MathAwareSpeechChunk[],\n\toptions: ResolveMathSpeechOptions = {},\n): Promise<ResolvedMathSpeech> => {\n\tif (!chunks.some((chunk) => chunk.type === \"math\")) {\n\t\treturn {\n\t\t\tspeechText: normalizeTextForSpeech(\n\t\t\t\tchunks\n\t\t\t\t\t.map((chunk) =>\n\t\t\t\t\t\tchunk.type === \"text\" ? chunk.text : chunk.fallbackText,\n\t\t\t\t\t)\n\t\t\t\t\t.join(\" \"),\n\t\t\t),\n\t\t\tusedMathSpeech: false,\n\t\t\tusedFallback: false,\n\t\t};\n\t}\n\n\tlet sre: SpeechRuleEngineApi | null = null;\n\tlet usedMathSpeech = false;\n\tlet usedFallback = false;\n\tconst loadSre = options.loadSre || defaultLoadSre;\n\tconst speechParts: string[] = [];\n\n\tfor (const chunk of chunks) {\n\t\tif (chunk.type === \"text\") {\n\t\t\tspeechParts.push(chunk.text);\n\t\t\tcontinue;\n\t\t}\n\t\ttry {\n\t\t\tif (!sre) {\n\t\t\t\tsre = await loadSre();\n\t\t\t}\n\t\t\tconst speech = normalizeTextForSpeech(\n\t\t\t\tawait toSpeechWithSreSettings(\n\t\t\t\t\tsre,\n\t\t\t\t\tchunk.mathml,\n\t\t\t\t\toptions.language,\n\t\t\t\t\t\"none\",\n\t\t\t\t\toptions.mathSpeech,\n\t\t\t\t),\n\t\t\t);\n\t\t\tif (speech) {\n\t\t\t\tspeechParts.push(speech);\n\t\t\t\tusedMathSpeech = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tusedFallback = true;\n\t\t\tspeechParts.push(chunk.fallbackText);\n\t\t} catch (error) {\n\t\t\tusedFallback = true;\n\t\t\tconsole.debug(\n\t\t\t\t\"[TTSService] Math speech generation failed; using visible fallback\",\n\t\t\t\t{\n\t\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t\t},\n\t\t\t);\n\t\t\tspeechParts.push(chunk.fallbackText);\n\t\t}\n\t}\n\n\t// Generated-SSML path: only meaningful for a single math chunk (the runtime\n\t// composes one chunk per equation). Computed after the plain pass so the\n\t// markup: \"none\" `speechText` above is unchanged. The \"none\" → \"ssml\"\n\t// engine reconfiguration happens sequentially within this call.\n\tconst speechText = normalizeTextForSpeech(speechParts.join(\" \"));\n\tlet ssml: string | undefined;\n\tif (\n\t\toptions.produceSsml &&\n\t\tsre &&\n\t\tusedMathSpeech &&\n\t\tchunks.length === 1 &&\n\t\tchunks[0].type === \"math\"\n\t) {\n\t\tconst generated = await generateMathSsml(\n\t\t\tsre,\n\t\t\tchunks[0].mathml,\n\t\t\toptions.language,\n\t\t\toptions.mathSpeech,\n\t\t);\n\t\tssml = generated ?? undefined;\n\t}\n\n\treturn {\n\t\tspeechText,\n\t\tusedMathSpeech,\n\t\tusedFallback,\n\t\tssml,\n\t};\n};\n"]}

package/dist/services/tts/mathml-sanitization.d.ts

@@ -0,0 +1 @@
+export declare const canonicalizeMathML: (input: string) => string | null;

package/dist/services/tts/mathml-sanitization.js

@@ -0,0 +1,170 @@
+const MATHML_NAMESPACE = "http://www.w3.org/1998/Math/MathML";
+const ALLOWED_MATHML_ELEMENTS = new Set([
+    "math",
+    "maction",
+    "menclose",
+    "merror",
+    "mfenced",
+    "mfrac",
+    "mi",
+    "mmultiscripts",
+    "mn",
+    "mo",
+    "mover",
+    "mpadded",
+    "mphantom",
+    "mprescripts",
+    "mroot",
+    "mrow",
+    "ms",
+    "mspace",
+    "msqrt",
+    "mstyle",
+    "msub",
+    "msubsup",
+    "msup",
+    "mtable",
+    "mtd",
+    "mtext",
+    "mtr",
+    "munder",
+    "munderover",
+    "none",
+    "semantics",
+    "annotation",
+    "annotation-xml",
+]);
+const ALLOWED_ATTRIBUTES = new Set([
+    "accent",
+    "accentunder",
+    "align",
+    "bevelled",
+    "class",
+    "close",
+    "columnalign",
+    "columnlines",
+    "columnspacing",
+    "columnspan",
+    "denomalign",
+    "depth",
+    "dir",
+    "display",
+    "encoding",
+    "fence",
+    "height",
+    "href",
+    "id",
+    "largeop",
+    "length",
+    "linethickness",
+    "lspace",
+    "mathbackground",
+    "mathcolor",
+    "mathsize",
+    "mathvariant",
+    "maxsize",
+    "minsize",
+    "movablelimits",
+    "notation",
+    "numalign",
+    "open",
+    "rowalign",
+    "rowlines",
+    "rowspacing",
+    "rowspan",
+    "rspace",
+    "scriptlevel",
+    "scriptminsize",
+    "scriptsizemultiplier",
+    "selection",
+    "separator",
+    "separators",
+    "stretchy",
+    "subscriptshift",
+    "supscriptshift",
+    "symmetric",
+    "width",
+    "xmlns",
+    "xml:lang",
+]);
+const escapeText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const escapeAttribute = (value) => escapeText(value).replace(/"/g, "&quot;");
+const isUnsafeAttribute = (name, value) => {
+    const lowerName = name.toLowerCase();
+    const lowerValue = value.trim().toLowerCase();
+    if (lowerName.startsWith("on"))
+        return true;
+    if (!ALLOWED_ATTRIBUTES.has(lowerName))
+        return true;
+    if (lowerValue.includes("javascript:"))
+        return true;
+    if (lowerValue.includes("data:text/html"))
+        return true;
+    return false;
+};
+const isAllowedMathElement = (element) => {
+    const localName = element.localName.toLowerCase();
+    if (!ALLOWED_MATHML_ELEMENTS.has(localName))
+        return false;
+    const namespace = element.namespaceURI;
+    return (!namespace ||
+        namespace === MATHML_NAMESPACE ||
+        namespace === "http://www.w3.org/1999/xhtml");
+};
+const serializeMathNode = (node) => {
+    if (node.nodeType === Node.TEXT_NODE) {
+        return escapeText(node.textContent || "");
+    }
+    if (node.nodeType === Node.COMMENT_NODE) {
+        return "";
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) {
+        return null;
+    }
+    const element = node;
+    if (!isAllowedMathElement(element))
+        return null;
+    const tagName = element.localName.toLowerCase();
+    const attrs = [];
+    for (const attr of Array.from(element.attributes)) {
+        const name = attr.name.toLowerCase();
+        if (isUnsafeAttribute(name, attr.value))
+            continue;
+        if (name === "xmlns" && attr.value !== MATHML_NAMESPACE)
+            return null;
+        attrs.push(`${name}="${escapeAttribute(attr.value)}"`);
+    }
+    if (tagName === "math" && !attrs.some((attr) => attr.startsWith("xmlns="))) {
+        attrs.unshift(`xmlns="${MATHML_NAMESPACE}"`);
+    }
+    const children = [];
+    for (const child of Array.from(element.childNodes)) {
+        const serialized = serializeMathNode(child);
+        if (serialized === null)
+            return null;
+        children.push(serialized);
+    }
+    const attrText = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+    return `<${tagName}${attrText}>${children.join("")}</${tagName}>`;
+};
+const parseMathML = (input) => {
+    if (typeof DOMParser !== "undefined") {
+        return new DOMParser().parseFromString(input, "application/xml");
+    }
+    return null;
+};
+export const canonicalizeMathML = (input) => {
+    const trimmed = String(input || "").trim();
+    if (!trimmed)
+        return null;
+    const parsed = parseMathML(trimmed);
+    if (!parsed)
+        return null;
+    if (parsed.getElementsByTagName("parsererror").length > 0)
+        return null;
+    const root = parsed.documentElement;
+    if (!root || root.localName.toLowerCase() !== "math")
+        return null;
+    return serializeMathNode(root);
+};
+//# sourceMappingURL=mathml-sanitization.js.map

package/dist/services/tts/mathml-sanitization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mathml-sanitization.js","sourceRoot":"","sources":["../../../src/services/tts/mathml-sanitization.ts"],"names":[],"mappings":"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","sourcesContent":["const MATHML_NAMESPACE = \"http://www.w3.org/1998/Math/MathML\";\n\nconst ALLOWED_MATHML_ELEMENTS = new Set([\n\t\"math\",\n\t\"maction\",\n\t\"menclose\",\n\t\"merror\",\n\t\"mfenced\",\n\t\"mfrac\",\n\t\"mi\",\n\t\"mmultiscripts\",\n\t\"mn\",\n\t\"mo\",\n\t\"mover\",\n\t\"mpadded\",\n\t\"mphantom\",\n\t\"mprescripts\",\n\t\"mroot\",\n\t\"mrow\",\n\t\"ms\",\n\t\"mspace\",\n\t\"msqrt\",\n\t\"mstyle\",\n\t\"msub\",\n\t\"msubsup\",\n\t\"msup\",\n\t\"mtable\",\n\t\"mtd\",\n\t\"mtext\",\n\t\"mtr\",\n\t\"munder\",\n\t\"munderover\",\n\t\"none\",\n\t\"semantics\",\n\t\"annotation\",\n\t\"annotation-xml\",\n]);\n\nconst ALLOWED_ATTRIBUTES = new Set([\n\t\"accent\",\n\t\"accentunder\",\n\t\"align\",\n\t\"bevelled\",\n\t\"class\",\n\t\"close\",\n\t\"columnalign\",\n\t\"columnlines\",\n\t\"columnspacing\",\n\t\"columnspan\",\n\t\"denomalign\",\n\t\"depth\",\n\t\"dir\",\n\t\"display\",\n\t\"encoding\",\n\t\"fence\",\n\t\"height\",\n\t\"href\",\n\t\"id\",\n\t\"largeop\",\n\t\"length\",\n\t\"linethickness\",\n\t\"lspace\",\n\t\"mathbackground\",\n\t\"mathcolor\",\n\t\"mathsize\",\n\t\"mathvariant\",\n\t\"maxsize\",\n\t\"minsize\",\n\t\"movablelimits\",\n\t\"notation\",\n\t\"numalign\",\n\t\"open\",\n\t\"rowalign\",\n\t\"rowlines\",\n\t\"rowspacing\",\n\t\"rowspan\",\n\t\"rspace\",\n\t\"scriptlevel\",\n\t\"scriptminsize\",\n\t\"scriptsizemultiplier\",\n\t\"selection\",\n\t\"separator\",\n\t\"separators\",\n\t\"stretchy\",\n\t\"subscriptshift\",\n\t\"supscriptshift\",\n\t\"symmetric\",\n\t\"width\",\n\t\"xmlns\",\n\t\"xml:lang\",\n]);\n\nconst escapeText = (value: string): string =>\n\tvalue.replace(/&/g, \"&amp;\").replace(/</g, \"&lt;\").replace(/>/g, \"&gt;\");\n\nconst escapeAttribute = (value: string): string =>\n\tescapeText(value).replace(/\"/g, \"&quot;\");\n\nconst isUnsafeAttribute = (name: string, value: string): boolean => {\n\tconst lowerName = name.toLowerCase();\n\tconst lowerValue = value.trim().toLowerCase();\n\tif (lowerName.startsWith(\"on\")) return true;\n\tif (!ALLOWED_ATTRIBUTES.has(lowerName)) return true;\n\tif (lowerValue.includes(\"javascript:\")) return true;\n\tif (lowerValue.includes(\"data:text/html\")) return true;\n\treturn false;\n};\n\nconst isAllowedMathElement = (element: Element): boolean => {\n\tconst localName = element.localName.toLowerCase();\n\tif (!ALLOWED_MATHML_ELEMENTS.has(localName)) return false;\n\tconst namespace = element.namespaceURI;\n\treturn (\n\t\t!namespace ||\n\t\tnamespace === MATHML_NAMESPACE ||\n\t\tnamespace === \"http://www.w3.org/1999/xhtml\"\n\t);\n};\n\nconst serializeMathNode = (node: Node): string | null => {\n\tif (node.nodeType === Node.TEXT_NODE) {\n\t\treturn escapeText(node.textContent || \"\");\n\t}\n\tif (node.nodeType === Node.COMMENT_NODE) {\n\t\treturn \"\";\n\t}\n\tif (node.nodeType !== Node.ELEMENT_NODE) {\n\t\treturn null;\n\t}\n\tconst element = node as Element;\n\tif (!isAllowedMathElement(element)) return null;\n\tconst tagName = element.localName.toLowerCase();\n\tconst attrs: string[] = [];\n\tfor (const attr of Array.from(element.attributes)) {\n\t\tconst name = attr.name.toLowerCase();\n\t\tif (isUnsafeAttribute(name, attr.value)) continue;\n\t\tif (name === \"xmlns\" && attr.value !== MATHML_NAMESPACE) return null;\n\t\tattrs.push(`${name}=\"${escapeAttribute(attr.value)}\"`);\n\t}\n\tif (tagName === \"math\" && !attrs.some((attr) => attr.startsWith(\"xmlns=\"))) {\n\t\tattrs.unshift(`xmlns=\"${MATHML_NAMESPACE}\"`);\n\t}\n\tconst children: string[] = [];\n\tfor (const child of Array.from(element.childNodes)) {\n\t\tconst serialized = serializeMathNode(child);\n\t\tif (serialized === null) return null;\n\t\tchildren.push(serialized);\n\t}\n\tconst attrText = attrs.length > 0 ? ` ${attrs.join(\" \")}` : \"\";\n\treturn `<${tagName}${attrText}>${children.join(\"\")}</${tagName}>`;\n};\n\nconst parseMathML = (input: string): Document | null => {\n\tif (typeof DOMParser !== \"undefined\") {\n\t\treturn new DOMParser().parseFromString(input, \"application/xml\");\n\t}\n\treturn null;\n};\n\nexport const canonicalizeMathML = (input: string): string | null => {\n\tconst trimmed = String(input || \"\").trim();\n\tif (!trimmed) return null;\n\tconst parsed = parseMathML(trimmed);\n\tif (!parsed) return null;\n\tif (parsed.getElementsByTagName(\"parsererror\").length > 0) return null;\n\tconst root = parsed.documentElement;\n\tif (!root || root.localName.toLowerCase() !== \"math\") return null;\n\treturn serializeMathNode(root);\n};\n"]}

package/dist/services/tts/ssml/spoken-text.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared SSML → spoken-text extractor.
+ *
+ * Strips SSML markup to the words a TTS engine would actually voice, while
+ * recording a `rawToSpokenOffsetMap` from raw-SSML character offsets to
+ * normalized spoken-text offsets. This is the single source of truth for SSML
+ * stripping used by:
+ *   - the catalog span aligner (`catalog-span-alignment.ts`),
+ *   - the math speech tokenizer (`math-alignment/speech-tokenizer.ts`),
+ *   - the runtime generated-speech path (PIE-623).
+ *
+ * Keeping one implementation guarantees provider word-boundary offsets (which
+ * are into the raw SSML string) map to the same spoken text on every path.
+ *
+ * Tag handling:
+ *   - Structural tags (`speak`, `p`, `s`, `emphasis`, `prosody`, `say-as`,
+ *     `voice`, `lang`) are transparent; their text content flows through.
+ *     `p`/`s` open tags inject a word boundary space.
+ *   - `break` injects a space (a pause is a word boundary).
+ *   - `sub alias="…"` substitutes the alias text (and skips the original).
+ *     `sub` with no alias marks the content unsupported for word tracking.
+ *   - Semantic tags that change *what* is spoken without leaving trackable
+ *     text (`audio`, `phoneme`) mark the content unsupported.
+ *   - Any other unknown element marks the content unsupported (degrade to
+ *     coarse region highlighting rather than mis-track).
+ */
+export interface ExtractedSpokenText {
+    spokenText: string;
+    rawToSpokenOffsetMap: Map<number, number>;
+    unsupportedSemantic: boolean;
+    hasMarkup: boolean;
+}
+export declare const extractSpokenText: (speechText: string) => ExtractedSpokenText;

package/dist/services/tts/ssml/spoken-text.js

@@ -0,0 +1,159 @@
+import { normalizeTextForSpeech } from "../text-processing.js";
+const STRUCTURAL_SSML_TAGS = new Set([
+    "speak",
+    "p",
+    "s",
+    "emphasis",
+    "prosody",
+    "say-as",
+    "voice",
+    "lang",
+]);
+const UNSUPPORTED_SEMANTIC_SSML_TAGS = new Set(["audio", "phoneme"]);
+const decodeXmlEntities = (value) => value
+    .replace(/"/g, '"')
+    .replace(/'/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&nbsp;/g, "\u00a0")
+    .replace(/&#160;/g, "\u00a0")
+    .replace(/&amp;/g, "&");
+const appendSourceText = (chars, value, rawOffset) => {
+    for (let i = 0; i < value.length; i++) {
+        chars.push({
+            char: value[i],
+            rawOffset: rawOffset === null ? null : rawOffset + i,
+        });
+    }
+};
+const appendDecodedXmlEntity = (chars, source, rawOffset) => {
+    const match = source
+        .slice(rawOffset)
+        .match(/^&(quot|apos|lt|gt|nbsp|amp|#160);/i);
+    if (!match)
+        return 0;
+    appendSourceText(chars, decodeXmlEntities(match[0]), rawOffset);
+    return match[0].length;
+};
+const appendSpace = (chars) => {
+    chars.push({ char: " ", rawOffset: null });
+};
+const normalizeSourceChars = (chars) => {
+    const rawToSpokenOffsetMap = new Map();
+    const out = [];
+    let lastWasWhitespace = true;
+    for (const sourceChar of chars) {
+        const isWhitespace = /\s/.test(sourceChar.char);
+        if (isWhitespace) {
+            if (!lastWasWhitespace && out.length > 0) {
+                out.push(" ");
+                if (sourceChar.rawOffset !== null) {
+                    rawToSpokenOffsetMap.set(sourceChar.rawOffset, out.length - 1);
+                }
+            }
+            lastWasWhitespace = true;
+            continue;
+        }
+        out.push(sourceChar.char);
+        if (sourceChar.rawOffset !== null) {
+            rawToSpokenOffsetMap.set(sourceChar.rawOffset, out.length - 1);
+        }
+        lastWasWhitespace = false;
+    }
+    while (out.length > 0 && out[out.length - 1] === " ") {
+        out.pop();
+    }
+    // Drop any raw→spoken entries that now point past the trimmed end; otherwise
+    // a boundary at a trailing space would map to an out-of-range spoken offset.
+    for (const [rawOffset, spokenOffset] of rawToSpokenOffsetMap) {
+        if (spokenOffset >= out.length)
+            rawToSpokenOffsetMap.delete(rawOffset);
+    }
+    return { text: out.join(""), rawToSpokenOffsetMap };
+};
+const getTagName = (tagSource) => {
+    const match = tagSource.match(/^<\/?\s*([A-Za-z0-9:-]+)/);
+    return match?.[1]?.toLowerCase() || "";
+};
+const getAttribute = (tagSource, name) => {
+    const pattern = new RegExp(`${name}\\s*=\\s*("([^"]*)"|'([^']*)')`, "i");
+    const match = tagSource.match(pattern);
+    return decodeXmlEntities(match?.[2] ?? match?.[3] ?? "") || null;
+};
+export const extractSpokenText = (speechText) => {
+    const sourceChars = [];
+    let unsupportedSemantic = false;
+    let hasMarkup = false;
+    let index = 0;
+    while (index < speechText.length) {
+        const char = speechText[index];
+        if (char !== "<") {
+            if (char === "&") {
+                const consumed = appendDecodedXmlEntity(sourceChars, speechText, index);
+                if (consumed > 0) {
+                    index += consumed;
+                    continue;
+                }
+            }
+            appendSourceText(sourceChars, char, index);
+            index++;
+            continue;
+        }
+        const closeIndex = speechText.indexOf(">", index + 1);
+        if (closeIndex < 0) {
+            appendSourceText(sourceChars, char, index);
+            index++;
+            continue;
+        }
+        hasMarkup = true;
+        const tagSource = speechText.slice(index, closeIndex + 1);
+        const tagName = getTagName(tagSource);
+        const isClosing = /^<\s*\//.test(tagSource);
+        const isSelfClosing = /\/\s*>$/.test(tagSource);
+        if (!isClosing && tagName === "sub") {
+            const alias = getAttribute(tagSource, "alias");
+            if (!alias) {
+                unsupportedSemantic = true;
+                index = closeIndex + 1;
+                continue;
+            }
+            appendSourceText(sourceChars, alias, null);
+            const closingSub = speechText
+                .toLowerCase()
+                .indexOf("</sub>", closeIndex + 1);
+            index = closingSub >= 0 ? closingSub + "</sub>".length : closeIndex + 1;
+            continue;
+        }
+        if (!isClosing && tagName === "break") {
+            appendSpace(sourceChars);
+            index = closeIndex + 1;
+            continue;
+        }
+        if (!isClosing && UNSUPPORTED_SEMANTIC_SSML_TAGS.has(tagName)) {
+            unsupportedSemantic = true;
+            if (isSelfClosing) {
+                index = closeIndex + 1;
+                continue;
+            }
+        }
+        if (tagName &&
+            !STRUCTURAL_SSML_TAGS.has(tagName) &&
+            !UNSUPPORTED_SEMANTIC_SSML_TAGS.has(tagName) &&
+            tagName !== "break" &&
+            tagName !== "sub") {
+            unsupportedSemantic = true;
+        }
+        if (!isClosing && (tagName === "p" || tagName === "s")) {
+            appendSpace(sourceChars);
+        }
+        index = closeIndex + 1;
+    }
+    const normalized = normalizeSourceChars(sourceChars);
+    return {
+        spokenText: normalizeTextForSpeech(normalized.text),
+        rawToSpokenOffsetMap: normalized.rawToSpokenOffsetMap,
+        unsupportedSemantic,
+        hasMarkup,
+    };
+};
+//# sourceMappingURL=spoken-text.js.map

package/dist/services/tts/ssml/spoken-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spoken-text.js","sourceRoot":"","sources":["../../../../src/services/tts/ssml/spoken-text.ts"],"names":[],"mappings":"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","sourcesContent":["import { normalizeTextForSpeech } from \"../text-processing.js\";\n\n/**\n * Shared SSML → spoken-text extractor.\n *\n * Strips SSML markup to the words a TTS engine would actually voice, while\n * recording a `rawToSpokenOffsetMap` from raw-SSML character offsets to\n * normalized spoken-text offsets. This is the single source of truth for SSML\n * stripping used by:\n *   - the catalog span aligner (`catalog-span-alignment.ts`),\n *   - the math speech tokenizer (`math-alignment/speech-tokenizer.ts`),\n *   - the runtime generated-speech path (PIE-623).\n *\n * Keeping one implementation guarantees provider word-boundary offsets (which\n * are into the raw SSML string) map to the same spoken text on every path.\n *\n * Tag handling:\n *   - Structural tags (`speak`, `p`, `s`, `emphasis`, `prosody`, `say-as`,\n *     `voice`, `lang`) are transparent; their text content flows through.\n *     `p`/`s` open tags inject a word boundary space.\n *   - `break` injects a space (a pause is a word boundary).\n *   - `sub alias=\"…\"` substitutes the alias text (and skips the original).\n *     `sub` with no alias marks the content unsupported for word tracking.\n *   - Semantic tags that change *what* is spoken without leaving trackable\n *     text (`audio`, `phoneme`) mark the content unsupported.\n *   - Any other unknown element marks the content unsupported (degrade to\n *     coarse region highlighting rather than mis-track).\n */\nexport interface ExtractedSpokenText {\n\tspokenText: string;\n\trawToSpokenOffsetMap: Map<number, number>;\n\tunsupportedSemantic: boolean;\n\thasMarkup: boolean;\n}\n\ninterface SourceChar {\n\tchar: string;\n\trawOffset: number | null;\n}\n\nconst STRUCTURAL_SSML_TAGS = new Set([\n\t\"speak\",\n\t\"p\",\n\t\"s\",\n\t\"emphasis\",\n\t\"prosody\",\n\t\"say-as\",\n\t\"voice\",\n\t\"lang\",\n]);\n\nconst UNSUPPORTED_SEMANTIC_SSML_TAGS = new Set([\"audio\", \"phoneme\"]);\n\nconst decodeXmlEntities = (value: string): string =>\n\tvalue\n\t\t.replace(/&quot;/g, '\"')\n\t\t.replace(/&apos;/g, \"'\")\n\t\t.replace(/&lt;/g, \"<\")\n\t\t.replace(/&gt;/g, \">\")\n\t\t.replace(/&nbsp;/g, \"\\u00a0\")\n\t\t.replace(/&#160;/g, \"\\u00a0\")\n\t\t.replace(/&amp;/g, \"&\");\n\nconst appendSourceText = (\n\tchars: SourceChar[],\n\tvalue: string,\n\trawOffset: number | null,\n): void => {\n\tfor (let i = 0; i < value.length; i++) {\n\t\tchars.push({\n\t\t\tchar: value[i],\n\t\t\trawOffset: rawOffset === null ? null : rawOffset + i,\n\t\t});\n\t}\n};\n\nconst appendDecodedXmlEntity = (\n\tchars: SourceChar[],\n\tsource: string,\n\trawOffset: number,\n): number => {\n\tconst match = source\n\t\t.slice(rawOffset)\n\t\t.match(/^&(quot|apos|lt|gt|nbsp|amp|#160);/i);\n\tif (!match) return 0;\n\tappendSourceText(chars, decodeXmlEntities(match[0]), rawOffset);\n\treturn match[0].length;\n};\n\nconst appendSpace = (chars: SourceChar[]): void => {\n\tchars.push({ char: \" \", rawOffset: null });\n};\n\nconst normalizeSourceChars = (\n\tchars: SourceChar[],\n): { text: string; rawToSpokenOffsetMap: Map<number, number> } => {\n\tconst rawToSpokenOffsetMap = new Map<number, number>();\n\tconst out: string[] = [];\n\tlet lastWasWhitespace = true;\n\n\tfor (const sourceChar of chars) {\n\t\tconst isWhitespace = /\\s/.test(sourceChar.char);\n\t\tif (isWhitespace) {\n\t\t\tif (!lastWasWhitespace && out.length > 0) {\n\t\t\t\tout.push(\" \");\n\t\t\t\tif (sourceChar.rawOffset !== null) {\n\t\t\t\t\trawToSpokenOffsetMap.set(sourceChar.rawOffset, out.length - 1);\n\t\t\t\t}\n\t\t\t}\n\t\t\tlastWasWhitespace = true;\n\t\t\tcontinue;\n\t\t}\n\t\tout.push(sourceChar.char);\n\t\tif (sourceChar.rawOffset !== null) {\n\t\t\trawToSpokenOffsetMap.set(sourceChar.rawOffset, out.length - 1);\n\t\t}\n\t\tlastWasWhitespace = false;\n\t}\n\n\twhile (out.length > 0 && out[out.length - 1] === \" \") {\n\t\tout.pop();\n\t}\n\n\t// Drop any raw→spoken entries that now point past the trimmed end; otherwise\n\t// a boundary at a trailing space would map to an out-of-range spoken offset.\n\tfor (const [rawOffset, spokenOffset] of rawToSpokenOffsetMap) {\n\t\tif (spokenOffset >= out.length) rawToSpokenOffsetMap.delete(rawOffset);\n\t}\n\n\treturn { text: out.join(\"\"), rawToSpokenOffsetMap };\n};\n\nconst getTagName = (tagSource: string): string => {\n\tconst match = tagSource.match(/^<\\/?\\s*([A-Za-z0-9:-]+)/);\n\treturn match?.[1]?.toLowerCase() || \"\";\n};\n\nconst getAttribute = (tagSource: string, name: string): string | null => {\n\tconst pattern = new RegExp(`${name}\\\\s*=\\\\s*(\"([^\"]*)\"|'([^']*)')`, \"i\");\n\tconst match = tagSource.match(pattern);\n\treturn decodeXmlEntities(match?.[2] ?? match?.[3] ?? \"\") || null;\n};\n\nexport const extractSpokenText = (speechText: string): ExtractedSpokenText => {\n\tconst sourceChars: SourceChar[] = [];\n\tlet unsupportedSemantic = false;\n\tlet hasMarkup = false;\n\tlet index = 0;\n\n\twhile (index < speechText.length) {\n\t\tconst char = speechText[index];\n\t\tif (char !== \"<\") {\n\t\t\tif (char === \"&\") {\n\t\t\t\tconst consumed = appendDecodedXmlEntity(sourceChars, speechText, index);\n\t\t\t\tif (consumed > 0) {\n\t\t\t\t\tindex += consumed;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t}\n\t\t\tappendSourceText(sourceChars, char, index);\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst closeIndex = speechText.indexOf(\">\", index + 1);\n\t\tif (closeIndex < 0) {\n\t\t\tappendSourceText(sourceChars, char, index);\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\thasMarkup = true;\n\t\tconst tagSource = speechText.slice(index, closeIndex + 1);\n\t\tconst tagName = getTagName(tagSource);\n\t\tconst isClosing = /^<\\s*\\//.test(tagSource);\n\t\tconst isSelfClosing = /\\/\\s*>$/.test(tagSource);\n\n\t\tif (!isClosing && tagName === \"sub\") {\n\t\t\tconst alias = getAttribute(tagSource, \"alias\");\n\t\t\tif (!alias) {\n\t\t\t\tunsupportedSemantic = true;\n\t\t\t\tindex = closeIndex + 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tappendSourceText(sourceChars, alias, null);\n\t\t\tconst closingSub = speechText\n\t\t\t\t.toLowerCase()\n\t\t\t\t.indexOf(\"</sub>\", closeIndex + 1);\n\t\t\tindex = closingSub >= 0 ? closingSub + \"</sub>\".length : closeIndex + 1;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (!isClosing && tagName === \"break\") {\n\t\t\tappendSpace(sourceChars);\n\t\t\tindex = closeIndex + 1;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (!isClosing && UNSUPPORTED_SEMANTIC_SSML_TAGS.has(tagName)) {\n\t\t\tunsupportedSemantic = true;\n\t\t\tif (isSelfClosing) {\n\t\t\t\tindex = closeIndex + 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\n\t\tif (\n\t\t\ttagName &&\n\t\t\t!STRUCTURAL_SSML_TAGS.has(tagName) &&\n\t\t\t!UNSUPPORTED_SEMANTIC_SSML_TAGS.has(tagName) &&\n\t\t\ttagName !== \"break\" &&\n\t\t\ttagName !== \"sub\"\n\t\t) {\n\t\t\tunsupportedSemantic = true;\n\t\t}\n\n\t\tif (!isClosing && (tagName === \"p\" || tagName === \"s\")) {\n\t\t\tappendSpace(sourceChars);\n\t\t}\n\t\tindex = closeIndex + 1;\n\t}\n\n\tconst normalized = normalizeSourceChars(sourceChars);\n\treturn {\n\t\tspokenText: normalizeTextForSpeech(normalized.text),\n\t\trawToSpokenOffsetMap: normalized.rawToSpokenOffsetMap,\n\t\tunsupportedSemantic,\n\t\thasMarkup,\n\t};\n};\n"]}

package/dist/services/tts/text-processing.d.ts

@@ -8,7 +8,10 @@ export interface TextProcessingOptions {
     boundarySpacingMode?: BoundarySpacingMode;
 }
 export declare const normalizeTextForSpeech: (text: string) => string;
+export declare const createSpeechAlignmentTokenPattern: () => RegExp;
 export declare const isElementHiddenForTTS: (element: Element) => boolean;
+export declare const isNodeHiddenForTTS: (node: Node, root?: Element | null) => boolean;
+export declare const shouldInsertWordBoundarySpace: (previousChar: string | null, nextChar: string | null, options?: TextProcessingOptions) => boolean;
 export declare const collectVisibleTextAndMap: (element: Element, options?: TextProcessingOptions) => {
     text: string;
     map: NormalizedTextMap;