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

package/dist/services/RangeSerializer.d.ts

@@ -7,7 +7,8 @@
  * Uses CSS selector paths and node indices for robust serialization that
  * 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.
+ * that renders into shadow roots round-trip; a path with no ` >>> ` is a plain
+ * selector path.
  */
 /**
  * Serialized form of a Range suitable for storage.
@@ -79,19 +80,9 @@ export declare class RangeSerializer {
      * Uses a hybrid approach:
      * - For element nodes: CSS selector path
      * - For text nodes: parent selector + text node index
-     *
-     * @param node - Node to get path for
-     * @param root - Root element
-     * @returns Path string
      */
     private getNodePath;
-    /**
-     * Get CSS selector path to an element.
-     *
-     * @param element - Element to get path for
-     * @param root - Root element
-     * @returns CSS selector path
-     */
+    /** Get CSS selector path to an element. */
     private getElementPath;
     /** The path to `shadowRoot` itself: its host's path and an empty step into it. */
     private getShadowRootPath;
@@ -100,28 +91,6 @@ export declare class RangeSerializer {
      * {@link SHADOW_STEP} continues in the shadow root of what the step before named.
      */
     private resolveElementPath;
-    /**
-     * Find a node by its path from root.
-     *
-     * @param path - Path string from getNodePath
-     * @param root - Root element
-     * @returns Node, or null if not found
-     */
+    /** The node a getNodePath path names, or null if not found. */
     private findNodeByPath;
-    /**
-     * Batch serialize multiple ranges.
-     *
-     * @param ranges - Ranges to serialize
-     * @param root - Root element
-     * @returns Array of serialized ranges
-     */
-    serializeMany(ranges: Range[], root: Element): SerializedRange[];
-    /**
-     * Batch deserialize multiple ranges.
-     *
-     * @param data - Array of serialized ranges
-     * @param root - Root element
-     * @returns Array of ranges (nulls for invalid ranges)
-     */
-    deserializeMany(data: SerializedRange[], root: Element): (Range | null)[];
 }

package/dist/services/RangeSerializer.js

@@ -7,7 +7,8 @@
  * Uses CSS selector paths and node indices for robust serialization that
  * 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.
+ * that renders into shadow roots round-trip; a path with no ` >>> ` is a plain
+ * selector path.
  */
 import { isShadowRootNode } from "./tts/flat-tree.js";
 /** Separates a shadow host's path from the path inside its shadow root. */
@@ -69,11 +70,9 @@ export class RangeSerializer {
             const range = new Range();
             range.setStart(startNode, data.startOffset);
             range.setEnd(endNode, data.endOffset);
-            // Validate text hasn't changed
             if (range.toString() === data.text) {
                 return range;
             }
-            // Text changed, range is invalid
             return null;
         }
         catch (error) {
@@ -88,22 +87,16 @@ export class RangeSerializer {
      * Uses a hybrid approach:
      * - For element nodes: CSS selector path
      * - For text nodes: parent selector + text node index
-     *
-     * @param node - Node to get path for
-     * @param root - Root element
-     * @returns Path string
      */
     getNodePath(node, root) {
         if (node === root) {
             return "";
         }
-        // Handle text nodes
         if (node.nodeType === Node.TEXT_NODE) {
             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 = isShadowRootNode(parent)
@@ -111,7 +104,6 @@ export class RangeSerializer {
                 : this.getElementPath(parent, root);
             return `${parentPath}::text[${index}]`;
         }
-        // Handle element nodes
         if (node.nodeType === Node.ELEMENT_NODE) {
             return this.getElementPath(node, root);
         }
@@ -120,13 +112,7 @@ export class RangeSerializer {
         }
         throw new Error(`Unsupported node type: ${node.nodeType}`);
     }
-    /**
-     * Get CSS selector path to an element.
-     *
-     * @param element - Element to get path for
-     * @param root - Root element
-     * @returns CSS selector path
-     */
+    /** Get CSS selector path to an element. */
     getElementPath(element, root) {
         if (element === root) {
             return "";
@@ -207,24 +193,16 @@ export class RangeSerializer {
         }
         return scope;
     }
-    /**
-     * Find a node by its path from root.
-     *
-     * @param path - Path string from getNodePath
-     * @param root - Root element
-     * @returns Node, or null if not found
-     */
+    /** The node a getNodePath path names, or null if not found. */
     findNodeByPath(path, root) {
         if (path === "") {
             return root;
         }
-        // Handle text node paths
         if (path.includes("::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
             let parent;
             try {
                 parent = this.resolveElementPath(elementPath, root);
@@ -235,11 +213,9 @@ export class RangeSerializer {
             }
             if (!parent)
                 return null;
-            // Find text node by index
             const textNodes = Array.from(parent.childNodes).filter((n) => n.nodeType === Node.TEXT_NODE);
             return textNodes[textIndex] || null;
         }
-        // Handle element paths
         try {
             return this.resolveElementPath(path, root);
         }
@@ -248,24 +224,4 @@ export class RangeSerializer {
             return null;
         }
     }
-    /**
-     * Batch serialize multiple ranges.
-     *
-     * @param ranges - Ranges to serialize
-     * @param root - Root element
-     * @returns Array of serialized ranges
-     */
-    serializeMany(ranges, root) {
-        return ranges.map((range) => this.serialize(range, root));
-    }
-    /**
-     * Batch deserialize multiple ranges.
-     *
-     * @param data - Array of serialized ranges
-     * @param root - Root element
-     * @returns Array of ranges (nulls for invalid ranges)
-     */
-    deserializeMany(data, root) {
-        return data.map((item) => this.deserialize(item, root));
-    }
 }

package/dist/services/SSMLExtractor.d.ts

@@ -13,8 +13,6 @@
  *
  * This enables proper pronunciation, emphasis, and pacing for TTS without
  * requiring authors to maintain separate catalog files.
- *
- * Part of PIE Assessment Toolkit.
  */
 import type { AccessibilityCatalog, ConfigEntity } from "@pie-players/pie-players-shared/types";
 /**
@@ -25,19 +23,11 @@ export interface ExtractionResult {
     cleanedConfig: ConfigEntity;
 }
 /**
- * Sanitize an SSML subtree in place: remove disallowed attributes and
- * replace disallowed elements with their text content (so phrasing order
- * is preserved but no scripts / iframes / unknown tags survive).
- */
-export declare function sanitizeSsmlElement(element: Element): void;
-/**
- * Serialize a sanitized `<speak>` element back to a minimal SSML string.
- * Uses a manual walker instead of `outerHTML` so that any namespace
- * quirks (e.g. `xmlns` attributes added by the HTML parser) are
- * normalised and disallowed descendants cannot reappear through quirks
- * in the serializer.
+ * SSML cut down to the allow-listed tags and attributes. Input with no markup,
+ * or with no DOMParser available, comes back unchanged. Otherwise the first
+ * <speak> element comes back sanitized, or, when there is none, the sanitized
+ * fragment with no <speak> wrapper.
  */
-export declare function serializeSsmlElement(element: Element): string;
 export declare function sanitizeSsmlString(input: string): string;
 /**
  * SSMLExtractor Service
@@ -46,26 +36,13 @@ export declare function sanitizeSsmlString(input: string): string;
  */
 export declare class SSMLExtractor {
     private catalogCounter;
-    /**
-     * Extract SSML from entire item config (markup + models)
-     *
-     * @param config Item configuration with potential embedded SSML
-     * @returns Extracted catalogs and cleaned config
-     */
+    /** Extract SSML from the item's markup, prompts and choice labels. */
     extractFromItemConfig(config: ConfigEntity): ExtractionResult;
-    /**
-     * Extract SSML from markup string
-     *
-     * @param markup HTML markup potentially containing <speak> elements
-     * @param idPrefix Prefix for generating catalog IDs
-     * @returns Extracted catalogs and cleaned markup
-     */
+    /** Extract SSML from one markup string. */
     private extractFromMarkup;
     /**
-     * Generate unique catalog ID
-     *
-     * @param prefix Context prefix (e.g., 'prompt-q1', 'choice-q1-a')
-     * @returns Unique catalog ID (e.g., 'auto-prompt-q1-0')
+     * A catalog id unique to this extractor until reset(), e.g.
+     * `auto-prompt-q1-0`.
      */
     private generateCatalogId;
     /**

package/dist/services/SSMLExtractor.js

@@ -13,8 +13,6 @@
  *
  * This enables proper pronunciation, emphasis, and pacing for TTS without
  * requiring authors to maintain separate catalog files.
- *
- * Part of PIE Assessment Toolkit.
  */
 /**
  * Allow-listed SSML elements (from the SSML 1.1 spec subset we forward to
@@ -38,11 +36,6 @@ const SSML_ALLOWED_TAGS = new Set([
     "audio",
     "lexicon",
 ]);
-/**
- * Allow-listed attributes across SSML elements. Attribute allow-listing is
- * global (not per-tag) because the union is small and consistent across
- * providers.
- */
 /**
  * Tags whose content must be dropped entirely (rather than unwrapped to
  * preserve phrasing text). These are dangerous containers whose text
@@ -58,6 +51,10 @@ const SSML_DROP_FULLY_TAGS = new Set([
     "noscript",
     "template",
 ]);
+/**
+ * Allow-listed attributes across SSML elements. One list covers every tag
+ * because the union is small and consistent across providers.
+ */
 const SSML_ALLOWED_ATTRS = new Set([
     "alphabet",
     "ph",
@@ -153,7 +150,7 @@ function isSafeSsmlAudioSrc(raw) {
  * replace disallowed elements with their text content (so phrasing order
  * is preserved but no scripts / iframes / unknown tags survive).
  */
-export function sanitizeSsmlElement(element) {
+function sanitizeSsmlElement(element) {
     // Walk children snapshot first because we may replace nodes as we go.
     const children = Array.from(element.children);
     for (const child of children) {
@@ -175,10 +172,8 @@ export function sanitizeSsmlElement(element) {
             element.removeAttribute(attrName);
         }
     }
-    // Belt-and-braces: even though `src` is allow-listed, SSML `<audio>`
-    // sends its URL to a server-side TTS provider that will dereference
-    // it. Refuse non-http(s) schemes and private / cloud-metadata hosts
-    // at the SSML boundary so we never forward an SSRF primitive.
+    // `src` survives the attribute allow-list, and a server-side provider
+    // fetches it: keep it only for an http(s) URL off SSML_PRIVATE_AUDIO_HOSTS.
     if (element.tagName.toLowerCase() === "audio") {
         const src = element.getAttribute("src");
         if (src !== null && !isSafeSsmlAudioSrc(src)) {
@@ -193,7 +188,7 @@ export function sanitizeSsmlElement(element) {
  * normalised and disallowed descendants cannot reappear through quirks
  * in the serializer.
  */
-export function serializeSsmlElement(element) {
+function serializeSsmlElement(element) {
     const tagName = element.tagName.toLowerCase();
     const attrs = Array.from(element.attributes)
         .filter((attr) => SSML_ALLOWED_ATTRS.has(attr.name.toLowerCase()))
@@ -227,6 +222,12 @@ export function serializeSsmlElement(element) {
     }
     return `<${tagName}${attrs}>${childPieces.join("")}</${tagName}>`;
 }
+/**
+ * SSML cut down to the allow-listed tags and attributes. Input with no markup,
+ * or with no DOMParser available, comes back unchanged. Otherwise the first
+ * <speak> element comes back sanitized, or, when there is none, the sanitized
+ * fragment with no <speak> wrapper.
+ */
 export function sanitizeSsmlString(input) {
     const trimmed = String(input || "").trim();
     if (!trimmed || !trimmed.includes("<"))
@@ -281,12 +282,7 @@ function escapeXmlAttr(value) {
  */
 export class SSMLExtractor {
     catalogCounter = 0;
-    /**
-     * Extract SSML from entire item config (markup + models)
-     *
-     * @param config Item configuration with potential embedded SSML
-     * @returns Extracted catalogs and cleaned config
-     */
+    /** Extract SSML from the item's markup, prompts and choice labels. */
     extractFromItemConfig(config) {
         const allCatalogs = [];
         // Shallow clone of config + a fresh models array. The per-model/choice
@@ -336,18 +332,11 @@ export class SSMLExtractor {
             cleanedConfig,
         };
     }
-    /**
-     * Extract SSML from markup string
-     *
-     * @param markup HTML markup potentially containing <speak> elements
-     * @param idPrefix Prefix for generating catalog IDs
-     * @returns Extracted catalogs and cleaned markup
-     */
+    /** Extract SSML from one markup string. */
     extractFromMarkup(markup, idPrefix) {
         if (!markup || markup.trim() === "") {
             return { catalogs: [], cleanedMarkup: markup };
         }
-        // Check if running in browser environment
         if (typeof window === "undefined" || typeof DOMParser === "undefined") {
             console.warn("[SSMLExtractor] DOMParser not available (SSR?), skipping extraction");
             return { catalogs: [], cleanedMarkup: markup };
@@ -356,16 +345,12 @@ export class SSMLExtractor {
         try {
             const parser = new DOMParser();
             const doc = parser.parseFromString(expandSelfClosingVoidTags(markup), "text/html");
-            // Find all <speak> elements
             const speakElements = Array.from(doc.querySelectorAll("speak"));
             if (speakElements.length === 0) {
-                // No SSML found, return original markup
                 return { catalogs: [], cleanedMarkup: markup };
             }
-            // Process each <speak> element
             for (const speakEl of speakElements) {
                 try {
-                    // Generate unique catalog ID
                     const catalogId = this.generateCatalogId(idPrefix);
                     // Sanitize before serializing so the SSML forwarded to the TTS
                     // provider only contains spec-allowed tags/attributes. This
@@ -373,7 +358,6 @@ export class SSMLExtractor {
                     // otherwise accept arbitrary HTML.
                     sanitizeSsmlElement(speakEl);
                     const ssmlContent = serializeSsmlElement(speakEl);
-                    // Extract language (check both xml:lang and lang attributes)
                     const language = speakEl.getAttribute("xml:lang") ||
                         speakEl.getAttribute("lang") ||
                         "en-US";
@@ -409,7 +393,6 @@ export class SSMLExtractor {
                     else {
                         wrapper.setAttribute("data-catalog-idref", catalogId);
                     }
-                    // Create catalog entry
                     catalogs.push({
                         identifier: catalogId,
                         cards: [
@@ -423,24 +406,19 @@ export class SSMLExtractor {
                 }
                 catch (error) {
                     console.error("[SSMLExtractor] Error processing <speak> element:", error);
-                    // Continue with other elements
                 }
             }
-            // Return cleaned markup
             const cleanedMarkup = doc.body.innerHTML;
             return { catalogs, cleanedMarkup };
         }
         catch (error) {
             console.error("[SSMLExtractor] Error parsing markup:", error);
-            // Return original markup if parsing fails
             return { catalogs: [], cleanedMarkup: markup };
         }
     }
     /**
-     * Generate unique catalog ID
-     *
-     * @param prefix Context prefix (e.g., 'prompt-q1', 'choice-q1-a')
-     * @returns Unique catalog ID (e.g., 'auto-prompt-q1-0')
+     * A catalog id unique to this extractor until reset(), e.g.
+     * `auto-prompt-q1-0`.
      */
     generateCatalogId(prefix) {
         const id = `auto-${prefix}-${this.catalogCounter}`;

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,11 +118,8 @@ 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.
      * `providerOptions` merge over the ones already configured.
@@ -153,8 +163,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 +179,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 +191,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 +207,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 +253,19 @@ export declare class TTSService {
      * running continues.
      */
     speak(target: Range | Element, options?: SpeakOptions): Promise<void>;
+    /**
+     * 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;
     /**
@@ -327,7 +341,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 +355,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;
 }