@pie-players/pie-assessment-toolkit 0.3.10 → 0.3.12

package/dist/services/PNPToolResolver.js

@@ -42,15 +42,15 @@
  *
  * Part of PIE Assessment Toolkit.
  */
-import { PNPProvenanceBuilder, } from "./pnp-provenance.js";
+import { PnpProvenanceBuilder, } from "./pnp-provenance.js";
 /**
  * Resolves tool availability from QTI 3.0 assessment structure
  */
-export class PNPToolResolver {
+export class PnpToolResolver {
     toolRegistry;
     enableProvenance;
     /**
-     * Create a PNPToolResolver
+     * Create a PnpToolResolver
      *
      * @param toolRegistry Tool registry for PNP support mapping
      * @param enableProvenance Enable detailed provenance tracking (default: true)
@@ -67,7 +67,7 @@ export class PNPToolResolver {
      * @returns Array of resolved tool configurations
      *
      * @example
-     * const resolver = new PNPToolResolver(registry);
+     * const resolver = new PnpToolResolver(registry);
      * const tools = resolver.resolveTools(assessment, itemRef);
      * tools.forEach(tool => {
      *   console.log(`${tool.id}: ${tool.enabled ? 'enabled' : 'disabled'}`);
@@ -91,7 +91,7 @@ export class PNPToolResolver {
      * @returns Resolution result with tools and provenance
      *
      * @example
-     * const resolver = new PNPToolResolver(registry);
+     * const resolver = new PnpToolResolver(registry);
      * const result = resolver.resolveToolsWithProvenance(assessment, itemRef);
      *
      * // Use resolved tools
@@ -110,7 +110,7 @@ export class PNPToolResolver {
         // Initialize provenance builder
         const contextId = `assessment-${assessment.id || "unknown"}${currentItemRef ? `-item-${currentItemRef.identifier}` : ""}`;
         const provenanceBuilder = this.enableProvenance
-            ? new PNPProvenanceBuilder(contextId)
+            ? new PnpProvenanceBuilder(contextId)
             : null;
         // Record configuration sources
         if (provenanceBuilder) {

package/dist/services/TTSService.d.ts

@@ -17,7 +17,7 @@
  */
 import type { ITTSProvider, TTSConfig, TTSProviderCapabilities } from "@pie-players/pie-tts";
 import type { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
-import type { IHighlightCoordinator } from "./interfaces.js";
+import type { HighlightCoordinatorApi } from "./interfaces.js";
 export type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, TTSProviderCapabilities, } from "@pie-players/pie-tts";
 /**
  * Playback state
@@ -30,6 +30,13 @@ export declare enum PlaybackState {
     ERROR = "error"
 }
 type HighlightMode = "word" | "sentence";
+interface SpeakOptions {
+    catalogId?: string;
+    language?: string;
+    contentElement?: Element;
+    wordBoundaryOffset?: number;
+    highlightModeOverride?: HighlightMode;
+}
 /**
  * TTSService
  *
@@ -73,7 +80,7 @@ export declare class TTSService {
     /**
      * Set highlight coordinator for word highlighting
      */
-    setHighlightCoordinator(coordinator: IHighlightCoordinator): void;
+    setHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;
     /**
      * Set accessibility catalog resolver for spoken content
      *
@@ -102,6 +109,9 @@ export declare class TTSService {
     private getBoundaryStrength;
     private getBoundaryAnchor;
     private createSpeechPlan;
+    private collectSpeechPlanBoundaries;
+    private createNodeStartOffsets;
+    private createSpeechPlanSegments;
     private segmentSentences;
     private createSeekSegmentsFromText;
     private getCurrentSeekSegmentIndex;
@@ -121,13 +131,15 @@ export declare class TTSService {
      * @param text Text to speak (will be normalized: trimmed and whitespace collapsed)
      * @param options Optional catalog ID, language, and content element for highlighting
      */
-    speak(text: string, options?: {
-        catalogId?: string;
-        language?: string;
-        contentElement?: Element;
-        wordBoundaryOffset?: number;
-        highlightModeOverride?: HighlightMode;
-    }): Promise<void>;
+    speak(text: string, options?: SpeakOptions): Promise<void>;
+    private applyLanguageSettings;
+    private resolveSpeechContent;
+    private logResolvedSpeechContent;
+    private initializeSpeakTracking;
+    private prepareHighlightsForSpeak;
+    private configureWordBoundaryHighlighting;
+    private executeSpeakPlayback;
+    private clearHighlightsAndTracking;
     /**
      * Speak a text range with accurate word highlighting
      *

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

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

package/dist/services/TTSService.js

@@ -16,6 +16,7 @@
  * Part of PIE Assessment Toolkit.
  */
 import { collectVisibleTextAndMap, extractVisibleText as extractVisibleTextFromDOM, isElementHiddenForTTS, normalizeTextForSpeech, } from "./tts/text-processing.js";
+import { segmentSentences as segmentTextToSentences, } from "./tts/text-segmentation.js";
 /**
  * Playback state
  */
@@ -295,17 +296,16 @@ export class TTSService {
         };
     }
     createSpeechPlan(contentElement, normalizedText) {
+        const boundaries = this.collectSpeechPlanBoundaries(contentElement, normalizedText);
+        return this.createSpeechPlanSegments(normalizedText, boundaries);
+    }
+    collectSpeechPlanBoundaries(contentElement, normalizedText) {
         const boundaries = new Map();
-        let previousBoundaryAnchor = null;
         const { map } = collectVisibleTextAndMap(contentElement, this.getTextProcessingOptions());
-        const nodeStartOffsets = new Map();
-        for (const [normalizedIndex, mapping] of map.entries()) {
-            if (!nodeStartOffsets.has(mapping.node)) {
-                nodeStartOffsets.set(mapping.node, normalizedIndex);
-            }
-        }
+        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;
@@ -322,6 +322,18 @@ export class TTSService {
             }
             currentNode = walker.nextNode();
         }
+        return boundaries;
+    }
+    createNodeStartOffsets(map) {
+        const nodeStartOffsets = new Map();
+        for (const [normalizedIndex, mapping] of map.entries()) {
+            if (!nodeStartOffsets.has(mapping.node)) {
+                nodeStartOffsets.set(mapping.node, normalizedIndex);
+            }
+        }
+        return nodeStartOffsets;
+    }
+    createSpeechPlanSegments(normalizedText, boundaries) {
         const points = Array.from(boundaries.keys())
             .filter((point) => point > 0 && point < normalizedText.length)
             .sort((a, b) => a - b);
@@ -356,39 +368,9 @@ export class TTSService {
         return segments.filter((segment) => segment.text.trim().length > 0);
     }
     segmentSentences(text) {
-        try {
-            const Segmenter = globalThis.Intl?.Segmenter;
-            if (typeof Segmenter === "function") {
-                const locale = this.ttsConfig.providerOptions
-                    ?.locale || undefined;
-                const segmenter = new Segmenter(locale, {
-                    granularity: "sentence",
-                });
-                const segments = Array.from(segmenter.segment(text))
-                    .map((segment) => ({
-                    text: segment.segment,
-                    offset: segment.index,
-                }))
-                    .filter((segment) => segment.text.trim().length > 0);
-                if (segments.length > 0)
-                    return segments;
-            }
-        }
-        catch {
-            // Fall through to regex segmentation.
-        }
-        const sentenceRegex = /[^.!?]+(?:[.!?]+|$)/g;
-        const raw = text.match(sentenceRegex) || [text];
-        const parsed = [];
-        let processed = 0;
-        for (const sentence of raw) {
-            const offset = text.indexOf(sentence, processed);
-            if (offset === -1)
-                continue;
-            parsed.push({ text: sentence, offset });
-            processed = offset + sentence.length;
-        }
-        return parsed.length > 0 ? parsed : [{ text, offset: 0 }];
+        const locale = this.ttsConfig.providerOptions
+            ?.locale || undefined;
+        return segmentTextToSentences(text, { locale });
     }
     createSeekSegmentsFromText(text) {
         return this.segmentSentences(text)
@@ -534,42 +516,94 @@ export class TTSService {
             throw new Error("TTS service not initialized");
         }
         const runId = ++this.speakRunId;
-        if (options?.language) {
-            const providerOptions = (this.ttsConfig.providerOptions ||
-                {});
-            const textNormalization = (providerOptions.textNormalization ||
-                {});
-            const segmenter = (providerOptions.segmenter || {});
-            const mergedProviderOptions = {
-                ...providerOptions,
+        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.setState(PlaybackState.LOADING);
+        this.prepareHighlightsForSpeak({
+            contentToSpeak,
+            options,
+            highlightMode,
+            shouldUsePlan,
+        });
+        try {
+            this.configureWordBoundaryHighlighting({
+                highlightMode,
+                wordBoundaryOffset: options?.wordBoundaryOffset || 0,
+            });
+            this.setState(PlaybackState.PLAYING);
+            await this.executeSpeakPlayback({
+                shouldUsePlan,
+                runId,
+                highlightMode,
+                contentToSpeak,
+            });
+            if (runId !== this.speakRunId)
+                return;
+            this.setState(PlaybackState.IDLE);
+            this.clearHighlightsAndTracking();
+        }
+        catch (error) {
+            console.error("TTS error:", error);
+            this.lastError = error instanceof Error ? error.message : String(error);
+            if (runId !== this.speakRunId)
+                return;
+            this.setState(PlaybackState.ERROR);
+            this.clearHighlightsAndTracking();
+            throw error;
+        }
+    }
+    async applyLanguageSettings(options) {
+        if (!options?.language || !this.provider)
+            return;
+        const providerOptions = (this.ttsConfig.providerOptions ||
+            {});
+        const textNormalization = (providerOptions.textNormalization ||
+            {});
+        const segmenter = (providerOptions.segmenter || {});
+        const mergedProviderOptions = {
+            ...providerOptions,
+            locale: options.language,
+            textNormalization: {
+                ...textNormalization,
                 locale: options.language,
-                textNormalization: {
-                    ...textNormalization,
-                    locale: options.language,
-                },
-                segmenter: {
-                    ...segmenter,
-                    locale: options.language,
-                },
-            };
-            this.ttsConfig = {
-                ...this.ttsConfig,
-                providerOptions: mergedProviderOptions,
-            };
-            if ("updateSettings" in this.provider &&
-                typeof this.provider.updateSettings ===
-                    "function") {
-                await this.provider.updateSettings({ providerOptions: mergedProviderOptions });
-            }
+            },
+            segmenter: {
+                ...segmenter,
+                locale: options.language,
+            },
+        };
+        this.ttsConfig = {
+            ...this.ttsConfig,
+            providerOptions: mergedProviderOptions,
+        };
+        if ("updateSettings" in this.provider &&
+            typeof this.provider.updateSettings ===
+                "function") {
+            await this.provider.updateSettings({ providerOptions: mergedProviderOptions });
         }
-        // Normalize input text and prefer visible DOM-derived text when available.
-        // This keeps generated speech aligned to what learners can actually see.
+    }
+    resolveSpeechContent(text, options) {
         const normalizedInputText = normalizeTextForSpeech(text);
         const normalizedText = options?.contentElement
             ? this.extractVisibleText(options.contentElement, options.language) ||
                 normalizedInputText
             : normalizedInputText;
-        // Try to resolve from accessibility catalog if catalogId provided
         let contentToSpeak = normalizedText;
         let usedCatalogSpoken = false;
         let speechSource = "dom-or-input";
@@ -580,7 +614,6 @@ export class TTSService {
                 useFallback: true,
             });
             if (catalogContent) {
-                // Use pre-authored spoken content from catalog
                 contentToSpeak = catalogContent.content;
                 usedCatalogSpoken = true;
                 speechSource = "catalog-spoken";
@@ -590,108 +623,88 @@ export class TTSService {
                 console.debug(`[TTSService] No catalog found for "${options.catalogId}", falling back to generated TTS`);
             }
         }
-        const preview = contentToSpeak.replace(/\s+/g, " ").trim().slice(0, 200);
+        return {
+            contentToSpeak,
+            usedCatalogSpoken,
+            speechSource,
+            normalizedText,
+        };
+    }
+    logResolvedSpeechContent(args) {
+        const preview = args.contentToSpeak.replace(/\s+/g, " ").trim().slice(0, 200);
         console.debug("[TTSService] Speak resolved content", {
-            source: speechSource,
-            catalogId: options?.catalogId || null,
-            length: contentToSpeak.length,
+            source: args.speechSource,
+            catalogId: args.catalogId || null,
+            length: args.contentToSpeak.length,
             preview,
         });
+    }
+    initializeSpeakTracking(contentToSpeak, options) {
         this.currentText = contentToSpeak;
         this.currentContentElement = options?.contentElement || null;
-        this.lastError = null; // Clear previous error
+        this.lastError = null;
         this.currentBoundaryOffset = 0;
         this.currentSeekSegmentIndex = 0;
-        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.setState(PlaybackState.LOADING);
-        // Build position map for highlighting if we have a content element
-        if (this.currentContentElement && this.highlightCoordinator) {
-            this.buildPositionMap(this.currentContentElement, contentToSpeak, options?.language);
-            // Fallback sentence-level highlight for non-planned flows.
-            // Planned sentence mode is updated progressively in speakWithPlan().
-            if (!(highlightMode === "sentence" && shouldUsePlan)) {
-                const range = document.createRange();
-                range.selectNodeContents(this.currentContentElement);
-                this.highlightCoordinator.highlightTTSSentence([range]);
-                console.log("[TTSService] Applied sentence-level highlighting");
-            }
+    }
+    prepareHighlightsForSpeak(args) {
+        if (!this.currentContentElement || !this.highlightCoordinator)
+            return;
+        this.buildPositionMap(this.currentContentElement, args.contentToSpeak, args.options?.language);
+        if (!(args.highlightMode === "sentence" && args.shouldUsePlan)) {
+            const range = document.createRange();
+            range.selectNodeContents(this.currentContentElement);
+            this.highlightCoordinator.highlightTTSSentence([range]);
+            console.log("[TTSService] Applied sentence-level highlighting");
+        }
+    }
+    configureWordBoundaryHighlighting(args) {
+        if (!this.provider ||
+            args.highlightMode !== "word" ||
+            !this.highlightCoordinator ||
+            !this.currentContentElement) {
+            return;
         }
-        try {
-            // Setup word boundary highlighting
-            if (highlightMode === "word" &&
-                this.highlightCoordinator &&
-                this.currentContentElement) {
-                this.provider.onWordBoundary = (word, charIndex, length) => {
-                    const wordLength = length || word.length;
-                    const globalIndex = charIndex +
-                        this.currentBoundaryOffset +
-                        (options?.wordBoundaryOffset || 0);
-                    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.highlightCoordinator.highlightTTSWord(highlightRange.node, highlightRange.start, highlightRange.end);
-                    }
-                    else {
-                        console.warn(`[TTSService] Could not find highlight range for position ${globalIndex}, length ${wordLength}`);
-                    }
-                };
-            }
-            this.setState(PlaybackState.PLAYING);
-            if (shouldUsePlan && this.currentContentElement) {
-                const segments = this.seekSegments;
-                if (segments.length > 0) {
-                    await this.speakWithPlan(segments, runId, { highlightMode });
-                }
-                else {
-                    await this.provider.speak(contentToSpeak);
-                }
+        this.provider.onWordBoundary = (word, charIndex, length) => {
+            const wordLength = length || word.length;
+            const globalIndex = charIndex + this.currentBoundaryOffset + args.wordBoundaryOffset;
+            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.highlightCoordinator.highlightTTSWord(highlightRange.node, highlightRange.start, highlightRange.end);
             }
             else {
-                await this.provider.speak(contentToSpeak);
+                console.warn(`[TTSService] Could not find highlight range for position ${globalIndex}, length ${wordLength}`);
             }
-            if (runId !== this.speakRunId)
-                return;
-            this.setState(PlaybackState.IDLE);
-            // Clear highlights when done
-            if (this.highlightCoordinator) {
-                this.highlightCoordinator.clearTTS();
+        };
+    }
+    async executeSpeakPlayback(args) {
+        if (args.shouldUsePlan && this.currentContentElement) {
+            const segments = this.seekSegments;
+            if (segments.length > 0) {
+                await this.speakWithPlan(segments, args.runId, {
+                    highlightMode: args.highlightMode,
+                });
             }
-            // Clear tracking
-            this.currentContentElement = null;
-            this.normalizedToDOM.clear();
-            this.currentBoundaryOffset = 0;
-            this.seekSegments = [];
-            this.currentSeekSegmentIndex = 0;
-        }
-        catch (error) {
-            console.error("TTS error:", error);
-            this.lastError = error instanceof Error ? error.message : String(error);
-            if (runId !== this.speakRunId)
-                return;
-            this.setState(PlaybackState.ERROR);
-            // Clear highlights on error
-            if (this.highlightCoordinator) {
-                this.highlightCoordinator.clearTTS();
+            else if (this.provider) {
+                await this.provider.speak(args.contentToSpeak);
             }
-            // Clear tracking
-            this.currentContentElement = null;
-            this.normalizedToDOM.clear();
-            this.currentBoundaryOffset = 0;
-            this.seekSegments = [];
-            this.currentSeekSegmentIndex = 0;
-            throw error;
+            return;
+        }
+        if (this.provider) {
+            await this.provider.speak(args.contentToSpeak);
         }
     }
+    clearHighlightsAndTracking() {
+        if (this.highlightCoordinator) {
+            this.highlightCoordinator.clearTTS();
+        }
+        this.currentContentElement = null;
+        this.normalizedToDOM.clear();
+        this.currentBoundaryOffset = 0;
+        this.seekSegments = [];
+        this.currentSeekSegmentIndex = 0;
+    }
     /**
      * Speak a text range with accurate word highlighting
      *
@@ -790,28 +803,14 @@ export class TTSService {
             if (runId !== this.speakRunId)
                 return;
             this.setState(PlaybackState.IDLE);
-            if (this.highlightCoordinator) {
-                this.highlightCoordinator.clearTTS();
-            }
-            this.currentContentElement = null;
-            this.normalizedToDOM.clear();
-            this.currentBoundaryOffset = 0;
-            this.seekSegments = [];
-            this.currentSeekSegmentIndex = 0;
+            this.clearHighlightsAndTracking();
         }
         catch (error) {
             if (runId !== this.speakRunId)
                 return;
             this.lastError = error instanceof Error ? error.message : String(error);
             this.setState(PlaybackState.ERROR);
-            if (this.highlightCoordinator) {
-                this.highlightCoordinator.clearTTS();
-            }
-            this.currentContentElement = null;
-            this.normalizedToDOM.clear();
-            this.currentBoundaryOffset = 0;
-            this.seekSegments = [];
-            this.currentSeekSegmentIndex = 0;
+            this.clearHighlightsAndTracking();
             throw error;
         }
     }