@pie-players/pie-assessment-toolkit 0.3.74 → 0.3.75

package/dist/services/RangeSerializer.d.ts

@@ -5,7 +5,9 @@
  * Used by both TTS (for timing data) and annotations (for persistence).
  *
  * Uses CSS selector paths and node indices for robust serialization that
- * survives content changes when possible.
+ * survives content changes when possible. A path into an open shadow root names
+ * its host, then ` >>> `, then the path inside the root, so ranges in content
+ * that renders into shadow roots round-trip; paths without one read as before.
  */
 /**
  * Serialized form of a Range suitable for storage.
@@ -91,6 +93,13 @@ export declare class RangeSerializer {
      * @returns CSS selector path
      */
     private getElementPath;
+    /** The path to `shadowRoot` itself: its host's path and an empty step into it. */
+    private getShadowRootPath;
+    /**
+     * The element, or shadow root, an element path names: each step after a
+     * {@link SHADOW_STEP} continues in the shadow root of what the step before named.
+     */
+    private resolveElementPath;
     /**
      * Find a node by its path from root.
      *

package/dist/services/RangeSerializer.js

@@ -5,8 +5,13 @@
  * Used by both TTS (for timing data) and annotations (for persistence).
  *
  * Uses CSS selector paths and node indices for robust serialization that
- * survives content changes when possible.
+ * survives content changes when possible. A path into an open shadow root names
+ * its host, then ` >>> `, then the path inside the root, so ranges in content
+ * that renders into shadow roots round-trip; paths without one read as before.
  */
+import { isShadowRootNode } from "./tts/flat-tree.js";
+/** Separates a shadow host's path from the path inside its shadow root. */
+const SHADOW_STEP = " >>> ";
 /**
  * RangeSerializer - Serialize and deserialize Range objects.
  */
@@ -94,20 +99,25 @@ export class RangeSerializer {
         }
         // Handle text nodes
         if (node.nodeType === Node.TEXT_NODE) {
-            const parent = node.parentElement;
+            const parent = node.parentNode;
             if (!parent) {
                 throw new Error("Text node has no parent");
             }
             // Get index of this text node among its siblings
             const textNodes = Array.from(parent.childNodes).filter((n) => n.nodeType === Node.TEXT_NODE);
             const index = textNodes.indexOf(node);
-            const parentPath = this.getElementPath(parent, root);
+            const parentPath = isShadowRootNode(parent)
+                ? this.getShadowRootPath(parent, root)
+                : this.getElementPath(parent, root);
             return `${parentPath}::text[${index}]`;
         }
         // Handle element nodes
         if (node.nodeType === Node.ELEMENT_NODE) {
             return this.getElementPath(node, root);
         }
+        if (isShadowRootNode(node)) {
+            return this.getShadowRootPath(node, root);
+        }
         throw new Error(`Unsupported node type: ${node.nodeType}`);
     }
     /**
@@ -121,27 +131,81 @@ export class RangeSerializer {
         if (element === root) {
             return "";
         }
-        const path = [];
+        const rootTree = root.getRootNode?.();
+        // One path per tree, outermost first.
+        const trees = [];
+        let path = [];
         let current = element;
+        // Ends `current`'s tree at the shadow root holding it, continuing at the host.
+        const leaveShadowRoot = (shadowRoot) => {
+            trees.unshift(path.join(" > "));
+            path = [];
+            current = shadowRoot.host;
+        };
         while (current && current !== root) {
-            // Use ID if available (more stable)
+            // Use ID if available (more stable). An id is unique within its tree, so
+            // the path still names the shadow host above it.
             if (current.id) {
                 path.unshift(`#${current.id}`);
+                const tree = current.getRootNode?.();
+                if (isShadowRootNode(tree) && tree !== rootTree) {
+                    leaveShadowRoot(tree);
+                    continue;
+                }
                 break;
             }
             // Otherwise use tag + nth-of-type
             const parent = current.parentElement;
-            if (!parent)
+            const parentNode = current.parentNode;
+            const siblingsParent = parent ?? (isShadowRootNode(parentNode) ? parentNode : null);
+            if (!siblingsParent)
                 break;
-            const siblings = Array.from(parent.children).filter((el) => el.tagName === current.tagName);
+            const tagName = current.tagName;
+            const siblings = Array.from(siblingsParent.children).filter((el) => el.tagName === tagName);
             const index = siblings.indexOf(current);
             const selector = siblings.length > 1
-                ? `${current.tagName.toLowerCase()}:nth-of-type(${index + 1})`
-                : current.tagName.toLowerCase();
+                ? `${tagName.toLowerCase()}:nth-of-type(${index + 1})`
+                : tagName.toLowerCase();
             path.unshift(selector);
-            current = parent;
+            if (parent) {
+                current = parent;
+            }
+            else {
+                leaveShadowRoot(siblingsParent);
+            }
         }
-        return path.join(" > ");
+        trees.unshift(path.join(" > "));
+        return trees.join(SHADOW_STEP);
+    }
+    /** The path to `shadowRoot` itself: its host's path and an empty step into it. */
+    getShadowRootPath(shadowRoot, root) {
+        return `${this.getElementPath(shadowRoot.host, root)}${SHADOW_STEP}`;
+    }
+    /**
+     * The element, or shadow root, an element path names: each step after a
+     * {@link SHADOW_STEP} continues in the shadow root of what the step before named.
+     */
+    resolveElementPath(path, root) {
+        let scope = root;
+        const steps = path.split(SHADOW_STEP);
+        for (let index = 0; index < steps.length; index++) {
+            if (index > 0) {
+                const shadowRoot = isShadowRootNode(scope)
+                    ? null
+                    : scope.shadowRoot;
+                if (!shadowRoot)
+                    return null;
+                scope = shadowRoot;
+            }
+            const selector = steps[index].trim();
+            if (!selector)
+                continue;
+            const found = scope.querySelector(selector);
+            if (!found)
+                return null;
+            scope = found;
+        }
+        return scope;
     }
     /**
      * Find a node by its path from root.
@@ -156,10 +220,19 @@ export class RangeSerializer {
         }
         // Handle text node paths
         if (path.includes("::text[")) {
-            const [elementPath, textPart] = path.split("::text[");
+            const marker = path.lastIndexOf("::text[");
+            const elementPath = path.slice(0, marker);
+            const textPart = path.slice(marker + "::text[".length);
             const textIndex = Number.parseInt(textPart.replace("]", ""), 10);
             // Find parent element
-            const parent = elementPath ? root.querySelector(elementPath) : root;
+            let parent;
+            try {
+                parent = this.resolveElementPath(elementPath, root);
+            }
+            catch (error) {
+                console.warn("Invalid selector path:", path, error);
+                return null;
+            }
             if (!parent)
                 return null;
             // Find text node by index
@@ -168,7 +241,7 @@ export class RangeSerializer {
         }
         // Handle element paths
         try {
-            return root.querySelector(path);
+            return this.resolveElementPath(path, root);
         }
         catch (error) {
             console.warn("Invalid selector path:", path, error);

package/dist/services/TTSService.d.ts

@@ -16,10 +16,11 @@
  * Part of PIE Assessment Toolkit.
  */
 import type { ITTSProvider, TTSConfig, TTSProviderCapabilities } from "@pie-players/pie-tts";
-import type { AccessibilityCatalogResolver, CatalogLookupContext } from "./AccessibilityCatalogResolver.js";
-import type { HighlightCoordinatorApi } from "./interfaces.js";
+import type { AccessibilityCatalogResolver } from "./AccessibilityCatalogResolver.js";
+import type { HighlightCoordinatorApi, SpeakOptions } from "./interfaces.js";
 import type { TTSHighlightTargetResolverProvider } from "./tts/highlight-target-resolver.js";
-export type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSFeature, TTSProviderCapabilities, } from "@pie-players/pie-tts";
+import { type SREMathSpeechOptions } from "./tts/math-speech.js";
+export type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSProviderCapabilities, } from "@pie-players/pie-tts";
 /**
  * Playback state
  */
@@ -30,16 +31,6 @@ export declare enum PlaybackState {
     PAUSED = "paused",
     ERROR = "error"
 }
-type HighlightMode = "word" | "sentence";
-interface SpeakOptions {
-    catalogId?: string;
-    catalogContext?: CatalogLookupContext;
-    ignoreCatalogs?: boolean;
-    language?: string;
-    contentElement?: Element;
-    wordBoundaryOffset?: number;
-    highlightModeOverride?: HighlightMode;
-}
 /**
  * TTSService
  *
@@ -53,7 +44,13 @@ export declare class TTSService {
     private highlightTargetResolverProvider;
     private catalogResolver;
     private state;
+    private resumeState;
     private ttsConfig;
+    private hostLocales;
+    private readLocale;
+    private disposed;
+    private readinessGate;
+    private mathSpeechSource;
     private currentText;
     private currentContentElement;
     private normalizedToDOM;
@@ -70,6 +67,8 @@ export declare class TTSService {
     private playbackStartDeferredRunId;
     private pendingPlaybackStartHighlights;
     private playbackStartBarrierCleanup;
+    private pauseHold;
+    private structuralPause;
     private playbackRateWriteQueue;
     private playbackRateRequestId;
     private pendingPlaybackRateRequest;
@@ -78,13 +77,31 @@ export declare class TTSService {
     private lastRenderedRegionTarget;
     private telemetryReporter;
     private readonly generatedMathSpeechResolver;
-    private static readonly debugEnabled;
     constructor();
-    private debugLog;
     private clearPlaybackStartBarrier;
     private notifyPlaybackStarted;
     private installPlaybackStartBarrier;
     private runWhenPlaybackStarts;
+    /** Resolves when run `runId` may start its next part: at once unless paused. */
+    private waitWhilePaused;
+    private releasePauseHold;
+    private waitStructuralPause;
+    private cancelStructuralPause;
+    /**
+     * 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.
+     */
+    private abandonRun;
+    /**
+     * 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.
+     */
+    private beginRun;
+    /** The run's audio is sounding; under a pause, it sounds again on resume. */
+    private markPlaying;
+    private assertNotDisposed;
     private emitTelemetry;
     /**
      * Initialize TTS service with a provider
@@ -94,18 +111,27 @@ export declare class TTSService {
      */
     initialize(provider: ITTSProvider, config?: Partial<TTSConfig>): Promise<void>;
     /**
-     * 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.
      */
     updateSettings(settings: Partial<TTSConfig>): Promise<void>;
     /**
      * Set highlight coordinator for word highlighting
      */
     setHighlightCoordinator(coordinator: HighlightCoordinatorApi): void;
+    /**
+     * 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: (() => Promise<void>) | null): void;
+    /**
+     * 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: (() => unknown) | null): void;
+    /** The start a speak must wait for, or null when it can speak now without yielding. */
+    private pendingReadiness;
     /**
      * Set a late-bound provider for optional host TTS highlight target remapping.
      *
@@ -131,18 +157,6 @@ export declare class TTSService {
      * @param resolver AccessibilityCatalogResolver instance
      */
     setCatalogResolver(resolver: AccessibilityCatalogResolver): void;
-    /**
-     * 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: string, language?: string): boolean;
     private getHighlightResolverRuntime;
     private getNodeElement;
     private isElementWithinScope;
@@ -150,18 +164,45 @@ export declare class TTSService {
     private resolveWordHighlightRange;
     private resolveSentenceHighlightTargets;
     private createTextRange;
-    private paintTTSWordRange;
+    /**
+     * 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.
+     */
+    private paintTTSWord;
     private paintTTSSentenceRanges;
     /**
      * Get provider capabilities
      */
     getCapabilities(): TTSProviderCapabilities | null;
+    private providerOptions;
+    /** The longest text the provider accepts in one speak, when it declares one. */
+    private maxTextLength;
+    /**
+     * 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.
+     */
+    private speakWithinLimit;
+    /** Segments no longer than the provider's `maxTextLength`, offsets kept. */
+    private segmentsWithinLimit;
     /**
      * Build a character-by-character map from normalized text positions to DOM positions
      * This handles the complexity of whitespace normalization
      */
     private getTextProcessingOptions;
-    private getMathSpeechOptions;
+    /**
+     * 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.
+     */
+    private resolveReadLanguage;
+    /**
+     * The host's SRE options for math speech: from the installed source, else as
+     * this service was initialized with.
+     */
+    getMathSpeechOptions(): SREMathSpeechOptions | undefined;
     private buildPositionMap;
     private getStructuralPauseProfile;
     private resolvePauseMsFromUnits;
@@ -195,22 +236,30 @@ export declare class TTSService {
     private getSegmentIndexForOffset;
     private highlightSentenceForOffset;
     /**
-     * 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.
      */
-    private findHighlightRange;
+    speak(target: Range | Element, options?: SpeakOptions): Promise<void>;
     /**
-     * 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
+     * Suppression is read from the live ancestors of what is read, because the
+     * element carrying it may sit above the content root.
+     */
+    private isSuppressedTarget;
+    private resolveElementTarget;
+    private resolveRangeTarget;
+    private speakContent;
+    /**
+     * 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.
      */
-    speak(text: string, options?: SpeakOptions): Promise<void>;
-    private switchProviderToBrowser;
-    private isBrowserSpeechFallbackAvailable;
     private applyLanguageSettings;
     private resolveSpeechContent;
     private resolveCatalogComposedSpeechContent;
@@ -226,6 +275,10 @@ export declare class TTSService {
      * defensive net if a capable provider still rejects a given SSML payload.
      */
     private resolveGeneratedPlaybackFormat;
+    /**
+     * With `range`, the selection only: an equation it holds whole reads as math
+     * speech, and a selection without one reads the selected text, `normalizedInputText`.
+     */
     private resolveGeneratedSpeechContent;
     private logResolvedSpeechContent;
     private initializeSpeakTracking;
@@ -233,7 +286,6 @@ export declare class TTSService {
     private configureWordBoundaryHighlighting;
     private clearWordBoundaryHighlighting;
     private highlightCatalogRegion;
-    private highlightCatalogActiveRange;
     private highlightRenderableRegionTarget;
     private highlightRenderableActiveTarget;
     private renderHighlightDecision;
@@ -253,28 +305,19 @@ export declare class TTSService {
     private speakCatalogChunkOnce;
     private executeSpeakPlayback;
     private clearHighlightsAndTracking;
-    /**
-     * 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.
      */
     private selectMappedRangeText;
-    speakRange(range: Range, options?: {
-        contentRoot?: Element | null;
-    }): Promise<void>;
     /**
-     * Pause playback
+     * Pause playback. A pause while the read is loading holds it: its audio does
+     * not start until {@link resume}.
      */
     pause(): void;
     /**
-     * Resume playback
+     * Resume playback, back to loading when the pause came before the audio
+     * started.
      */
     resume(): void;
     private normalizePlaybackRate;
@@ -287,6 +330,16 @@ export declare class TTSService {
      * Stop playback
      */
     stop(): void;
+    /**
+     * Stop playback and drop the provider, whose owner destroys it. A later speak
+     * waits on the readiness gate, as before the first {@link initialize}.
+     */
+    releaseProvider(): void;
+    /**
+     * Stop, release the provider and drop every listener, hook and pending timer.
+     * A disposed service cannot speak or be initialized again.
+     */
+    dispose(): void;
     /**
      * Request UI-level TTS controls to hand off/deactivate.
      *
@@ -316,16 +369,10 @@ export declare class TTSService {
      */
     getLastError(): string | null;
     /**
-     * Subscribe to state changes
-     *
-     * @param id Unique listener ID
-     * @param callback Function to call on state change
-     */
-    onStateChange(id: string, callback: (state: PlaybackState) => void): void;
-    /**
-     * 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: string, callback: (state: PlaybackState) => void): void;
+    onStateChange(callback: (state: PlaybackState) => void): () => void;
     /**
      * Set state and notify listeners
      */