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

package/dist/services/tts/catalog-span-alignment.js

@@ -1,25 +1,8 @@
-import { extractSpokenText } from "./ssml/spoken-text.js";
-import { createSpeechAlignmentTokenPattern, normalizeTextForSpeech, } from "./text-processing.js";
-// Shared Unicode-aware tokenizer (see `createSpeechAlignmentTokenPattern`), so
-// accented Latin and non-Latin words tokenize the same way here as in the math
-// speech tokenizer. LIMITATION (i18n): the phrase table below is still English,
-// so multi-word operator phrases ("plus or minus", "divided by") only align for
-// English speech; other locales degrade to coarse region highlighting. A fresh
-// pattern per call because of the global flag's mutable `lastIndex`.
-const TOKEN_PATTERN = createSpeechAlignmentTokenPattern();
-const NUMERIC_WORDS = new Map([
-    ["zero", "0"],
-    ["one", "1"],
-    ["two", "2"],
-    ["three", "3"],
-    ["four", "4"],
-    ["five", "5"],
-    ["six", "6"],
-    ["seven", "7"],
-    ["eight", "8"],
-    ["nine", "9"],
-    ["ten", "10"],
-]);
+import { tokenizeAlignmentText, tokenizeSpeechSource, } from "./math-alignment/speech-tokenizer.js";
+import { normalizeTextForSpeech } from "./text-processing.js";
+// LIMITATION (i18n): the phrase table is English, so multi-word operator
+// phrases ("plus or minus", "divided by") only align for English speech; other
+// locales degrade to coarse region highlighting.
 const SPOKEN_PHRASE_TARGETS = [
     { phrase: ["plus", "or", "minus"], visible: "±", score: 8 },
     { phrase: ["square", "root"], visible: "√", score: 8 },
@@ -36,28 +19,12 @@ const SPOKEN_PHRASE_TARGETS = [
     { phrase: ["minus"], visible: "-", score: 5 },
     { phrase: ["plus"], visible: "+", score: 5 },
 ];
-const tokenize = (text) => {
-    const tokens = [];
-    for (const match of text.matchAll(TOKEN_PATTERN)) {
-        const value = match[0];
-        const start = match.index ?? 0;
-        tokens.push({
-            text: value,
-            normalized: value.toLowerCase(),
-            start,
-            end: start + value.length,
-        });
-    }
-    return tokens;
-};
-const normalizedTokenValue = (token) => NUMERIC_WORDS.get(token.normalized) || token.normalized;
 const createCandidates = (spokenTokens, visibleTokens) => {
     const candidates = [];
     for (let spokenIndex = 0; spokenIndex < spokenTokens.length; spokenIndex++) {
         for (let visibleIndex = 0; visibleIndex < visibleTokens.length; visibleIndex++) {
-            const spokenValue = normalizedTokenValue(spokenTokens[spokenIndex]);
-            const visibleValue = normalizedTokenValue(visibleTokens[visibleIndex]);
-            if (spokenValue === visibleValue) {
+            if (spokenTokens[spokenIndex].normalized ===
+                visibleTokens[visibleIndex].normalized) {
                 candidates.push({
                     spokenStartToken: spokenIndex,
                     spokenEndToken: spokenIndex + 1,
@@ -74,7 +41,9 @@ const createCandidates = (spokenTokens, visibleTokens) => {
                 continue;
             }
             for (let visibleIndex = 0; visibleIndex < visibleTokens.length; visibleIndex++) {
-                if (visibleTokens[visibleIndex].normalized !== phraseTarget.visible) {
+                // Glyph targets compare against the visible text as written, so a
+                // visible number word ("two") never stands in for the digit "2".
+                if (visibleTokens[visibleIndex].text !== phraseTarget.visible) {
                     continue;
                 }
                 candidates.push({
@@ -151,21 +120,20 @@ const scoreConfidence = (anchors, spokenTokens, visibleTokens) => {
     return Math.min(1, tokenCoverage * averageScore);
 };
 export const createCatalogSpanAlignment = (args) => {
-    const extracted = extractSpokenText(args.speechText);
+    const speech = tokenizeSpeechSource({ speechText: args.speechText });
     const visibleText = normalizeTextForSpeech(args.visibleText);
-    const spokenText = extracted.spokenText;
-    const spokenTokens = tokenize(spokenText);
-    const visibleTokens = tokenize(visibleText);
-    const anchors = extracted.unsupportedSemantic
+    const spokenTokens = speech.tokens;
+    const visibleTokens = tokenizeAlignmentText(visibleText);
+    const anchors = speech.unsupportedSemantic
         ? []
         : computeAnchors(spokenTokens, visibleTokens);
     const confidence = scoreConfidence(anchors, spokenTokens, visibleTokens);
-    const isExact = spokenText === visibleText && spokenText.length > 0;
+    const isExact = speech.spokenText === visibleText && speech.spokenText.length > 0;
     const hasShortSingleExactAnchor = anchors.length === 1 &&
         anchors[0].score === 10 &&
         spokenTokens.length <= 2 &&
         visibleTokens.length <= 2;
-    const playbackMode = extracted.unsupportedSemantic
+    const playbackMode = speech.unsupportedSemantic
         ? "region-fallback"
         : isExact
             ? "exact-word"
@@ -174,107 +142,14 @@ export const createCatalogSpanAlignment = (args) => {
                     ? "anchor-span"
                     : "region-fallback"
                 : "region-fallback";
-    const boundaryOffsetMode = extracted.unsupportedSemantic
-        ? "unsupported"
-        : extracted.hasMarkup
-            ? "raw-ssml"
-            : "plain-spoken-text";
     return {
-        speechText: args.speechText,
-        spokenText,
+        speech,
         visibleText,
         playbackMode,
-        boundaryOffsetMode,
         anchors,
         confidence,
-        spokenTokens,
-        visibleTokens,
-        rawToSpokenOffsetMap: extracted.rawToSpokenOffsetMap,
-    };
-};
-const findTokenAtOffset = (tokens, offset) => tokens.find((token) => token.start <= offset && offset < token.end) || null;
-const normalizeBoundaryWord = (word) => {
-    if (!word)
-        return null;
-    if (/^<[^>]+>$/.test(word.trim()))
-        return null;
-    const token = tokenize(word)[0];
-    if (!token)
-        return null;
-    return NUMERIC_WORDS.get(token.normalized) || token.normalized;
-};
-const candidateMatchesBoundaryWord = (alignment, candidate, boundaryWord) => {
-    const normalizedBoundary = normalizeBoundaryWord(boundaryWord);
-    if (!candidate || !normalizedBoundary)
-        return false;
-    const token = findTokenAtOffset(alignment.spokenTokens, candidate.start);
-    if (!token)
-        return false;
-    return normalizedTokenValue(token) === normalizedBoundary;
-};
-const mapRawOffsetToSpokenOffset = (alignment, position) => {
-    const direct = alignment.rawToSpokenOffsetMap.get(position);
-    if (direct !== undefined)
-        return direct;
-    for (let offset = position; offset < alignment.speechText.length; offset++) {
-        const mapped = alignment.rawToSpokenOffsetMap.get(offset);
-        if (mapped !== undefined)
-            return mapped;
-        if (alignment.speechText[offset] === ">")
-            break;
-    }
-    return null;
-};
-const resolveRawBoundaryOffset = (alignment, position, safeLength) => {
-    const mappedStart = mapRawOffsetToSpokenOffset(alignment, position);
-    if (mappedStart === null)
-        return null;
-    const mappedEnd = mapRawOffsetToSpokenOffset(alignment, Math.max(position, position + safeLength - 1));
-    const token = findTokenAtOffset(alignment.spokenTokens, mappedStart);
-    const mappedLength = mappedEnd !== null && mappedEnd >= mappedStart
-        ? mappedEnd - mappedStart + 1
-        : token
-            ? token.end - mappedStart
-            : safeLength;
-    return { start: mappedStart, length: Math.max(1, mappedLength) };
-};
-const resolvePlainBoundaryOffset = (alignment, position, safeLength) => {
-    if (position < 0 || position >= alignment.spokenText.length)
-        return null;
-    const token = findTokenAtOffset(alignment.spokenTokens, position);
-    if (!token)
-        return null;
-    return {
-        start: position,
-        length: Math.min(safeLength, token.end - position),
     };
 };
-export const resolveSpokenBoundaryOffset = (alignment, position, length = 1, boundaryWord) => {
-    if (alignment.boundaryOffsetMode === "unsupported" ||
-        !Number.isFinite(position)) {
-        return null;
-    }
-    const safeLength = Math.max(1, Number.isFinite(length) ? length : 1);
-    if (boundaryWord && /^<[^>]+>$/.test(boundaryWord.trim()))
-        return null;
-    if (alignment.boundaryOffsetMode === "raw-ssml") {
-        const rawCandidate = resolveRawBoundaryOffset(alignment, position, safeLength);
-        const plainCandidate = resolvePlainBoundaryOffset(alignment, position, safeLength);
-        if (boundaryWord) {
-            if (candidateMatchesBoundaryWord(alignment, rawCandidate, boundaryWord)) {
-                return rawCandidate;
-            }
-            if (candidateMatchesBoundaryWord(alignment, plainCandidate, boundaryWord)) {
-                return plainCandidate;
-            }
-            if (normalizeBoundaryWord(boundaryWord))
-                return null;
-        }
-        return rawCandidate || plainCandidate;
-    }
-    return (resolvePlainBoundaryOffset(alignment, position, safeLength) ||
-        resolveRawBoundaryOffset(alignment, position, safeLength));
-};
 export const resolveVisibleSpanForBoundary = (alignment, spokenOffset) => {
     if (alignment.playbackMode === "region-fallback")
         return null;

package/dist/services/tts/flat-tree.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The tree read-aloud walks: the flat tree, which is the tree the page renders.
+ *
+ * An element with an open shadow root contributes that root's children in place
+ * of its own light children, and a `<slot>` inside a shadow root contributes the
+ * nodes assigned to it, flattened through nested slots, so a host's light
+ * children are reached once, at the slot that renders them. Closed shadow roots
+ * are invisible to script, so their hosts are walked as light DOM.
+ *
+ * Toolkit chrome is skipped wherever it appears: toolbars and tool elements
+ * render their controls into open shadow roots, and descending into them would
+ * read button labels as content. So are the empty `aria-hidden` anchors the
+ * shells and the toolkit keep beside their slots, and elements whose text never
+ * renders (`style`, `script`, `noscript`, `template`).
+ *
+ * Node types are compared as the spec's numbers, so this module reads no DOM
+ * global, at import or at call time.
+ */
+export declare const isShadowRootNode: (node: Node | null | undefined) => node is ShadowRoot;
+/** Toolbars, tool elements and debug panels: chrome around content, never content. */
+export declare const isToolkitChromeElement: (element: Element) => boolean;
+/** `node`'s children in the flat tree, with skipped elements left out. */
+export declare const flatTreeChildNodes: (node: Node) => Node[];
+/**
+ * What a visitor returns: `"skip"` leaves the node's subtree out, `"stop"` ends
+ * the walk, anything else descends.
+ */
+export type FlatTreeVisitResult = "skip" | "stop" | undefined;
+/** Visits `root`'s flat-tree descendants in rendering order; `root` itself is not visited. */
+export declare const walkFlatTree: (root: Node, visit: (node: Node) => FlatTreeVisitResult) => void;
+/** `root`'s text nodes in rendering order. */
+export declare const flatTreeTextNodes: (root: Node) => Text[];
+/** `textContent` over the flat tree: shadow content in, skipped elements out. */
+export declare const flatTextContent: (root: Node) => string;
+/** Elements under `root` matching `selector`, in rendering order. */
+export declare const flatQuerySelectorAll: (root: Node, selector: string) => Element[];
+export declare const flatQuerySelector: (root: Node, selector: string) => Element | null;
+/**
+ * `node`'s parent in the flat tree: the slot rendering it, else its parent, with
+ * a shadow root standing for its host.
+ */
+export declare const flatTreeParentNode: (node: Node) => Node | null;
+export declare const flatTreeParentElement: (node: Node) => Element | null;
+/** The nearest element at or above `node` in the flat tree that matches `selector`. */
+export declare const flatTreeClosest: (node: Node, selector: string) => Element | null;
+/**
+ * `node`'s parent element, continuing from a shadow root to its host. This is the
+ * chain inheritance follows (`lang`, regions an author marks up), and for slotted
+ * content it stays in the light tree the author wrote.
+ */
+export declare const composedParentElement: (node: Node) => Element | null;
+/**
+ * The nearest element at or above `node` on the composed chain that matches
+ * `selector`, or null. With `boundary`, the climb ends after testing it.
+ */
+export declare const composedClosest: (node: Node, selector: string, boundary?: Element | null) => Element | null;
+/** `contains` across shadow boundaries: whether `node` is `container` or below it. */
+export declare const composedContains: (container: Node | null | undefined, node: Node | null | undefined) => boolean;
+/**
+ * `node`, or the shadow host above it, that lies in the tree rooted at
+ * `treeRoot`; null when `node` is not inside that tree at any depth.
+ */
+export declare const retargetToTree: (node: Node, treeRoot: Node) => Node | null;
+/**
+ * Whether the character at `offset` in `node` lies inside `range`. A live range
+ * holds nodes of one tree only, so a node in a shadow tree below it counts as
+ * inside when the range holds that tree's host whole.
+ */
+export declare const rangeHoldsTextPosition: (range: Range, node: Text, offset: number) => boolean;
+/** Whether `range` intersects `node`, counting a shadow tree below the range as {@link rangeHoldsTextPosition} does. */
+export declare const rangeIntersectsComposedNode: (range: Range, node: Node) => boolean;

package/dist/services/tts/flat-tree.js

@@ -0,0 +1,269 @@
+/**
+ * The tree read-aloud walks: the flat tree, which is the tree the page renders.
+ *
+ * An element with an open shadow root contributes that root's children in place
+ * of its own light children, and a `<slot>` inside a shadow root contributes the
+ * nodes assigned to it, flattened through nested slots, so a host's light
+ * children are reached once, at the slot that renders them. Closed shadow roots
+ * are invisible to script, so their hosts are walked as light DOM.
+ *
+ * Toolkit chrome is skipped wherever it appears: toolbars and tool elements
+ * render their controls into open shadow roots, and descending into them would
+ * read button labels as content. So are the empty `aria-hidden` anchors the
+ * shells and the toolkit keep beside their slots, and elements whose text never
+ * renders (`style`, `script`, `noscript`, `template`).
+ *
+ * Node types are compared as the spec's numbers, so this module reads no DOM
+ * global, at import or at call time.
+ */
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const DOCUMENT_FRAGMENT_NODE = 11;
+const CHROME_TAGS = new Set([
+    "pie-item-toolbar",
+    "pie-section-toolbar",
+    "pie-item-player-session-debugger",
+]);
+const CHROME_TAG_PREFIXES = ["pie-tool-", "pie-section-player-tools-"];
+const UNRENDERED_TEXT_TAGS = new Set([
+    "style",
+    "script",
+    "noscript",
+    "template",
+]);
+export const isShadowRootNode = (node) => !!node &&
+    node.nodeType === DOCUMENT_FRAGMENT_NODE &&
+    node.host?.nodeType === ELEMENT_NODE;
+/** Toolbars, tool elements and debug panels: chrome around content, never content. */
+export const isToolkitChromeElement = (element) => {
+    const tag = element.localName?.toLowerCase() || "";
+    if (CHROME_TAGS.has(tag))
+        return true;
+    return CHROME_TAG_PREFIXES.some((prefix) => tag.startsWith(prefix));
+};
+const isSkippedElement = (element) => {
+    const tag = element.localName?.toLowerCase() || "";
+    if (UNRENDERED_TEXT_TAGS.has(tag))
+        return true;
+    if (isToolkitChromeElement(element))
+        return true;
+    // A shell's anchor: an `aria-hidden` element at the top of a shadow root,
+    // there to reach the host's context and holding nothing to read.
+    return (isShadowRootNode(element.parentNode) &&
+        element.getAttribute("aria-hidden") === "true");
+};
+const slotFlattenedNodes = (slot) => {
+    if (!isShadowRootNode(slot.getRootNode?.()))
+        return null;
+    const assignedNodes = slot.assignedNodes;
+    if (typeof assignedNodes !== "function")
+        return null;
+    try {
+        return assignedNodes.call(slot, { flatten: true });
+    }
+    catch {
+        return null;
+    }
+};
+/** `node`'s children in the flat tree, with skipped elements left out. */
+export const flatTreeChildNodes = (node) => {
+    let children = node.childNodes;
+    if (node.nodeType === ELEMENT_NODE) {
+        const element = node;
+        const shadowRoot = element.shadowRoot;
+        if (shadowRoot) {
+            children = shadowRoot.childNodes;
+        }
+        else if (element.localName?.toLowerCase() === "slot") {
+            children = slotFlattenedNodes(element) ?? element.childNodes;
+        }
+    }
+    const result = [];
+    for (const child of Array.from(children || [])) {
+        if (child.nodeType === ELEMENT_NODE && isSkippedElement(child)) {
+            continue;
+        }
+        result.push(child);
+    }
+    return result;
+};
+/** Visits `root`'s flat-tree descendants in rendering order; `root` itself is not visited. */
+export const walkFlatTree = (root, visit) => {
+    const descend = (node) => {
+        for (const child of flatTreeChildNodes(node)) {
+            const result = visit(child);
+            if (result === "stop")
+                return false;
+            if (result === "skip")
+                continue;
+            if (!descend(child))
+                return false;
+        }
+        return true;
+    };
+    descend(root);
+};
+/** `root`'s text nodes in rendering order. */
+export const flatTreeTextNodes = (root) => {
+    const nodes = [];
+    walkFlatTree(root, (node) => {
+        if (node.nodeType === TEXT_NODE)
+            nodes.push(node);
+        return undefined;
+    });
+    return nodes;
+};
+/** `textContent` over the flat tree: shadow content in, skipped elements out. */
+export const flatTextContent = (root) => flatTreeTextNodes(root)
+    .map((node) => node.data)
+    .join("");
+/** Elements under `root` matching `selector`, in rendering order. */
+export const flatQuerySelectorAll = (root, selector) => {
+    const matches = [];
+    walkFlatTree(root, (node) => {
+        if (node.nodeType === ELEMENT_NODE && node.matches(selector)) {
+            matches.push(node);
+        }
+        return undefined;
+    });
+    return matches;
+};
+export const flatQuerySelector = (root, selector) => {
+    let match = null;
+    walkFlatTree(root, (node) => {
+        if (node.nodeType === ELEMENT_NODE && node.matches(selector)) {
+            match = node;
+            return "stop";
+        }
+        return undefined;
+    });
+    return match;
+};
+/**
+ * `node`'s parent in the flat tree: the slot rendering it, else its parent, with
+ * a shadow root standing for its host.
+ */
+export const flatTreeParentNode = (node) => {
+    const slot = node.assignedSlot;
+    if (slot)
+        return slot;
+    const parent = node.parentNode;
+    if (isShadowRootNode(parent))
+        return parent.host;
+    return parent;
+};
+export const flatTreeParentElement = (node) => {
+    let parent = flatTreeParentNode(node);
+    while (parent && parent.nodeType !== ELEMENT_NODE) {
+        parent = flatTreeParentNode(parent);
+    }
+    return parent;
+};
+/** The nearest element at or above `node` in the flat tree that matches `selector`. */
+export const flatTreeClosest = (node, selector) => {
+    let current = node.nodeType === ELEMENT_NODE
+        ? node
+        : flatTreeParentElement(node);
+    while (current) {
+        if (current.matches(selector))
+            return current;
+        current = flatTreeParentElement(current);
+    }
+    return null;
+};
+/**
+ * `node`'s parent element, continuing from a shadow root to its host. This is the
+ * chain inheritance follows (`lang`, regions an author marks up), and for slotted
+ * content it stays in the light tree the author wrote.
+ */
+export const composedParentElement = (node) => {
+    if (node.parentElement)
+        return node.parentElement;
+    const parent = node.parentNode;
+    return isShadowRootNode(parent) ? parent.host : null;
+};
+/**
+ * The nearest element at or above `node` on the composed chain that matches
+ * `selector`, or null. With `boundary`, the climb ends after testing it.
+ */
+export const composedClosest = (node, selector, boundary) => {
+    let current = node.nodeType === ELEMENT_NODE
+        ? node
+        : composedParentElement(node);
+    while (current) {
+        if (current.matches(selector))
+            return current;
+        if (boundary && current === boundary)
+            return null;
+        current = composedParentElement(current);
+    }
+    return null;
+};
+/** `contains` across shadow boundaries: whether `node` is `container` or below it. */
+export const composedContains = (container, node) => {
+    if (!container || !node)
+        return false;
+    let current = node;
+    while (current) {
+        if (current === container || container.contains(current))
+            return true;
+        const root = current.getRootNode?.();
+        current = isShadowRootNode(root) ? root.host : null;
+    }
+    return false;
+};
+/**
+ * `node`, or the shadow host above it, that lies in the tree rooted at
+ * `treeRoot`; null when `node` is not inside that tree at any depth.
+ */
+export const retargetToTree = (node, treeRoot) => {
+    let current = node;
+    while (current) {
+        const root = current.getRootNode?.();
+        if (root === treeRoot)
+            return current;
+        current = isShadowRootNode(root) ? root.host : null;
+    }
+    return null;
+};
+/**
+ * Whether the character at `offset` in `node` lies inside `range`. A live range
+ * holds nodes of one tree only, so a node in a shadow tree below it counts as
+ * inside when the range holds that tree's host whole.
+ */
+export const rangeHoldsTextPosition = (range, node, offset) => {
+    try {
+        const treeRoot = range.startContainer.getRootNode?.();
+        if (!treeRoot || node.getRootNode?.() === treeRoot) {
+            return (range.comparePoint(node, offset) === 0 &&
+                range.comparePoint(node, Math.min(offset + 1, node.length)) === 0);
+        }
+        return rangeHoldsNodeWhole(range, retargetToTree(node, treeRoot));
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether `range` intersects `node`, counting a shadow tree below the range as {@link rangeHoldsTextPosition} does. */
+export const rangeIntersectsComposedNode = (range, node) => {
+    try {
+        const treeRoot = range.startContainer.getRootNode?.();
+        if (!treeRoot || node.getRootNode?.() === treeRoot) {
+            return range.intersectsNode(node);
+        }
+        return rangeHoldsNodeWhole(range, retargetToTree(node, treeRoot));
+    }
+    catch {
+        return false;
+    }
+};
+const rangeHoldsNodeWhole = (range, node) => {
+    const parent = node?.parentNode;
+    if (!node || !parent)
+        return false;
+    const index = Array.prototype.indexOf.call(parent.childNodes, node);
+    if (index < 0)
+        return false;
+    return (range.comparePoint(parent, index) === 0 &&
+        range.comparePoint(parent, index + 1) === 0);
+};

package/dist/services/tts/generated-speech/assemble-plan.d.ts

@@ -1,5 +1,5 @@
 import type { MathAwareSpeechChunk } from "../math-aware-text-processing.js";
-import { type ResolvedMathSpeech, type SREMathSpeechOptions } from "../math-speech.js";
+import { type ResolveMathSpeechOptions, type ResolvedMathSpeech, type SREMathSpeechOptions } from "../math-speech.js";
 import type { AssembledSpeech } from "./types.js";
 type MathChunk = Extract<MathAwareSpeechChunk, {
     type: "math";
@@ -13,6 +13,8 @@ export type MathSpeechResolver = (chunk: MathChunk, options: {
     language?: string;
     produceSsml?: boolean;
     mathSpeech?: SREMathSpeechOptions;
+    /** The read's one engine load, shared by its equations. */
+    loadSre?: ResolveMathSpeechOptions["loadSre"];
 }) => Promise<ResolvedMathSpeech>;
 /**
  * Assemble an anchor-free speech plan from already-collected math-aware chunks.

package/dist/services/tts/generated-speech/assemble-plan.js

@@ -1,4 +1,4 @@
-import { resolveMathSpeechFromChunks, } from "../math-speech.js";
+import { createReadSreLoad, resolveMathSpeechFromChunks, } from "../math-speech.js";
 import { normalizeTextForSpeech } from "../text-processing.js";
 import { segmentSentences as segmentTextToSentences } from "../text-segmentation.js";
 const defaultMathSpeechResolver = (chunk, options) => resolveMathSpeechFromChunks([chunk], options);
@@ -37,6 +37,7 @@ const shouldPreserveProseChunk = (chunk) => {
  */
 export const assembleGeneratedSpeech = async (args) => {
     const resolveMathSpeech = args.resolveMathSpeech ?? defaultMathSpeechResolver;
+    const loadSre = createReadSreLoad(args.mathSpeech);
     const { visibleText } = args;
     const segments = [];
     // Cursor-based span tracking:
@@ -84,6 +85,7 @@ export const assembleGeneratedSpeech = async (args) => {
             language: args.language,
             produceSsml: args.produceSsml,
             mathSpeech: args.mathSpeech,
+            loadSre,
         });
         const usedFallback = !generated.speechText;
         const spokenText = generated.speechText || chunk.fallbackText;

package/dist/services/tts/generated-speech/dom/build-dom-plan.d.ts

@@ -16,6 +16,8 @@ export interface BuildGeneratedSpeechResult {
  */
 export declare const buildGeneratedSpeechFromRoot: (args: {
     contentRoot: Element;
+    /** Limit the plan to the part of `contentRoot` this range selects. */
+    range?: Range;
     language?: string;
     mathSpeech?: SREMathSpeechOptions;
     textProcessingOptions?: TextProcessingOptions;

package/dist/services/tts/generated-speech/dom/build-dom-plan.js

@@ -17,7 +17,7 @@ const sliceVisibleMap = (map, start, end) => {
  * entry point that touches the DOM; assembly and serialization stay pure.
  */
 export const buildGeneratedSpeechFromRoot = async (args) => {
-    const extracted = collectMathAwareTextAndMap(args.contentRoot, args.textProcessingOptions);
+    const extracted = collectMathAwareTextAndMap(args.contentRoot, args.textProcessingOptions, args.range);
     const assembled = await assembleGeneratedSpeech({
         chunks: extracted.chunks,
         visibleText: extracted.visibleText,

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

@@ -7,7 +7,9 @@ export interface MathSpeechCacheOptions {
 /**
  * Build a memoized {@link MathSpeechResolver}.
  *
- * Caches only DOM-free spoken-text results keyed by
+ * Caches only DOM-free spoken-text results that SRE produced, so an equation
+ * read as its visible text after a failed engine load is resolved again on
+ * the next read. Keyed by
  * `(SRE version, locale, output mode, SRE mathSpeech options, MathML source)`.
  * Never caches DOM nodes or maps. Bounded by a simple LRU so long sessions do
  * not grow unbounded.

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

@@ -35,7 +35,9 @@ const cacheKeyFor = (language, produceSsml, mathSpeech, mathml) => `${SRE_CACHE_
 /**
  * Build a memoized {@link MathSpeechResolver}.
  *
- * Caches only DOM-free spoken-text results keyed by
+ * Caches only DOM-free spoken-text results that SRE produced, so an equation
+ * read as its visible text after a failed engine load is resolved again on
+ * the next read. Keyed by
  * `(SRE version, locale, output mode, SRE mathSpeech options, MathML source)`.
  * Never caches DOM nodes or maps. Bounded by a simple LRU so long sessions do
  * not grow unbounded.
@@ -66,6 +68,8 @@ export const createMemoizedMathSpeechResolver = (options = {}) => {
             return cached;
         }
         const resolved = await resolve(chunk, { ...opts, mathSpeech });
+        if (resolved.usedFallback)
+            return resolved;
         if (produceSsml && resolved.ssml && maxEntries > 1) {
             setCached(cacheKeyFor(opts.language, false, mathSpeech, chunk.mathml), {
                 speechText: resolved.speechText,

package/dist/services/tts/generated-speech/types.d.ts

@@ -14,7 +14,6 @@
  * without rewriting the core. The runtime binds live DOM via `DomAnchor`
  * (see `./dom/types.ts`).
  */
-export type StructuralBreakStrength = "weak" | "medium" | "strong";
 export interface ProseSegment {
     kind: "prose";
     /** Spoken words for this prose run. Identical to `visibleText` today. */
@@ -53,18 +52,7 @@ export interface MathSegment {
      */
     ssml?: string;
 }
-/**
- * A structural pause. Breaks are never standalone speakable units: the DOM
- * adapter folds them into the SSML of an adjacent speakable segment (or relies
- * on the gap between sequential per-chunk utterances). Modeled here so the
- * plan can carry pause intent for the SSML serializer.
- */
-export interface StructuralBreak {
-    kind: "break";
-    strength: StructuralBreakStrength;
-}
 export type SpeechSegment = ProseSegment | MathSegment;
-export type PlanSegment = SpeechSegment | StructuralBreak;
 /** One assembled (still anchor-free) segment plus its source chunk index. */
 export interface AssembledSegment {
     segment: SpeechSegment;