@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

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

@@ -1,5 +1,9 @@
 import { tokenizeAlignmentText, tokenizeSpeechSource, } from "./math-alignment/speech-tokenizer.js";
 import { normalizeTextForSpeech } from "./text-processing.js";
+// A spoken token equal to a visible token; phrase targets score below it.
+const EXACT_TOKEN_SCORE = 10;
+// Below this, an anchored chunk highlights its region instead of spans.
+const MIN_ANCHOR_SPAN_CONFIDENCE = 0.12;
 // 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.
@@ -29,7 +33,7 @@ const createCandidates = (spokenTokens, visibleTokens) => {
                     spokenStartToken: spokenIndex,
                     spokenEndToken: spokenIndex + 1,
                     visibleToken: visibleIndex,
-                    score: 10,
+                    score: EXACT_TOKEN_SCORE,
                 });
             }
         }
@@ -57,6 +61,9 @@ const createCandidates = (spokenTokens, visibleTokens) => {
     }
     return candidates;
 };
+// The highest-scoring chain of candidates monotonic in both spoken and visible
+// order (O(n²) DP). A gap whose spoken and visible token counts differ by more
+// than 2 pays the excess.
 const computeAnchors = (spokenTokens, visibleTokens) => {
     const candidates = createCandidates(spokenTokens, visibleTokens).sort((left, right) => spokenTokens[left.spokenStartToken].start -
         spokenTokens[right.spokenStartToken].start ||
@@ -116,7 +123,7 @@ const scoreConfidence = (anchors, spokenTokens, visibleTokens) => {
         Math.max(1, Math.min(spokenTokens.length, visibleTokens.length));
     const averageScore = anchors.reduce((total, anchor) => total + anchor.score, 0) /
         anchors.length /
-        10;
+        EXACT_TOKEN_SCORE;
     return Math.min(1, tokenCoverage * averageScore);
 };
 export const createCatalogSpanAlignment = (args) => {
@@ -130,17 +137,17 @@ export const createCatalogSpanAlignment = (args) => {
     const confidence = scoreConfidence(anchors, spokenTokens, visibleTokens);
     const isExact = speech.spokenText === visibleText && speech.spokenText.length > 0;
     const hasShortSingleExactAnchor = anchors.length === 1 &&
-        anchors[0].score === 10 &&
+        anchors[0].score === EXACT_TOKEN_SCORE &&
         spokenTokens.length <= 2 &&
         visibleTokens.length <= 2;
+    const anchorsAreTrusted = (anchors.length >= 2 || hasShortSingleExactAnchor) &&
+        confidence >= MIN_ANCHOR_SPAN_CONFIDENCE;
     const playbackMode = speech.unsupportedSemantic
         ? "region-fallback"
         : isExact
             ? "exact-word"
-            : anchors.length >= 2 || hasShortSingleExactAnchor
-                ? confidence >= 0.12
-                    ? "anchor-span"
-                    : "region-fallback"
+            : anchorsAreTrusted
+                ? "anchor-span"
                 : "region-fallback";
     return {
         speech,

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

@@ -0,0 +1,64 @@
+/**
+ * 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;
+/** `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;
+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. */
+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.
+ */
+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/dom/to-chunk-inputs.d.ts

@@ -3,8 +3,8 @@ import type { DomAnchor, GeneratedSpeechChunk } from "./types.js";
 export interface PlanToChunksOptions {
     /**
      * Playback format:
-     *   - "plain" (default): plain spoken text for every chunk (Phase A, the
-     *     stable generated-speech behavior).
+     *   - "plain" (default): plain spoken text for every chunk (the stable
+     *     generated-speech behavior).
      *   - "ssml": math chunks with SRE SSML send that SSML to the provider (with
      *     a plain fallback attached); prose chunks always stay plain.
      */

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

@@ -1,5 +1,5 @@
 /**
- * Generated-speech module (PIE-623): runtime speech composition for math items
+ * Generated-speech module: runtime speech composition for math items
  * that ship without authored SSML / `accessibilityCatalogs`.
  *
  * Layering:

package/dist/services/tts/generated-speech/index.js

@@ -1,5 +1,5 @@
 /**
- * Generated-speech module (PIE-623): runtime speech composition for math items
+ * Generated-speech module: runtime speech composition for math items
  * that ship without authored SSML / `accessibilityCatalogs`.
  *
  * Layering:

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

@@ -2,7 +2,7 @@
  * Generated-speech plan model (PURE core).
  *
  * This module is the speech-composition core for items that contain math but
- * ship without authored SSML / `accessibilityCatalogs` (PIE-623). It is
+ * ship without authored SSML / `accessibilityCatalogs`. It is
  * deliberately free of any imports from `TTSService`, the highlight renderer,
  * `HighlightCoordinator`, Svelte, or custom-element entrypoints
  * (`scripts/check-speech-composition-purity.mjs` enforces this). DOM primitive

package/dist/services/tts/generated-speech/types.js

@@ -2,7 +2,7 @@
  * Generated-speech plan model (PURE core).
  *
  * This module is the speech-composition core for items that contain math but
- * ship without authored SSML / `accessibilityCatalogs` (PIE-623). It is
+ * ship without authored SSML / `accessibilityCatalogs`. It is
  * deliberately free of any imports from `TTSService`, the highlight renderer,
  * `HighlightCoordinator`, Svelte, or custom-element entrypoints
  * (`scripts/check-speech-composition-purity.mjs` enforces this). DOM primitive

package/dist/services/tts/highlight-pipeline/create-highlight-plan.js

@@ -3,12 +3,19 @@ import { createHighlightDecision } from "./highlight-policy.js";
 import { resolveMathBoundaryTarget } from "./math-semantic-resolver.js";
 import { resolveProseBoundaryTarget } from "./prose-boundary-resolver.js";
 import { classifyMathHighlightCapability, createRenderedMathTargetResolver, } from "./rendered-math-target-resolver.js";
+import { composedContains, composedParentElement, rangeIntersectsComposedNode, } from "../flat-tree.js";
 import { isNodeHiddenForTTS } from "../text-processing.js";
+import { createRangesFromVisibleMap } from "./visible-map-range.js";
+const regionRangesFor = (chunk) => {
+    const ranges = createRangesFromVisibleMap(chunk.visibleMap, 0, chunk.visibleText.length);
+    return ranges.length > 1 ? ranges : undefined;
+};
 const regionTargetFor = (chunk) => chunk.regionRange
     ? {
         type: "range",
         quality: "region",
         range: chunk.regionRange,
+        ranges: regionRangesFor(chunk),
     }
     : chunk.regionElement
         ? {
@@ -29,12 +36,13 @@ const mathCandidatesForTarget = (target, chunk) => {
         return chunk.mathAlignments;
     return chunk.mathAlignments.filter(({ element }) => {
         try {
-            if (target.type === "range")
-                return target.range.intersectsNode(element);
+            if (target.type === "range") {
+                return (target.ranges ?? [target.range]).some((range) => rangeIntersectsComposedNode(range, element));
+            }
             if (target.type === "element") {
-                return target.element === element || target.element.contains(element);
+                return composedContains(target.element, element);
             }
-            return target.node.parentElement?.contains(element) || false;
+            return composedContains(composedParentElement(target.node), element);
         }
         catch {
             return false;
@@ -59,11 +67,10 @@ const TEXT_NODE = 3;
 // the last token — painting it would be a likely false positive, and "false
 // positives are worse than coarse highlighting." A single-text-node prose range
 // is kept: it underlines one token cleanly and usefully fills in any token the
-// math resolver missed. (The highlight coordinator no longer escalates word
-// ranges to the whole <math> / <mjx-container>, so this is now a precision
-// policy rather than flash-suppression — see HighlightCoordinator
-// WORD_FALLBACK_SELECTOR.)
-const wouldEscalateInsideTokenMath = (planned, target, candidates) => {
+// math resolver missed. The word layer never escalates a range to the enclosing
+// <math>/<mjx-container> (HighlightCoordinator WORD_FALLBACK_SELECTOR), so this
+// is a precision policy.
+const isMultiNodeRangeInsideTokenMath = (planned, target, candidates) => {
     if (!target || target.type !== "range")
         return false;
     const { startContainer, endContainer } = target.range;
@@ -120,8 +127,7 @@ export const createTTSHighlightPlan = (args) => {
             const planned = plannedChunksById.get(chunkId);
             if (!planned)
                 return missingChunkDecision();
-            const alignments = planned.chunk.mathAlignments;
-            const soleElement = alignments.length === 1 ? alignments[0].element : null;
+            const soleElement = soleEquationElement(planned.chunk.mathAlignments);
             const capability = soleElement
                 ? planned.mathCapabilityByElement.get(soleElement)
                 : null;
@@ -156,9 +162,9 @@ export const createTTSHighlightPlan = (args) => {
             const normalized = normalizeBoundaryEvent(chunk, event);
             const proseTarget = resolveProseBoundaryTarget(chunk, normalized);
             const mathCandidates = mathCandidatesForTarget(proseTarget, chunk);
-            const resolvedMathTarget = (!proseTarget || mathCandidates.length > 0
+            const resolvedMathTarget = !proseTarget || mathCandidates.length > 0
                 ? resolveMathBoundaryTarget(chunk, normalized, event, mathCandidates, planned.renderedMathTargetResolver)
-                : null) || null;
+                : null;
             const mathTarget = resolvedMathTarget?.quality === "semantic-token"
                 ? resolvedMathTarget
                 : (renderHiddenProseTarget(planned, proseTarget) ??
@@ -187,15 +193,15 @@ export const createTTSHighlightPlan = (args) => {
             }
             // (2) A spoken word that maps to visible prose. The prose anchor is
             // precise; a coarse math expression fallback must never override it.
-            // Exception: a multi-node prose range inside a token-mode equation
-            // would escalate to the whole expression, so it is rejected here and
+            // Exception: a multi-node prose range inside a token-mode equation is
+            // an untrustworthy glyph-level match, so it is rejected here and
             // falls through to the token hold below. When per-token math
             // highlighting is disabled, any prose range that lands inside a
             // formula is likewise rejected so the formula stays a single block.
             if (proseTarget &&
                 !isHiddenRange(proseTarget) &&
                 (mathTokenHighlighting
-                    ? !wouldEscalateInsideTokenMath(planned, proseTarget, mathCandidates)
+                    ? !isMultiNodeRangeInsideTokenMath(planned, proseTarget, mathCandidates)
                     : mathCandidates.length === 0)) {
                 return createHighlightDecision({
                     semanticTarget: proseTarget,

package/dist/services/tts/highlight-pipeline/prose-boundary-resolver.js

@@ -1,19 +1,21 @@
 import { resolveVisibleSpanForBoundary } from "../catalog-span-alignment.js";
-import { createRangeFromVisibleMap } from "./visible-map-range.js";
+import { createRangesFromVisibleMap } from "./visible-map-range.js";
 export const resolveProseBoundaryTarget = (chunk, boundary) => {
     if (!chunk.catalogAlignment || boundary.chunkSpokenStart === null)
         return null;
     const visibleSpan = resolveVisibleSpanForBoundary(chunk.catalogAlignment, boundary.chunkSpokenStart);
     if (!visibleSpan)
         return null;
-    const range = createRangeFromVisibleMap(chunk.visibleMap, visibleSpan.start, visibleSpan.end);
-    if (!range)
+    // One range per tree, as the uncataloged word path builds them.
+    const ranges = createRangesFromVisibleMap(chunk.visibleMap, visibleSpan.start, visibleSpan.end);
+    if (ranges.length === 0)
         return null;
     return {
         type: "range",
         quality: chunk.catalogAlignment.playbackMode === "exact-word"
             ? "exact-word"
             : "semantic-token",
-        range,
+        range: ranges[0],
+        ranges: ranges.length > 1 ? ranges : undefined,
     };
 };