@pie-players/pie-assessment-toolkit 0.3.51 → 0.3.53

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 = {};
@@ -86,6 +87,7 @@ export class TTSService {
     currentBoundaryOffset = 0;
     activeWordBoundaryOffset = 0;
     seekSegments = [];
+    playbackChunks = [];
     sentenceHighlightSegments = [];
     currentSeekSegmentIndex = 0;
     activeSentenceStartOffset = null;
@@ -210,6 +212,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
      *
@@ -221,6 +234,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
      */
@@ -554,6 +706,24 @@ export class TTSService {
             .filter((offset) => offset > 0);
         return this.splitSegmentsAtBoundaries(grammaticalSegments, structuralBoundaries, args.contentToSpeak);
     }
+    createSeekSegmentsFromSpeechChunks(chunks) {
+        let offset = 0;
+        return chunks.map((chunk) => {
+            const speechText = chunk.plainFallback?.speechText ||
+                (this.hasExplicitBreakSemantics(chunk.speechText)
+                    ? chunk.visibleText
+                    : chunk.speechText) ||
+                chunk.visibleText;
+            const text = normalizeTextForSpeech(speechText) || chunk.visibleText || "";
+            const segment = {
+                text,
+                startOffset: offset,
+                pauseMsAfter: 0,
+            };
+            offset += Math.max(1, text.length + 1);
+            return segment;
+        });
+    }
     getCurrentSeekSegmentIndex() {
         if (this.seekSegments.length === 0)
             return 0;
@@ -629,7 +799,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) {
@@ -743,8 +913,10 @@ export class TTSService {
                 !usedCatalogSpoken &&
                 !hasExplicitBreaks &&
                 speechMatchesVisibleText;
-            this.seekSegments =
-                hasExplicitBreaks || !speechMatchesVisibleText
+            this.playbackChunks = speechChunks?.length ? speechChunks : [];
+            this.seekSegments = this.playbackChunks.length
+                ? this.createSeekSegmentsFromSpeechChunks(this.playbackChunks)
+                : hasExplicitBreaks || !speechMatchesVisibleText
                     ? []
                     : shouldUsePlan && this.currentContentElement
                         ? this.createSpeechPlan(this.currentContentElement, normalizedText)
@@ -1155,6 +1327,7 @@ export class TTSService {
         this.currentContentElement = options?.contentElement || null;
         this.lastError = null;
         this.currentBoundaryOffset = 0;
+        this.playbackChunks = [];
         this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
     }
@@ -1174,7 +1347,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.
@@ -1198,7 +1371,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}`);
@@ -1218,7 +1397,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)
@@ -1226,7 +1405,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.
@@ -1235,12 +1414,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 ||
@@ -1248,7 +1422,8 @@ export class TTSService {
             typeof document === "undefined") {
             return;
         }
-        if (sameRenderableHighlightTarget(this.lastRenderedRegionTarget, target)) {
+        if (!this.highlightTargetResolverProvider &&
+            sameRenderableHighlightTarget(this.lastRenderedRegionTarget, target)) {
             return;
         }
         try {
@@ -1257,7 +1432,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;
             }
@@ -1265,7 +1440,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 {
@@ -1286,13 +1461,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
@@ -1413,9 +1601,15 @@ export class TTSService {
     }
     async executeSpeakPlayback(args) {
         if (args.speechChunks?.length && this.provider) {
-            for (const chunk of args.speechChunks) {
+            for (let index = 0; index < args.speechChunks.length; index++) {
                 if (args.runId !== this.speakRunId)
                     return;
+                this.currentSeekSegmentIndex = index;
+                const segment = this.seekSegments[index];
+                if (segment) {
+                    this.currentBoundaryOffset = segment.startOffset;
+                }
+                const chunk = args.speechChunks[index];
                 await this.speakCatalogChunk(chunk, args.runId);
             }
             return;
@@ -1446,6 +1640,7 @@ export class TTSService {
         this.currentBoundaryOffset = 0;
         this.activeWordBoundaryOffset = 0;
         this.seekSegments = [];
+        this.playbackChunks = [];
         this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
@@ -1530,6 +1725,9 @@ export class TTSService {
         if (!this.provider || this.seekSegments.length === 0)
             return;
         const safeTargetIndex = Math.max(0, Math.min(this.seekSegments.length - 1, targetIndex));
+        const restartChunks = this.playbackChunks.length
+            ? this.playbackChunks.slice(safeTargetIndex)
+            : null;
         this.speakRunId += 1;
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
@@ -1542,13 +1740,29 @@ export class TTSService {
                 highlightMode: this.activeHighlightMode,
                 wordBoundaryOffset: this.activeWordBoundaryOffset,
             });
-            await this.speakWithPlan(restartSegments, runId, {
-                highlightMode: this.activeHighlightMode,
-            });
+            if (restartChunks) {
+                for (let index = 0; index < restartChunks.length; index++) {
+                    if (runId !== this.speakRunId)
+                        return;
+                    const absoluteIndex = safeTargetIndex + index;
+                    this.currentSeekSegmentIndex = absoluteIndex;
+                    const segment = this.seekSegments[absoluteIndex];
+                    if (segment) {
+                        this.currentBoundaryOffset = segment.startOffset;
+                    }
+                    await this.speakCatalogChunk(restartChunks[index], runId);
+                }
+            }
+            else {
+                await this.speakWithPlan(restartSegments, runId, {
+                    highlightMode: this.activeHighlightMode,
+                });
+            }
             if (runId !== this.speakRunId)
                 return;
             this.setState(PlaybackState.IDLE);
             this.clearHighlightsAndTracking();
+            this.highlightTargetResolverProvider = null;
         }
         catch (error) {
             if (runId !== this.speakRunId)
@@ -1556,6 +1770,7 @@ export class TTSService {
             this.lastError = error instanceof Error ? error.message : String(error);
             this.setState(PlaybackState.ERROR);
             this.clearHighlightsAndTracking();
+            this.highlightTargetResolverProvider = null;
             throw error;
         }
     }
@@ -1607,6 +1822,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
@@ -1620,6 +1836,7 @@ export class TTSService {
         this.currentBoundaryOffset = 0;
         this.activeWordBoundaryOffset = 0;
         this.seekSegments = [];
+        this.playbackChunks = [];
         this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;