@pie-players/pie-assessment-toolkit 0.3.74 → 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) => {
@@ -72,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();
@@ -82,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);
@@ -121,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) {
@@ -230,7 +232,7 @@ const textFallbackFromMathML = (mathml) => {
 const mapFallbackToAssistiveMath = (element, fallbackText) => {
     const map = new Map();
     const sourceMath = isMathJaxElement(element)
-        ? element.querySelector("mjx-assistive-mml math")
+        ? flatQuerySelector(element, "mjx-assistive-mml math")
         : null;
     if (!sourceMath)
         return map;
@@ -247,7 +249,7 @@ const mapFallbackToAssistiveMath = (element, fallbackText) => {
         }
         if (node.nodeType !== 1 || isAnnotationElement(node))
             return;
-        for (const child of Array.from(node.childNodes)) {
+        for (const child of flatTreeChildNodes(node)) {
             visit(child);
         }
     };
@@ -281,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);
         }
     };
@@ -307,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;
@@ -328,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);
@@ -358,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);
@@ -378,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

@@ -43,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 (engineOptions) => {
-    if (!sreLoadPromise) {
-        setSreStartupLocaleSource(engineOptions);
-        sreLoadPromise = import("./sre-engine.js").then(({ default: candidate }) => {
-            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
@@ -47,9 +81,9 @@ const setupSre = async (sre, language, markup, mathSpeech) => {
         ...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,
     });
@@ -80,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;
@@ -99,8 +133,7 @@ export const resolveMathSpeechFromChunks = async (chunks, options = {}) => {
     let sre = null;
     let usedMathSpeech = false;
     let usedFallback = false;
-    const loadSre = options.loadSre ||
-        (() => defaultLoadSre(normalizeSREMathSpeechOptions(options.mathSpeech)?.engineOptions));
+    const loadSre = options.loadSre || createReadSreLoad(options.mathSpeech);
     const speechParts = [];
     for (const chunk of chunks) {
         if (chunk.type === "text") {
@@ -122,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/ssml/spoken-text.d.ts

@@ -1,29 +1,5 @@
-/**
- * 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).
- */
+/** Whether `text` is an SSML document: it opens with a `<speak>` element. */
+export declare const isSsmlDocument: (text: string) => boolean;
 export interface ExtractedSpokenText {
     spokenText: string;
     rawToSpokenOffsetMap: Map<number, number>;

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

@@ -1,4 +1,33 @@
 import { normalizeTextForSpeech } from "../text-processing.js";
+/**
+ * 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).
+ */
+const SSML_DOCUMENT = /^\s*<speak[\s/>]/i;
+/** Whether `text` is an SSML document: it opens with a `<speak>` element. */
+export const isSsmlDocument = (text) => SSML_DOCUMENT.test(text);
 const STRUCTURAL_SSML_TAGS = new Set([
     "speak",
     "p",

package/dist/services/tts/start-failure.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `code` a speak's rejection carries when speech could not start, as
+ * distinct from a failure while speaking. Read by shape: several copies of the
+ * toolkit can share a page, so an error class from one fails `instanceof` in
+ * another.
+ */
+export declare const TTS_START_FAILED_CODE = "tts-start-failed";
+/** Whether a speak rejected because speech could not start. */
+export declare function isTTSStartFailure(error: unknown): boolean;
+/** Marks `cause` as a start failure, keeping its message and stack. */
+export declare function toTTSStartFailure(cause: unknown): Error;

package/dist/services/tts/start-failure.js

@@ -0,0 +1,19 @@
+/**
+ * The `code` a speak's rejection carries when speech could not start, as
+ * distinct from a failure while speaking. Read by shape: several copies of the
+ * toolkit can share a page, so an error class from one fails `instanceof` in
+ * another.
+ */
+export const TTS_START_FAILED_CODE = "tts-start-failed";
+/** Whether a speak rejected because speech could not start. */
+export function isTTSStartFailure(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === TTS_START_FAILED_CODE);
+}
+/** Marks `cause` as a start failure, keeping its message and stack. */
+export function toTTSStartFailure(cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    error.code = TTS_START_FAILED_CODE;
+    return error;
+}

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

@@ -62,6 +62,15 @@ export declare const collectRangeTextForSpeech: (range: Range, root: Element) =>
     text: string;
     filtered: boolean;
 };
+/** The part of `textNode`'s text that `range` holds, for a node it intersects. */
+export declare const textInRange: (textNode: Text, range: Range) => string;
+/**
+ * Whether `range` holds all of `element`'s speakable text: its first and last
+ * speakable characters, which a contiguous range holding both holds everything
+ * between. An element with no speakable text, an image for one, is held when the
+ * range touches it, since no part of it can be selected alone.
+ */
+export declare const rangeHoldsSpeakableElement: (range: Range, element: Element, 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;