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

package/dist/services/tts/highlight-pipeline/boundary-normalizer.js

@@ -1,43 +1,4 @@
-import { resolveSpokenBoundaryOffset } from "../catalog-span-alignment.js";
-import { resolveBoundaryToSpeechToken, tokenizeSpeechSource, } from "../math-alignment/speech-tokenizer.js";
-const normalizeBoundaryWord = (word) => {
-    if (!word || /^<[^>]+>$/.test(word.trim()))
-        return null;
-    return (tokenizeSpeechSource({ speechText: word }).tokens[0]?.normalized || null);
-};
-// Resolve a provider boundary for a chunk that carries no catalog span
-// alignment — notably the generated-SSML math path, whose `speechText` is a
-// raw `<speak>` document. The provider's offset is an index into `speechText`
-// exactly as it was sent (which may include SSML tags), so we tokenize that
-// same string and let the shared speech tokenizer translate the offset into the
-// extracted spoken text. Returns the boundary in spoken-text space alongside
-// that spoken text, so the downstream word/offset checks share one coordinate
-// system. The previous "direct" path treated the raw-SSML offset as a
-// spoken-text offset and rejected every math boundary (PIE-623 regression).
-const speechSourceBoundary = (chunk, event) => {
-    const tokenization = tokenizeSpeechSource({ speechText: chunk.speechText });
-    if (!Number.isFinite(event.position)) {
-        return { boundary: null, spokenText: tokenization.spokenText };
-    }
-    const resolved = resolveBoundaryToSpeechToken({
-        tokenization,
-        position: event.position,
-        length: event.length,
-        boundaryWord: event.word,
-    });
-    return {
-        boundary: resolved
-            ? { start: resolved.start, length: resolved.length }
-            : null,
-        spokenText: tokenization.spokenText,
-    };
-};
-const tokenAtOffsetMatches = (speechText, start, normalizedWord) => {
-    if (!normalizedWord)
-        return true;
-    const token = tokenizeSpeechSource({ speechText }).tokens.find((candidate) => candidate.start <= start && start < candidate.end);
-    return token?.normalized === normalizedWord;
-};
+import { normalizeBoundaryWord, resolveBoundaryToSpeechToken, tokenizeSpeechSource, } from "../math-alignment/speech-tokenizer.js";
 export const normalizeBoundaryEvent = (chunk, event) => {
     const normalizedWord = normalizeBoundaryWord(event.word);
     if (chunk.id !== event.chunkId) {
@@ -61,17 +22,16 @@ export const normalizeBoundaryEvent = (chunk, event) => {
             reason: "boundary offset space is unsupported",
         };
     }
-    let boundary;
-    let spokenText;
-    if (chunk.catalogAlignment) {
-        boundary = resolveSpokenBoundaryOffset(chunk.catalogAlignment, event.position, event.length, event.word);
-        spokenText = chunk.catalogAlignment.spokenText;
-    }
-    else {
-        const resolved = speechSourceBoundary(chunk, event);
-        boundary = resolved.boundary;
-        spokenText = resolved.spokenText;
-    }
+    // The provider's offset indexes `speechText` exactly as sent, which may be a
+    // raw `<speak>` document; the shared tokenizer maps it into spoken text and
+    // checks it against the reported word, on the catalog path and without one.
+    const boundary = resolveBoundaryToSpeechToken({
+        tokenization: chunk.catalogAlignment?.speech ??
+            tokenizeSpeechSource({ speechText: chunk.speechText }),
+        position: event.position,
+        length: event.length,
+        boundaryWord: event.word,
+    });
     if (!boundary) {
         return {
             chunkId: chunk.id,
@@ -82,22 +42,12 @@ export const normalizeBoundaryEvent = (chunk, event) => {
             reason: "could not resolve provider boundary to chunk speech",
         };
     }
-    if (!tokenAtOffsetMatches(spokenText, boundary.start, normalizedWord)) {
-        return {
-            chunkId: chunk.id,
-            normalizedWord,
-            chunkSpokenStart: null,
-            chunkSpokenEnd: null,
-            confidence: 0,
-            reason: "could not resolve provider boundary to matching word",
-        };
-    }
     return {
         chunkId: chunk.id,
         normalizedWord,
         chunkSpokenStart: boundary.start,
         chunkSpokenEnd: boundary.start + boundary.length,
-        confidence: normalizedWord ? 1 : 0.75,
+        confidence: boundary.confidence,
         reason: chunk.catalogAlignment
             ? "resolved through catalog alignment"
             : "resolved through speech tokenization",

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

@@ -3,11 +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
         ? {
@@ -28,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;
@@ -73,6 +82,25 @@ const wouldEscalateInsideTokenMath = (planned, target, candidates) => {
         element.contains(startContainer) &&
         element.contains(endContainer));
 };
+// A prose range in hidden content paints nothing. Catalog words over MathJax
+// math land in its clipped source MathML, so they select the equation, and a
+// range over one source token resolves to that token's rendered glyph — the
+// fill-in a single-text-node range gives native MathML.
+const isHiddenRange = (target) => target?.type === "range" && isNodeHiddenForTTS(target.range.startContainer);
+const renderHiddenProseTarget = (planned, target) => {
+    if (!isHiddenRange(target))
+        return null;
+    const { startContainer, endContainer, startOffset, endOffset } = target.range;
+    if (startContainer !== endContainer || startContainer.nodeType !== TEXT_NODE)
+        return null;
+    return planned.renderedMathTargetResolver({
+        type: "text-range",
+        quality: "exact-word",
+        node: startContainer,
+        startOffset,
+        endOffset,
+    });
+};
 const createPlannedChunk = (chunk, mathTokenHighlighting) => ({
     chunk,
     regionTarget: regionTargetFor(chunk),
@@ -136,9 +164,13 @@ export const createTTSHighlightPlan = (args) => {
             const normalized = normalizeBoundaryEvent(chunk, event);
             const proseTarget = resolveProseBoundaryTarget(chunk, normalized);
             const mathCandidates = mathCandidatesForTarget(proseTarget, chunk);
-            const mathTarget = (!proseTarget || mathCandidates.length > 0
+            const resolvedMathTarget = (!proseTarget || mathCandidates.length > 0
                 ? resolveMathBoundaryTarget(chunk, normalized, event, mathCandidates, planned.renderedMathTargetResolver)
                 : null) || null;
+            const mathTarget = resolvedMathTarget?.quality === "semantic-token"
+                ? resolvedMathTarget
+                : (renderHiddenProseTarget(planned, proseTarget) ??
+                    resolvedMathTarget);
             const mathTokenTarget = mathTokenHighlighting &&
                 mathTarget &&
                 mathTarget.quality !== "expression"
@@ -169,6 +201,7 @@ export const createTTSHighlightPlan = (args) => {
             // 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)
                     : mathCandidates.length === 0)) {

package/dist/services/tts/highlight-pipeline/normalize-speech-chunks.js

@@ -1,10 +1,7 @@
 const chunkOffsetSpaceFor = (chunk) => {
-    if (chunk.alignment?.boundaryOffsetMode)
-        return chunk.alignment.boundaryOffsetMode;
-    const mathOffsetSpace = chunk.mathAlignment?.speech.boundaryOffsetSpace;
-    if (mathOffsetSpace)
-        return mathOffsetSpace;
-    return "plain-spoken-text";
+    return (chunk.alignment?.speech.boundaryOffsetSpace ??
+        chunk.mathAlignment?.speech.boundaryOffsetSpace ??
+        "plain-spoken-text");
 };
 const mathAlignmentsFor = (chunk) => {
     if (chunk.mathAlignments?.length)

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,
     };
 };

package/dist/services/tts/highlight-pipeline/readable-region.js

@@ -1,3 +1,4 @@
+import { composedClosest, composedContains } from "../flat-tree.js";
 const READABLE_REGION_SELECTOR = [
     "[data-pie-tts-region]",
     "[data-catalog-region]",
@@ -10,8 +11,8 @@ const READABLE_REGION_SELECTOR = [
     "div",
 ].join(",");
 export const resolveReadableRegion = (sourceElement, contentRoot) => {
-    const region = sourceElement.closest(READABLE_REGION_SELECTOR);
-    if (region && contentRoot.contains(region)) {
+    const region = composedClosest(sourceElement, READABLE_REGION_SELECTOR);
+    if (region && composedContains(contentRoot, region)) {
         return region;
     }
     return sourceElement;

package/dist/services/tts/highlight-pipeline/types.d.ts

@@ -44,6 +44,11 @@ export type RenderableHighlightTarget = {
     type: "range";
     quality: "exact-word" | "semantic-token" | "expression" | "region";
     range: Range;
+    /**
+     * Every range to paint when the target crosses shadow boundaries, one per
+     * tree, `range` among them; absent when `range` covers the target.
+     */
+    ranges?: Range[];
 } | {
     type: "element";
     quality: "semantic-token" | "expression" | "region";

package/dist/services/tts/highlight-pipeline/visible-map-range.d.ts

@@ -1,2 +1,14 @@
 import type { NormalizedTextMap } from "../text-processing.js";
+/**
+ * The range over visible characters `start` to `end` (exclusive). A live range
+ * holds one tree, so when the span runs into a shadow tree, or out of one, the
+ * range ends at the last character in the tree it starts in.
+ */
 export declare const createRangeFromVisibleMap: (visibleMap: NormalizedTextMap | undefined, start: number, end: number) => Range | null;
+/**
+ * The ranges over visible characters `start` to `end` (exclusive), one per run of
+ * characters in the same tree, so a span crossing shadow boundaries paints in
+ * each tree it covers. A span within one tree gives exactly
+ * {@link createRangeFromVisibleMap}'s range.
+ */
+export declare const createRangesFromVisibleMap: (visibleMap: NormalizedTextMap | undefined, start: number, end: number) => Range[];

package/dist/services/tts/highlight-pipeline/visible-map-range.js

@@ -1,3 +1,20 @@
+const treeOf = (mapping) => mapping.node.getRootNode?.() ?? mapping.node;
+const rangeBetween = (start, end) => {
+    try {
+        const range = document.createRange();
+        range.setStart(start.node, start.offset);
+        range.setEnd(end.node, end.offset + 1);
+        return range;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The range over visible characters `start` to `end` (exclusive). A live range
+ * holds one tree, so when the span runs into a shadow tree, or out of one, the
+ * range ends at the last character in the tree it starts in.
+ */
 export const createRangeFromVisibleMap = (visibleMap, start, end) => {
     if (!visibleMap || typeof document === "undefined")
         return null;
@@ -9,13 +26,62 @@ export const createRangeFromVisibleMap = (visibleMap, start, end) => {
         return null;
     if (!endMapping)
         endMapping = startMapping;
-    try {
-        const range = document.createRange();
-        range.setStart(startMapping.node, startMapping.offset);
-        range.setEnd(endMapping.node, endMapping.offset + 1);
-        return range;
+    if (treeOf(endMapping) !== treeOf(startMapping)) {
+        const tree = treeOf(startMapping);
+        endMapping = startMapping;
+        for (let index = start + 1; index < end; index++) {
+            const mapping = visibleMap.get(index);
+            if (mapping && treeOf(mapping) === tree)
+                endMapping = mapping;
+        }
     }
-    catch {
-        return null;
+    return rangeBetween(startMapping, endMapping);
+};
+/**
+ * The ranges over visible characters `start` to `end` (exclusive), one per run of
+ * characters in the same tree, so a span crossing shadow boundaries paints in
+ * each tree it covers. A span within one tree gives exactly
+ * {@link createRangeFromVisibleMap}'s range.
+ */
+export const createRangesFromVisibleMap = (visibleMap, start, end) => {
+    if (!visibleMap || typeof document === "undefined" || end <= start)
+        return [];
+    const startMapping = visibleMap.get(start);
+    if (!startMapping)
+        return [];
+    const tree = treeOf(startMapping);
+    let crossesTrees = false;
+    for (let index = start + 1; index < end && !crossesTrees; index++) {
+        const mapping = visibleMap.get(index);
+        if (mapping && treeOf(mapping) !== tree)
+            crossesTrees = true;
+    }
+    if (!crossesTrees) {
+        const range = createRangeFromVisibleMap(visibleMap, start, end);
+        return range ? [range] : [];
+    }
+    const ranges = [];
+    let runStart = null;
+    let runEnd = null;
+    const closeRun = () => {
+        if (runStart && runEnd) {
+            const range = rangeBetween(runStart, runEnd);
+            if (range)
+                ranges.push(range);
+        }
+        runStart = null;
+        runEnd = null;
+    };
+    for (let index = start; index < end; index++) {
+        const mapping = visibleMap.get(index);
+        if (!mapping)
+            continue;
+        if (runStart && treeOf(runStart) !== treeOf(mapping))
+            closeRun();
+        if (!runStart)
+            runStart = mapping;
+        runEnd = mapping;
     }
+    closeRun();
+    return ranges;
 };

package/dist/services/tts/math-alignment/index.d.ts

@@ -14,11 +14,6 @@ export declare const resolveHighlightTargetForBoundary: (alignment: MathAwareAli
     length?: number;
     boundaryWord?: string;
 }) => HighlightTarget;
-export declare const resolveMatchedHighlightTargetForBoundary: (alignment: MathAwareAlignment, args: {
-    position: number;
-    length?: number;
-    boundaryWord?: string;
-}) => HighlightTarget | null;
 export declare const resolveMatchedHighlightTargetForSpokenBoundary: (alignment: MathAwareAlignment, args: {
     position: number;
     length?: number;

package/dist/services/tts/math-alignment/index.js

@@ -1,7 +1,7 @@
 import { tokenizeMathML } from "./mathml-tokenizer.js";
 import { resolveMatchedHighlightTargetForBoundary as resolveMatchedTargetForBoundary, resolveHighlightTargetForBoundary as resolveTargetForBoundary, } from "./range-resolver.js";
 import { alignSpeechToMath } from "./sequence-aligner.js";
-import { resolveBoundaryToSpeechToken, resolveSpokenOffsetToSpeechToken, tokenizeSpeechSource, } from "./speech-tokenizer.js";
+import { normalizeBoundaryWord, resolveBoundaryToSpeechToken, resolveSpokenOffsetToSpeechToken, tokenizeSpeechSource, } from "./speech-tokenizer.js";
 export const createMathAwareAlignment = (args) => {
     const speech = tokenizeSpeechSource({ speechText: args.speechText });
     const math = tokenizeMathML(args.mathElement);
@@ -23,18 +23,6 @@ export const resolveHighlightTargetForBoundary = (alignment, args) => {
         boundary,
     });
 };
-export const resolveMatchedHighlightTargetForBoundary = (alignment, args) => {
-    const boundary = resolveBoundaryToSpeechToken({
-        tokenization: alignment.speech,
-        position: args.position,
-        length: args.length,
-        boundaryWord: args.boundaryWord,
-    });
-    return resolveMatchedTargetForBoundary({
-        alignment: alignment.result,
-        boundary,
-    });
-};
 export const resolveMatchedHighlightTargetForSpokenBoundary = (alignment, args) => {
     const boundary = resolveSpokenOffsetToSpeechToken({
         tokenization: alignment.speech,
@@ -48,18 +36,10 @@ export const resolveMatchedHighlightTargetForSpokenBoundary = (alignment, args)
     });
 };
 export const resolveUniqueMathTargetForBoundaryWord = (alignment, args) => {
-    if (!args.boundaryWord || /^<[^>]+>$/.test(args.boundaryWord.trim())) {
-        return null;
-    }
-    const boundaryToken = tokenizeSpeechSource({
-        speechText: args.boundaryWord,
-    }).tokens[0];
-    if (!boundaryToken)
+    const normalized = normalizeBoundaryWord(args.boundaryWord);
+    if (!normalized)
         return null;
-    const matches = alignment.math.tokens.filter((token) => {
-        const normalized = boundaryToken.normalized.toLowerCase();
-        return (token.normalized.toLowerCase() === normalized ||
-            token.spokenAliases.some((alias) => alias.toLowerCase() === normalized));
-    });
+    const matches = alignment.math.tokens.filter((token) => token.normalized.toLowerCase() === normalized ||
+        token.spokenAliases.some((alias) => alias.toLowerCase() === normalized));
     return matches.length === 1 ? matches[0].target : null;
 };

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

@@ -1,4 +1,4 @@
-import type { BoundaryOffsetSpace, SpeechAlignmentToken } from "./types.js";
+import type { AlignmentTextToken, BoundaryOffsetSpace, SpeechAlignmentToken } from "./types.js";
 export interface SpeechSourceTokenization {
     speechText: string;
     spokenText: string;
@@ -14,9 +14,17 @@ export interface ResolvedSpeechBoundary {
     length: number;
     confidence: number;
 }
+export declare const tokenizeAlignmentText: (text: string) => AlignmentTextToken[];
 export declare const tokenizeSpeechSource: (args: {
     speechText: string;
 }) => SpeechSourceTokenization;
+/**
+ * A provider boundary word in the form spoken tokens compare in, or null when
+ * the word carries no token (empty, a control tag, punctuation). The word goes
+ * through the same SSML extraction as the chunk, so an entity-encoded word
+ * normalizes to the text it encodes.
+ */
+export declare const normalizeBoundaryWord: (word?: string) => string | null;
 export declare const resolveBoundaryToSpeechToken: (args: {
     tokenization: SpeechSourceTokenization;
     position: number;

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

@@ -1,8 +1,8 @@
 import { extractSpokenText } from "../ssml/spoken-text.js";
 import { createSpeechAlignmentTokenPattern } from "../text-processing.js";
-// Shared Unicode-aware tokenizer, identical to the catalog span aligner's, so
-// spoken text tokenizes the same way on both paths (see
-// `createSpeechAlignmentTokenPattern`).
+// The one tokenizer and normalization table for TTS alignment. Spoken text,
+// visible catalog text and provider boundary words all tokenize here, so a word
+// normalizes the same way on the catalog, math and generated-speech paths.
 const TOKEN_PATTERN = createSpeechAlignmentTokenPattern();
 const NUMERIC_WORDS = new Map([
     ["zero", "0"],
@@ -21,24 +21,27 @@ const normalizedTokenValue = (value) => {
     const normalized = value.toLowerCase();
     return NUMERIC_WORDS.get(normalized) || normalized;
 };
-const tokenizeSpokenText = (spokenText) => {
+export const tokenizeAlignmentText = (text) => {
     const tokens = [];
-    for (const match of spokenText.matchAll(TOKEN_PATTERN)) {
-        const text = match[0];
+    for (const match of text.matchAll(TOKEN_PATTERN)) {
+        const value = match[0];
         const start = match.index ?? 0;
         tokens.push({
-            id: `speech-token-${tokens.length}`,
-            text,
-            normalized: normalizedTokenValue(text),
+            text: value,
+            normalized: normalizedTokenValue(value),
             start,
-            end: start + text.length,
-            sourceStart: start,
-            sourceEnd: start + text.length,
-            coordinateSystem: "normalized-speech",
+            end: start + value.length,
         });
     }
     return tokens;
 };
+const tokenizeSpokenText = (spokenText) => tokenizeAlignmentText(spokenText).map((token, index) => ({
+    ...token,
+    id: `speech-token-${index}`,
+    sourceStart: token.start,
+    sourceEnd: token.end,
+    coordinateSystem: "normalized-speech",
+}));
 export const tokenizeSpeechSource = (args) => {
     const extracted = extractSpokenText(args.speechText);
     return {
@@ -55,15 +58,17 @@ export const tokenizeSpeechSource = (args) => {
         hasMarkup: extracted.hasMarkup,
     };
 };
-const normalizeBoundaryWord = (word) => {
-    if (!word)
+const isControlTagWord = (word) => Boolean(word && /^<[^>]+>$/.test(word.trim()));
+/**
+ * A provider boundary word in the form spoken tokens compare in, or null when
+ * the word carries no token (empty, a control tag, punctuation). The word goes
+ * through the same SSML extraction as the chunk, so an entity-encoded word
+ * normalizes to the text it encodes.
+ */
+export const normalizeBoundaryWord = (word) => {
+    if (!word || isControlTagWord(word))
         return null;
-    if (/^<[^>]+>$/.test(word.trim()))
-        return null;
-    const match = word.match(TOKEN_PATTERN);
-    if (!match?.[0])
-        return null;
-    return normalizedTokenValue(match[0]);
+    return (tokenizeSpeechSource({ speechText: word }).tokens[0]?.normalized ?? null);
 };
 const findTokenAtOffset = (tokens, offset) => tokens.find((token) => token.start <= offset && offset < token.end) || null;
 const mapRawOffsetToSpokenOffset = (tokenization, position) => {
@@ -92,32 +97,29 @@ const candidateForOffset = (tokenization, offset, length) => {
         confidence: 0.75,
     };
 };
-const candidateMatchesWord = (candidate, boundaryWord) => {
-    const normalizedBoundary = normalizeBoundaryWord(boundaryWord);
-    return Boolean(candidate &&
-        normalizedBoundary &&
-        candidate.token.normalized === normalizedBoundary);
-};
+const candidateMatchesWord = (candidate, normalizedWord) => Boolean(candidate &&
+    normalizedWord &&
+    candidate.token.normalized === normalizedWord);
 export const resolveBoundaryToSpeechToken = (args) => {
     if (args.tokenization.boundaryOffsetSpace === "unsupported" ||
         !Number.isFinite(args.position) ||
-        (args.boundaryWord && /^<[^>]+>$/.test(args.boundaryWord.trim()))) {
+        isControlTagWord(args.boundaryWord)) {
         return null;
     }
     const safeLength = Math.max(1, Number.isFinite(args.length) ? args.length : 1);
+    const normalizedWord = normalizeBoundaryWord(args.boundaryWord);
     const rawCandidate = candidateForOffset(args.tokenization, mapRawOffsetToSpokenOffset(args.tokenization, args.position), safeLength);
     const plainCandidate = candidateForOffset(args.tokenization, args.position >= 0 && args.position < args.tokenization.spokenText.length
         ? args.position
         : null, safeLength);
-    if (candidateMatchesWord(rawCandidate, args.boundaryWord)) {
+    if (candidateMatchesWord(rawCandidate, normalizedWord)) {
         return { ...rawCandidate, confidence: 1 };
     }
-    if (candidateMatchesWord(plainCandidate, args.boundaryWord)) {
+    if (candidateMatchesWord(plainCandidate, normalizedWord)) {
         return { ...plainCandidate, confidence: 1 };
     }
-    if (args.boundaryWord && normalizeBoundaryWord(args.boundaryWord)) {
+    if (normalizedWord)
         return null;
-    }
     return args.tokenization.boundaryOffsetSpace === "raw-ssml"
         ? rawCandidate || plainCandidate
         : plainCandidate || rawCandidate;
@@ -125,18 +127,18 @@ export const resolveBoundaryToSpeechToken = (args) => {
 export const resolveSpokenOffsetToSpeechToken = (args) => {
     if (args.tokenization.boundaryOffsetSpace === "unsupported" ||
         !Number.isFinite(args.position) ||
-        (args.boundaryWord && /^<[^>]+>$/.test(args.boundaryWord.trim()))) {
+        isControlTagWord(args.boundaryWord)) {
         return null;
     }
     const safeLength = Math.max(1, Number.isFinite(args.length) ? args.length : 1);
+    const normalizedWord = normalizeBoundaryWord(args.boundaryWord);
     const spokenCandidate = candidateForOffset(args.tokenization, args.position >= 0 && args.position < args.tokenization.spokenText.length
         ? args.position
         : null, safeLength);
-    if (candidateMatchesWord(spokenCandidate, args.boundaryWord)) {
+    if (candidateMatchesWord(spokenCandidate, normalizedWord)) {
         return { ...spokenCandidate, confidence: 1 };
     }
-    if (args.boundaryWord && normalizeBoundaryWord(args.boundaryWord)) {
+    if (normalizedWord)
         return null;
-    }
     return spokenCandidate;
 };

package/dist/services/tts/math-alignment/types.d.ts

@@ -34,12 +34,14 @@ export interface MathMLTokenizationResult {
 }
 export type BoundaryCoordinateSystem = "normalized-speech" | "raw-ssml" | "provider-speech-marks";
 export type BoundaryOffsetSpace = "plain-spoken-text" | "raw-ssml" | "unsupported";
-export interface SpeechAlignmentToken {
-    id: string;
+export interface AlignmentTextToken {
     text: string;
     normalized: string;
     start: number;
     end: number;
+}
+export interface SpeechAlignmentToken extends AlignmentTextToken {
+    id: string;
     sourceStart: number;
     sourceEnd: number;
     coordinateSystem: BoundaryCoordinateSystem;

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

@@ -15,4 +15,8 @@ export interface MathAwareTextResult {
     chunks: MathAwareSpeechChunk[];
     containsMathMarkup: boolean;
 }
-export declare const collectMathAwareTextAndMap: (element: Element, options?: TextProcessingOptions) => MathAwareTextResult;
+/**
+ * With `range`, only the part of `element` the range selects: text it selects
+ * and equations it holds whole.
+ */
+export declare const collectMathAwareTextAndMap: (element: Element, options?: TextProcessingOptions, range?: Range) => MathAwareTextResult;