@pie-players/pie-assessment-toolkit 0.3.75 → 1.0.0-beta.1

package/dist/services/TTSService.d.ts

@@ -1,26 +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 { 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";
 import { type SREMathSpeechOptions } from "./tts/math-speech.js";
-export type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSProviderCapabilities, } from "@pie-players/pie-tts";
+import type { ToolkitTTSConfig } from "./tts/provider-options.js";
 /**
  * Playback state
  */
@@ -32,8 +34,6 @@ export declare enum PlaybackState {
     ERROR = "error"
 }
 /**
- * TTSService
- *
  * Instantiable service for text-to-speech functionality.
  * Each instance manages its own playback state.
  */
@@ -57,6 +57,7 @@ export declare class TTSService {
     private listeners;
     private lastError;
     private speakRunId;
+    private runOwner;
     private currentBoundaryOffset;
     private activeWordBoundaryOffset;
     private seekSegments;
@@ -74,12 +75,24 @@ export declare class TTSService {
     private pendingPlaybackRateRequest;
     private activePlaybackRate;
     private activeHighlightMode;
+    private wordlessPartHighlight;
     private lastRenderedRegionTarget;
     private telemetryReporter;
     private readonly generatedMathSpeechResolver;
-    constructor();
     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. */
@@ -105,13 +118,11 @@ export declare class TTSService {
     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 rate, pitch, voice or provider options without reinitializing.
+     * Update rate, pitch, volume, voice or provider options without
+     * reinitializing.
      * `providerOptions` merge over the ones already configured.
      */
     updateSettings(settings: Partial<TTSConfig>): Promise<void>;
@@ -153,8 +164,6 @@ 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;
     private getHighlightResolverRuntime;
@@ -171,10 +180,6 @@ export declare class TTSService {
      */
     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;
@@ -187,8 +192,8 @@ export declare class TTSService {
     /** 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;
     /**
@@ -203,12 +208,15 @@ export declare class TTSService {
      * 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;
     /**
@@ -246,12 +254,19 @@ export declare class TTSService {
      * running continues.
      */
     speak(target: Range | Element, options?: SpeakOptions): Promise<void>;
+    /**
+     * Sets the rate, pitch and volume a run starts at, after any rate write in
+     * flight. The run has no playback yet, so nothing restarts.
+     */
+    private applyRunSettings;
     /**
      * 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;
     /**
@@ -327,7 +342,8 @@ 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;
     /**
@@ -340,41 +356,19 @@ export declare class TTSService {
      * A disposed service cannot speak or be initialized again.
      */
     dispose(): 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
-     */
-    isPlaying(): boolean;
-    /**
-     * Check if paused
-     */
-    isPaused(): boolean;
     /**
      * Get current state
      */
     getState(): PlaybackState;
-    /**
-     * Get current text being spoken
-     */
-    getCurrentText(): string | null;
-    /**
-     * Get the last error message
-     * Returns null if no error has occurred
-     */
-    getLastError(): string | null;
+    getRunOwner(): string | null;
     /**
      * Subscribe to playback state changes. The returned function unsubscribes;
      * each subscription is its own, so the same callback can be subscribed twice.
      */
     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;
 }