@pie-players/pie-assessment-toolkit 0.3.28 → 0.3.30

package/dist/services/SSMLExtractor.js

@@ -16,6 +16,189 @@
  *
  * Part of PIE Assessment Toolkit.
  */
+/**
+ * Allow-listed SSML elements (from the SSML 1.1 spec subset we forward to
+ * TTS providers). Anything outside this list is unwrapped during
+ * sanitization so we never leak author-supplied scripts, iframes, or
+ * arbitrary HTML into the TTS pipeline.
+ */
+const SSML_ALLOWED_TAGS = new Set([
+    "speak",
+    "break",
+    "prosody",
+    "emphasis",
+    "say-as",
+    "sub",
+    "mark",
+    "phoneme",
+    "lang",
+    "p",
+    "s",
+    "voice",
+    "audio",
+    "lexicon",
+]);
+/**
+ * Allow-listed attributes across SSML elements. Attribute allow-listing is
+ * global (not per-tag) because the union is small and consistent across
+ * providers.
+ */
+/**
+ * Tags whose content must be dropped entirely (rather than unwrapped to
+ * preserve phrasing text). These are dangerous containers whose text
+ * payload could be re-interpreted downstream.
+ */
+const SSML_DROP_FULLY_TAGS = new Set([
+    "script",
+    "style",
+    "iframe",
+    "object",
+    "embed",
+    "foreignobject",
+    "noscript",
+    "template",
+]);
+const SSML_ALLOWED_ATTRS = new Set([
+    "alphabet",
+    "ph",
+    "time",
+    "strength",
+    "rate",
+    "pitch",
+    "volume",
+    "name",
+    "interpret-as",
+    "format",
+    "detail",
+    "language",
+    "xml:lang",
+    "lang",
+    "gender",
+    "src",
+]);
+/**
+ * Hosts that must never appear inside an SSML `<audio src>` because they
+ * would cause the server-side TTS provider to fetch a private / metadata
+ * endpoint on behalf of the request. Mirrors the SchoolCity provider's
+ * defense-in-depth check; the SSML-side block is cheap and belt-and-braces.
+ */
+const SSML_PRIVATE_AUDIO_HOSTS = [
+    /^localhost$/i,
+    /^127(?:\.\d{1,3}){3}$/,
+    /^0(?:\.\d{1,3}){3}$/,
+    /^10(?:\.\d{1,3}){3}$/,
+    /^192\.168(?:\.\d{1,3}){2}$/,
+    /^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/,
+    /^169\.254(?:\.\d{1,3}){2}$/,
+    /^::1$/,
+    /^fe80:/i,
+    /^fc00:/i,
+    /^fd[0-9a-f]{2}:/i,
+    /^metadata\.google\.internal$/i,
+    /^metadata\.azure\.internal$/i,
+    /^metadata\.packet\.net$/i,
+];
+function isSafeSsmlAudioSrc(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return false;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return false;
+    }
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "");
+    return !SSML_PRIVATE_AUDIO_HOSTS.some((pattern) => pattern.test(hostname));
+}
+/**
+ * Sanitize an SSML subtree in place: remove disallowed attributes and
+ * replace disallowed elements with their text content (so phrasing order
+ * is preserved but no scripts / iframes / unknown tags survive).
+ */
+function sanitizeSsmlElement(element) {
+    // Walk children snapshot first because we may replace nodes as we go.
+    const children = Array.from(element.children);
+    for (const child of children) {
+        const tagName = child.tagName.toLowerCase();
+        if (SSML_DROP_FULLY_TAGS.has(tagName)) {
+            child.remove();
+            continue;
+        }
+        sanitizeSsmlElement(child);
+        if (!SSML_ALLOWED_TAGS.has(tagName)) {
+            const textNode = element.ownerDocument.createTextNode(child.textContent ?? "");
+            child.replaceWith(textNode);
+        }
+    }
+    // Strip disallowed attributes on the surviving node.
+    const attrNames = Array.from(element.attributes).map((attr) => attr.name);
+    for (const attrName of attrNames) {
+        if (!SSML_ALLOWED_ATTRS.has(attrName.toLowerCase())) {
+            element.removeAttribute(attrName);
+        }
+    }
+    // Belt-and-braces: even though `src` is allow-listed, SSML `<audio>`
+    // sends its URL to a server-side TTS provider that will dereference
+    // it. Refuse non-http(s) schemes and private / cloud-metadata hosts
+    // at the SSML boundary so we never forward an SSRF primitive.
+    if (element.tagName.toLowerCase() === "audio") {
+        const src = element.getAttribute("src");
+        if (src !== null && !isSafeSsmlAudioSrc(src)) {
+            element.removeAttribute("src");
+        }
+    }
+}
+/**
+ * Serialize a sanitized `<speak>` element back to a minimal SSML string.
+ * Uses a manual walker instead of `outerHTML` so that any namespace
+ * quirks (e.g. `xmlns` attributes added by the HTML parser) are
+ * normalised and disallowed descendants cannot reappear through quirks
+ * in the serializer.
+ */
+function serializeSsmlElement(element) {
+    const tagName = element.tagName.toLowerCase();
+    const attrs = Array.from(element.attributes)
+        .filter((attr) => SSML_ALLOWED_ATTRS.has(attr.name.toLowerCase()))
+        .map((attr) => ` ${attr.name}="${escapeXmlAttr(attr.value)}"`)
+        .join("");
+    const childPieces = [];
+    for (const node of Array.from(element.childNodes)) {
+        if (node.nodeType === 3 /* text */) {
+            childPieces.push(escapeXmlText(node.nodeValue ?? ""));
+        }
+        else if (node.nodeType === 1 /* element */) {
+            const childElement = node;
+            const childTag = childElement.tagName.toLowerCase();
+            if (SSML_DROP_FULLY_TAGS.has(childTag)) {
+                continue;
+            }
+            if (SSML_ALLOWED_TAGS.has(childTag)) {
+                childPieces.push(serializeSsmlElement(childElement));
+            }
+            else {
+                childPieces.push(escapeXmlText(childElement.textContent ?? ""));
+            }
+        }
+    }
+    return `<${tagName}${attrs}>${childPieces.join("")}</${tagName}>`;
+}
+function escapeXmlText(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function escapeXmlAttr(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
 /**
  * SSMLExtractor Service
  *
@@ -107,8 +290,12 @@ export class SSMLExtractor {
                 try {
                     // Generate unique catalog ID
                     const catalogId = this.generateCatalogId(idPrefix);
-                    // Extract SSML content
-                    const ssmlContent = speakEl.outerHTML;
+                    // Sanitize before serializing so the SSML forwarded to the TTS
+                    // provider only contains spec-allowed tags/attributes. This
+                    // closes an author-content -> TTS-server pipeline that would
+                    // otherwise accept arbitrary HTML.
+                    sanitizeSsmlElement(speakEl);
+                    const ssmlContent = serializeSsmlElement(speakEl);
                     // Extract language (check both xml:lang and lang attributes)
                     const language = speakEl.getAttribute("xml:lang") ||
                         speakEl.getAttribute("lang") ||

package/dist/services/SSMLExtractor.js.map

@@ -1 +1 @@
-{"version":3,"file":"SSMLExtractor.js","sourceRoot":"","sources":["../../src/services/SSMLExtractor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SSMLExtractor.js","sourceRoot":"","sources":["../../src/services/SSMLExtractor.ts"],"names":[],"mappings":"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"}

package/dist/services/TTSService.d.ts

@@ -58,6 +58,7 @@ export declare class TTSService {
     private speakRunId;
     private currentBoundaryOffset;
     private seekSegments;
+    private sentenceHighlightSegments;
     private currentSeekSegmentIndex;
     private activeSentenceStartOffset;
     private activeHighlightMode;
@@ -117,10 +118,12 @@ export declare class TTSService {
     private createSpeechPlanSegments;
     private segmentSentences;
     private createSeekSegmentsFromText;
+    private splitSegmentsAtBoundaries;
+    private createSentenceHighlightSegments;
     private getCurrentSeekSegmentIndex;
     private speakWithPlan;
     private highlightSentenceSegment;
-    private getSeekSegmentIndexForOffset;
+    private getSegmentIndexForOffset;
     private highlightSentenceForOffset;
     /**
      * Find text node and offsets for highlighting a word
@@ -139,6 +142,7 @@ export declare class TTSService {
     speak(text: string, options?: SpeakOptions): Promise<void>;
     private shouldAttemptBrowserFallback;
     private switchProviderToBrowser;
+    private isBrowserSpeechFallbackAvailable;
     private retryWithBrowserFallback;
     private applyLanguageSettings;
     private resolveSpeechContent;
@@ -174,6 +178,13 @@ export declare class TTSService {
      * Stop playback
      */
     stop(): void;
+    /**
+     * Request UI-level TTS controls to hand off/deactivate.
+     *
+     * This is intentionally separate from playback controls so hosts can orchestrate
+     * control handoff explicitly (for example: stop playback, then dismiss controls).
+     */
+    requestControlHandoff(): void;
     /**
      * Check if currently playing
      */

package/dist/services/TTSService.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TTSService.d.ts","sourceRoot":"","sources":["../../src/services/TTSService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACX,YAAY,EAEZ,SAAS,EACT,uBAAuB,EACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AACtF,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAqB/D,YAAY,EACX,YAAY,EACZ,0BAA0B,EAC1B,SAAS,EACT,UAAU,EACV,uBAAuB,GACvB,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,oBAAY,aAAa;IACxB,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,MAAM,WAAW;IACjB,KAAK,UAAU;CACf;AAWD,KAAK,aAAa,GAAG,MAAM,GAAG,UAAU,CAAC;AAEzC,UAAU,YAAY;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qBAAqB,CAAC,EAAE,aAAa,CAAC;CACtC;AASD;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,oBAAoB,CAAwC;IACpE,OAAO,CAAC,eAAe,CAA6C;IACpE,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,qBAAqB,CAAwB;IACrD,OAAO,CAAC,eAAe,CACZ;IACX,OAAO,CAAC,SAAS,CAA0D;IAC3E,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,yBAAyB,CAAuB;IACxD,OAAO,CAAC,mBAAmB,CAAyB;IACpD,OAAO,CAAC,iBAAiB,CAEV;;YAID,aAAa;IAW3B;;;;;OAKG;IACG,UAAU,CACf,QAAQ,EAAE,YAAY,EACtB,MAAM,GAAE,OAAO,CAAC,SAAS,CAAM,GAC7B,OAAO,CAAC,IAAI,CAAC;IAmBhB;;;;;;;OAOG;IACG,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBjE;;OAEG;IACH,uBAAuB,CAAC,WAAW,EAAE,uBAAuB,GAAG,IAAI;IAInE;;;;;;;OAOG;IACH,kBAAkB,CAAC,QAAQ,EAAE,4BAA4B,GAAG,IAAI;IAIhE;;OAEG;IACH,eAAe,IAAI,uBAAuB,GAAG,IAAI;IAIjD;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAyBhC,OAAO,CAAC,gBAAgB;IA+DxB,OAAO,CAAC,yBAAyB;IA8BjC,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,yBAAyB;IAKjC,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,mBAAmB;IA+B3B,OAAO,CAAC,iBAAiB;IA6CzB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,2BAA2B;IAsCnC,OAAO,CAAC,sBAAsB;IAY9B,OAAO,CAAC,wBAAwB;IAsChC,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,0BAA0B;IAclC,OAAO,CAAC,0BAA0B;YAapB,aAAa;IAsD3B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,4BAA4B;IAapC,OAAO,CAAC,0BAA0B;IAUlC;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IAyD1B;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAgFhE,OAAO,CAAC,4BAA4B;YAkBtB,uBAAuB;YA8CvB,wBAAwB;YA0BxB,qBAAqB;IAuCnC,OAAO,CAAC,oBAAoB;IA4D5B,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,uBAAuB;IAY/B,OAAO,CAAC,yBAAyB;IAiCjC,OAAO,CAAC,iCAAiC;YAyC3B,oBAAoB;IAsBlC,OAAO,CAAC,0BAA0B;IAYlC;;;;;;;OAOG;IACG,UAAU,CACf,KAAK,EAAE,KAAK,EACZ,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,GACxC,OAAO,CAAC,IAAI,CAAC;IA0ChB;;OAEG;IACH,KAAK,IAAI,IAAI;IASb;;OAEG;IACH,MAAM,IAAI,IAAI;YASA,MAAM;IAyCd,WAAW,CAAC,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrC,YAAY,CAAC,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C;;OAEG;IACH,IAAI,IAAI,IAAI;IAqBZ;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,QAAQ,IAAI,aAAa;IAIzB;;OAEG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;;OAGG;IACH,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAOzE;;OAEG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI;IAU1E;;OAEG;IACH,OAAO,CAAC,QAAQ;CAqEhB"}
+{"version":3,"file":"TTSService.d.ts","sourceRoot":"","sources":["../../src/services/TTSService.ts"],"names":[],"mappings":"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"}

package/dist/services/TTSService.js

@@ -18,6 +18,7 @@
 import { BrowserTTSProvider } from "./tts/browser-provider.js";
 import { collectVisibleTextAndMap, extractVisibleText as extractVisibleTextFromDOM, isElementHiddenForTTS, normalizeTextForSpeech, } from "./tts/text-processing.js";
 import { segmentSentences as segmentTextToSentences, } from "./tts/text-segmentation.js";
+import { PIE_TTS_CONTROL_HANDOFF_EVENT, } from "./tts-control-events.js";
 /**
  * Playback state
  */
@@ -50,6 +51,7 @@ export class TTSService {
     speakRunId = 0;
     currentBoundaryOffset = 0;
     seekSegments = [];
+    sentenceHighlightSegments = [];
     currentSeekSegmentIndex = 0;
     activeSentenceStartOffset = null;
     activeHighlightMode = "word";
@@ -403,6 +405,52 @@ export class TTSService {
         })
             .filter((segment) => segment.text.length > 0);
     }
+    splitSegmentsAtBoundaries(segments, boundaryOffsets, sourceText) {
+        if (segments.length === 0 || boundaryOffsets.length === 0)
+            return segments;
+        const normalizedBoundaries = Array.from(new Set(boundaryOffsets))
+            .filter((offset) => Number.isFinite(offset) && offset > 0)
+            .sort((left, right) => left - right);
+        if (normalizedBoundaries.length === 0)
+            return segments;
+        const result = [];
+        for (const segment of segments) {
+            const segmentStart = segment.startOffset;
+            const segmentEnd = segment.startOffset + segment.text.length;
+            const splitPoints = normalizedBoundaries.filter((offset) => offset > segmentStart && offset < segmentEnd);
+            if (splitPoints.length === 0) {
+                result.push(segment);
+                continue;
+            }
+            let cursor = segmentStart;
+            for (const point of [...splitPoints, segmentEnd]) {
+                const raw = sourceText.substring(cursor, point);
+                const leadingWhitespace = raw.match(/^\s*/)?.[0].length || 0;
+                const trailingWhitespace = raw.match(/\s*$/)?.[0].length || 0;
+                const startOffset = cursor + leadingWhitespace;
+                const endOffset = point - trailingWhitespace;
+                if (endOffset > startOffset) {
+                    result.push({
+                        text: sourceText.substring(startOffset, endOffset),
+                        startOffset,
+                        pauseMsAfter: 0,
+                    });
+                }
+                cursor = point;
+            }
+        }
+        return result;
+    }
+    createSentenceHighlightSegments(args) {
+        const grammaticalSegments = this.createSeekSegmentsFromText(args.contentToSpeak);
+        if (!args.shouldUsePlan || args.playbackSegments.length === 0) {
+            return grammaticalSegments;
+        }
+        const structuralBoundaries = args.playbackSegments
+            .map((segment) => segment.startOffset)
+            .filter((offset) => offset > 0);
+        return this.splitSegmentsAtBoundaries(grammaticalSegments, structuralBoundaries, args.contentToSpeak);
+    }
     getCurrentSeekSegmentIndex() {
         if (this.seekSegments.length === 0)
             return 0;
@@ -475,12 +523,12 @@ export class TTSService {
         this.highlightCoordinator.highlightTTSSentence([range]);
         this.activeSentenceStartOffset = startOffset;
     }
-    getSeekSegmentIndexForOffset(offset) {
-        if (this.seekSegments.length === 0)
+    getSegmentIndexForOffset(segments, offset) {
+        if (segments.length === 0)
             return -1;
         let index = -1;
-        for (let i = 0; i < this.seekSegments.length; i++) {
-            if (this.seekSegments[i].startOffset <= offset) {
+        for (let i = 0; i < segments.length; i++) {
+            if (segments[i].startOffset <= offset) {
                 index = i;
             }
             else {
@@ -490,12 +538,13 @@ export class TTSService {
         return index;
     }
     highlightSentenceForOffset(offset) {
-        if (!this.highlightCoordinator || this.seekSegments.length === 0)
+        const segments = this.sentenceHighlightSegments;
+        if (!this.highlightCoordinator || segments.length === 0)
             return;
-        const segmentIndex = this.getSeekSegmentIndexForOffset(offset);
+        const segmentIndex = this.getSegmentIndexForOffset(segments, offset);
         if (segmentIndex < 0)
             return;
-        const segment = this.seekSegments[segmentIndex];
+        const segment = segments[segmentIndex];
         if (!segment)
             return;
         if (this.activeSentenceStartOffset === segment.startOffset)
@@ -580,6 +629,13 @@ export class TTSService {
             : shouldUsePlan && this.currentContentElement
                 ? this.createSpeechPlan(this.currentContentElement, normalizedText)
                 : this.createSeekSegmentsFromText(contentToSpeak);
+        this.sentenceHighlightSegments = this.hasExplicitBreakSemantics(contentToSpeak)
+            ? []
+            : this.createSentenceHighlightSegments({
+                contentToSpeak,
+                shouldUsePlan,
+                playbackSegments: this.seekSegments,
+            });
         this.setState(PlaybackState.LOADING);
         this.prepareHighlightsForSpeak({
             contentToSpeak,
@@ -645,23 +701,19 @@ export class TTSService {
         const message = (error instanceof Error ? error.message : String(error))
             .toLowerCase()
             .trim();
-        if (!message)
+        // Avoid fallback for expected cancellation/superseded flows.
+        if (message.includes("superseded by a newer request"))
             return false;
-        if (message.includes("text-to-speech service encountered an error"))
-            return true;
-        if (message.includes("service unavailable"))
-            return true;
-        if (message.includes("failed to fetch"))
-            return true;
-        if (message.includes("network error"))
-            return true;
-        if (message.includes("failed to download synthesized audio"))
-            return true;
-        if (/\b5\d{2}\b/.test(message))
-            return true;
-        if (/server returned 5\d{2}/.test(message))
-            return true;
-        return false;
+        if (message.includes("aborterror"))
+            return false;
+        if (message.includes("aborted"))
+            return false;
+        if (message.includes("cancelled"))
+            return false;
+        if (message.includes("canceled"))
+            return false;
+        // For non-browser providers, default to browser fallback on runtime errors.
+        return true;
     }
     async switchProviderToBrowser(reason) {
         if (!this.currentProvider)
@@ -703,9 +755,18 @@ export class TTSService {
             return false;
         }
     }
+    isBrowserSpeechFallbackAvailable() {
+        if (typeof window === "undefined")
+            return false;
+        if (!("speechSynthesis" in window))
+            return false;
+        return typeof globalThis.SpeechSynthesisUtterance === "function";
+    }
     async retryWithBrowserFallback(args) {
         if (!this.shouldAttemptBrowserFallback(args.error))
             return false;
+        if (!this.isBrowserSpeechFallbackAvailable())
+            return false;
         const switched = await this.switchProviderToBrowser(args.error);
         if (!switched)
             return false;
@@ -824,7 +885,7 @@ export class TTSService {
         if (args.highlightMode === "sentence" && args.shouldUsePlan) {
             return;
         }
-        const initialSegment = this.seekSegments[0];
+        const initialSegment = this.sentenceHighlightSegments[0] || this.seekSegments[0];
         if (initialSegment) {
             this.highlightSentenceSegment(initialSegment.startOffset, initialSegment.text);
             console.log("[TTSService] Applied initial sentence highlighting");
@@ -889,6 +950,7 @@ export class TTSService {
         this.normalizedToDOM.clear();
         this.currentBoundaryOffset = 0;
         this.seekSegments = [];
+        this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
     }
@@ -1028,9 +1090,24 @@ export class TTSService {
         this.normalizedToDOM.clear();
         this.currentBoundaryOffset = 0;
         this.seekSegments = [];
+        this.sentenceHighlightSegments = [];
         this.currentSeekSegmentIndex = 0;
         this.activeSentenceStartOffset = null;
     }
+    /**
+     * Request UI-level TTS controls to hand off/deactivate.
+     *
+     * This is intentionally separate from playback controls so hosts can orchestrate
+     * control handoff explicitly (for example: stop playback, then dismiss controls).
+     */
+    requestControlHandoff() {
+        if (typeof window === "undefined")
+            return;
+        const detail = { source: "host" };
+        window.dispatchEvent(new CustomEvent(PIE_TTS_CONTROL_HANDOFF_EVENT, {
+            detail,
+        }));
+    }
     /**
      * Check if currently playing
      */