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

package/dist/services/TTSService.d.ts

@@ -1,25 +1,28 @@
 /**
  * TTSService
  *
- * Text-to-speech service with pluggable provider architecture.
- * Manages playback state, coordinates multiple TTS entry points,
- * and integrates with HighlightCoordinator for word highlighting.
+ * Owns one read-aloud session: the installed provider, playback state, and the
+ * word and sentence highlights painted through HighlightCoordinator.
  *
- * Features:
- * - Pluggable TTS providers (browser, AWS Polly, etc.)
- * - QTI 3.0 accessibility catalogs (pre-authored spoken content)
- * - Unified playback state management
- * - Prevents conflicts from simultaneous speech
- * - Word highlighting integration
- * - Playback controls: play, pause, resume, stop
- *
- * Part of PIE Assessment Toolkit.
+ * Layout:
+ * - Provider and host wiring: initialize, setCatalogResolver, the highlight
+ *   target resolver and math-speech sources.
+ * - Content resolution: catalog spoken card, then catalog-composed chunks
+ *   (script and/or recording with a plain fallback), then generated speech.
+ * - Speech plan: structural pauses, seek segments, sentence segments and the
+ *   normalized-to-DOM position map.
+ * - Playback: speakContent → executeSpeakPlayback, the run guard (speakRunId,
+ *   runOwner), the pause hold and the playback-start barrier.
+ * - Highlight painting: boundary handling, the host resolver remap, catalog
+ *   highlight plans.
+ * - Controls and state: pause/resume/stop/seek/rate, setState and listeners.
  */
-import type { ITTSProvider, TTSConfig, TTSProviderCapabilities } from "@pie-players/pie-tts";
-import type { AccessibilityCatalogResolver, CatalogLookupContext } from "./AccessibilityCatalogResolver.js";
-import type { HighlightCoordinatorApi } from "./interfaces.js";
+import type { ITTSProvider, TTSConfig } from "@pie-players/pie-tts";
+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";
+import type { ToolkitTTSConfig } from "./tts/provider-options.js";
 /**
  * Playback state
  */
@@ -30,19 +33,7 @@ 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
- *
  * Instantiable service for text-to-speech functionality.
  * Each instance manages its own playback state.
  */
@@ -53,13 +44,20 @@ 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;
     private listeners;
     private lastError;
     private speakRunId;
+    private runOwner;
     private currentBoundaryOffset;
     private activeWordBoundaryOffset;
     private seekSegments;
@@ -70,42 +68,80 @@ export declare class TTSService {
     private playbackStartDeferredRunId;
     private pendingPlaybackStartHighlights;
     private playbackStartBarrierCleanup;
+    private pauseHold;
+    private structuralPause;
     private playbackRateWriteQueue;
     private playbackRateRequestId;
     private pendingPlaybackRateRequest;
     private activePlaybackRate;
     private activeHighlightMode;
+    private wordlessPartHighlight;
     private lastRenderedRegionTarget;
     private telemetryReporter;
     private readonly generatedMathSpeechResolver;
-    private static readonly debugEnabled;
-    constructor();
-    private debugLog;
     private clearPlaybackStartBarrier;
     private notifyPlaybackStarted;
+    /**
+     * A word-mode part whose playback sends no boundaries, such as a server
+     * response without speech marks, highlights as a sentence-mode read does.
+     * Catalog chunks and a single speak highlight the same in both modes.
+     */
+    private highlightWordlessPlayback;
+    /**
+     * Defers marking the run playing, and the highlights queued through
+     * runWhenPlaybackStarts, until the provider or the recording signals that
+     * audio started. Returns the barrier's cleanup, or null when nothing will
+     * signal a start, in which case the caller marks the run playing itself.
+     */
     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
-     *
-     * @param provider TTS provider instance
-     * @param config Provider configuration
      */
-    initialize(provider: ITTSProvider, config?: Partial<TTSConfig>): Promise<void>;
+    initialize(provider: ITTSProvider, config?: Partial<ToolkitTTSConfig>): 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.
      *
@@ -127,22 +163,8 @@ export declare class TTSService {
      *
      * When set, the speak() method will check for pre-authored spoken
      * content in catalogs before falling back to generated TTS.
-     *
-     * @param resolver AccessibilityCatalogResolver instance
      */
     setCatalogResolver(resolver: 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,24 +172,50 @@ 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;
+    private providerOptions;
+    /** The longest text the provider accepts in one speak, when it declares one. */
+    private maxTextLength;
     /**
-     * Get provider capabilities
+     * Speak `text`, in pieces when it exceeds the provider's `maxTextLength`. Word
+     * boundaries keep indexing the whole text. An SSML document cannot be cut, so
+     * one over the limit fails and the chunk's plain fallback reads instead.
      */
-    getCapabilities(): TTSProviderCapabilities | null;
+    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
+     * Text-collection options for `locale`, with the provider's boundary-spacing
+     * mode when it names a known one.
      */
     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;
+    /**
+     * Rebuilds normalizedToDOM from `element`'s visible text; traced runs also
+     * log how it differs from `spokenText`.
+     */
     private buildPositionMap;
     private getStructuralPauseProfile;
     private resolvePauseMsFromUnits;
     private resolveHighlightMode;
     private hasExplicitBreakSemantics;
-    private isElementHidden;
     private getBoundaryStrength;
     private getBoundaryAnchor;
     /**
@@ -195,22 +243,37 @@ 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
+     * Sets the rate a run starts at, after any rate write in flight. The run has
+     * no playback yet, so nothing restarts.
+     */
+    private applyRunRate;
+    /**
+     * 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;
+    /** Whether the root's card, or a card of a node inside it, would be read. */
+    private holdsSpokenCard;
+    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 +289,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 +300,6 @@ export declare class TTSService {
     private configureWordBoundaryHighlighting;
     private clearWordBoundaryHighlighting;
     private highlightCatalogRegion;
-    private highlightCatalogActiveRange;
     private highlightRenderableRegionTarget;
     private highlightRenderableActiveTarget;
     private renderHighlightDecision;
@@ -253,28 +319,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;
@@ -284,50 +341,33 @@ export declare class TTSService {
     seekForward(units?: number): Promise<void>;
     seekBackward(units?: number): Promise<void>;
     /**
-     * Stop playback
+     * Stop playback and release the run owner. A run that ends on its own keeps
+     * its owner, so the owning control can replay it.
      */
     stop(): void;
     /**
-     * Request UI-level TTS controls to hand off/deactivate.
-     *
-     * This is intentionally separate from playback controls so hosts can orchestrate
-     * control handoff explicitly (for example: stop playback, then dismiss controls).
-     */
-    requestControlHandoff(): void;
-    /**
-     * Check if currently playing
+     * Stop playback and drop the provider, whose owner destroys it. A later speak
+     * waits on the readiness gate, as before the first {@link initialize}.
      */
-    isPlaying(): boolean;
+    releaseProvider(): void;
     /**
-     * Check if paused
+     * Stop, release the provider and drop every listener, hook and pending timer.
+     * A disposed service cannot speak or be initialized again.
      */
-    isPaused(): boolean;
+    dispose(): void;
     /**
      * Get current state
      */
     getState(): PlaybackState;
+    getRunOwner(): string | null;
     /**
-     * Get current text being spoken
-     */
-    getCurrentText(): string | null;
-    /**
-     * Get the last error message
-     * Returns null if no error has occurred
-     */
-    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
+     * Set state and notify listeners. `announceUnchanged` notifies listeners even
+     * when the state does not change; telemetry fires only on a change.
      */
     private setState;
 }