@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

package/dist/services/TTSService.js

@@ -1,23 +1,24 @@
 /**
  * TTSService
  *
- * Text-to-speech service with pluggable provider architecture.
- * Manages playback state, coordinates multiple TTS entry points,
- * and integrates with HighlightCoordinator for word highlighting.
+ * Owns one read-aloud session: the installed provider, playback state, and the
+ * word and sentence highlights painted through HighlightCoordinator.
  *
- * Features:
- * - Pluggable TTS providers (browser, AWS Polly, etc.)
- * - QTI 3.0 accessibility catalogs (pre-authored spoken content)
- * - Unified playback state management
- * - Prevents conflicts from simultaneous speech
- * - Word highlighting integration
- * - Playback controls: play, pause, resume, stop
- *
- * Part of PIE Assessment Toolkit.
+ * Layout:
+ * - Provider and host wiring: initialize, setCatalogResolver, the highlight
+ *   target resolver and math-speech sources.
+ * - Content resolution: catalog spoken card, then catalog-composed chunks
+ *   (script and/or recording with a plain fallback), then generated speech.
+ * - Speech plan: structural pauses, seek segments, sentence segments and the
+ *   normalized-to-DOM position map.
+ * - Playback: speakContent → executeSpeakPlayback, the run guard (speakRunId,
+ *   runOwner), the pause hold and the playback-start barrier.
+ * - Highlight painting: boundary handling, the host resolver remap, catalog
+ *   highlight plans.
+ * - Controls and state: pause/resume/stop/seek/rate, setState and listeners.
  */
 import { applyMediaFragment, enforceMediaFragment, } from "@pie-players/pie-players-shared/media";
 import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
-import { HighlightType } from "./HighlightCoordinator.js";
 import { resolveSpokenAudioMedia, } from "./spoken-audio-cards.js";
 import { DEFAULT_CONTENT_LANGUAGE, findContentLanguage, findLangAttribute, } from "../runtime/content-language.js";
 import { isSsmlDocument } from "./tts/ssml/spoken-text.js";
@@ -32,7 +33,6 @@ import { toTTSStartFailure } from "./tts/start-failure.js";
 import { segmentSentences as segmentTextToSentences, splitTextToLength, } from "./tts/text-segmentation.js";
 import { createTTSHighlightPlan, normalizeSpeechChunks, resolveReadableRegion, } from "./tts/highlight-pipeline/index.js";
 import { createRangesFromVisibleMap } from "./tts/highlight-pipeline/visible-map-range.js";
-import { PIE_TTS_CONTROL_HANDOFF_EVENT, } from "./tts-control-events.js";
 // Debug lines need `PIE_TTS_DEBUG=1` or `globalThis.__PIE_TTS_DEBUG__ = true`.
 const logger = createPieLogger("tts-service", isTtsDebugEnabled);
 /**
@@ -46,6 +46,14 @@ export var PlaybackState;
     PlaybackState["PAUSED"] = "paused";
     PlaybackState["ERROR"] = "error";
 })(PlaybackState || (PlaybackState = {}));
+const DEFAULT_STRUCTURAL_PAUSE_PROFILE = {
+    baseMs: 280,
+    units: { minor: 0.65, section: 1.0, major: 1.35 },
+    minMs: 120,
+    maxMs: 900,
+};
+const MIN_PLAYBACK_RATE = 0.25;
+const MAX_PLAYBACK_RATE = 4;
 const optionalString = (value) => typeof value === "string" && value.trim() ? value.trim() : undefined;
 const hostLocalesOf = (options, previous = {}) => {
     if (!options)
@@ -89,12 +97,53 @@ const sameRenderableHighlightTarget = (left, right) => {
     return false;
 };
 /**
- * TTSService
- *
+ * Where two texts first differ, with 20 characters of context each side;
+ * debug tracing only.
+ */
+const firstDifference = (spoken, normalized) => {
+    for (let i = 0; i < Math.min(spoken.length, normalized.length); i++) {
+        if (spoken[i] !== normalized[i]) {
+            return {
+                index: i,
+                spokenChar: spoken[i],
+                normalizedChar: normalized[i],
+                spokenContext: spoken.substring(Math.max(0, i - 20), i + 20),
+                normalizedContext: normalized.substring(Math.max(0, i - 20), i + 20),
+            };
+        }
+    }
+    return null;
+};
+/** The authored `data-tts-break-ms` pause, when it is a positive number. */
+const explicitBreakMsOf = (element) => {
+    const ms = Number(element.getAttribute("data-tts-break-ms"));
+    return Number.isFinite(ms) && ms > 0 ? ms : null;
+};
+const isBlockDisplay = (element) => {
+    if (typeof window === "undefined")
+        return false;
+    const display = window.getComputedStyle(element).display;
+    return (display === "block" ||
+        display === "list-item" ||
+        display.startsWith("table") ||
+        display === "flex" ||
+        display === "grid");
+};
+/** `[start, end)` of `text` with its surrounding whitespace excluded. */
+const trimSpan = (text, start, end) => {
+    const raw = text.substring(start, end);
+    return {
+        start: start + (raw.match(/^\s*/)?.[0].length || 0),
+        end: end - (raw.match(/\s*$/)?.[0].length || 0),
+    };
+};
+/**
  * Instantiable service for text-to-speech functionality.
  * Each instance manages its own playback state.
  */
 export class TTSService {
+    // currentProvider is the provider the host installed; provider is the
+    // implementation its initialize() returned, which does the speaking.
     currentProvider = null;
     provider = null;
     highlightCoordinator = null;
@@ -115,10 +164,18 @@ export class TTSService {
     mathSpeechSource = null;
     currentText = null;
     currentContentElement = null;
+    // Offsets in the normalized visible text of the element being read, mapped
+    // to DOM text positions; word boundaries resolve through it.
     normalizedToDOM = new Map();
     listeners = new Set();
     lastError = null;
+    // Bumped by every new run and by stop, restart and dispose; an async step
+    // that resumes under an older id has been superseded and returns.
     speakRunId = 0;
+    runOwner = null;
+    // currentBoundaryOffset is the spoken-text offset the run has reached, which
+    // seek and word boundaries count from; activeWordBoundaryOffset is where the
+    // spoken text starts in the element's visible text, nonzero for a selection.
     currentBoundaryOffset = 0;
     activeWordBoundaryOffset = 0;
     seekSegments = [];
@@ -142,20 +199,21 @@ export class TTSService {
     pendingPlaybackRateRequest = null;
     activePlaybackRate = null;
     activeHighlightMode = "word";
+    // What the plan part being spoken paints in sentence mode.
+    wordlessPartHighlight = null;
     lastRenderedRegionTarget = null;
     telemetryReporter = null;
-    // Memoized SRE resolver for the runtime generated-speech path (PIE-623).
+    // Memoized SRE resolver for the runtime generated-speech path.
     // Caches DOM-free spoken text keyed by SRE settings and MathML source across
     // utterances within this service instance.
     generatedMathSpeechResolver = createMemoizedMathSpeechResolver();
-    constructor() { }
     clearPlaybackStartBarrier(cleanup = this.playbackStartBarrierCleanup) {
         cleanup?.();
         if (this.playbackStartBarrierCleanup === cleanup) {
             this.playbackStartBarrierCleanup = null;
         }
     }
-    notifyPlaybackStarted(runId) {
+    notifyPlaybackStarted(runId, playback) {
         if (this.playbackStartDeferredRunId !== runId ||
             runId !== this.speakRunId) {
             return;
@@ -170,7 +228,27 @@ export class TTSService {
         for (const applyHighlight of pendingHighlights) {
             applyHighlight();
         }
+        if (playback?.wordBoundaries === false)
+            this.highlightWordlessPlayback();
     }
+    /**
+     * A word-mode part whose playback sends no boundaries, such as a server
+     * response without speech marks, highlights as a sentence-mode read does.
+     * Catalog chunks and a single speak highlight the same in both modes.
+     */
+    highlightWordlessPlayback() {
+        const paint = this.wordlessPartHighlight;
+        if (!paint || this.activeHighlightMode !== "word")
+            return;
+        this.highlightCoordinator?.clearTTSWord();
+        paint();
+    }
+    /**
+     * Defers marking the run playing, and the highlights queued through
+     * runWhenPlaybackStarts, until the provider or the recording signals that
+     * audio started. Returns the barrier's cleanup, or null when nothing will
+     * signal a start, in which case the caller marks the run playing itself.
+     */
     installPlaybackStartBarrier(runId, hasMediaStartSignal = false) {
         this.clearPlaybackStartBarrier();
         const provider = this.provider;
@@ -178,12 +256,12 @@ export class TTSService {
         if (!startAwareProvider && !hasMediaStartSignal)
             return null;
         const previousOnPlaybackStart = startAwareProvider?.onPlaybackStart;
-        const onPlaybackStart = () => {
+        const onPlaybackStart = (playback) => {
             try {
-                this.notifyPlaybackStarted(runId);
+                this.notifyPlaybackStarted(runId, playback);
             }
             finally {
-                previousOnPlaybackStart?.();
+                previousOnPlaybackStart?.(playback);
             }
         };
         if (startAwareProvider) {
@@ -259,17 +337,19 @@ export class TTSService {
      * run, whatever it is still waiting for: the provider, its content or the
      * provider's audio.
      */
-    beginRun() {
+    beginRun(owner) {
         // A recorded clip that starts the new run would otherwise play over the
         // previous run's synthesis, which only the provider's next speak stops.
         const supersedesPlayback = this.state === PlaybackState.LOADING ||
             this.state === PlaybackState.PLAYING ||
             this.state === PlaybackState.PAUSED;
         const runId = ++this.speakRunId;
+        this.runOwner = owner;
         this.abandonRun();
         if (supersedesPlayback)
             this.provider?.stop();
-        this.setState(PlaybackState.LOADING);
+        // Announced even from loading, so a listener sees the owner change.
+        this.setState(PlaybackState.LOADING, true);
         return runId;
     }
     /** The run's audio is sounding; under a pause, it sounds again on resume. */
@@ -295,9 +375,6 @@ export class TTSService {
     }
     /**
      * Initialize TTS service with a provider
-     *
-     * @param provider TTS provider instance
-     * @param config Provider configuration
      */
     async initialize(provider, config = {}) {
         if (this.disposed)
@@ -312,7 +389,8 @@ export class TTSService {
         this.provider = await provider.initialize(config);
     }
     /**
-     * Update rate, pitch, voice or provider options without reinitializing.
+     * Update rate, pitch, volume, voice or provider options without
+     * reinitializing.
      * `providerOptions` merge over the ones already configured.
      */
     async updateSettings(settings) {
@@ -391,8 +469,6 @@ export class TTSService {
      *
      * When set, the speak() method will check for pre-authored spoken
      * content in catalogs before falling back to generated TTS.
-     *
-     * @param resolver AccessibilityCatalogResolver instance
      */
     setCatalogResolver(resolver) {
         this.catalogResolver = resolver;
@@ -529,12 +605,6 @@ export class TTSService {
         }
         this.highlightCoordinator.highlightTTSSentence(paintedRanges);
     }
-    /**
-     * Get provider capabilities
-     */
-    getCapabilities() {
-        return this.currentProvider?.getCapabilities() || null;
-    }
     providerOptions() {
         const options = this.ttsConfig.providerOptions;
         return options && typeof options === "object" ? options : {};
@@ -603,8 +673,8 @@ export class TTSService {
         });
     }
     /**
-     * Build a character-by-character map from normalized text positions to DOM positions
-     * This handles the complexity of whitespace normalization
+     * Text-collection options for `locale`, with the provider's boundary-spacing
+     * mode when it names a known one.
      */
     getTextProcessingOptions(locale) {
         const mode = this.providerOptions().textNormalization?.boundarySpacingMode;
@@ -640,6 +710,10 @@ export class TTSService {
         }
         return normalizeSREMathSpeechOptions(this.providerOptions().mathSpeech);
     }
+    /**
+     * Rebuilds normalizedToDOM from `element`'s visible text; traced runs also
+     * log how it differs from `spokenText`.
+     */
     buildPositionMap(element, spokenText, language) {
         this.normalizedToDOM.clear();
         const { text: normalizedDomText, map } = collectVisibleTextAndMap(element, this.getTextProcessingOptions(language));
@@ -655,20 +729,7 @@ export class TTSService {
             normalizedPreview: normalizedDomText.substring(0, 150),
             differAtIndex: spokenText === normalizedDomText
                 ? null
-                : (() => {
-                    for (let i = 0; i < Math.min(spokenText.length, normalizedDomText.length); i++) {
-                        if (spokenText[i] !== normalizedDomText[i]) {
-                            return {
-                                index: i,
-                                spokenChar: spokenText[i],
-                                normalizedChar: normalizedDomText[i],
-                                spokenContext: spokenText.substring(Math.max(0, i - 20), i + 20),
-                                normalizedContext: normalizedDomText.substring(Math.max(0, i - 20), i + 20),
-                            };
-                        }
-                    }
-                    return null;
-                })(),
+                : firstDifference(spokenText, normalizedDomText),
         });
         logger.debug("Position map built:", {
             entries: this.normalizedToDOM.size,
@@ -697,20 +758,21 @@ export class TTSService {
             }
             return fallback;
         };
+        const defaults = DEFAULT_STRUCTURAL_PAUSE_PROFILE;
         return {
-            baseMs: toNumber(custom.baseMs, 280),
+            baseMs: toNumber(custom.baseMs, defaults.baseMs),
             units: {
-                minor: toNumber(customUnits.minor, 0.65),
-                section: toNumber(customUnits.section, 1.0),
-                major: toNumber(customUnits.major, 1.35),
+                minor: toNumber(customUnits.minor, defaults.units.minor),
+                section: toNumber(customUnits.section, defaults.units.section),
+                major: toNumber(customUnits.major, defaults.units.major),
             },
-            minMs: toNumber(custom.minMs, 120),
-            maxMs: toNumber(custom.maxMs, 900),
+            minMs: toNumber(custom.minMs, defaults.minMs),
+            maxMs: toNumber(custom.maxMs, defaults.maxMs),
         };
     }
     resolvePauseMsFromUnits(units) {
         const profile = this.getStructuralPauseProfile();
-        const rate = Math.max(0.25, Math.min(4, Number(this.ttsConfig.rate || 1)));
+        const rate = Math.max(MIN_PLAYBACK_RATE, Math.min(MAX_PLAYBACK_RATE, Number(this.ttsConfig.rate || 1)));
         const raw = (profile.baseMs * Math.max(0, units)) / rate;
         return Math.max(profile.minMs, Math.min(profile.maxMs, Math.round(raw)));
     }
@@ -730,12 +792,8 @@ export class TTSService {
             return false;
         return /<\s*break\b|<\s*speak\b|<\s*prosody\b|<\s*p\b|<\s*s\b/i.test(text);
     }
-    isElementHidden(element) {
-        return isElementHiddenForTTS(element);
-    }
     getBoundaryStrength(element) {
-        const explicitBreakMs = Number(element.getAttribute("data-tts-break-ms"));
-        if (Number.isFinite(explicitBreakMs) && explicitBreakMs > 0)
+        if (explicitBreakMsOf(element) !== null)
             return "major";
         const tagName = element.tagName.toUpperCase();
         if (tagName.match(/^H[1-6]$/))
@@ -750,26 +808,16 @@ export class TTSService {
             tagName === "LI") {
             return "section";
         }
-        if (typeof window !== "undefined") {
-            const display = window.getComputedStyle(element).display;
-            if (display === "block" ||
-                display === "list-item" ||
-                display.startsWith("table") ||
-                display === "flex" ||
-                display === "grid") {
-                return "minor";
-            }
-        }
         return "minor";
     }
     getBoundaryAnchor(textNode, root) {
         let current = flatTreeParentElement(textNode);
         let best = null;
         while (current && current !== root) {
-            if (this.isElementHidden(current))
+            if (isElementHiddenForTTS(current))
                 return null;
-            const explicitBreakMs = Number(current.getAttribute("data-tts-break-ms"));
-            if (Number.isFinite(explicitBreakMs) && explicitBreakMs > 0) {
+            const explicitBreakMs = explicitBreakMsOf(current);
+            if (explicitBreakMs !== null) {
                 return {
                     anchor: current,
                     units: explicitBreakMs / this.getStructuralPauseProfile().baseMs,
@@ -784,18 +832,8 @@ export class TTSService {
                 best = current;
                 break;
             }
-            if (!best) {
-                if (typeof window !== "undefined") {
-                    const display = window.getComputedStyle(current).display;
-                    if (display === "block" ||
-                        display === "list-item" ||
-                        display.startsWith("table") ||
-                        display === "flex" ||
-                        display === "grid") {
-                        best = current;
-                    }
-                }
-            }
+            if (!best && isBlockDisplay(current))
+                best = current;
             current = flatTreeParentElement(current);
         }
         if (!best)
@@ -812,7 +850,7 @@ export class TTSService {
      * part of it.
      */
     createSpeechPlan(contentElement, normalizedText, textOffset, language) {
-        const boundaries = this.collectSpeechPlanBoundaries(contentElement, normalizedText, language);
+        const boundaries = this.collectSpeechPlanBoundaries(contentElement, language);
         if (textOffset === 0) {
             return this.createSpeechPlanSegments(normalizedText, boundaries);
         }
@@ -822,7 +860,7 @@ export class TTSService {
         }
         return this.createSpeechPlanSegments(normalizedText, shifted);
     }
-    collectSpeechPlanBoundaries(contentElement, normalizedText, language) {
+    collectSpeechPlanBoundaries(contentElement, language) {
         const boundaries = new Map();
         // The same locale the position map used, so the boundary offsets index the
         // text the map built.
@@ -832,7 +870,7 @@ export class TTSService {
         for (const textNode of flatTreeTextNodes(contentElement)) {
             const parent = flatTreeParentElement(textNode);
             if (parent &&
-                !this.isElementHidden(parent) &&
+                !isElementHiddenForTTS(parent) &&
                 !isNodeSuppressedForTTS(textNode)) {
                 const boundary = this.getBoundaryAnchor(textNode, contentElement);
                 const boundaryPoint = nodeStartOffsets.get(textNode);
@@ -863,11 +901,7 @@ export class TTSService {
         const segments = [];
         let start = 0;
         for (const point of points) {
-            const raw = normalizedText.substring(start, point);
-            const leading = raw.match(/^\s*/)?.[0].length || 0;
-            const trailing = raw.match(/\s*$/)?.[0].length || 0;
-            const segmentStart = start + leading;
-            const segmentEnd = point - trailing;
+            const { start: segmentStart, end: segmentEnd } = trimSpan(normalizedText, start, point);
             if (segmentEnd > segmentStart) {
                 const text = normalizedText.substring(segmentStart, segmentEnd);
                 segments.push({
@@ -925,11 +959,7 @@ export class TTSService {
             }
             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;
+                const { start: startOffset, end: endOffset } = trimSpan(sourceText, cursor, point);
                 if (endOffset > startOffset) {
                     result.push({
                         text: sourceText.substring(startOffset, endOffset),
@@ -953,6 +983,9 @@ export class TTSService {
         return this.splitSegmentsAtBoundaries(grammaticalSegments, structuralBoundaries, args.contentToSpeak);
     }
     createSeekSegmentsFromSpeechChunks(chunks) {
+        // One seek segment per chunk, at offsets into a virtual text that joins the
+        // chunks with one separator character. A chunk whose speech is SSML is
+        // measured by its plain fallback or visible text.
         let offset = 0;
         return chunks.map((chunk) => {
             const speechText = chunk.plainFallback?.speechText ||
@@ -966,23 +999,12 @@ export class TTSService {
                 startOffset: offset,
                 pauseMsAfter: 0,
             };
-            offset += Math.max(1, text.length + 1);
+            offset += text.length + 1;
             return segment;
         });
     }
     getCurrentSeekSegmentIndex() {
-        if (this.seekSegments.length === 0)
-            return 0;
-        let index = 0;
-        for (let i = 0; i < this.seekSegments.length; i++) {
-            if (this.seekSegments[i].startOffset <= this.currentBoundaryOffset) {
-                index = i;
-            }
-            else {
-                break;
-            }
-        }
-        return index;
+        return Math.max(0, this.getSegmentIndexForOffset(this.seekSegments, this.currentBoundaryOffset));
     }
     async speakWithPlan(segments, runId, options) {
         if (!this.provider || segments.length === 0)
@@ -1022,12 +1044,21 @@ export class TTSService {
             if (runId !== this.speakRunId)
                 return;
             this.currentBoundaryOffset = segment.startOffset;
+            const highlightSegment = () => {
+                this.highlightSentenceSegment(segment.startOffset, segment.text);
+            };
             if (shouldTrackSentenceProgress) {
-                this.runWhenPlaybackStarts(runId, () => {
-                    this.highlightSentenceSegment(segment.startOffset, segment.text);
-                });
+                this.runWhenPlaybackStarts(runId, highlightSegment);
+            }
+            this.wordlessPartHighlight = highlightSegment;
+            try {
+                await this.speakWithinLimit(segment.text, runId);
+            }
+            finally {
+                if (this.wordlessPartHighlight === highlightSegment) {
+                    this.wordlessPartHighlight = null;
+                }
             }
-            await this.speakWithinLimit(segment.text, runId);
             const pauseMs = segment.pauseMsAfter ?? 0;
             if (pauseMs > 0 && runId === this.speakRunId) {
                 await this.waitStructuralPause(pauseMs);
@@ -1100,7 +1131,8 @@ export class TTSService {
         const pendingReadiness = this.pendingReadiness();
         // A speak waiting on its provider is already the current run, so a pause
         // or stop issued meanwhile applies to it.
-        const waitingRunId = pendingReadiness ? this.beginRun() : null;
+        const owner = options.ownerId ?? null;
+        const waitingRunId = pendingReadiness ? this.beginRun(owner) : null;
         if (pendingReadiness) {
             try {
                 await pendingReadiness;
@@ -1128,7 +1160,38 @@ export class TTSService {
                 this.setState(PlaybackState.IDLE);
             return;
         }
-        await this.speakContent(content.text, content.options, waitingRunId ?? this.beginRun());
+        const runId = waitingRunId ?? this.beginRun(owner);
+        if (options.rate !== undefined ||
+            options.pitch !== undefined ||
+            options.volume !== undefined) {
+            await this.applyRunSettings(options);
+            if (runId !== this.speakRunId)
+                return;
+        }
+        await this.speakContent(content.text, content.options, runId);
+    }
+    /**
+     * Sets the rate, pitch and volume a run starts at, after any rate write in
+     * flight. The run has no playback yet, so nothing restarts.
+     */
+    async applyRunSettings(options) {
+        await this.playbackRateWriteQueue;
+        const settings = {};
+        if (options.rate !== undefined) {
+            const nextRate = this.normalizePlaybackRate(options.rate);
+            const currentRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
+            if (nextRate !== currentRate)
+                settings.rate = nextRate;
+        }
+        if (options.pitch !== undefined && options.pitch !== this.ttsConfig.pitch) {
+            settings.pitch = options.pitch;
+        }
+        if (options.volume !== undefined &&
+            options.volume !== this.ttsConfig.volume) {
+            settings.volume = options.volume;
+        }
+        if (Object.keys(settings).length > 0)
+            await this.updateSettings(settings);
     }
     /**
      * Suppression is read from the live ancestors of what is read, because the
@@ -1143,22 +1206,38 @@ export class TTSService {
     resolveElementTarget(root, options, language) {
         if (this.isSuppressedTarget(root))
             return null;
-        // Math-aware, so an element holding only an equation still reads.
+        const contentOptions = {
+            catalogId: options.catalogId,
+            catalogContext: options.catalogContext,
+            language: language.locale,
+            contentLanguage: language.contentLanguage,
+            contentElement: root,
+        };
+        // Math-aware, so an element holding only an equation still reads; a spoken
+        // card reads for content with no text, an image among them.
         const text = collectMathAwareTextAndMap(root, this.getTextProcessingOptions(language.locale)).visibleText.trim();
-        if (!text) {
+        if (!text && !this.holdsSpokenCard(root, contentOptions)) {
             console.warn("[tts] the content to read holds no speakable text; nothing was spoken.");
             return null;
         }
-        return {
-            text,
-            options: {
-                catalogId: options.catalogId,
-                catalogContext: options.catalogContext,
-                language: language.locale,
-                contentLanguage: language.contentLanguage,
-                contentElement: root,
-            },
-        };
+        return { text, options: contentOptions };
+    }
+    /** Whether the root's card, or a card of a node inside it, would be read. */
+    holdsSpokenCard(root, options) {
+        if (!this.catalogResolver)
+            return false;
+        if (options.catalogId) {
+            const card = this.catalogResolver.getAlternative(options.catalogId, {
+                type: "spoken",
+                language: options.language,
+                useFallback: true,
+                context: options.catalogContext,
+                form: "content",
+            });
+            if (card?.content !== undefined)
+                return true;
+        }
+        return this.collectCatalogSpeechChunks(root, options).some((chunk) => chunk.sourceElement);
     }
     resolveRangeTarget(range, options, language) {
         if (this.isSuppressedTarget(range.commonAncestorContainer))
@@ -1237,27 +1316,35 @@ export class TTSService {
             this.logResolvedSpeechContent({
                 contentToSpeak,
                 speechSource,
-                catalogId: options?.catalogId,
+                catalogId: options.catalogId,
             });
             this.initializeSpeakTracking(highlightText, options);
             const highlightMode = speechMatchesVisibleText
                 ? this.resolveHighlightMode()
                 : "sentence";
             this.activeHighlightMode = highlightMode;
-            this.activeWordBoundaryOffset = options?.wordBoundaryOffset || 0;
+            const wordBoundaryOffset = options.wordBoundaryOffset || 0;
+            this.activeWordBoundaryOffset = wordBoundaryOffset;
             const hasExplicitBreaks = this.hasExplicitBreakSemantics(contentToSpeak);
             const shouldUsePlan = !!this.currentContentElement &&
                 !usedCatalogSpoken &&
                 !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, options?.wordBoundaryOffset || 0, options?.language)
-                        : this.createSeekSegmentsFromText(highlightText);
+            if (this.playbackChunks.length) {
+                this.seekSegments = this.createSeekSegmentsFromSpeechChunks(this.playbackChunks);
+            }
+            else if (hasExplicitBreaks || !speechMatchesVisibleText) {
+                // Authored SSML breaks, and speech that differs from the visible text,
+                // leave no visible-text offsets to seek to.
+                this.seekSegments = [];
+            }
+            else if (shouldUsePlan && this.currentContentElement) {
+                this.seekSegments = this.createSpeechPlan(this.currentContentElement, normalizedText, wordBoundaryOffset, options.language);
+            }
+            else {
+                this.seekSegments = this.createSeekSegmentsFromText(highlightText);
+            }
             this.sentenceHighlightSegments = hasExplicitBreaks
                 ? []
                 : this.createSentenceHighlightSegments({
@@ -1276,7 +1363,7 @@ export class TTSService {
             if (speechMatchesVisibleText) {
                 this.configureWordBoundaryHighlighting({
                     highlightMode,
-                    wordBoundaryOffset: options?.wordBoundaryOffset || 0,
+                    wordBoundaryOffset,
                 });
             }
             else {
@@ -1421,6 +1508,9 @@ export class TTSService {
         };
     }
     collectCatalogSpeechChunks(root, options) {
+        const catalogResolver = this.catalogResolver;
+        if (!catalogResolver)
+            return [];
         const chunks = [];
         let textBuffer = "";
         const flushTextBuffer = () => {
@@ -1457,14 +1547,14 @@ export class TTSService {
             // Two lookups rather than one, because `form` is a preference: asking for
             // the payload form happily returns a script card when no recording
             // exists, so the answer has to be checked rather than assumed.
-            const audioCard = this.catalogResolver.getAlternative(catalogIdRef, {
+            const audioCard = catalogResolver.getAlternative(catalogIdRef, {
                 ...lookup,
                 form: "payload",
             });
             const audio = audioCard?.payload
                 ? (resolveSpokenAudioMedia({ payload: audioCard.payload }) ?? undefined)
                 : undefined;
-            const scriptCard = this.catalogResolver.getAlternative(catalogIdRef, {
+            const scriptCard = catalogResolver.getAlternative(catalogIdRef, {
                 ...lookup,
                 form: "content",
             });
@@ -1518,47 +1608,45 @@ export class TTSService {
                 const visibleText = collectedVisible.visibleText ||
                     normalizeTextForSpeech(flatTextContent(element));
                 const regionElement = resolveReadableRegion(element, root);
-                // The script chunk, when there is a script. Built exactly as before,
-                // and it doubles as the recording's fallback: word-level alignment is
-                // only meaningful for the synthesized path, which is the one that runs
-                // if the audio cannot play.
-                const scriptChunk = catalog.script !== undefined
-                    ? (() => {
-                        const script = catalog.script;
-                        const alignment = createCatalogSpanAlignment({
+                // The script chunk doubles as the recording's fallback: word-level
+                // alignment is meaningful only on the synthesized path, which is the one
+                // that runs if the audio cannot play.
+                let scriptChunk = null;
+                if (catalog.script !== undefined) {
+                    const script = catalog.script;
+                    const alignment = createCatalogSpanAlignment({
+                        speechText: script,
+                        visibleText,
+                    });
+                    const mathElement = getSingleMathElementForAlignment(element, visibleText);
+                    const mathAlignment = mathElement
+                        ? createMathAwareAlignment({
+                            mathElement,
                             speechText: script,
-                            visibleText,
-                        });
-                        const mathElement = getSingleMathElementForAlignment(element, visibleText);
-                        const mathAlignment = mathElement
-                            ? createMathAwareAlignment({
-                                mathElement,
+                        })
+                        : undefined;
+                    const mathAlignments = mathAlignment
+                        ? undefined
+                        : getMathElementsForAlignment(element).map((candidate) => ({
+                            element: candidate,
+                            alignment: createMathAwareAlignment({
+                                mathElement: candidate,
                                 speechText: script,
-                            })
-                            : undefined;
-                        const mathAlignments = mathAlignment
-                            ? undefined
-                            : getMathElementsForAlignment(element).map((candidate) => ({
-                                element: candidate,
-                                alignment: createMathAwareAlignment({
-                                    mathElement: candidate,
-                                    speechText: script,
-                                }),
-                            }));
-                        return {
-                            speechText: script,
-                            visibleText,
-                            sourceElement: element,
-                            regionElement,
-                            speechMatchesVisibleText: normalizeTextForSpeech(script) === visibleText,
-                            playbackMode: alignment.playbackMode,
-                            alignment,
-                            mathAlignment,
-                            mathAlignments,
-                            visibleMap: collectedVisible.map,
-                        };
-                    })()
-                    : null;
+                            }),
+                        }));
+                    scriptChunk = {
+                        speechText: script,
+                        visibleText,
+                        sourceElement: element,
+                        regionElement,
+                        speechMatchesVisibleText: normalizeTextForSpeech(script) === visibleText,
+                        playbackMode: alignment.playbackMode,
+                        alignment,
+                        mathAlignment,
+                        mathAlignments,
+                        visibleMap: collectedVisible.map,
+                    };
+                }
                 if (catalog.audio) {
                     chunks.push(scriptChunk
                         ? {
@@ -1743,7 +1831,7 @@ export class TTSService {
             this.lastRenderedRegionTarget = null;
             if (chunk.regionRange) {
                 const ranges = createRangesFromVisibleMap(chunk.visibleMap, 0, chunk.visibleText.length);
-                this.highlightCoordinator.clearHighlights(HighlightType.TTS_WORD);
+                this.highlightCoordinator.clearTTSWord();
                 this.paintTTSSentenceRanges(ranges.length > 1 ? ranges : [chunk.regionRange]);
                 return;
             }
@@ -1751,7 +1839,7 @@ export class TTSService {
                 return;
             const range = document.createRange();
             range.selectNodeContents(element);
-            this.highlightCoordinator.clearHighlights(HighlightType.TTS_WORD);
+            this.highlightCoordinator.clearTTSWord();
             this.paintTTSSentenceRanges([range]);
         }
         catch {
@@ -1799,7 +1887,7 @@ export class TTSService {
             // Clear the word layer so the previously spoken word does not stay
             // highlighted. (The "hold last token" behavior returns a non-null
             // target, so it does not reach here.)
-            this.highlightCoordinator.clearHighlights(HighlightType.TTS_WORD);
+            this.highlightCoordinator.clearTTSWord();
             return;
         }
         if (target.type === "text-range") {
@@ -1847,17 +1935,18 @@ export class TTSService {
             await this.speakCatalogChunkOnce(chunk, runId);
         }
         catch (error) {
-            // Speak-time fallback: if an SSML math chunk is rejected by the
-            // provider, retry once with its precomputed plain-text variant (same
-            // anchors, plain alignment). The fallback chunk carries no further
-            // fallback, so this cannot recurse.
+            // A chunk with a plainFallback retries once with it when speaking fails:
+            // a rejected SSML math chunk falls back to its plain-text variant, a
+            // recording that cannot play to its script. The fallback carries no
+            // fallback of its own, so this cannot recurse.
             if (chunk.plainFallback && runId === this.speakRunId) {
                 logger.debug("SSML chunk speak failed; retrying plain text", {
                     message: error instanceof Error ? error.message : String(error),
                 });
-                // A recorded-first run can own the start barrier even when its fallback
-                // provider has no formal start signal. Drop the failed recording's queued
-                // highlight and resume that non-start-aware provider's immediate-start lifecycle.
+                // A run that began with a recording holds the start barrier for the
+                // recording's start signal. A provider with no start signal of its own
+                // would never release it, so drop the recording's queued highlight and
+                // mark the run playing now.
                 if (this.playbackStartDeferredRunId === runId &&
                     this.provider &&
                     !("onPlaybackStart" in this.provider)) {
@@ -2001,6 +2090,9 @@ export class TTSService {
                 mathTokenHighlighting,
             })
             : null;
+        const providerOffsetSpace = !pipelineChunk || pipelineChunk.offsetSpace === "unsupported"
+            ? "unknown"
+            : pipelineChunk.offsetSpace;
         this.runWhenPlaybackStarts(runId, () => {
             if (highlightPlan && pipelineChunk && chunk.mathAlignment) {
                 this.renderHighlightDecision(highlightPlan.resolveInitial(pipelineChunk.id));
@@ -2037,21 +2129,15 @@ export class TTSService {
         const provider = this.provider;
         const previousOnWordBoundary = provider.onWordBoundary;
         const installedHandler = (word, position, length) => {
-            if (runId !== this.speakRunId)
+            if (runId !== this.speakRunId || !highlightPlan || !pipelineChunk)
                 return;
-            if (highlightPlan && pipelineChunk) {
-                const providerOffsetSpace = pipelineChunk.offsetSpace === "unsupported"
-                    ? "unknown"
-                    : pipelineChunk.offsetSpace;
-                this.renderHighlightDecision(highlightPlan.resolveBoundary({
-                    chunkId: pipelineChunk.id,
-                    word,
-                    position,
-                    length,
-                    providerOffsetSpace,
-                }));
-                return;
-            }
+            this.renderHighlightDecision(highlightPlan.resolveBoundary({
+                chunkId: pipelineChunk.id,
+                word,
+                position,
+                length,
+                providerOffsetSpace,
+            }));
         };
         provider.onWordBoundary = installedHandler;
         try {
@@ -2080,16 +2166,12 @@ export class TTSService {
             }
             return;
         }
-        if (args.shouldUsePlan && this.currentContentElement) {
-            const segments = this.seekSegments;
-            if (segments.length > 0) {
-                await this.speakWithPlan(segments, args.runId, {
-                    highlightMode: args.highlightMode,
-                });
-            }
-            else {
-                await this.speakWithinLimit(args.contentToSpeak, args.runId);
-            }
+        if (args.shouldUsePlan &&
+            this.currentContentElement &&
+            this.seekSegments.length > 0) {
+            await this.speakWithPlan(this.seekSegments, args.runId, {
+                highlightMode: args.highlightMode,
+            });
             return;
         }
         await this.speakWithinLimit(args.contentToSpeak, args.runId);
@@ -2111,6 +2193,7 @@ export class TTSService {
         this.playbackChunks = [];
         this.sentenceHighlightSegments = [];
         this.activeSentenceStartOffset = null;
+        this.wordlessPartHighlight = null;
     }
     /**
      * The selected part of `root`'s normalized visible text and where it starts, or
@@ -2171,7 +2254,7 @@ export class TTSService {
     normalizePlaybackRate(rate) {
         if (!Number.isFinite(rate))
             return 1;
-        return Math.max(0.25, Math.min(4, rate));
+        return Math.max(MIN_PLAYBACK_RATE, Math.min(MAX_PLAYBACK_RATE, rate));
     }
     async restartFromSeekIndex(targetIndex) {
         if (!this.provider || this.seekSegments.length === 0)
@@ -2233,8 +2316,11 @@ export class TTSService {
             this.clearHighlightsAndTracking();
         }
         catch (error) {
-            if (runId !== this.speakRunId)
+            // A superseded run's failure is the abort that superseded it.
+            if (runId !== this.speakRunId) {
+                logger.debug("Superseded seek restart failed:", error);
                 return;
+            }
             this.lastError = error instanceof Error ? error.message : String(error);
             this.setState(PlaybackState.ERROR);
             this.clearHighlightsAndTracking();
@@ -2332,32 +2418,19 @@ export class TTSService {
         await this.seekBy(-step);
     }
     /**
-     * Stop playback
+     * Stop playback and release the run owner. A run that ends on its own keeps
+     * its owner, so the owning control can replay it.
      */
     stop() {
         this.speakRunId += 1;
         this.abandonRun();
-        if (this.provider) {
-            this.provider.onWordBoundary = undefined;
-            this.provider.stop();
-        }
-        this.setState(PlaybackState.IDLE);
+        this.provider?.stop();
+        this.clearHighlightsAndTracking();
         this.currentText = null;
-        // Clear highlights
-        if (this.highlightCoordinator) {
-            this.highlightCoordinator.clearTTS();
-        }
-        // Clear tracking
-        this.lastRenderedRegionTarget = null;
-        this.currentContentElement = null;
-        this.normalizedToDOM.clear();
-        this.currentBoundaryOffset = 0;
-        this.activeWordBoundaryOffset = 0;
-        this.seekSegments = [];
-        this.playbackChunks = [];
-        this.sentenceHighlightSegments = [];
-        this.activeSentenceStartOffset = null;
-        this.activePlaybackRate = null;
+        // Announced even from idle, so a listener sees the owner released.
+        const releasedOwner = this.runOwner !== null;
+        this.runOwner = null;
+        this.setState(PlaybackState.IDLE, releasedOwner);
     }
     /**
      * Stop playback and drop the provider, whose owner destroys it. A later speak
@@ -2389,50 +2462,14 @@ export class TTSService {
         this.catalogResolver = null;
         this.telemetryReporter = 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
-     */
-    isPlaying() {
-        return this.state === PlaybackState.PLAYING;
-    }
-    /**
-     * Check if paused
-     */
-    isPaused() {
-        return this.state === PlaybackState.PAUSED;
-    }
     /**
      * Get current state
      */
     getState() {
         return this.state;
     }
-    /**
-     * Get current text being spoken
-     */
-    getCurrentText() {
-        return this.currentText;
-    }
-    /**
-     * Get the last error message
-     * Returns null if no error has occurred
-     */
-    getLastError() {
-        return this.lastError;
+    getRunOwner() {
+        return this.runOwner;
     }
     /**
      * Subscribe to playback state changes. The returned function unsubscribes;
@@ -2446,17 +2483,19 @@ export class TTSService {
         };
     }
     /**
-     * Set state and notify listeners
+     * Set state and notify listeners. `announceUnchanged` notifies listeners even
+     * when the state does not change; telemetry fires only on a change.
      */
-    setState(newState) {
-        if (this.state === newState)
-            return;
+    setState(newState, announceUnchanged = false) {
         const previousState = this.state;
+        if (previousState === newState && !announceUnchanged)
+            return;
         this.state = newState;
-        // Notify all listeners
         for (const listener of [...this.listeners]) {
             listener(newState);
         }
+        if (previousState === newState)
+            return;
         void this.emitTelemetry("pie-tool-playback-state-changed", {
             toolId: "textToSpeech",
             previousState,