@pie-players/pie-assessment-toolkit 0.3.50 → 0.3.52

package/dist/services/TTSService.js

@@ -74,6 +74,7 @@ export class TTSService {
     currentProvider = null;
     provider = null;
     highlightCoordinator = null;
+    highlightTargetResolverProvider = null;
     catalogResolver = null;
     state = PlaybackState.IDLE;
     ttsConfig = {};
@@ -84,6 +85,7 @@ export class TTSService {
     lastError = null;
     speakRunId = 0;
     currentBoundaryOffset = 0;
+    activeWordBoundaryOffset = 0;
     seekSegments = [];
     sentenceHighlightSegments = [];
     currentSeekSegmentIndex = 0;
@@ -209,6 +211,17 @@ export class TTSService {
     setHighlightCoordinator(coordinator) {
         this.highlightCoordinator = coordinator;
     }
+    /**
+     * Set a late-bound provider for optional host TTS highlight target remapping.
+     */
+    setHighlightTargetResolverProvider(provider) {
+        this.highlightTargetResolverProvider = provider;
+        return () => {
+            if (this.highlightTargetResolverProvider === provider) {
+                this.highlightTargetResolverProvider = null;
+            }
+        };
+    }
     /**
      * Set accessibility catalog resolver for spoken content
      *
@@ -220,6 +233,145 @@ export class TTSService {
     setCatalogResolver(resolver) {
         this.catalogResolver = resolver;
     }
+    getHighlightResolverRuntime() {
+        let provided = null;
+        try {
+            provided = this.highlightTargetResolverProvider?.() ?? null;
+        }
+        catch {
+            provided = null;
+        }
+        const providedContext = provided?.context ?? {};
+        const fallbackScope = typeof HTMLElement !== "undefined" &&
+            this.currentContentElement instanceof HTMLElement
+            ? this.currentContentElement
+            : null;
+        return {
+            context: {
+                ...providedContext,
+                scopeElement: providedContext.scopeElement ?? fallbackScope,
+            },
+            resolver: provided?.resolver ?? null,
+        };
+    }
+    getNodeElement(node) {
+        if (!node)
+            return null;
+        return node.nodeType === Node.ELEMENT_NODE
+            ? node
+            : node.parentElement;
+    }
+    isElementWithinScope(element, scope) {
+        if (!scope)
+            return true;
+        return element === scope || scope.contains(element);
+    }
+    isRangeWithinScope(range, scope) {
+        const startElement = this.getNodeElement(range.startContainer);
+        const endElement = this.getNodeElement(range.endContainer);
+        if (!startElement || !endElement)
+            return false;
+        return (this.isElementWithinScope(startElement, scope) &&
+            this.isElementWithinScope(endElement, scope));
+    }
+    resolveWordHighlightRange(nativeRange) {
+        const { context, resolver } = this.getHighlightResolverRuntime();
+        const scope = context.scopeElement ?? this.currentContentElement;
+        try {
+            const resolved = resolver?.resolveWordRange?.(nativeRange, context);
+            if (resolved && this.isRangeWithinScope(resolved, scope)) {
+                return { range: resolved, remapped: !sameRange(nativeRange, resolved) };
+            }
+        }
+        catch {
+            // Fail open: custom resolver failures must not interrupt TTS playback.
+        }
+        return { range: nativeRange, remapped: false };
+    }
+    resolveSentenceHighlightTargets(nativeRanges) {
+        const { context, resolver } = this.getHighlightResolverRuntime();
+        const scope = context.scopeElement ?? this.currentContentElement;
+        try {
+            const resolved = resolver?.resolveSentenceRanges?.(nativeRanges, context);
+            if (!resolved)
+                return { ranges: nativeRanges, elements: [] };
+            const ranges = [];
+            const elements = [];
+            for (const target of resolved) {
+                if (typeof Range !== "undefined" && target instanceof Range) {
+                    if (!this.isRangeWithinScope(target, scope)) {
+                        return { ranges: nativeRanges, elements: [] };
+                    }
+                    ranges.push(target);
+                    continue;
+                }
+                if (typeof Element !== "undefined" && target instanceof Element) {
+                    if (!this.isElementWithinScope(target, scope)) {
+                        return { ranges: nativeRanges, elements: [] };
+                    }
+                    elements.push(target);
+                    continue;
+                }
+                return { ranges: nativeRanges, elements: [] };
+            }
+            return { ranges, elements };
+        }
+        catch {
+            // Fail open: custom resolver failures must not interrupt TTS playback.
+            return { ranges: nativeRanges, elements: [] };
+        }
+    }
+    createTextRange(node, startOffset, endOffset) {
+        if (typeof document === "undefined")
+            return null;
+        if (typeof document.createRange !== "function")
+            return null;
+        try {
+            const range = document.createRange();
+            range.setStart(node, startOffset);
+            range.setEnd(node, endOffset);
+            if (range.startContainer !== node || range.endContainer !== node) {
+                return null;
+            }
+            return range;
+        }
+        catch {
+            return null;
+        }
+    }
+    paintTTSWordRange(range) {
+        if (!this.highlightCoordinator)
+            return;
+        try {
+            if (range.startContainer === range.endContainer &&
+                range.startContainer.nodeType === Node.TEXT_NODE) {
+                this.highlightCoordinator.highlightTTSWord(range.startContainer, range.startOffset, range.endOffset);
+                return;
+            }
+        }
+        catch {
+            // Fall through to generic range painting for lightweight test doubles.
+        }
+        this.highlightCoordinator.highlightRange(range, HighlightType.TTS_WORD, HighlightColor.YELLOW);
+    }
+    paintTTSSentenceRanges(nativeRanges) {
+        if (!this.highlightCoordinator)
+            return;
+        const { ranges, elements } = this.resolveSentenceHighlightTargets(nativeRanges);
+        if (elements.length > 0 &&
+            ranges.length === 0 &&
+            this.highlightCoordinator.highlightTTSSentenceElements) {
+            this.highlightCoordinator.highlightTTSSentenceElements(elements);
+            return;
+        }
+        const paintedRanges = [...ranges];
+        for (const element of elements) {
+            const elementRange = document.createRange();
+            elementRange.selectNodeContents(element);
+            paintedRanges.push(elementRange);
+        }
+        this.highlightCoordinator.highlightTTSSentence(paintedRanges);
+    }
     /**
      * Get provider capabilities
      */
@@ -577,11 +729,11 @@ export class TTSService {
             this.currentBoundaryOffset = 0;
             const originalOnWordBoundary = this.provider.onWordBoundary;
             this.provider.onWordBoundary = (word, position, length) => {
+                originalOnWordBoundary?.(word, position, length);
                 if (Number.isFinite(position)) {
                     this.currentBoundaryOffset = position;
                     this.currentSeekSegmentIndex = this.getCurrentSeekSegmentIndex();
                 }
-                originalOnWordBoundary?.(word, position, length);
             };
             try {
                 await providerWithPlan.speakSegments(segments);
@@ -593,6 +745,10 @@ export class TTSService {
             }
             return;
         }
+        this.configureWordBoundaryHighlighting({
+            highlightMode: options?.highlightMode || "word",
+            wordBoundaryOffset: this.activeWordBoundaryOffset,
+        });
         for (const segment of segments) {
             if (runId !== this.speakRunId)
                 return;
@@ -624,7 +780,7 @@ export class TTSService {
         const range = document.createRange();
         range.setStart(start.node, start.offset);
         range.setEnd(end.node, end.offset + 1);
-        this.highlightCoordinator.highlightTTSSentence([range]);
+        this.paintTTSSentenceRanges([range]);
         this.activeSentenceStartOffset = startOffset;
     }
     getSegmentIndexForOffset(segments, offset) {
@@ -732,6 +888,7 @@ export class TTSService {
             const highlightMode = options?.highlightModeOverride ||
                 (speechMatchesVisibleText ? this.resolveHighlightMode() : "sentence");
             this.activeHighlightMode = highlightMode;
+            this.activeWordBoundaryOffset = options?.wordBoundaryOffset || 0;
             const hasExplicitBreaks = this.hasExplicitBreakSemantics(contentToSpeak);
             const shouldUsePlan = !!this.currentContentElement &&
                 !usedCatalogSpoken &&
@@ -1168,7 +1325,7 @@ export class TTSService {
             try {
                 const range = document.createRange();
                 range.selectNodeContents(this.currentContentElement);
-                this.highlightCoordinator.highlightTTSSentence([range]);
+                this.paintTTSSentenceRanges([range]);
             }
             catch {
                 // No-op fallback when DOM range creation fails.
@@ -1192,7 +1349,13 @@ export class TTSService {
             if (highlightRange && this.highlightCoordinator) {
                 const highlightText = highlightRange.node.textContent?.substring(highlightRange.start, highlightRange.end) || "";
                 this.debugLog(`[TTSService] Highlighting "${highlightText}" (word: "${word}") at position ${globalIndex}`);
-                this.highlightCoordinator.highlightTTSWord(highlightRange.node, highlightRange.start, highlightRange.end);
+                const nativeRange = this.createTextRange(highlightRange.node, highlightRange.start, highlightRange.end);
+                if (nativeRange) {
+                    this.paintTTSWordRange(this.resolveWordHighlightRange(nativeRange).range);
+                }
+                else {
+                    this.highlightCoordinator.highlightTTSWord(highlightRange.node, highlightRange.start, highlightRange.end);
+                }
             }
             else {
                 console.warn(`[TTSService] Could not find highlight range for position ${globalIndex}, length ${wordLength}`);
@@ -1212,7 +1375,7 @@ export class TTSService {
             this.lastRenderedRegionTarget = null;
             if (chunk.regionRange) {
                 this.highlightCoordinator.clearHighlights?.(HighlightType.TTS_WORD);
-                this.highlightCoordinator.highlightTTSSentence([chunk.regionRange]);
+                this.paintTTSSentenceRanges([chunk.regionRange]);
                 return;
             }
             if (!element)
@@ -1220,7 +1383,7 @@ export class TTSService {
             const range = document.createRange();
             range.selectNodeContents(element);
             this.highlightCoordinator.clearHighlights?.(HighlightType.TTS_WORD);
-            this.highlightCoordinator.highlightTTSSentence([range]);
+            this.paintTTSSentenceRanges([range]);
         }
         catch {
             // Continue playback even when a detached node cannot be highlighted.
@@ -1229,12 +1392,7 @@ export class TTSService {
     highlightCatalogActiveRange(range) {
         if (!this.highlightCoordinator)
             return;
-        if (range.startContainer === range.endContainer &&
-            range.startContainer.nodeType === Node.TEXT_NODE) {
-            this.highlightCoordinator.highlightTTSWord(range.startContainer, range.startOffset, range.endOffset);
-            return;
-        }
-        this.highlightCoordinator.highlightRange(range, HighlightType.TTS_WORD, HighlightColor.YELLOW);
+        this.paintTTSWordRange(this.resolveWordHighlightRange(range).range);
     }
     highlightRenderableRegionTarget(target) {
         if (!this.highlightCoordinator ||
@@ -1242,7 +1400,8 @@ export class TTSService {
             typeof document === "undefined") {
             return;
         }
-        if (sameRenderableHighlightTarget(this.lastRenderedRegionTarget, target)) {
+        if (!this.highlightTargetResolverProvider &&
+            sameRenderableHighlightTarget(this.lastRenderedRegionTarget, target)) {
             return;
         }
         try {
@@ -1251,7 +1410,7 @@ export class TTSService {
                 range.selectNodeContents(target.element);
             }
             else if (target.type === "range") {
-                this.highlightCoordinator.highlightTTSSentence([target.range]);
+                this.paintTTSSentenceRanges([target.range]);
                 this.lastRenderedRegionTarget = target;
                 return;
             }
@@ -1259,7 +1418,7 @@ export class TTSService {
                 range.setStart(target.node, target.startOffset);
                 range.setEnd(target.node, target.endOffset);
             }
-            this.highlightCoordinator.highlightTTSSentence([range]);
+            this.paintTTSSentenceRanges([range]);
             this.lastRenderedRegionTarget = target;
         }
         catch {
@@ -1280,13 +1439,26 @@ export class TTSService {
             return;
         }
         if (target.type === "text-range") {
-            this.highlightCoordinator.highlightTTSWord(target.node, target.startOffset, target.endOffset);
+            const nativeRange = this.createTextRange(target.node, target.startOffset, target.endOffset);
+            if (nativeRange) {
+                this.paintTTSWordRange(this.resolveWordHighlightRange(nativeRange).range);
+            }
+            else {
+                this.highlightCoordinator.highlightTTSWord(target.node, target.startOffset, target.endOffset);
+            }
             return;
         }
         if (target.type === "range") {
             this.highlightCatalogActiveRange(target.range);
             return;
         }
+        const elementNativeRange = document.createRange();
+        elementNativeRange.selectNodeContents(target.element);
+        const resolvedElementRange = this.resolveWordHighlightRange(elementNativeRange);
+        if (resolvedElementRange.remapped) {
+            this.paintTTSWordRange(resolvedElementRange.range);
+            return;
+        }
         // Element targets are atomic: a resolved math token, a whole-expression
         // fallback, or a replaced element (image/svg). Paint exactly the resolved
         // element. Native MathML / HTML tokens that expose a single text node keep
@@ -1438,6 +1610,7 @@ export class TTSService {
         this.currentContentElement = null;
         this.normalizedToDOM.clear();
         this.currentBoundaryOffset = 0;
+        this.activeWordBoundaryOffset = 0;
         this.seekSegments = [];
         this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;
@@ -1514,32 +1687,27 @@ export class TTSService {
             this.setState(PlaybackState.PLAYING);
         }
     }
-    async seekBy(units) {
-        if (!this.provider || !this.currentText)
-            return;
-        if (this.state !== PlaybackState.PLAYING &&
-            this.state !== PlaybackState.PAUSED) {
-            return;
-        }
-        if (this.hasExplicitBreakSemantics(this.currentText))
-            return;
-        if (this.seekSegments.length === 0)
-            return;
-        const delta = Number.isFinite(units) ? Math.trunc(units) : 0;
-        if (delta === 0)
-            return;
-        const currentIndex = this.getCurrentSeekSegmentIndex();
-        const targetIndex = Math.max(0, Math.min(this.seekSegments.length - 1, currentIndex + delta));
-        if (targetIndex === currentIndex)
+    normalizePlaybackRate(rate) {
+        if (!Number.isFinite(rate))
+            return 1;
+        return Math.max(0.25, Math.min(4, rate));
+    }
+    async restartFromSeekIndex(targetIndex) {
+        if (!this.provider || this.seekSegments.length === 0)
             return;
+        const safeTargetIndex = Math.max(0, Math.min(this.seekSegments.length - 1, targetIndex));
         this.speakRunId += 1;
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
-        this.currentSeekSegmentIndex = targetIndex;
+        this.currentSeekSegmentIndex = safeTargetIndex;
         const runId = ++this.speakRunId;
-        const restartSegments = this.seekSegments.slice(targetIndex);
+        const restartSegments = this.seekSegments.slice(safeTargetIndex);
         this.setState(PlaybackState.PLAYING);
         try {
+            this.configureWordBoundaryHighlighting({
+                highlightMode: this.activeHighlightMode,
+                wordBoundaryOffset: this.activeWordBoundaryOffset,
+            });
             await this.speakWithPlan(restartSegments, runId, {
                 highlightMode: this.activeHighlightMode,
             });
@@ -1547,6 +1715,7 @@ export class TTSService {
                 return;
             this.setState(PlaybackState.IDLE);
             this.clearHighlightsAndTracking();
+            this.highlightTargetResolverProvider = null;
         }
         catch (error) {
             if (runId !== this.speakRunId)
@@ -1554,9 +1723,41 @@ export class TTSService {
             this.lastError = error instanceof Error ? error.message : String(error);
             this.setState(PlaybackState.ERROR);
             this.clearHighlightsAndTracking();
+            this.highlightTargetResolverProvider = null;
             throw error;
         }
     }
+    async setPlaybackRate(rate) {
+        const nextRate = this.normalizePlaybackRate(rate);
+        await this.updateSettings({ rate: nextRate });
+        if (this.state !== PlaybackState.PLAYING ||
+            !this.currentText ||
+            this.seekSegments.length === 0 ||
+            this.hasExplicitBreakSemantics(this.currentText)) {
+            return;
+        }
+        await this.restartFromSeekIndex(this.getCurrentSeekSegmentIndex());
+    }
+    async seekBy(units) {
+        if (!this.provider || !this.currentText)
+            return;
+        if (this.state !== PlaybackState.PLAYING &&
+            this.state !== PlaybackState.PAUSED) {
+            return;
+        }
+        if (this.hasExplicitBreakSemantics(this.currentText))
+            return;
+        if (this.seekSegments.length === 0)
+            return;
+        const delta = Number.isFinite(units) ? Math.trunc(units) : 0;
+        if (delta === 0)
+            return;
+        const currentIndex = this.getCurrentSeekSegmentIndex();
+        const targetIndex = Math.max(0, Math.min(this.seekSegments.length - 1, currentIndex + delta));
+        if (targetIndex === currentIndex)
+            return;
+        await this.restartFromSeekIndex(targetIndex);
+    }
     async seekForward(units = 1) {
         const step = Number.isFinite(units) ? Math.max(1, Math.trunc(units)) : 1;
         await this.seekBy(step);
@@ -1574,6 +1775,7 @@ export class TTSService {
         this.speakRunId += 1;
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
+        this.highlightTargetResolverProvider = null;
         this.setState(PlaybackState.IDLE);
         this.currentText = null;
         // Clear highlights
@@ -1585,6 +1787,7 @@ export class TTSService {
         this.currentContentElement = null;
         this.normalizedToDOM.clear();
         this.currentBoundaryOffset = 0;
+        this.activeWordBoundaryOffset = 0;
         this.seekSegments = [];
         this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;