@pie-players/pie-assessment-toolkit 0.3.44 → 0.3.45

package/dist/services/TTSService.js

@@ -15,9 +15,16 @@
  *
  * Part of PIE Assessment Toolkit.
  */
+import { HighlightColor, HighlightType } from "./HighlightCoordinator.js";
 import { BrowserTTSProvider } from "./tts/browser-provider.js";
-import { collectVisibleTextAndMap, extractVisibleText as extractVisibleTextFromDOM, isElementHiddenForTTS, normalizeTextForSpeech, } from "./tts/text-processing.js";
+import { collectVisibleTextAndMap, isElementHiddenForTTS, isNodeHiddenForTTS, normalizeTextForSpeech, } 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 { createTTSHighlightPlan, normalizeSpeechChunks, resolveReadableRegion, } from "./tts/highlight-pipeline/index.js";
 import { PIE_TTS_CONTROL_HANDOFF_EVENT, } from "./tts-control-events.js";
 /**
  * Playback state
@@ -30,6 +37,30 @@ export var PlaybackState;
     PlaybackState["PAUSED"] = "paused";
     PlaybackState["ERROR"] = "error";
 })(PlaybackState || (PlaybackState = {}));
+const sameRange = (left, right) => left === right ||
+    (left.startContainer === right.startContainer &&
+        left.startOffset === right.startOffset &&
+        left.endContainer === right.endContainer &&
+        left.endOffset === right.endOffset);
+const sameRenderableHighlightTarget = (left, right) => {
+    if (left === right)
+        return true;
+    if (!left || !right || left.type !== right.type || left.quality !== right.quality) {
+        return false;
+    }
+    if (left.type === "range" && right.type === "range") {
+        return sameRange(left.range, right.range);
+    }
+    if (left.type === "element" && right.type === "element") {
+        return left.element === right.element;
+    }
+    if (left.type === "text-range" && right.type === "text-range") {
+        return (left.node === right.node &&
+            left.startOffset === right.startOffset &&
+            left.endOffset === right.endOffset);
+    }
+    return false;
+};
 /**
  * TTSService
  *
@@ -55,8 +86,38 @@ export class TTSService {
     currentSeekSegmentIndex = 0;
     activeSentenceStartOffset = null;
     activeHighlightMode = "word";
+    lastRenderedRegionTarget = null;
     telemetryReporter = null;
+    // Memoized SRE resolver for the runtime generated-speech path (PIE-623).
+    // 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);
+        }
+    }
     async emitTelemetry(eventName, payload) {
         try {
             await this.telemetryReporter?.(eventName, payload);
@@ -81,8 +142,27 @@ export class TTSService {
             typeof providerOptions.__pieTelemetry === "function"
                 ? providerOptions.__pieTelemetry
                 : null;
-        // Initialize provider and get implementation
-        this.provider = await provider.initialize(config);
+        // 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;
+            }
+        }
     }
     /**
      * Update TTS settings dynamically without full reinitialization
@@ -97,10 +177,21 @@ export class TTSService {
             throw new Error("TTSService not initialized. Call initialize() first.");
         }
         // If the provider implementation has an updateSettings method, use it
-        if ("updateSettings" in this.provider &&
-            typeof this.provider.updateSettings === "function") {
-            await this.provider.updateSettings(settings);
-            this.ttsConfig = { ...this.ttsConfig, ...settings };
+        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
@@ -138,7 +229,8 @@ export class TTSService {
      */
     getTextProcessingOptions(language) {
         const providerOptions = (this.ttsConfig.providerOptions || {});
-        const textNormalization = (providerOptions.textNormalization || {});
+        const textNormalization = (providerOptions.textNormalization ||
+            {});
         const mode = textNormalization.boundarySpacingMode;
         const boundarySpacingMode = mode === "none" || mode === "alnum" || mode === "segmenterPreferred"
             ? mode
@@ -149,11 +241,18 @@ export class TTSService {
                 : undefined);
         return { locale, boundarySpacingMode };
     }
+    getMathSpeechOptions() {
+        const providerOptions = (this.ttsConfig.providerOptions || {});
+        const mathSpeech = providerOptions.mathSpeech;
+        return normalizeSREMathSpeechOptions(mathSpeech);
+    }
     buildPositionMap(element, spokenText, language) {
         this.normalizedToDOM.clear();
         const { text: normalizedDomText, map } = collectVisibleTextAndMap(element, this.getTextProcessingOptions(language));
         this.normalizedToDOM = map;
-        console.log("[TTSService] Text comparison:", {
+        if (!TTSService.debugEnabled)
+            return;
+        this.debugLog("[TTSService] Text comparison:", {
             spokenLength: spokenText.length,
             normalizedDomLength: normalizedDomText.length,
             match: spokenText === normalizedDomText,
@@ -176,7 +275,7 @@ export class TTSService {
                     return null;
                 })(),
         });
-        console.log("[TTSService] Position map built:", {
+        this.debugLog("[TTSService] Position map built:", {
             entries: this.normalizedToDOM.size,
             spokenTextLength: spokenText.length,
             normalizedDomLength: normalizedDomText.length,
@@ -242,9 +341,6 @@ export class TTSService {
     isElementHidden(element) {
         return isElementHiddenForTTS(element);
     }
-    extractVisibleText(element, language) {
-        return extractVisibleTextFromDOM(element, this.getTextProcessingOptions(language));
-    }
     getBoundaryStrength(element) {
         const explicitBreakMs = Number(element.getAttribute("data-tts-break-ms"));
         if (Number.isFinite(explicitBreakMs) && explicitBreakMs > 0)
@@ -289,7 +385,10 @@ export class TTSService {
             }
             const role = (current.getAttribute("role") || "").toLowerCase();
             const tagName = current.tagName.toUpperCase();
-            if (tagName.match(/^H[1-6]$/) || role === "heading" || role === "listitem" || tagName === "LI") {
+            if (tagName.match(/^H[1-6]$/) ||
+                role === "heading" ||
+                role === "listitem" ||
+                tagName === "LI") {
                 best = current;
                 break;
             }
@@ -485,7 +584,9 @@ export class TTSService {
                 await providerWithPlan.speakSegments(segments);
             }
             finally {
-                this.provider.onWordBoundary = originalOnWordBoundary;
+                if (runId === this.speakRunId && this.provider === providerWithPlan) {
+                    this.provider.onWordBoundary = originalOnWordBoundary;
+                }
             }
             return;
         }
@@ -611,49 +712,64 @@ export class TTSService {
             throw new Error("TTS service not initialized");
         }
         const runId = ++this.speakRunId;
-        await this.applyLanguageSettings(options);
-        const { contentToSpeak, normalizedText, usedCatalogSpoken, speechSource } = this.resolveSpeechContent(text, options);
-        this.logResolvedSpeechContent({
-            contentToSpeak,
-            speechSource,
-            catalogId: options?.catalogId,
-        });
-        this.initializeSpeakTracking(contentToSpeak, options);
-        const highlightMode = options?.highlightModeOverride || this.resolveHighlightMode();
-        this.activeHighlightMode = highlightMode;
-        const shouldUsePlan = !!this.currentContentElement &&
-            !usedCatalogSpoken &&
-            !this.hasExplicitBreakSemantics(contentToSpeak);
-        this.seekSegments = this.hasExplicitBreakSemantics(contentToSpeak)
-            ? []
-            : shouldUsePlan && this.currentContentElement
-                ? this.createSpeechPlan(this.currentContentElement, normalizedText)
-                : this.createSeekSegmentsFromText(contentToSpeak);
-        this.sentenceHighlightSegments = this.hasExplicitBreakSemantics(contentToSpeak)
-            ? []
-            : this.createSentenceHighlightSegments({
+        try {
+            await this.applyLanguageSettings(options);
+            if (runId !== this.speakRunId)
+                return;
+            const resolvedContent = await this.resolveSpeechContent(text, options);
+            if (runId !== this.speakRunId)
+                return;
+            const { contentToSpeak, speechText, highlightText, normalizedText, usedCatalogSpoken, speechSource, speechMatchesVisibleText, speechChunks, } = resolvedContent;
+            this.logResolvedSpeechContent({
                 contentToSpeak,
-                shouldUsePlan,
-                playbackSegments: this.seekSegments,
+                speechSource,
+                catalogId: options?.catalogId,
             });
-        this.setState(PlaybackState.LOADING);
-        this.prepareHighlightsForSpeak({
-            contentToSpeak,
-            options,
-            highlightMode,
-            shouldUsePlan,
-        });
-        try {
-            this.configureWordBoundaryHighlighting({
+            this.initializeSpeakTracking(highlightText, options);
+            const highlightMode = options?.highlightModeOverride ||
+                (speechMatchesVisibleText ? this.resolveHighlightMode() : "sentence");
+            this.activeHighlightMode = highlightMode;
+            const hasExplicitBreaks = this.hasExplicitBreakSemantics(contentToSpeak);
+            const shouldUsePlan = !!this.currentContentElement &&
+                !usedCatalogSpoken &&
+                !hasExplicitBreaks &&
+                speechMatchesVisibleText;
+            this.seekSegments =
+                hasExplicitBreaks || !speechMatchesVisibleText
+                    ? []
+                    : shouldUsePlan && this.currentContentElement
+                        ? this.createSpeechPlan(this.currentContentElement, normalizedText)
+                        : this.createSeekSegmentsFromText(highlightText);
+            this.sentenceHighlightSegments = hasExplicitBreaks
+                ? []
+                : this.createSentenceHighlightSegments({
+                    contentToSpeak: highlightText,
+                    shouldUsePlan,
+                    playbackSegments: this.seekSegments,
+                });
+            this.setState(PlaybackState.LOADING);
+            this.prepareHighlightsForSpeak({
+                contentToSpeak: highlightText,
+                options,
                 highlightMode,
-                wordBoundaryOffset: options?.wordBoundaryOffset || 0,
+                shouldUsePlan,
             });
+            if (speechMatchesVisibleText) {
+                this.configureWordBoundaryHighlighting({
+                    highlightMode,
+                    wordBoundaryOffset: options?.wordBoundaryOffset || 0,
+                });
+            }
+            else {
+                this.clearWordBoundaryHighlighting();
+            }
             this.setState(PlaybackState.PLAYING);
             await this.executeSpeakPlayback({
                 shouldUsePlan,
                 runId,
                 highlightMode,
-                contentToSpeak,
+                contentToSpeak: speechText,
+                speechChunks,
             });
             if (runId !== this.speakRunId)
                 return;
@@ -662,26 +778,6 @@ export class TTSService {
         }
         catch (error) {
             let finalError = error;
-            if (runId === this.speakRunId) {
-                try {
-                    const recovered = await this.retryWithBrowserFallback({
-                        error,
-                        runId,
-                        shouldUsePlan,
-                        highlightMode,
-                        contentToSpeak,
-                        wordBoundaryOffset: options?.wordBoundaryOffset || 0,
-                    });
-                    if (recovered) {
-                        this.setState(PlaybackState.IDLE);
-                        this.clearHighlightsAndTracking();
-                        return;
-                    }
-                }
-                catch (retryError) {
-                    finalError = retryError;
-                }
-            }
             console.error("TTS error:", finalError);
             this.lastError =
                 finalError instanceof Error ? finalError.message : String(finalError);
@@ -692,35 +788,26 @@ export class TTSService {
             throw finalError;
         }
     }
-    shouldAttemptBrowserFallback(error) {
-        if (!this.provider || !this.currentProvider)
-            return false;
-        const providerId = (this.currentProvider.providerId || "").toLowerCase();
-        if (providerId === "browser")
-            return false;
-        const message = (error instanceof Error ? error.message : String(error))
-            .toLowerCase()
-            .trim();
-        // Avoid fallback for expected cancellation/superseded flows.
-        if (message.includes("superseded by a newer request"))
-            return false;
-        if (message.includes("aborterror"))
-            return false;
-        if (message.includes("aborted"))
-            return false;
-        if (message.includes("cancelled"))
-            return false;
-        if (message.includes("canceled"))
-            return false;
-        // For non-browser providers, default to browser fallback on runtime errors.
-        return true;
-    }
-    async switchProviderToBrowser(reason) {
+    async switchProviderToBrowser(reason, context) {
         if (!this.currentProvider)
             return false;
         const fallbackProvider = new BrowserTTSProvider();
         const previousProviderId = this.currentProvider.providerId;
         const browserConfig = { ...this.ttsConfig };
+        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();
@@ -729,21 +816,23 @@ export class TTSService {
             this.ttsConfig = browserConfig;
             await this.emitTelemetry("pie-tool-runtime-fallback", {
                 toolId: "textToSpeech",
-                operation: "tts-speak",
+                operation,
                 fromProvider: previousProviderId,
                 toProvider: fallbackProvider.providerId,
                 reason: reason instanceof Error ? reason.message : String(reason),
+                ...offendingDiagnostic,
             });
-            console.warn("[TTSService] Server TTS playback failed; switched to browser fallback", {
+            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: "tts-speak",
+                operation,
                 fromProvider: previousProviderId,
                 toProvider: "browser",
                 errorType: "TTSRuntimeFallbackError",
@@ -760,36 +849,13 @@ export class TTSService {
             return false;
         if (!("speechSynthesis" in window))
             return false;
-        return typeof globalThis.SpeechSynthesisUtterance === "function";
-    }
-    async retryWithBrowserFallback(args) {
-        if (!this.shouldAttemptBrowserFallback(args.error))
-            return false;
-        if (!this.isBrowserSpeechFallbackAvailable())
-            return false;
-        const switched = await this.switchProviderToBrowser(args.error);
-        if (!switched)
-            return false;
-        if (args.runId !== this.speakRunId)
-            return true;
-        // Rebind highlight callbacks to the newly initialized provider, then retry once.
-        this.configureWordBoundaryHighlighting({
-            highlightMode: args.highlightMode,
-            wordBoundaryOffset: args.wordBoundaryOffset,
-        });
-        await this.executeSpeakPlayback({
-            shouldUsePlan: args.shouldUsePlan,
-            runId: args.runId,
-            highlightMode: args.highlightMode,
-            contentToSpeak: args.contentToSpeak,
-        });
-        return true;
+        return (typeof globalThis
+            .SpeechSynthesisUtterance === "function");
     }
     async applyLanguageSettings(options) {
         if (!options?.language || !this.provider)
             return;
-        const providerOptions = (this.ttsConfig.providerOptions ||
-            {});
+        const providerOptions = (this.ttsConfig.providerOptions || {});
         const textNormalization = (providerOptions.textNormalization ||
             {});
         const segmenter = (providerOptions.segmenter || {});
@@ -815,55 +881,260 @@ export class TTSService {
             await this.provider.updateSettings({ providerOptions: mergedProviderOptions });
         }
     }
-    resolveSpeechContent(text, options) {
+    async resolveSpeechContent(text, options) {
         const normalizedInputText = normalizeTextForSpeech(text);
-        const normalizedText = options?.contentElement
-            ? this.extractVisibleText(options.contentElement, options.language) ||
-                normalizedInputText
-            : normalizedInputText;
-        let contentToSpeak = normalizedText;
-        let usedCatalogSpoken = false;
-        let speechSource = "dom-or-input";
+        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) {
             const catalogContent = this.catalogResolver.getAlternative(options.catalogId, {
                 type: "spoken",
                 language: options.language || "en-US",
                 useFallback: true,
+                context: options.catalogContext,
             });
             if (catalogContent) {
-                contentToSpeak = catalogContent.content;
-                usedCatalogSpoken = true;
-                speechSource = "catalog-spoken";
-                console.debug(`[TTSService] Using catalog content for "${options.catalogId}" (${catalogContent.language})`);
-            }
-            else {
-                console.debug(`[TTSService] No catalog found for "${options.catalogId}", falling back to generated TTS`);
+                const visibleText = options?.contentElement
+                    ? collectMathAwareTextAndMap(options.contentElement, this.getTextProcessingOptions(options.language)).visibleText || normalizedInputText
+                    : normalizedInputText;
+                const normalizedCatalogText = normalizeTextForSpeech(catalogContent.content);
+                this.debugLog(`[TTSService] Using catalog content for "${options.catalogId}" (${catalogContent.language})`);
+                return {
+                    contentToSpeak: catalogContent.content,
+                    speechText: catalogContent.content,
+                    visibleText,
+                    highlightText: visibleText,
+                    usedCatalogSpoken: true,
+                    speechSource: "catalog-spoken",
+                    normalizedText: visibleText,
+                    containsMathMarkup: false,
+                    speechMatchesVisibleText: normalizedCatalogText === visibleText,
+                };
             }
+            this.debugLog(`[TTSService] No catalog found for "${options.catalogId}", falling back to generated TTS`);
         }
-        if (usedCatalogSpoken && options?.contentElement) {
-            const normalizedCatalogText = normalizeTextForSpeech(contentToSpeak);
-            const preserveCatalogSpeech = this.hasExplicitBreakSemantics(contentToSpeak);
-            if (!preserveCatalogSpeech && normalizedCatalogText !== normalizedText) {
-                console.warn("[TTSService] Catalog spoken text diverges from visible DOM; using normalized visible text to keep highlighting aligned.", {
-                    catalogId: options.catalogId || null,
-                    catalogLength: normalizedCatalogText.length,
-                    visibleLength: normalizedText.length,
+        const composed = options?.contentElement
+            ? this.resolveCatalogComposedSpeechContent(options.contentElement, normalizedInputText, options)
+            : null;
+        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,
+            };
+        return {
+            ...generated,
+            usedCatalogSpoken: false,
+            speechSource: "dom-or-input",
+        };
+    }
+    resolveCatalogComposedSpeechContent(contentElement, normalizedInputText, options) {
+        if (!this.catalogResolver)
+            return null;
+        const chunks = this.collectCatalogSpeechChunks(contentElement, options);
+        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;
+        return {
+            contentToSpeak: speechText,
+            speechText,
+            visibleText,
+            highlightText: visibleText,
+            usedCatalogSpoken: true,
+            speechSource: "catalog-spoken",
+            normalizedText: visibleText,
+            containsMathMarkup: false,
+            speechMatchesVisibleText: chunks.every((chunk) => chunk.speechMatchesVisibleText),
+            speechChunks: chunks,
+        };
+    }
+    collectCatalogSpeechChunks(root, options) {
+        const chunks = [];
+        let textBuffer = "";
+        const flushTextBuffer = () => {
+            const visibleText = normalizeTextForSpeech(textBuffer);
+            textBuffer = "";
+            if (!visibleText)
+                return;
+            chunks.push({
+                speechText: visibleText,
+                visibleText,
+                sourceElement: null,
+                speechMatchesVisibleText: true,
+            });
+        };
+        const resolveCatalog = (element) => {
+            const catalogIdRef = element.getAttribute("data-catalog-idref");
+            if (!catalogIdRef)
+                return null;
+            return this.catalogResolver.getAlternative(catalogIdRef, {
+                type: "spoken",
+                language: options.language || "en-US",
+                useFallback: true,
+                context: options.catalogContext,
+            });
+        };
+        const getSingleMathElementForAlignment = (element, visibleText) => {
+            const mathElements = getMathElementsForAlignment(element);
+            if (mathElements.length !== 1)
+                return null;
+            const mathElement = mathElements[0];
+            const mathVisibleText = collectMathAwareTextAndMap(mathElement, this.getTextProcessingOptions(options.language)).visibleText || normalizeTextForSpeech(mathElement.textContent || "");
+            const compact = (value) => normalizeTextForSpeech(value).replace(/\s+/g, "");
+            return compact(mathVisibleText) === compact(visibleText)
+                ? mathElement
+                : null;
+        };
+        const getMathElementsForAlignment = (element) => {
+            const mathElements = Array.from(element.querySelectorAll("math"));
+            if (element.localName?.toLowerCase() === "math") {
+                return [element, ...mathElements];
+            }
+            return mathElements;
+        };
+        const visit = (node) => {
+            if (isNodeHiddenForTTS(node, root))
+                return;
+            if (node.nodeType === Node.TEXT_NODE) {
+                textBuffer += ` ${node.textContent || ""}`;
+                return;
+            }
+            if (node.nodeType !== Node.ELEMENT_NODE)
+                return;
+            const element = node;
+            const catalog = resolveCatalog(element);
+            if (catalog) {
+                flushTextBuffer();
+                const collectedVisible = collectMathAwareTextAndMap(element, this.getTextProcessingOptions(options.language));
+                const visibleText = collectedVisible.visibleText ||
+                    normalizeTextForSpeech(element.textContent || "");
+                const alignment = createCatalogSpanAlignment({
+                    speechText: catalog.content,
+                    visibleText,
+                });
+                const mathElement = getSingleMathElementForAlignment(element, visibleText);
+                const mathAlignment = mathElement
+                    ? createMathAwareAlignment({
+                        mathElement,
+                        speechText: catalog.content,
+                    })
+                    : undefined;
+                const mathAlignments = mathAlignment
+                    ? undefined
+                    : getMathElementsForAlignment(element).map((candidate) => ({
+                        element: candidate,
+                        alignment: createMathAwareAlignment({
+                            mathElement: candidate,
+                            speechText: catalog.content,
+                        }),
+                    }));
+                const speechText = normalizeTextForSpeech(catalog.content);
+                chunks.push({
+                    speechText: catalog.content,
+                    visibleText,
+                    sourceElement: element,
+                    regionElement: resolveReadableRegion(element, root),
+                    speechMatchesVisibleText: speechText === visibleText,
+                    playbackMode: alignment.playbackMode,
+                    alignment,
+                    mathAlignment,
+                    mathAlignments,
+                    visibleMap: collectedVisible.map,
                 });
-                contentToSpeak = normalizedText;
-                usedCatalogSpoken = false;
-                speechSource = "dom-or-input";
+                return;
             }
+            for (const child of Array.from(element.childNodes)) {
+                visit(child);
+            }
+        };
+        visit(root);
+        flushTextBuffer();
+        return chunks;
+    }
+    /**
+     * Decide the playback format for the generated (no authored catalog) math
+     * path. SSML is only emitted to providers that report `supportsSSML`: the
+     * browser Web Speech API speaks tags literally (capability `false`), and the
+     * server bridge reports `true` only for SSML-reliable backends (Polly,
+     * Google) — the `custom`/SchoolCity transport stays plain.
+     *
+     * A speak-time plain fallback (`SpeechCompositionChunk.plainFallback`) is the
+     * defensive net if a capable provider still rejects a given SSML payload.
+     */
+    resolveGeneratedPlaybackFormat() {
+        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) {
+        // 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
+        // (`plan.plainSpeechText`) so seek/structural-pause planning is unaffected.
+        const playbackFormat = this.resolveGeneratedPlaybackFormat();
+        const { plan, containsMathMarkup, visibleText: collectedVisibleText } = await buildGeneratedSpeechFromRoot({
+            contentRoot: contentElement,
+            language,
+            mathSpeech: this.getMathSpeechOptions(),
+            textProcessingOptions: this.getTextProcessingOptions(language),
+            produceSsml: playbackFormat === "ssml",
+            resolveMathSpeech: this.generatedMathSpeechResolver,
+        });
+        const visibleText = collectedVisibleText || normalizedInputText;
+        if (!containsMathMarkup) {
+            return {
+                contentToSpeak: visibleText,
+                speechText: visibleText,
+                visibleText,
+                highlightText: visibleText,
+                normalizedText: visibleText,
+                containsMathMarkup: false,
+                speechMatchesVisibleText: true,
+            };
         }
+        const speechChunks = planToCompositionChunkInputs(plan, {
+            format: playbackFormat,
+        });
+        const speechText = plan.plainSpeechText;
         return {
-            contentToSpeak,
-            usedCatalogSpoken,
-            speechSource,
-            normalizedText,
+            contentToSpeak: speechText,
+            speechText,
+            visibleText,
+            highlightText: visibleText,
+            normalizedText: visibleText,
+            containsMathMarkup: true,
+            speechMatchesVisibleText: speechText === visibleText,
+            speechChunks,
         };
     }
     logResolvedSpeechContent(args) {
-        const preview = args.contentToSpeak.replace(/\s+/g, " ").trim().slice(0, 200);
-        console.debug("[TTSService] Speak resolved content", {
+        const preview = args.contentToSpeak
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 200);
+        this.debugLog("[TTSService] Speak resolved content", {
             source: args.speechSource,
             catalogId: args.catalogId || null,
             length: args.contentToSpeak.length,
@@ -888,7 +1159,7 @@ export class TTSService {
         const initialSegment = this.sentenceHighlightSegments[0] || this.seekSegments[0];
         if (initialSegment) {
             this.highlightSentenceSegment(initialSegment.startOffset, initialSegment.text);
-            console.log("[TTSService] Applied initial sentence highlighting");
+            this.debugLog("[TTSService] Applied initial sentence highlighting");
         }
         else {
             try {
@@ -917,7 +1188,7 @@ export class TTSService {
             const highlightRange = this.findHighlightRange(globalIndex, wordLength);
             if (highlightRange && this.highlightCoordinator) {
                 const highlightText = highlightRange.node.textContent?.substring(highlightRange.start, highlightRange.end) || "";
-                console.log(`[TTSService] Highlighting "${highlightText}" (word: "${word}") at position ${globalIndex}`);
+                this.debugLog(`[TTSService] Highlighting "${highlightText}" (word: "${word}") at position ${globalIndex}`);
                 this.highlightCoordinator.highlightTTSWord(highlightRange.node, highlightRange.start, highlightRange.end);
             }
             else {
@@ -925,7 +1196,221 @@ export class TTSService {
             }
         };
     }
+    clearWordBoundaryHighlighting() {
+        if (this.provider) {
+            this.provider.onWordBoundary = undefined;
+        }
+    }
+    highlightCatalogRegion(chunk) {
+        const element = chunk.regionElement || chunk.sourceElement;
+        if ((!element && !chunk.regionRange) || !this.highlightCoordinator)
+            return;
+        try {
+            this.lastRenderedRegionTarget = null;
+            if (chunk.regionRange) {
+                this.highlightCoordinator.clearHighlights?.(HighlightType.TTS_WORD);
+                this.highlightCoordinator.highlightTTSSentence([chunk.regionRange]);
+                return;
+            }
+            if (!element)
+                return;
+            const range = document.createRange();
+            range.selectNodeContents(element);
+            this.highlightCoordinator.clearHighlights?.(HighlightType.TTS_WORD);
+            this.highlightCoordinator.highlightTTSSentence([range]);
+        }
+        catch {
+            // Continue playback even when a detached node cannot be highlighted.
+        }
+    }
+    highlightCatalogActiveRange(range) {
+        if (!this.highlightCoordinator)
+            return;
+        if (range.startContainer === range.endContainer &&
+            range.startContainer.nodeType === Node.TEXT_NODE) {
+            this.highlightCoordinator.highlightTTSWord(range.startContainer, range.startOffset, range.endOffset);
+            return;
+        }
+        this.highlightCoordinator.highlightRange(range, HighlightType.TTS_WORD, HighlightColor.YELLOW);
+    }
+    highlightRenderableRegionTarget(target) {
+        if (!this.highlightCoordinator ||
+            !target ||
+            typeof document === "undefined") {
+            return;
+        }
+        if (sameRenderableHighlightTarget(this.lastRenderedRegionTarget, target)) {
+            return;
+        }
+        try {
+            const range = document.createRange();
+            if (target.type === "element") {
+                range.selectNodeContents(target.element);
+            }
+            else if (target.type === "range") {
+                this.highlightCoordinator.highlightTTSSentence([target.range]);
+                this.lastRenderedRegionTarget = target;
+                return;
+            }
+            else {
+                range.setStart(target.node, target.startOffset);
+                range.setEnd(target.node, target.endOffset);
+            }
+            this.highlightCoordinator.highlightTTSSentence([range]);
+            this.lastRenderedRegionTarget = target;
+        }
+        catch {
+            // Continue playback even when a detached node cannot be highlighted.
+        }
+    }
+    highlightRenderableActiveTarget(target) {
+        if (!this.highlightCoordinator || typeof document === "undefined") {
+            return;
+        }
+        if (!target) {
+            // No active word for this boundary — an unresolved prose word, an SSML
+            // break/pause, or a token-mode equation still awaiting its first token.
+            // 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);
+            return;
+        }
+        if (target.type === "text-range") {
+            this.highlightCoordinator.highlightTTSWord(target.node, target.startOffset, target.endOffset);
+            return;
+        }
+        if (target.type === "range") {
+            this.highlightCatalogActiveRange(target.range);
+            return;
+        }
+        // Element targets are atomic: a resolved math token, a whole-expression
+        // fallback, or a replaced element (image/svg). Paint exactly the resolved
+        // element. Native MathML / HTML tokens that expose a single text node keep
+        // the CSS-range underline (it reads more precisely than an element box);
+        // everything else — notably MathJax CHTML tokens (`<mjx-mi><mjx-c/>`),
+        // which have no text node, and expression fallbacks — is marked on the
+        // element itself. Crucially we no longer escalate to the enclosing
+        // `<math>` / `<mjx-container>`: that escalation is why MathJax math only
+        // ever highlighted as a full block while native MathML tracked per-token.
+        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);
+            return;
+        }
+        this.highlightCoordinator.highlightTTSWordElement?.(target.element);
+    }
+    renderHighlightDecision(decision) {
+        this.highlightRenderableRegionTarget(decision.regionTarget);
+        this.highlightRenderableActiveTarget(decision.activeTarget);
+    }
+    async speakCatalogChunk(chunk, runId) {
+        try {
+            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.
+            if (chunk.plainFallback && runId === this.speakRunId) {
+                this.debugLog("[TTSService] SSML chunk speak failed; retrying plain text", { message: error instanceof Error ? error.message : String(error) });
+                await this.speakCatalogChunkOnce(chunk.plainFallback, runId);
+                return;
+            }
+            throw error;
+        }
+    }
+    async speakCatalogChunkOnce(chunk, runId) {
+        if (!this.provider)
+            return;
+        this.lastRenderedRegionTarget = null;
+        const contentRoot = chunk.regionElement || chunk.sourceElement || this.currentContentElement;
+        const pipelineChunk = contentRoot
+            ? normalizeSpeechChunks({
+                contentRoot,
+                chunks: [chunk],
+            })[0]
+            : null;
+        // Carried through the config channel (see buildRuntimeTTSConfig); defaults
+        // to per-token math highlighting unless a host explicitly disables it.
+        const mathTokenHighlighting = this.ttsConfig.mathTokenHighlighting !== false;
+        const highlightPlan = pipelineChunk
+            ? createTTSHighlightPlan({
+                chunks: [pipelineChunk],
+                mathTokenHighlighting,
+            })
+            : null;
+        if (highlightPlan && pipelineChunk && chunk.mathAlignment) {
+            this.renderHighlightDecision(highlightPlan.resolveInitial(pipelineChunk.id));
+        }
+        else {
+            this.highlightCatalogRegion(chunk);
+        }
+        const canUseChunkBoundaries = chunk.sourceElement &&
+            ((chunk.mathAlignment && chunk.mathAlignment.speech.tokens.length > 0) ||
+                (chunk.mathAlignments && chunk.mathAlignments.length > 0) ||
+                (chunk.alignment &&
+                    chunk.visibleMap &&
+                    (chunk.playbackMode === "exact-word" ||
+                        chunk.playbackMode === "anchor-span")));
+        if (!canUseChunkBoundaries) {
+            const provider = this.provider;
+            const previousOnWordBoundary = provider.onWordBoundary;
+            provider.onWordBoundary = undefined;
+            try {
+                await provider.speak(chunk.speechText);
+            }
+            finally {
+                if (this.provider === provider &&
+                    runId === this.speakRunId &&
+                    provider.onWordBoundary === undefined) {
+                    provider.onWordBoundary = previousOnWordBoundary;
+                }
+            }
+            return;
+        }
+        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,
+                }));
+                return;
+            }
+        };
+        provider.onWordBoundary = installedHandler;
+        try {
+            await provider.speak(chunk.speechText);
+        }
+        finally {
+            if (this.provider === provider &&
+                runId === this.speakRunId &&
+                provider.onWordBoundary === installedHandler) {
+                provider.onWordBoundary = previousOnWordBoundary;
+            }
+        }
+    }
     async executeSpeakPlayback(args) {
+        if (args.speechChunks?.length && this.provider) {
+            for (const chunk of args.speechChunks) {
+                if (args.runId !== this.speakRunId)
+                    return;
+                await this.speakCatalogChunk(chunk, args.runId);
+            }
+            return;
+        }
         if (args.shouldUsePlan && this.currentContentElement) {
             const segments = this.seekSegments;
             if (segments.length > 0) {
@@ -946,6 +1431,7 @@ export class TTSService {
         if (this.highlightCoordinator) {
             this.highlightCoordinator.clearTTS();
         }
+        this.lastRenderedRegionTarget = null;
         this.currentContentElement = null;
         this.normalizedToDOM.clear();
         this.currentBoundaryOffset = 0;
@@ -987,8 +1473,10 @@ export class TTSService {
         beforeRange.selectNodeContents(root);
         beforeRange.setEnd(range.startContainer, range.startOffset);
         const textBeforeRange = beforeRange.toString();
-        const offset = normalizeTextForSpeech(textBeforeRange).length;
-        console.log("[TTSService] speakRange offset calculation:", {
+        const normalizedTextBeforeRange = normalizeTextForSpeech(textBeforeRange);
+        const offset = normalizedTextBeforeRange.length +
+            (/\s$/.test(textBeforeRange) && normalizedTextBeforeRange ? 1 : 0);
+        this.debugLog("[TTSService] speakRange offset calculation:", {
             selectedText: text,
             textBeforeRange: textBeforeRange.substring(0, 100),
             offset,
@@ -997,6 +1485,7 @@ export class TTSService {
         // Speak the text with the root element as context
         await this.speak(text, {
             contentElement: root,
+            ignoreCatalogs: true,
             wordBoundaryOffset: offset,
         });
     }
@@ -1025,7 +1514,8 @@ export class TTSService {
     async seekBy(units) {
         if (!this.provider || !this.currentText)
             return;
-        if (this.state !== PlaybackState.PLAYING && this.state !== PlaybackState.PAUSED) {
+        if (this.state !== PlaybackState.PLAYING &&
+            this.state !== PlaybackState.PAUSED) {
             return;
         }
         if (this.hasExplicitBreakSemantics(this.currentText))
@@ -1040,6 +1530,7 @@ export class TTSService {
         if (targetIndex === currentIndex)
             return;
         this.speakRunId += 1;
+        this.provider.onWordBoundary = undefined;
         this.provider.stop();
         this.currentSeekSegmentIndex = targetIndex;
         const runId = ++this.speakRunId;
@@ -1078,6 +1569,7 @@ export class TTSService {
         if (!this.provider)
             return;
         this.speakRunId += 1;
+        this.provider.onWordBoundary = undefined;
         this.provider.stop();
         this.setState(PlaybackState.IDLE);
         this.currentText = null;
@@ -1086,6 +1578,7 @@ export class TTSService {
             this.highlightCoordinator.clearTTS();
         }
         // Clear tracking
+        this.lastRenderedRegionTarget = null;
         this.currentContentElement = null;
         this.normalizedToDOM.clear();
         this.currentBoundaryOffset = 0;