@pie-players/pie-assessment-toolkit 0.3.74 → 1.0.0-beta.0

package/dist/services/TTSService.js

@@ -1,33 +1,40 @@
 /**
  * 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 { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
+import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { resolveSpokenAudioMedia, } from "./spoken-audio-cards.js";
-import { BrowserTTSProvider } from "./tts/browser-provider.js";
-import { collectRangeTextForSpeech, collectVisibleTextAndMap, isElementHiddenForTTS, isNodeExcludedFromSpeech, isNodeSuppressedForTTS, normalizeTextForSpeech, } from "./tts/text-processing.js";
+import { DEFAULT_CONTENT_LANGUAGE, findContentLanguage, findLangAttribute, } from "../runtime/content-language.js";
+import { isSsmlDocument } from "./tts/ssml/spoken-text.js";
+import { composedContains, composedParentElement, flatQuerySelectorAll, flatTextContent, flatTreeChildNodes, flatTreeParentElement, flatTreeTextNodes, rangeHoldsTextPosition, rangeIntersectsComposedNode, } from "./tts/flat-tree.js";
+import { collectRangeTextForSpeech, collectVisibleTextAndMap, isElementHiddenForTTS, isNodeExcludedFromSpeech, isNodeSuppressedForTTS, normalizeTextForSpeech, rangeHoldsSpeakableElement, textInRange, } from "./tts/text-processing.js";
 import { createCatalogSpanAlignment, } from "./tts/catalog-span-alignment.js";
 import { createMathAwareAlignment, } from "./tts/math-alignment/index.js";
 import { collectMathAwareTextAndMap } from "./tts/math-aware-text-processing.js";
 import { buildGeneratedSpeechFromRoot, createMemoizedMathSpeechResolver, planToCompositionChunkInputs, } from "./tts/generated-speech/index.js";
 import { normalizeSREMathSpeechOptions, } from "./tts/math-speech.js";
-import { segmentSentences as segmentTextToSentences, } from "./tts/text-segmentation.js";
+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 { PIE_TTS_CONTROL_HANDOFF_EVENT, } from "./tts-control-events.js";
+import { createRangesFromVisibleMap } from "./tts/highlight-pipeline/visible-map-range.js";
+// Debug lines need `PIE_TTS_DEBUG=1` or `globalThis.__PIE_TTS_DEBUG__ = true`.
+const logger = createPieLogger("tts-service", isTtsDebugEnabled);
 /**
  * Playback state
  */
@@ -39,6 +46,29 @@ 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)
+        return previous;
+    return {
+        locale: "locale" in options ? optionalString(options.locale) : previous.locale,
+        textNormalization: options.textNormalization && "locale" in options.textNormalization
+            ? optionalString(options.textNormalization.locale)
+            : previous.textNormalization,
+        segmenter: options.segmenter && "locale" in options.segmenter
+            ? optionalString(options.segmenter.locale)
+            : previous.segmenter,
+    };
+};
+const isRange = (target) => "commonAncestorContainer" in target;
 const sameRange = (left, right) => left === right ||
     (left.startContainer === right.startContainer &&
         left.startOffset === right.startOffset &&
@@ -67,92 +97,158 @@ 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;
     highlightTargetResolverProvider = null;
     catalogResolver = null;
     state = PlaybackState.IDLE;
+    // The state a resume returns to: loading when the pause came before the
+    // audio started sounding.
+    resumeState = PlaybackState.PLAYING;
     ttsConfig = {};
+    // The locales the host configured. A read naming a language sets all three
+    // to it; a read naming none restores these.
+    hostLocales = {};
+    // The locale of the read in progress, which segmentation reads.
+    readLocale = DEFAULT_CONTENT_LANGUAGE;
+    disposed = false;
+    readinessGate = null;
+    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 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 = [];
     playbackChunks = [];
     // The recording currently playing, if any. `cancel` settles the pending play
     // promise as well as stopping the element, so stop/seek cannot wedge the
-    // chunk loop on a run that has already been superseded.
+    // chunk loop on a run that has already been superseded. `play` starts it, or
+    // starts it again after a pause.
     activeRecordedAudio = null;
     sentenceHighlightSegments = [];
     activeSentenceStartOffset = null;
     playbackStartDeferredRunId = null;
     pendingPlaybackStartHighlights = [];
     playbackStartBarrierCleanup = null;
+    // A pause between two parts of a run, in a structural gap or while the next
+    // part loads, holds the run here until resume.
+    pauseHold = null;
+    structuralPause = null;
     playbackRateWriteQueue = Promise.resolve();
     playbackRateRequestId = 0;
     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();
-    // Verbose alignment/highlight tracing is opt-in: it is expensive (large
-    // objects, a full text diff per utterance) and noisy in production. Enable
-    // with `PIE_TTS_DEBUG=1` or `globalThis.__PIE_TTS_DEBUG__ = true`.
-    static debugEnabled = (() => {
-        try {
-            if (typeof process !== "undefined" &&
-                process.env?.PIE_TTS_DEBUG === "1") {
-                return true;
-            }
-        }
-        catch {
-            // `process` is not defined in the browser; fall through to the global.
-        }
-        return (globalThis.__PIE_TTS_DEBUG__ === true);
-    })();
-    constructor() { }
-    debugLog(message, detail) {
-        if (!TTSService.debugEnabled)
-            return;
-        if (detail === undefined) {
-            console.debug(message);
-        }
-        else {
-            console.debug(message, detail);
-        }
-    }
     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;
         }
-        this.setState(PlaybackState.PLAYING);
+        if (this.state === PlaybackState.PAUSED) {
+            // The learner paused before this part began: it holds where it started.
+            this.activeRecordedAudio?.element.pause();
+            this.provider?.pause();
+        }
+        this.markPlaying();
         const pendingHighlights = this.pendingPlaybackStartHighlights.splice(0);
         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;
@@ -160,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) {
@@ -191,6 +287,84 @@ export class TTSService {
         }
         callback();
     }
+    /** Resolves when run `runId` may start its next part: at once unless paused. */
+    async waitWhilePaused(runId) {
+        while (this.state === PlaybackState.PAUSED && runId === this.speakRunId) {
+            if (!this.pauseHold) {
+                let release = () => { };
+                const promise = new Promise((resolve) => {
+                    release = resolve;
+                });
+                this.pauseHold = { promise, release };
+            }
+            await this.pauseHold.promise;
+        }
+    }
+    releasePauseHold() {
+        const hold = this.pauseHold;
+        this.pauseHold = null;
+        hold?.release();
+    }
+    waitStructuralPause(pauseMs) {
+        this.cancelStructuralPause();
+        return new Promise((resolve) => {
+            const finish = () => {
+                if (this.structuralPause?.finish === finish) {
+                    clearTimeout(this.structuralPause.timer);
+                    this.structuralPause = null;
+                }
+                resolve();
+            };
+            this.structuralPause = { timer: setTimeout(finish, pauseMs), finish };
+        });
+    }
+    cancelStructuralPause() {
+        this.structuralPause?.finish();
+    }
+    /**
+     * Release what a superseded run still holds: its start barrier, a recorded
+     * clip still playing, a structural gap and a pause hold. Its loops then see
+     * the new run id and return.
+     */
+    abandonRun() {
+        this.clearPlaybackStartBarrier();
+        this.cancelRecordedAudio();
+        this.cancelStructuralPause();
+        this.releasePauseHold();
+    }
+    /**
+     * Start a run and enter loading. From here a pause or stop applies to the
+     * run, whatever it is still waiting for: the provider, its content or the
+     * provider's audio.
+     */
+    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();
+        // 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. */
+    markPlaying() {
+        if (this.state === PlaybackState.PAUSED) {
+            this.resumeState = PlaybackState.PLAYING;
+            return;
+        }
+        this.setState(PlaybackState.PLAYING);
+    }
+    assertNotDisposed() {
+        if (this.disposed) {
+            throw toTTSStartFailure(new Error("TTS service disposed"));
+        }
+    }
     async emitTelemetry(eventName, payload) {
         try {
             await this.telemetryReporter?.(eventName, payload);
@@ -201,77 +375,41 @@ 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)
+            throw new Error("TTS service disposed");
         this.currentProvider = provider;
         this.ttsConfig = { ...config };
-        const providerOptions = config.providerOptions && typeof config.providerOptions === "object"
-            ? config.providerOptions
-            : {};
-        this.telemetryReporter =
-            typeof providerOptions.__pieTelemetry === "function"
-                ? providerOptions.__pieTelemetry
-                : null;
-        // Initialize provider and get implementation. Browser fallback is only
-        // allowed here, before the configured provider has successfully become
-        // the active runtime. Per-call playback/synthesis errors must surface
-        // instead of silently replacing a user-selected provider and voice.
-        try {
-            this.provider = await provider.initialize(config);
-        }
-        catch (error) {
-            if (provider.providerId.toLowerCase() === "browser") {
-                throw error;
-            }
-            if (!this.isBrowserSpeechFallbackAvailable()) {
-                throw error;
-            }
-            const switched = await this.switchProviderToBrowser(error, {
-                operation: "tts-initialize",
-            });
-            if (!switched) {
-                throw error;
-            }
-        }
+        this.hostLocales = hostLocalesOf(config.providerOptions);
+        const telemetry = this.providerOptions().__pieTelemetry;
+        this.telemetryReporter = typeof telemetry === "function" ? telemetry : null;
+        // A provider that fails to start throws to the caller, which owns any
+        // fallback. Playback and synthesis errors surface the same way.
+        this.provider = await provider.initialize(config);
     }
     /**
-     * Update TTS settings dynamically without full reinitialization
-     *
-     * This allows changing rate, pitch, and voice on the fly.
-     * Note: Some providers may require reinitialization for voice changes.
-     *
-     * @param settings Partial settings to update (rate, pitch, voice)
+     * Update rate, pitch, voice or provider options without reinitializing.
+     * `providerOptions` merge over the ones already configured.
      */
     async updateSettings(settings) {
         if (!this.provider) {
             throw new Error("TTSService not initialized. Call initialize() first.");
         }
-        // If the provider implementation has an updateSettings method, use it
-        const provider = this.provider;
-        if (typeof provider.updateSettings === "function") {
-            const mergedSettings = {
-                ...settings,
-                ...(settings.providerOptions
-                    ? {
-                        providerOptions: {
-                            ...(this.ttsConfig.providerOptions || {}),
-                            ...settings.providerOptions,
-                        },
-                    }
-                    : {}),
-            };
-            await provider.updateSettings(mergedSettings);
-            this.ttsConfig = { ...this.ttsConfig, ...mergedSettings };
-        }
-        else {
-            // Fallback: Reinitialize with merged config
-            // This requires storing the original config, which we don't have
-            // So for now, just log a warning
-            console.warn("[TTSService] Provider does not support dynamic settings updates. Some settings may require reinitialization.");
-        }
+        const mergedSettings = {
+            ...settings,
+            ...(settings.providerOptions
+                ? {
+                    providerOptions: {
+                        ...this.providerOptions(),
+                        ...settings.providerOptions,
+                    },
+                }
+                : {}),
+        };
+        await this.provider.updateSettings(mergedSettings);
+        this.ttsConfig = { ...this.ttsConfig, ...mergedSettings };
+        this.hostLocales = hostLocalesOf(settings.providerOptions, this.hostLocales);
     }
     /**
      * Set highlight coordinator for word highlighting
@@ -279,6 +417,29 @@ export class TTSService {
     setHighlightCoordinator(coordinator) {
         this.highlightCoordinator = coordinator;
     }
+    /**
+     * Starts the service when a caller speaks before it is initialized; a gate
+     * that rejects fails the speak with its error. The coordinator installs one
+     * that runs its own text-to-speech start.
+     */
+    setReadinessGate(gate) {
+        this.readinessGate = gate;
+    }
+    /**
+     * Where the configured math speech options come from before, and apart from,
+     * initialization, so math names do not depend on when speech started.
+     */
+    setMathSpeechSource(source) {
+        this.mathSpeechSource = source;
+    }
+    /** The start a speak must wait for, or null when it can speak now without yielding. */
+    pendingReadiness() {
+        if (this.provider || !this.readinessGate)
+            return null;
+        return this.readinessGate().catch((error) => {
+            throw toTTSStartFailure(error);
+        });
+    }
     /**
      * Set a late-bound provider for optional host TTS highlight target remapping.
      *
@@ -307,37 +468,10 @@ 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;
     }
-    /**
-     * Whether a catalog holds spoken content this service could actually speak.
-     *
-     * Exists because `data-catalog-idref` is one attribute with several readers:
-     * a node can be docked to a catalog that carries only a signing card, and the
-     * nearest docked ancestor of a selection is therefore not necessarily the one
-     * holding its authored SSML. A caller resolving a selection climbs ancestors
-     * and asks this before settling on an id — see the TTS tool's
-     * `findSpokenCatalogId`. Without it, a signing card docked on an inner node
-     * silently shadows authored speech on an outer one.
-     */
-    hasSpokenAlternate(catalogId, language = "en-US") {
-        if (!catalogId || !this.catalogResolver)
-            return false;
-        const resolved = this.catalogResolver.getAlternative(catalogId, {
-            type: "spoken",
-            language,
-            useFallback: true,
-            // The string form specifically. A node may also carry a recording of the
-            // same script; that one is not what this reports on, and card order must
-            // not decide the answer.
-            form: "content",
-        });
-        return resolved?.content !== undefined;
-    }
     getHighlightResolverRuntime() {
         let provided = null;
         try {
@@ -364,12 +498,12 @@ export class TTSService {
             return null;
         return node.nodeType === Node.ELEMENT_NODE
             ? node
-            : node.parentElement;
+            : composedParentElement(node);
     }
     isElementWithinScope(element, scope) {
         if (!scope)
             return true;
-        return element === scope || scope.contains(element);
+        return composedContains(scope, element);
     }
     isRangeWithinScope(range, scope) {
         const startElement = this.getNodeElement(range.startContainer);
@@ -444,28 +578,21 @@ export class TTSService {
             return null;
         }
     }
-    paintTTSWordRange(range) {
-        if (!this.highlightCoordinator)
+    /**
+     * Paint the spoken word, each range offered to the host's resolver. A word
+     * split across inline elements is one range over its text nodes; across
+     * shadow trees, one range per tree.
+     */
+    paintTTSWord(nativeRanges) {
+        if (!this.highlightCoordinator || nativeRanges.length === 0)
             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);
+        this.highlightCoordinator.highlightTTSWord(nativeRanges.map((range) => this.resolveWordHighlightRange(range).range));
     }
     paintTTSSentenceRanges(nativeRanges) {
         if (!this.highlightCoordinator)
             return;
         const { ranges, elements } = this.resolveSentenceHighlightTargets(nativeRanges);
-        if (elements.length > 0 &&
-            ranges.length === 0 &&
-            this.highlightCoordinator.highlightTTSSentenceElements) {
+        if (elements.length > 0 && ranges.length === 0) {
             this.highlightCoordinator.highlightTTSSentenceElements(elements);
             return;
         }
@@ -477,42 +604,123 @@ export class TTSService {
         }
         this.highlightCoordinator.highlightTTSSentence(paintedRanges);
     }
+    providerOptions() {
+        const options = this.ttsConfig.providerOptions;
+        return options && typeof options === "object" ? options : {};
+    }
+    /** The longest text the provider accepts in one speak, when it declares one. */
+    maxTextLength() {
+        const limit = this.currentProvider?.getCapabilities?.().maxTextLength;
+        return typeof limit === "number" && limit > 0 ? limit : undefined;
+    }
     /**
-     * Get provider capabilities
+     * Speak `text`, in pieces when it exceeds the provider's `maxTextLength`. Word
+     * boundaries keep indexing the whole text. An SSML document cannot be cut, so
+     * one over the limit fails and the chunk's plain fallback reads instead.
      */
-    getCapabilities() {
-        return this.currentProvider?.getCapabilities() || null;
+    async speakWithinLimit(text, runId) {
+        const provider = this.provider;
+        if (!provider)
+            return;
+        const limit = this.maxTextLength();
+        if (!limit || text.length <= limit) {
+            await this.waitWhilePaused(runId);
+            if (runId !== this.speakRunId || this.provider !== provider)
+                return;
+            await provider.speak(text);
+            return;
+        }
+        if (isSsmlDocument(text)) {
+            throw new Error(`[tts] SSML of ${text.length} characters exceeds the provider's limit of ${limit}`);
+        }
+        const onWordBoundary = provider.onWordBoundary;
+        try {
+            for (const piece of splitTextToLength(text, limit, {
+                locale: this.readLocale,
+            })) {
+                await this.waitWhilePaused(runId);
+                if (runId !== this.speakRunId || this.provider !== provider)
+                    return;
+                provider.onWordBoundary = onWordBoundary
+                    ? (word, position, length) => onWordBoundary(word, position + piece.offset, length)
+                    : undefined;
+                await provider.speak(piece.text);
+            }
+        }
+        finally {
+            if (this.provider === provider && runId === this.speakRunId) {
+                provider.onWordBoundary = onWordBoundary;
+            }
+        }
+    }
+    /** Segments no longer than the provider's `maxTextLength`, offsets kept. */
+    segmentsWithinLimit(segments) {
+        const limit = this.maxTextLength();
+        if (!limit)
+            return segments;
+        return segments.flatMap((segment) => {
+            if (segment.text.length <= limit)
+                return [segment];
+            const pieces = splitTextToLength(segment.text, limit, {
+                locale: this.readLocale,
+            });
+            return pieces.map((piece, index) => ({
+                text: piece.text,
+                startOffset: segment.startOffset + piece.offset,
+                pauseMsAfter: index === pieces.length - 1 ? segment.pauseMsAfter : undefined,
+            }));
+        });
     }
     /**
-     * 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(language) {
-        const providerOptions = (this.ttsConfig.providerOptions || {});
-        const textNormalization = (providerOptions.textNormalization ||
-            {});
-        const mode = textNormalization.boundarySpacingMode;
+    getTextProcessingOptions(locale) {
+        const mode = this.providerOptions().textNormalization?.boundarySpacingMode;
         const boundarySpacingMode = mode === "none" || mode === "alnum" || mode === "segmenterPreferred"
             ? mode
             : undefined;
-        const locale = language ||
-            (typeof textNormalization.locale === "string"
-                ? textNormalization.locale
-                : undefined);
         return { locale, boundarySpacingMode };
     }
+    /**
+     * The language a read of `node` is in. Its content language is the nearest
+     * `lang` between it and its shell, else the language the speak names, else a
+     * pinned `lang_id`. Its locale is that content language, else the host's
+     * configured locale, else en-US.
+     */
+    resolveReadLanguage(node, named) {
+        const contentLanguage = findContentLanguage(node, { contentLanguage: named }) ??
+            optionalString(this.providerOptions().lang_id);
+        return {
+            contentLanguage,
+            locale: contentLanguage ??
+                this.hostLocales.locale ??
+                this.hostLocales.textNormalization ??
+                DEFAULT_CONTENT_LANGUAGE,
+        };
+    }
+    /**
+     * The host's SRE options for math speech: from the installed source, else as
+     * this service was initialized with.
+     */
     getMathSpeechOptions() {
-        const providerOptions = (this.ttsConfig.providerOptions || {});
-        const mathSpeech = providerOptions.mathSpeech;
-        return normalizeSREMathSpeechOptions(mathSpeech);
+        if (this.mathSpeechSource) {
+            return normalizeSREMathSpeechOptions(this.mathSpeechSource());
+        }
+        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));
         this.normalizedToDOM = map;
-        if (!TTSService.debugEnabled)
+        // The comparison below diffs the whole text, so it runs only when traced.
+        if (!isTtsDebugEnabled())
             return;
-        this.debugLog("[TTSService] Text comparison:", {
+        logger.debug("Text comparison:", {
             spokenLength: spokenText.length,
             normalizedDomLength: normalizedDomText.length,
             match: spokenText === normalizedDomText,
@@ -520,22 +728,9 @@ 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),
         });
-        this.debugLog("[TTSService] Position map built:", {
+        logger.debug("Position map built:", {
             entries: this.normalizedToDOM.size,
             spokenTextLength: spokenText.length,
             normalizedDomLength: normalizedDomText.length,
@@ -551,9 +746,8 @@ export class TTSService {
         });
     }
     getStructuralPauseProfile() {
-        const providerOptions = (this.ttsConfig.providerOptions || {});
-        const custom = (providerOptions.structuralPauses || {});
-        const customUnits = (custom.units || {});
+        const custom = this.providerOptions().structuralPauses || {};
+        const customUnits = custom.units || {};
         const toNumber = (value, fallback) => {
             if (typeof value === "number" && Number.isFinite(value))
                 return value;
@@ -563,47 +757,42 @@ 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)));
     }
     resolveHighlightMode() {
-        const providerOptions = (this.ttsConfig.providerOptions || {});
-        const configuredMode = providerOptions.highlightMode;
+        const configuredMode = this.providerOptions().highlightMode;
         if (configuredMode === "word" || configuredMode === "sentence") {
             return configuredMode;
         }
-        const providerId = (this.currentProvider?.providerId || "").toLowerCase();
-        if (providerId === "browser") {
-            return "sentence";
+        const capabilities = this.currentProvider?.getCapabilities();
+        if (capabilities?.defaultHighlightMode) {
+            return capabilities.defaultHighlightMode;
         }
-        const supportsWordBoundary = this.currentProvider?.getCapabilities().supportsWordBoundary ?? false;
-        return supportsWordBoundary ? "word" : "sentence";
+        return capabilities?.supportsWordBoundary ? "word" : "sentence";
     }
     hasExplicitBreakSemantics(text) {
         if (!text.includes("<"))
             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]$/))
@@ -618,26 +807,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 = textNode.parentElement;
+        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,
@@ -652,19 +831,9 @@ 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;
-                    }
-                }
-            }
-            current = current.parentElement;
+            if (!best && isBlockDisplay(current))
+                best = current;
+            current = flatTreeParentElement(current);
         }
         if (!best)
             return null;
@@ -679,8 +848,8 @@ export class TTSService {
      * boundaries are collected over the whole element, and a selection speaks only
      * part of it.
      */
-    createSpeechPlan(contentElement, normalizedText, textOffset = 0) {
-        const boundaries = this.collectSpeechPlanBoundaries(contentElement, normalizedText);
+    createSpeechPlan(contentElement, normalizedText, textOffset, language) {
+        const boundaries = this.collectSpeechPlanBoundaries(contentElement, language);
         if (textOffset === 0) {
             return this.createSpeechPlanSegments(normalizedText, boundaries);
         }
@@ -690,18 +859,17 @@ export class TTSService {
         }
         return this.createSpeechPlanSegments(normalizedText, shifted);
     }
-    collectSpeechPlanBoundaries(contentElement, normalizedText) {
+    collectSpeechPlanBoundaries(contentElement, language) {
         const boundaries = new Map();
-        const { map } = collectVisibleTextAndMap(contentElement, this.getTextProcessingOptions());
+        // The same locale the position map used, so the boundary offsets index the
+        // text the map built.
+        const { map } = collectVisibleTextAndMap(contentElement, this.getTextProcessingOptions(language));
         const nodeStartOffsets = this.createNodeStartOffsets(map);
-        const walker = document.createTreeWalker(contentElement, NodeFilter.SHOW_TEXT);
-        let currentNode = walker.nextNode();
         let previousBoundaryAnchor = null;
-        while (currentNode) {
-            const textNode = currentNode;
-            const parent = textNode.parentElement;
+        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);
@@ -713,7 +881,6 @@ export class TTSService {
                     previousBoundaryAnchor = boundary.anchor;
                 }
             }
-            currentNode = walker.nextNode();
         }
         return boundaries;
     }
@@ -733,11 +900,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({
@@ -761,9 +924,7 @@ export class TTSService {
         return segments.filter((segment) => segment.text.trim().length > 0);
     }
     segmentSentences(text) {
-        const locale = this.ttsConfig.providerOptions
-            ?.locale || undefined;
-        return segmentTextToSentences(text, { locale });
+        return segmentTextToSentences(text, { locale: this.readLocale });
     }
     createSeekSegmentsFromText(text) {
         return this.segmentSentences(text)
@@ -797,11 +958,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),
@@ -825,6 +982,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 ||
@@ -838,23 +998,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)
@@ -863,6 +1012,10 @@ export class TTSService {
         const providerWithPlan = this.provider;
         if (!shouldTrackSentenceProgress &&
             typeof providerWithPlan.speakSegments === "function") {
+            await this.waitWhilePaused(runId);
+            if (runId !== this.speakRunId || this.provider !== providerWithPlan) {
+                return;
+            }
             this.currentBoundaryOffset = 0;
             const originalOnWordBoundary = this.provider.onWordBoundary;
             this.provider.onWordBoundary = (word, position, length) => {
@@ -872,7 +1025,7 @@ export class TTSService {
                 }
             };
             try {
-                await providerWithPlan.speakSegments(segments);
+                await providerWithPlan.speakSegments(this.segmentsWithinLimit(segments));
             }
             finally {
                 if (runId === this.speakRunId && this.provider === providerWithPlan) {
@@ -886,18 +1039,28 @@ export class TTSService {
             wordBoundaryOffset: this.activeWordBoundaryOffset,
         });
         for (const segment of segments) {
+            await this.waitWhilePaused(runId);
             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.provider.speak(segment.text);
             const pauseMs = segment.pauseMsAfter ?? 0;
-            if (pauseMs > 0) {
-                await new Promise((resolve) => setTimeout(resolve, pauseMs));
+            if (pauseMs > 0 && runId === this.speakRunId) {
+                await this.waitStructuralPause(pauseMs);
             }
         }
     }
@@ -917,10 +1080,11 @@ export class TTSService {
         const end = this.normalizedToDOM.get(mapStart + length - 1);
         if (!start || !end)
             return;
-        const range = document.createRange();
-        range.setStart(start.node, start.offset);
-        range.setEnd(end.node, end.offset + 1);
-        this.paintTTSSentenceRanges([range]);
+        // One range per tree: a sentence running into a shadow root paints in both.
+        const ranges = createRangesFromVisibleMap(this.normalizedToDOM, mapStart, mapStart + length);
+        if (ranges.length === 0)
+            return;
+        this.paintTTSSentenceRanges(ranges);
         this.activeSentenceStartOffset = startOffset;
     }
     getSegmentIndexForOffset(segments, offset) {
@@ -952,66 +1116,180 @@ export class TTSService {
         this.highlightSentenceSegment(segment.startOffset, segment.text);
     }
     /**
-     * Find text node and offsets for highlighting a word
+     * Read `target` aloud: a range reads the text it selects, an element its
+     * content. A node with a spoken card that the target holds whole reads its
+     * card, `catalogId` names the card of the content root, and math reads as
+     * math speech.
      *
-     * @param charIndex Character position in normalized/spoken text
-     * @param length Length of the word
-     * @returns Text node and local offsets, or null if not found
+     * Content marked not-to-be-spoken is never read, a named card included. When
+     * the target holds nothing speakable, nothing is spoken and playback already
+     * running continues.
      */
-    findHighlightRange(charIndex, length) {
-        const startPos = this.normalizedToDOM.get(charIndex);
-        if (!startPos) {
-            console.warn(`[TTSService] No mapping found for start position ${charIndex}`, {
-                totalMappings: this.normalizedToDOM.size,
-                nearbyMappings: Array.from(this.normalizedToDOM.entries())
-                    .filter(([pos]) => Math.abs(pos - charIndex) < 5)
-                    .map(([pos, { offset, node }]) => ({
-                    pos,
-                    offset,
-                    char: node.textContent?.[offset],
-                })),
-            });
+    async speak(target, options = {}) {
+        this.assertNotDisposed();
+        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 owner = options.ownerId ?? null;
+        const waitingRunId = pendingReadiness ? this.beginRun(owner) : null;
+        if (pendingReadiness) {
+            try {
+                await pendingReadiness;
+            }
+            catch (error) {
+                if (waitingRunId === this.speakRunId)
+                    this.setState(PlaybackState.IDLE);
+                throw error;
+            }
+            this.assertNotDisposed();
+            if (waitingRunId !== this.speakRunId)
+                return;
+        }
+        if (!this.provider) {
+            if (waitingRunId !== null)
+                this.setState(PlaybackState.IDLE);
+            throw toTTSStartFailure(new Error("TTS service not initialized"));
+        }
+        const language = this.resolveReadLanguage(isRange(target) ? target.startContainer : target, options.language);
+        const content = isRange(target)
+            ? this.resolveRangeTarget(target, options, language)
+            : this.resolveElementTarget(target, options, language);
+        if (!content) {
+            if (waitingRunId !== null)
+                this.setState(PlaybackState.IDLE);
+            return;
+        }
+        const runId = waitingRunId ?? this.beginRun(owner);
+        if (options.rate !== undefined) {
+            await this.applyRunRate(options.rate);
+            if (runId !== this.speakRunId)
+                return;
+        }
+        await this.speakContent(content.text, content.options, runId);
+    }
+    /**
+     * Sets the rate a run starts at, after any rate write in flight. The run has
+     * no playback yet, so nothing restarts.
+     */
+    async applyRunRate(rate) {
+        await this.playbackRateWriteQueue;
+        const nextRate = this.normalizePlaybackRate(rate);
+        const currentRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
+        if (nextRate === currentRate)
+            return;
+        await this.updateSettings({ rate: nextRate });
+    }
+    /**
+     * Suppression is read from the live ancestors of what is read, because the
+     * element carrying it may sit above the content root.
+     */
+    isSuppressedTarget(node) {
+        if (!isNodeSuppressedForTTS(node))
+            return false;
+        console.warn("[tts] the content to read lies inside content marked not-to-be-spoken; nothing was spoken.");
+        return true;
+    }
+    resolveElementTarget(root, options, language) {
+        if (this.isSuppressedTarget(root))
+            return null;
+        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 && !this.holdsSpokenCard(root, contentOptions)) {
+            console.warn("[tts] the content to read holds no speakable text; nothing was spoken.");
             return null;
         }
-        // Find the end position (last character of the word)
-        const endIndex = charIndex + length - 1;
-        const endPos = this.normalizedToDOM.get(endIndex);
-        if (!endPos) {
-            console.warn(`[TTSService] No mapping found for end position ${endIndex}`, {
-                startChar: charIndex,
-                length,
-                totalMappings: this.normalizedToDOM.size,
+        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))
+            return null;
+        // Highlighting stays scoped to the content root when one is named, else to
+        // the selection's nearest element.
+        const ancestor = range.commonAncestorContainer;
+        const root = options.contentRoot ||
+            (ancestor.nodeType === Node.ELEMENT_NODE
+                ? ancestor
+                : composedParentElement(ancestor));
+        if (!root)
+            return null;
+        const selected = collectRangeTextForSpeech(range, root);
+        const selectedText = selected.text.trim();
+        if (!selectedText) {
+            if (selected.filtered) {
+                console.warn("[tts] every part of the selection is either hidden or marked not-to-be-spoken; nothing was spoken.");
+            }
             return null;
         }
-        // For simplicity, if the word spans multiple nodes, just highlight in the first node
-        // (This is a rare edge case and would require creating multiple ranges)
-        if (startPos.node !== endPos.node) {
-            console.warn(`[TTSService] Word spans multiple nodes, highlighting in first node only`);
-            return {
-                node: startPos.node,
-                start: startPos.offset,
-                end: (startPos.node.textContent || "").length,
-            };
+        // The spoken text and its offset come from the root's visible-text map, which
+        // the highlight position map and the structural speech plan index too. Joined
+        // from raw text nodes instead, a selection loses the space the map inserts
+        // between blocks, and every offset after that boundary drifts.
+        const mapped = this.selectMappedRangeText(range, root, language.locale);
+        let text = selectedText;
+        let offset = mapped?.offset ?? 0;
+        if (mapped) {
+            text = mapped.text;
         }
+        else {
+            // Filtered the same way as the speech itself: the offset indexes into the
+            // highlight text, which comes from the exclusion-aware collectors.
+            const beforeRange = document.createRange();
+            beforeRange.selectNodeContents(root);
+            beforeRange.setEnd(range.startContainer, range.startOffset);
+            const textBeforeRange = collectRangeTextForSpeech(beforeRange, root).text;
+            const normalizedTextBeforeRange = normalizeTextForSpeech(textBeforeRange);
+            offset =
+                normalizedTextBeforeRange.length +
+                    (/\s$/.test(textBeforeRange) && normalizedTextBeforeRange ? 1 : 0);
+        }
+        logger.debug("selection offset calculation:", {
+            selectedText: text,
+            mapped: !!mapped,
+            offset,
+            rootTag: root.tagName,
+        });
         return {
-            node: startPos.node,
-            start: startPos.offset,
-            end: endPos.offset + 1, // +1 because we want to include the character at endPos
+            text,
+            options: {
+                // The root's card reads only when the selection holds all of the root.
+                catalogId: options.catalogId && rangeHoldsSpeakableElement(range, root, root)
+                    ? options.catalogId
+                    : undefined,
+                catalogContext: options.catalogContext,
+                language: language.locale,
+                contentLanguage: language.contentLanguage,
+                contentElement: root,
+                contentRange: range,
+                wordBoundaryOffset: offset,
+            },
         };
     }
-    /**
-     * Speak text with optional catalog support
-     *
-     * @param text Text to speak (will be normalized: trimmed and whitespace collapsed)
-     * @param options Optional catalog ID, language, and content element for highlighting
-     */
-    async speak(text, options) {
-        if (!this.provider) {
-            throw new Error("TTS service not initialized");
-        }
-        const runId = ++this.speakRunId;
-        this.clearPlaybackStartBarrier();
+    async speakContent(text, options, runId) {
         let playbackStartBarrier = null;
         try {
             await this.applyLanguageSettings(options);
@@ -1024,26 +1302,35 @@ export class TTSService {
             this.logResolvedSpeechContent({
                 contentToSpeak,
                 speechSource,
-                catalogId: options?.catalogId,
+                catalogId: options.catalogId,
             });
             this.initializeSpeakTracking(highlightText, options);
-            const highlightMode = options?.highlightModeOverride ||
-                (speechMatchesVisibleText ? this.resolveHighlightMode() : "sentence");
+            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)
-                        : 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({
@@ -1051,7 +1338,6 @@ export class TTSService {
                     shouldUsePlan,
                     playbackSegments: this.seekSegments,
                 });
-            this.setState(PlaybackState.LOADING);
             playbackStartBarrier = this.installPlaybackStartBarrier(runId, !!this.playbackChunks[0]?.audio);
             this.prepareHighlightsForSpeak({
                 contentToSpeak: highlightText,
@@ -1063,15 +1349,14 @@ export class TTSService {
             if (speechMatchesVisibleText) {
                 this.configureWordBoundaryHighlighting({
                     highlightMode,
-                    wordBoundaryOffset: options?.wordBoundaryOffset || 0,
+                    wordBoundaryOffset,
                 });
             }
             else {
                 this.clearWordBoundaryHighlighting();
             }
-            if (!playbackStartBarrier) {
-                this.setState(PlaybackState.PLAYING);
-            }
+            if (!playbackStartBarrier)
+                this.markPlaying();
             this.activePlaybackRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
             await this.executeSpeakPlayback({
                 shouldUsePlan,
@@ -1086,146 +1371,68 @@ export class TTSService {
             this.clearHighlightsAndTracking();
         }
         catch (error) {
-            let finalError = error;
-            console.error("TTS error:", finalError);
-            this.lastError =
-                finalError instanceof Error ? finalError.message : String(finalError);
+            // A superseded run's failure is the abort that superseded it.
             if (runId !== this.speakRunId)
                 return;
+            console.error("TTS error:", error);
+            this.lastError = error instanceof Error ? error.message : String(error);
             this.setState(PlaybackState.ERROR);
             this.clearHighlightsAndTracking();
-            throw finalError;
+            throw error;
         }
         finally {
             this.clearPlaybackStartBarrier(playbackStartBarrier);
         }
     }
-    async switchProviderToBrowser(reason, context) {
-        if (!this.currentProvider)
-            return false;
-        const fallbackProvider = new BrowserTTSProvider();
-        const previousProviderId = this.currentProvider.providerId;
-        // Voice identifiers and provider extensions belong to the provider that
-        // rejected initialization. Carry only settings whose meaning is portable
-        // when crossing the provider boundary; otherwise a Polly/Google/SC voice
-        // such as "Joanna" can incorrectly become an explicit Browser voice.
-        const browserConfig = {};
-        if (this.ttsConfig.rate !== undefined) {
-            browserConfig.rate = this.ttsConfig.rate;
-        }
-        if (this.ttsConfig.pitch !== undefined) {
-            browserConfig.pitch = this.ttsConfig.pitch;
-        }
-        if (this.ttsConfig.mathTokenHighlighting !== undefined) {
-            browserConfig.mathTokenHighlighting =
-                this.ttsConfig.mathTokenHighlighting;
-        }
-        const operation = context?.operation || "tts-initialize";
-        const offendingText = context?.contentToSpeak ?? "";
-        const offendingPreview = offendingText
-            .replace(/\s+/g, " ")
-            .trim()
-            .slice(0, 120);
-        const offendingDiagnostic = offendingText.length > 0
-            ? {
-                textLength: offendingText.length,
-                textPreview: offendingPreview.length < offendingText.length
-                    ? `${offendingPreview}…`
-                    : offendingPreview,
-            }
-            : {};
-        try {
-            this.provider?.stop();
-            this.currentProvider.destroy();
-            this.currentProvider = fallbackProvider;
-            this.provider = await fallbackProvider.initialize(browserConfig);
-            this.ttsConfig = browserConfig;
-            await this.emitTelemetry("pie-tool-runtime-fallback", {
-                toolId: "textToSpeech",
-                operation,
-                fromProvider: previousProviderId,
-                toProvider: fallbackProvider.providerId,
-                reason: reason instanceof Error ? reason.message : String(reason),
-                ...offendingDiagnostic,
-            });
-            console.warn("[TTSService] TTS provider initialization failed; switched to browser fallback", {
-                fromProvider: previousProviderId,
-                reason,
-                ...offendingDiagnostic,
-            });
-            return true;
-        }
-        catch (fallbackError) {
-            await this.emitTelemetry("pie-tool-runtime-fallback-error", {
-                toolId: "textToSpeech",
-                operation,
-                fromProvider: previousProviderId,
-                toProvider: "browser",
-                errorType: "TTSRuntimeFallbackError",
-                message: fallbackError instanceof Error
-                    ? fallbackError.message
-                    : String(fallbackError),
-            });
-            console.error("[TTSService] Failed to switch to browser fallback provider", fallbackError);
-            return false;
-        }
-    }
-    isBrowserSpeechFallbackAvailable() {
-        if (typeof window === "undefined")
-            return false;
-        if (!("speechSynthesis" in window))
-            return false;
-        return (typeof globalThis
-            .SpeechSynthesisUtterance === "function");
-    }
+    /**
+     * Hand the read's language to the provider. A read in a named content language
+     * sets the provider's locales and `contentLanguage` to it, so a browser voice
+     * follows it; a read naming none restores the host's locales and clears
+     * `contentLanguage`, so the browser voice follows the browser's language.
+     */
     async applyLanguageSettings(options) {
-        if (!options?.language || !this.provider)
+        if (!this.provider)
+            return;
+        this.readLocale = options.language;
+        const named = options.contentLanguage;
+        const providerOptions = this.providerOptions();
+        const next = {
+            locale: named ?? this.hostLocales.locale,
+            textNormalization: named ?? this.hostLocales.textNormalization,
+            segmenter: named ?? this.hostLocales.segmenter,
+        };
+        if (providerOptions.contentLanguage === named &&
+            optionalString(providerOptions.locale) === next.locale &&
+            optionalString(providerOptions.textNormalization?.locale) ===
+                next.textNormalization &&
+            optionalString(providerOptions.segmenter?.locale) === next.segmenter) {
             return;
-        const providerOptions = (this.ttsConfig.providerOptions || {});
-        const textNormalization = (providerOptions.textNormalization ||
-            {});
-        const segmenter = (providerOptions.segmenter || {});
+        }
+        // Every key is set, undefined included: providers merge options shallowly.
         const mergedProviderOptions = {
             ...providerOptions,
-            locale: options.language,
+            locale: next.locale,
             textNormalization: {
-                ...textNormalization,
-                locale: options.language,
-            },
-            segmenter: {
-                ...segmenter,
-                locale: options.language,
+                ...providerOptions.textNormalization,
+                locale: next.textNormalization,
             },
+            segmenter: { ...providerOptions.segmenter, locale: next.segmenter },
+            contentLanguage: named,
         };
         this.ttsConfig = {
             ...this.ttsConfig,
             providerOptions: mergedProviderOptions,
         };
-        if ("updateSettings" in this.provider &&
-            typeof this.provider.updateSettings ===
-                "function") {
-            await this.provider.updateSettings({ providerOptions: mergedProviderOptions });
-        }
+        await this.provider.updateSettings({
+            providerOptions: mergedProviderOptions,
+        });
     }
     async resolveSpeechContent(text, options) {
         const normalizedInputText = normalizeTextForSpeech(text);
-        if (options?.ignoreCatalogs) {
-            return {
-                contentToSpeak: normalizedInputText,
-                speechText: normalizedInputText,
-                visibleText: normalizedInputText,
-                highlightText: normalizedInputText,
-                usedCatalogSpoken: false,
-                speechSource: "dom-or-input",
-                normalizedText: normalizedInputText,
-                containsMathMarkup: false,
-                speechMatchesVisibleText: true,
-            };
-        }
-        if (options?.catalogId && this.catalogResolver) {
+        if (options.catalogId && this.catalogResolver) {
             const catalogContent = this.catalogResolver.getAlternative(options.catalogId, {
                 type: "spoken",
-                language: options.language || "en-US",
+                language: options.language,
                 useFallback: true,
                 context: options.catalogContext,
                 form: "content",
@@ -1234,11 +1441,9 @@ export class TTSService {
             // instance. Fall through to generated TTS rather than speaking "".
             const spokenText = catalogContent?.content;
             if (catalogContent && spokenText !== undefined) {
-                const visibleText = options?.contentElement
-                    ? collectMathAwareTextAndMap(options.contentElement, this.getTextProcessingOptions(options.language)).visibleText || normalizedInputText
-                    : normalizedInputText;
+                const visibleText = collectMathAwareTextAndMap(options.contentElement, this.getTextProcessingOptions(options.language)).visibleText || normalizedInputText;
                 const normalizedCatalogText = normalizeTextForSpeech(spokenText);
-                this.debugLog(`[TTSService] Using catalog content for "${options.catalogId}" (${catalogContent.language})`);
+                logger.debug(`Using catalog content for "${options.catalogId}" (${catalogContent.language})`);
                 return {
                     contentToSpeak: spokenText,
                     speechText: spokenText,
@@ -1251,24 +1456,12 @@ export class TTSService {
                     speechMatchesVisibleText: normalizedCatalogText === visibleText,
                 };
             }
-            this.debugLog(`[TTSService] No catalog found for "${options.catalogId}", falling back to generated TTS`);
+            logger.debug(`No catalog found for "${options.catalogId}", falling back to generated TTS`);
         }
-        const composed = options?.contentElement
-            ? this.resolveCatalogComposedSpeechContent(options.contentElement, normalizedInputText, options)
-            : null;
+        const composed = this.resolveCatalogComposedSpeechContent(options.contentElement, normalizedInputText, options);
         if (composed)
             return composed;
-        const generated = options?.contentElement
-            ? await this.resolveGeneratedSpeechContent(options.contentElement, normalizedInputText, options.language)
-            : {
-                contentToSpeak: normalizedInputText,
-                speechText: normalizedInputText,
-                visibleText: normalizedInputText,
-                highlightText: normalizedInputText,
-                normalizedText: normalizedInputText,
-                containsMathMarkup: false,
-                speechMatchesVisibleText: true,
-            };
+        const generated = await this.resolveGeneratedSpeechContent(options.contentElement, normalizedInputText, options.language, options.contentRange);
         return {
             ...generated,
             usedCatalogSpoken: false,
@@ -1282,7 +1475,11 @@ export class TTSService {
         if (!chunks.some((chunk) => chunk.sourceElement))
             return null;
         const speechText = normalizeTextForSpeech(chunks.map((chunk) => chunk.speechText).join(" "));
-        const visibleText = collectMathAwareTextAndMap(contentElement, this.getTextProcessingOptions(options.language)).visibleText || normalizedInputText;
+        // A selection's visible text is the text it holds, which the caller passes:
+        // the highlight offsets index it from `wordBoundaryOffset`.
+        const visibleText = options.contentRange
+            ? normalizedInputText
+            : collectMathAwareTextAndMap(contentElement, this.getTextProcessingOptions(options.language)).visibleText || normalizedInputText;
         return {
             contentToSpeak: speechText,
             speechText,
@@ -1297,6 +1494,9 @@ export class TTSService {
         };
     }
     collectCatalogSpeechChunks(root, options) {
+        const catalogResolver = this.catalogResolver;
+        if (!catalogResolver)
+            return [];
         const chunks = [];
         let textBuffer = "";
         const flushTextBuffer = () => {
@@ -1311,27 +1511,36 @@ export class TTSService {
                 speechMatchesVisibleText: true,
             });
         };
+        const range = options.contentRange;
         const resolveCatalog = (element) => {
             const catalogIdRef = element.getAttribute("data-catalog-idref");
             if (!catalogIdRef)
                 return null;
+            // A card reads its whole node, so it stands in for a selection's part of
+            // the node only when the selection holds all of it. A part reads as the
+            // visible text selected.
+            if (range && !rangeHoldsSpeakableElement(range, element, root)) {
+                return null;
+            }
             const lookup = {
                 type: "spoken",
-                language: options.language || "en-US",
+                // The node's own language first: a `lang` inside the read content
+                // names the language of the part it marks.
+                language: findLangAttribute(element, root) || options.language,
                 useFallback: true,
                 context: options.catalogContext,
             };
             // 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",
             });
@@ -1354,7 +1563,7 @@ export class TTSService {
                 : null;
         };
         const getMathElementsForAlignment = (element) => {
-            const mathElements = Array.from(element.querySelectorAll("math"));
+            const mathElements = flatQuerySelectorAll(element, "math");
             if (element.localName?.toLowerCase() === "math") {
                 return [element, ...mathElements];
             }
@@ -1367,7 +1576,12 @@ export class TTSService {
             if (isNodeExcludedFromSpeech(node, root))
                 return;
             if (node.nodeType === Node.TEXT_NODE) {
-                textBuffer += ` ${node.textContent || ""}`;
+                if (!range) {
+                    textBuffer += ` ${node.textContent || ""}`;
+                }
+                else if (rangeIntersectsComposedNode(range, node)) {
+                    textBuffer += ` ${textInRange(node, range)}`;
+                }
                 return;
             }
             if (node.nodeType !== Node.ELEMENT_NODE)
@@ -1378,49 +1592,47 @@ export class TTSService {
                 flushTextBuffer();
                 const collectedVisible = collectMathAwareTextAndMap(element, this.getTextProcessingOptions(options.language));
                 const visibleText = collectedVisible.visibleText ||
-                    normalizeTextForSpeech(element.textContent || "");
+                    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
                         ? {
@@ -1446,7 +1658,7 @@ export class TTSService {
                     chunks.push(scriptChunk);
                 return;
             }
-            for (const child of Array.from(element.childNodes)) {
+            for (const child of flatTreeChildNodes(element)) {
                 visit(child);
             }
         };
@@ -1468,12 +1680,13 @@ export class TTSService {
         const provider = this.currentProvider;
         if (!provider)
             return "plain";
-        // Belt-and-suspenders: the browser provider can never voice SSML.
-        if (provider.providerId?.toLowerCase() === "browser")
-            return "plain";
         return provider.getCapabilities?.().supportsSSML ? "ssml" : "plain";
     }
-    async resolveGeneratedSpeechContent(contentElement, normalizedInputText, language) {
+    /**
+     * With `range`, the selection only: an equation it holds whole reads as math
+     * speech, and a selection without one reads the selected text, `normalizedInputText`.
+     */
+    async resolveGeneratedSpeechContent(contentElement, normalizedInputText, language, range) {
         // Delegate to the generated-speech module: a pure plan assembly + SRE
         // memoization core, plus a DOM adapter that binds live-DOM anchors and
         // emits playback chunks. The aggregate `contentToSpeak` stays plain text
@@ -1481,14 +1694,19 @@ export class TTSService {
         const playbackFormat = this.resolveGeneratedPlaybackFormat();
         const { plan, containsMathMarkup, visibleText: collectedVisibleText, } = await buildGeneratedSpeechFromRoot({
             contentRoot: contentElement,
+            range,
             language,
             mathSpeech: this.getMathSpeechOptions(),
             textProcessingOptions: this.getTextProcessingOptions(language),
             produceSsml: playbackFormat === "ssml",
             resolveMathSpeech: this.generatedMathSpeechResolver,
         });
-        const visibleText = collectedVisibleText || normalizedInputText;
         if (!containsMathMarkup) {
+            // The input text is the selection's text in the root's visible-text map,
+            // which its highlight offsets index.
+            const visibleText = range
+                ? normalizedInputText
+                : collectedVisibleText || normalizedInputText;
             return {
                 contentToSpeak: visibleText,
                 speechText: visibleText,
@@ -1499,6 +1717,7 @@ export class TTSService {
                 speechMatchesVisibleText: true,
             };
         }
+        const visibleText = collectedVisibleText || normalizedInputText;
         const speechChunks = planToCompositionChunkInputs(plan, {
             format: playbackFormat,
         });
@@ -1519,7 +1738,7 @@ export class TTSService {
             .replace(/\s+/g, " ")
             .trim()
             .slice(0, 200);
-        this.debugLog("[TTSService] Speak resolved content", {
+        logger.debug("Speak resolved content", {
             source: args.speechSource,
             catalogId: args.catalogId || null,
             length: args.contentToSpeak.length,
@@ -1528,7 +1747,7 @@ export class TTSService {
     }
     initializeSpeakTracking(contentToSpeak, options) {
         this.currentText = contentToSpeak;
-        this.currentContentElement = options?.contentElement || null;
+        this.currentContentElement = options.contentElement;
         this.lastError = null;
         this.currentBoundaryOffset = 0;
         this.playbackChunks = [];
@@ -1537,7 +1756,7 @@ export class TTSService {
     prepareHighlightsForSpeak(args) {
         if (!this.currentContentElement || !this.highlightCoordinator)
             return;
-        this.buildPositionMap(this.currentContentElement, args.contentToSpeak, args.options?.language);
+        this.buildPositionMap(this.currentContentElement, args.contentToSpeak, args.options.language);
         if (args.highlightMode === "sentence" && args.shouldUsePlan) {
             return;
         }
@@ -1545,7 +1764,7 @@ export class TTSService {
         this.runWhenPlaybackStarts(args.runId, () => {
             if (initialSegment) {
                 this.highlightSentenceSegment(initialSegment.startOffset, initialSegment.text);
-                this.debugLog("[TTSService] Applied initial sentence highlighting");
+                logger.debug("Applied initial sentence highlighting");
             }
             else {
                 try {
@@ -1560,34 +1779,29 @@ export class TTSService {
         });
     }
     configureWordBoundaryHighlighting(args) {
-        if (!this.provider ||
-            args.highlightMode !== "word" ||
-            !this.highlightCoordinator ||
-            !this.currentContentElement) {
+        if (!this.provider)
+            return;
+        // A sentence-mode read paints no words, so it takes no word boundaries.
+        if (args.highlightMode === "sentence") {
+            this.provider.onWordBoundary = undefined;
             return;
         }
-        // Word index uses the same globalIndex as highlightTTSWord (browser boundaries
-        // or ServerTTSProvider time-scaled onWordBoundary).
+        if (!this.highlightCoordinator || !this.currentContentElement)
+            return;
+        // Browser boundaries and the server provider's time-scaled boundaries index
+        // the same spoken text.
         this.provider.onWordBoundary = (word, charIndex, length) => {
             const wordLength = length || word.length;
             const spokenIndex = charIndex + this.currentBoundaryOffset;
             const globalIndex = spokenIndex + args.wordBoundaryOffset;
             this.highlightSentenceForOffset(spokenIndex);
-            const highlightRange = this.findHighlightRange(globalIndex, wordLength);
-            if (highlightRange && this.highlightCoordinator) {
-                const highlightText = highlightRange.node.textContent?.substring(highlightRange.start, highlightRange.end) || "";
-                this.debugLog(`[TTSService] Highlighting "${highlightText}" (word: "${word}") at position ${globalIndex}`);
-                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}`);
+            const ranges = createRangesFromVisibleMap(this.normalizedToDOM, globalIndex, globalIndex + wordLength);
+            if (ranges.length === 0) {
+                logger.debug(`no text at position ${globalIndex}, length ${wordLength}, to highlight`);
+                return;
             }
+            logger.debug(`Highlighting "${ranges.join("")}" (word: "${word}") at position ${globalIndex}`);
+            this.paintTTSWord(ranges);
         };
     }
     clearWordBoundaryHighlighting() {
@@ -1602,26 +1816,22 @@ export class TTSService {
         try {
             this.lastRenderedRegionTarget = null;
             if (chunk.regionRange) {
-                this.highlightCoordinator.clearHighlights?.(HighlightType.TTS_WORD);
-                this.paintTTSSentenceRanges([chunk.regionRange]);
+                const ranges = createRangesFromVisibleMap(chunk.visibleMap, 0, chunk.visibleText.length);
+                this.highlightCoordinator.clearTTSWord();
+                this.paintTTSSentenceRanges(ranges.length > 1 ? ranges : [chunk.regionRange]);
                 return;
             }
             if (!element)
                 return;
             const range = document.createRange();
             range.selectNodeContents(element);
-            this.highlightCoordinator.clearHighlights?.(HighlightType.TTS_WORD);
+            this.highlightCoordinator.clearTTSWord();
             this.paintTTSSentenceRanges([range]);
         }
         catch {
             // Continue playback even when a detached node cannot be highlighted.
         }
     }
-    highlightCatalogActiveRange(range) {
-        if (!this.highlightCoordinator)
-            return;
-        this.paintTTSWordRange(this.resolveWordHighlightRange(range).range);
-    }
     highlightRenderableRegionTarget(target) {
         if (!this.highlightCoordinator ||
             !target ||
@@ -1638,7 +1848,7 @@ export class TTSService {
                 range.selectNodeContents(target.element);
             }
             else if (target.type === "range") {
-                this.paintTTSSentenceRanges([target.range]);
+                this.paintTTSSentenceRanges(target.ranges ?? [target.range]);
                 this.lastRenderedRegionTarget = target;
                 return;
             }
@@ -1663,28 +1873,24 @@ 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") {
             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);
-            }
+            if (nativeRange)
+                this.paintTTSWord([nativeRange]);
             return;
         }
         if (target.type === "range") {
-            this.highlightCatalogActiveRange(target.range);
+            this.paintTTSWord(target.ranges ?? [target.range]);
             return;
         }
         const elementNativeRange = document.createRange();
         elementNativeRange.selectNodeContents(target.element);
         const resolvedElementRange = this.resolveWordHighlightRange(elementNativeRange);
         if (resolvedElementRange.remapped) {
-            this.paintTTSWordRange(resolvedElementRange.range);
+            this.highlightCoordinator.highlightTTSWord([resolvedElementRange.range]);
             return;
         }
         // Element targets are atomic: a resolved math token, a whole-expression
@@ -1699,10 +1905,12 @@ export class TTSService {
         const onlyChild = target.element.childNodes.length === 1 ? target.element.firstChild : null;
         if (target.quality === "semantic-token" &&
             onlyChild?.nodeType === Node.TEXT_NODE) {
-            this.highlightCoordinator.highlightTTSWord(onlyChild, 0, onlyChild.textContent?.length || 0);
+            const tokenRange = document.createRange();
+            tokenRange.selectNodeContents(onlyChild);
+            this.highlightCoordinator.highlightTTSWord([tokenRange]);
             return;
         }
-        this.highlightCoordinator.highlightTTSWordElement?.(target.element);
+        this.highlightCoordinator.highlightTTSWordElement(target.element);
     }
     renderHighlightDecision(decision) {
         this.highlightRenderableRegionTarget(decision.regionTarget);
@@ -1713,21 +1921,24 @@ 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) {
-                this.debugLog("[TTSService] 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.
+                logger.debug("SSML chunk speak failed; retrying plain text", {
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                // 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)) {
                     this.pendingPlaybackStartHighlights = [];
                     this.clearPlaybackStartBarrier();
-                    this.setState(PlaybackState.PLAYING);
+                    this.markPlaying();
                 }
                 await this.speakCatalogChunkOnce(chunk.plainFallback, runId);
                 return;
@@ -1787,6 +1998,18 @@ export class TTSService {
                 cleanup();
                 reject(new Error(`[tts] recorded audio failed to play: ${source.src}`));
             };
+            // A pause before the clip starts rejects its play with an AbortError;
+            // resume plays it, so that rejection is no failure of the clip.
+            const play = () => {
+                Promise.resolve(element.play())
+                    .then(markStarted)
+                    .catch((error) => {
+                    const aborted = error?.name === "AbortError";
+                    if (aborted && this.state === PlaybackState.PAUSED)
+                        return;
+                    onError();
+                });
+            };
             // Cancellation has to settle this promise, not just stop the element:
             // `stop()` bumps the run id, and a pending play that never resolves would
             // wedge the chunk loop on a run nobody is listening to any more.
@@ -1800,6 +2023,7 @@ export class TTSService {
                     element.pause();
                     resolve();
                 },
+                play,
             };
             element.addEventListener("ended", onEnded);
             element.addEventListener("error", onError);
@@ -1807,7 +2031,7 @@ export class TTSService {
             // Reaching the slice's end is this clip finishing, so the chunk sequence
             // advances rather than the element merely pausing.
             disposeFragment = enforceMediaFragment(element, media.fragment, onEnded);
-            Promise.resolve(element.play()).then(markStarted).catch(onError);
+            play();
         }).finally(() => {
             if (this.activeRecordedAudio?.element === element) {
                 this.activeRecordedAudio = null;
@@ -1852,6 +2076,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));
@@ -1860,7 +2087,9 @@ export class TTSService {
                 this.highlightCatalogRegion(chunk);
             }
         });
-        const canUseChunkBoundaries = chunk.sourceElement &&
+        // A sentence-mode read takes no word boundaries, aligned chunk or not.
+        const canUseChunkBoundaries = this.resolveHighlightMode() === "word" &&
+            chunk.sourceElement &&
             ((chunk.mathAlignment && chunk.mathAlignment.speech.tokens.length > 0) ||
                 (chunk.mathAlignments && chunk.mathAlignments.length > 0) ||
                 (chunk.alignment &&
@@ -1872,7 +2101,7 @@ export class TTSService {
             const previousOnWordBoundary = provider.onWordBoundary;
             provider.onWordBoundary = undefined;
             try {
-                await provider.speak(chunk.speechText);
+                await this.speakWithinLimit(chunk.speechText, runId);
             }
             finally {
                 if (this.provider === provider &&
@@ -1886,25 +2115,19 @@ export class TTSService {
         const provider = this.provider;
         const previousOnWordBoundary = provider.onWordBoundary;
         const installedHandler = (word, position, length) => {
-            if (runId !== this.speakRunId)
-                return;
-            if (highlightPlan && pipelineChunk) {
-                const providerOffsetSpace = pipelineChunk.offsetSpace === "unsupported"
-                    ? "unknown"
-                    : pipelineChunk.offsetSpace;
-                this.renderHighlightDecision(highlightPlan.resolveBoundary({
-                    chunkId: pipelineChunk.id,
-                    word,
-                    position,
-                    length,
-                    providerOffsetSpace,
-                }));
+            if (runId !== this.speakRunId || !highlightPlan || !pipelineChunk)
                 return;
-            }
+            this.renderHighlightDecision(highlightPlan.resolveBoundary({
+                chunkId: pipelineChunk.id,
+                word,
+                position,
+                length,
+                providerOffsetSpace,
+            }));
         };
         provider.onWordBoundary = installedHandler;
         try {
-            await provider.speak(chunk.speechText);
+            await this.speakWithinLimit(chunk.speechText, runId);
         }
         finally {
             if (this.provider === provider &&
@@ -1917,6 +2140,7 @@ export class TTSService {
     async executeSpeakPlayback(args) {
         if (args.speechChunks?.length && this.provider) {
             for (let index = 0; index < args.speechChunks.length; index++) {
+                await this.waitWhilePaused(args.runId);
                 if (args.runId !== this.speakRunId)
                     return;
                 const segment = this.seekSegments[index];
@@ -1928,23 +2152,19 @@ 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 if (this.provider) {
-                await this.provider.speak(args.contentToSpeak);
-            }
+        if (args.shouldUsePlan &&
+            this.currentContentElement &&
+            this.seekSegments.length > 0) {
+            await this.speakWithPlan(this.seekSegments, args.runId, {
+                highlightMode: args.highlightMode,
+            });
             return;
         }
-        if (this.provider) {
-            await this.provider.speak(args.contentToSpeak);
-        }
+        await this.speakWithinLimit(args.contentToSpeak, args.runId);
     }
     clearHighlightsAndTracking() {
+        // A finished run leaves no handler for the next read to inherit.
+        this.clearWordBoundaryHighlighting();
         this.pendingPlaybackStartHighlights = [];
         this.activePlaybackRate = null;
         if (this.highlightCoordinator) {
@@ -1959,38 +2179,22 @@ export class TTSService {
         this.playbackChunks = [];
         this.sentenceHighlightSegments = [];
         this.activeSentenceStartOffset = null;
+        this.wordlessPartHighlight = null;
     }
-    /**
-     * Speak a text range with accurate word highlighting
-     *
-     * This calculates the offset of the range within its parent element
-     * to ensure word highlighting aligns correctly with the selected text.
-     *
-     * @param range DOM Range to speak
-     */
     /**
      * The selected part of `root`'s normalized visible text and where it starts, or
      * null when the map is unavailable or holds no selected character.
      */
-    selectMappedRangeText(range, root) {
+    selectMappedRangeText(range, root, language) {
         if (typeof range.comparePoint !== "function")
             return null;
-        const { text: rootText, map } = collectVisibleTextAndMap(root, this.getTextProcessingOptions());
+        const { text: rootText, map } = collectVisibleTextAndMap(root, this.getTextProcessingOptions(language));
         let start = -1;
         let end = -1;
         for (const [index, { node, offset }] of map) {
             if (index >= rootText.length)
                 continue;
-            let inside = false;
-            try {
-                inside =
-                    range.comparePoint(node, offset) === 0 &&
-                        range.comparePoint(node, Math.min(offset + 1, node.length)) === 0;
-            }
-            catch {
-                inside = false;
-            }
-            if (!inside)
+            if (!rangeHoldsTextPosition(range, node, offset))
                 continue;
             if (start === -1 || index < start)
                 start = index;
@@ -2004,103 +2208,39 @@ export class TTSService {
         const text = raw.trim();
         return text ? { text, offset: start + leading } : null;
     }
-    async speakRange(range, options) {
-        if (!this.provider) {
-            throw new Error("TTS service not initialized");
-        }
-        // Enforced from the live ancestors rather than from `root`, because the
-        // element carrying the suppression may sit above whatever root the caller
-        // passed or the range happens to resolve to.
-        if (isNodeSuppressedForTTS(range.commonAncestorContainer)) {
-            console.warn("[tts] selection lies inside content marked not-to-be-spoken; nothing was spoken. Selecting a node and pressing read-aloud must not become a way around suppression.");
-            return;
-        }
-        // Use explicit content root when provided; otherwise keep highlighting scoped
-        // to the selected range's nearest element ancestor.
-        const fromOptions = options?.contentRoot || null;
-        let root = fromOptions;
-        if (!root) {
-            const ancestor = range.commonAncestorContainer;
-            root =
-                ancestor.nodeType === Node.ELEMENT_NODE
-                    ? ancestor
-                    : ancestor.parentElement;
-        }
-        if (!root)
-            return;
-        const selected = collectRangeTextForSpeech(range, root);
-        const selectedText = selected.text.trim();
-        if (!selectedText) {
-            if (selected.filtered) {
-                console.warn("[tts] every part of the selection is either hidden or marked not-to-be-spoken; nothing was spoken.");
-            }
-            return;
-        }
-        // The spoken text and its offset come from the root's visible-text map, which
-        // the highlight position map and the structural speech plan index too. Joined
-        // from raw text nodes instead, a selection loses the space the map inserts
-        // between blocks, and every offset after that boundary drifts.
-        const mapped = this.selectMappedRangeText(range, root);
-        let text = selectedText;
-        let offset = mapped?.offset ?? 0;
-        if (mapped) {
-            text = mapped.text;
-        }
-        else {
-            // Filtered the same way as the speech itself: the offset indexes into the
-            // highlight text, which comes from the exclusion-aware collectors.
-            const beforeRange = document.createRange();
-            beforeRange.selectNodeContents(root);
-            beforeRange.setEnd(range.startContainer, range.startOffset);
-            const textBeforeRange = collectRangeTextForSpeech(beforeRange, root).text;
-            const normalizedTextBeforeRange = normalizeTextForSpeech(textBeforeRange);
-            offset =
-                normalizedTextBeforeRange.length +
-                    (/\s$/.test(textBeforeRange) && normalizedTextBeforeRange ? 1 : 0);
-        }
-        this.debugLog("[TTSService] speakRange offset calculation:", {
-            selectedText: text,
-            mapped: !!mapped,
-            offset,
-            rootTag: root.tagName,
-        });
-        // Speak the text with the root element as context
-        await this.speak(text, {
-            contentElement: root,
-            ignoreCatalogs: true,
-            wordBoundaryOffset: offset,
-        });
-    }
     /**
-     * Pause playback
+     * Pause playback. A pause while the read is loading holds it: its audio does
+     * not start until {@link resume}.
      */
     pause() {
-        if (!this.provider)
+        if (this.state !== PlaybackState.PLAYING &&
+            this.state !== PlaybackState.LOADING) {
             return;
-        if (this.state === PlaybackState.PLAYING) {
-            this.activeRecordedAudio?.element.pause();
-            this.provider.pause();
-            this.setState(PlaybackState.PAUSED);
         }
+        this.resumeState = this.state;
+        this.activeRecordedAudio?.element.pause();
+        this.provider?.pause();
+        // Between two parts, nothing is playing to pause: the run holds before
+        // its next part instead.
+        this.setState(PlaybackState.PAUSED);
     }
     /**
-     * Resume playback
+     * Resume playback, back to loading when the pause came before the audio
+     * started.
      */
     resume() {
-        if (!this.provider)
+        if (this.state !== PlaybackState.PAUSED)
             return;
-        if (this.state === PlaybackState.PAUSED) {
-            const recorded = this.activeRecordedAudio?.element;
-            if (recorded)
-                void Promise.resolve(recorded.play()).catch(() => { });
-            this.provider.resume();
-            this.setState(PlaybackState.PLAYING);
-        }
+        // State first: audio that starts during resume reports into it.
+        this.setState(this.resumeState);
+        this.activeRecordedAudio?.play();
+        this.provider?.resume();
+        this.releasePauseHold();
     }
     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)
@@ -2109,18 +2249,27 @@ export class TTSService {
         const restartChunks = this.playbackChunks.length
             ? this.playbackChunks.slice(safeTargetIndex)
             : null;
+        // A seek under a pause moves the cursor and stays paused: the restarted
+        // run holds before its first part until resume.
+        const holdPaused = this.state === PlaybackState.PAUSED;
         this.speakRunId += 1;
-        this.clearPlaybackStartBarrier();
-        this.cancelRecordedAudio();
+        this.abandonRun();
         this.provider.onWordBoundary = undefined;
         this.provider.stop();
         const runId = ++this.speakRunId;
         const restartSegments = this.seekSegments.slice(safeTargetIndex);
         this.highlightCoordinator?.clearTTS();
         this.activeSentenceStartOffset = null;
-        this.setState(PlaybackState.LOADING);
+        this.currentBoundaryOffset = this.seekSegments[safeTargetIndex].startOffset;
+        if (!holdPaused)
+            this.setState(PlaybackState.LOADING);
         const playbackStartBarrier = this.installPlaybackStartBarrier(runId, !!restartChunks?.[0]?.audio);
-        if (!playbackStartBarrier) {
+        if (holdPaused) {
+            this.resumeState = playbackStartBarrier
+                ? PlaybackState.LOADING
+                : PlaybackState.PLAYING;
+        }
+        else if (!playbackStartBarrier) {
             this.setState(PlaybackState.PLAYING);
         }
         this.activePlaybackRate = this.normalizePlaybackRate(Number(this.ttsConfig.rate ?? 1));
@@ -2131,6 +2280,7 @@ export class TTSService {
             });
             if (restartChunks) {
                 for (let index = 0; index < restartChunks.length; index++) {
+                    await this.waitWhilePaused(runId);
                     if (runId !== this.speakRunId)
                         return;
                     const absoluteIndex = safeTargetIndex + index;
@@ -2152,8 +2302,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();
@@ -2251,59 +2404,49 @@ 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() {
-        if (!this.provider)
-            return;
         this.speakRunId += 1;
-        this.clearPlaybackStartBarrier();
-        this.cancelRecordedAudio();
-        this.provider.onWordBoundary = undefined;
-        this.provider.stop();
-        this.setState(PlaybackState.IDLE);
+        this.abandonRun();
+        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;
-    }
-    /**
-     * 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,
-        }));
+        // Announced even from idle, so a listener sees the owner released.
+        const releasedOwner = this.runOwner !== null;
+        this.runOwner = null;
+        this.setState(PlaybackState.IDLE, releasedOwner);
     }
     /**
-     * Check if currently playing
+     * Stop playback and drop the provider, whose owner destroys it. A later speak
+     * waits on the readiness gate, as before the first {@link initialize}.
      */
-    isPlaying() {
-        return this.state === PlaybackState.PLAYING;
+    releaseProvider() {
+        this.stop();
+        this.provider = null;
+        this.currentProvider = null;
     }
     /**
-     * Check if paused
+     * Stop, release the provider and drop every listener, hook and pending timer.
+     * A disposed service cannot speak or be initialized again.
      */
-    isPaused() {
-        return this.state === PlaybackState.PAUSED;
+    dispose() {
+        if (this.disposed)
+            return;
+        this.releaseProvider();
+        this.disposed = true;
+        this.speakRunId += 1;
+        this.abandonRun();
+        this.playbackRateRequestId += 1;
+        this.pendingPlaybackRateRequest = null;
+        this.listeners.clear();
+        this.readinessGate = null;
+        this.mathSpeechSource = null;
+        this.highlightTargetResolverProvider = null;
+        this.highlightCoordinator = null;
+        this.catalogResolver = null;
+        this.telemetryReporter = null;
     }
     /**
      * Get current state
@@ -2311,60 +2454,36 @@ export class TTSService {
     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;
-    }
-    /**
-     * Subscribe to state changes
-     *
-     * @param id Unique listener ID
-     * @param callback Function to call on state change
-     */
-    onStateChange(id, callback) {
-        if (!this.listeners.has(id)) {
-            this.listeners.set(id, new Set());
-        }
-        this.listeners.get(id).add(callback);
+    getRunOwner() {
+        return this.runOwner;
     }
     /**
-     * Unsubscribe from state changes
+     * Subscribe to playback state changes. The returned function unsubscribes;
+     * each subscription is its own, so the same callback can be subscribed twice.
      */
-    offStateChange(id, callback) {
-        const callbacks = this.listeners.get(id);
-        if (callbacks) {
-            callbacks.delete(callback);
-            if (callbacks.size === 0) {
-                this.listeners.delete(id);
-            }
-        }
+    onStateChange(callback) {
+        const listener = (state) => callback(state);
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
     }
     /**
-     * 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 callbacks of this.listeners.values()) {
-            for (const callback of callbacks) {
-                callback(newState);
-            }
+        for (const listener of [...this.listeners]) {
+            listener(newState);
         }
+        if (previousState === newState)
+            return;
         void this.emitTelemetry("pie-tool-playback-state-changed", {
             toolId: "textToSpeech",
-            providerId: "tts",
             previousState,
             state: newState,
         });
@@ -2374,7 +2493,6 @@ export class TTSService {
                 : "pie-tool-playback-start";
             void this.emitTelemetry(eventName, {
                 toolId: "textToSpeech",
-                providerId: "tts",
                 previousState,
                 state: newState,
             });
@@ -2383,7 +2501,6 @@ export class TTSService {
         if (newState === PlaybackState.PAUSED) {
             void this.emitTelemetry("pie-tool-playback-pause", {
                 toolId: "textToSpeech",
-                providerId: "tts",
                 previousState,
                 state: newState,
             });
@@ -2392,7 +2509,6 @@ export class TTSService {
         if (newState === PlaybackState.ERROR) {
             void this.emitTelemetry("pie-tool-playback-error", {
                 toolId: "textToSpeech",
-                providerId: "tts",
                 previousState,
                 state: newState,
                 message: this.lastError || undefined,
@@ -2405,7 +2521,6 @@ export class TTSService {
                 previousState === PlaybackState.LOADING)) {
             void this.emitTelemetry("pie-tool-playback-stop", {
                 toolId: "textToSpeech",
-                providerId: "tts",
                 previousState,
                 state: newState,
             });