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

package/dist/services/HighlightCoordinator.js

@@ -11,8 +11,6 @@
  * - Configurable colors and styles
  * - Annotation persistence via RangeSerializer
  *
- * Part of PIE Assessment Toolkit.
- *
  * Browser Support:
  * - Chrome/Edge 105+
  * - Safari 17.2+
@@ -383,31 +381,55 @@ export class HighlightCoordinator {
         this.applyAdaptiveTTSStyle();
         this.setupThemeObservation();
     }
+    /**
+     * Re-adapt the TTS colors when the page's theme moves: on the document
+     * element, on a `<pie-theme>` host, and when a `<pie-theme>` mounts, which
+     * themes its target as it connects.
+     */
     setupThemeObservation() {
         if (typeof document === "undefined")
             return;
         if (typeof MutationObserver === "undefined")
             return;
-        const refresh = () => this.applyAdaptiveTTSStyle();
-        this.themeObserver = new MutationObserver(refresh);
-        this.themeObserver.observe(document.documentElement, {
+        const themeHosts = document.getElementsByTagName("pie-theme");
+        const observedHosts = new WeakSet();
+        const observeNewHosts = () => {
+            let found = false;
+            for (const host of themeHosts) {
+                if (observedHosts.has(host))
+                    continue;
+                observedHosts.add(host);
+                observer.observe(host, {
+                    attributes: true,
+                    attributeFilter: [
+                        "theme",
+                        "scheme",
+                        "provider",
+                        "variables",
+                        "style",
+                        "data-theme",
+                        "data-color-scheme",
+                    ],
+                });
+                found = true;
+            }
+            return found;
+        };
+        const observer = new MutationObserver((records) => {
+            const mounted = observeNewHosts();
+            if (mounted || records.some((record) => record.type === "attributes")) {
+                this.applyAdaptiveTTSStyle();
+            }
+        });
+        this.themeObserver = observer;
+        observer.observe(document.documentElement, {
             attributes: true,
             attributeFilter: ["style", "data-theme", "data-color-scheme", "class"],
         });
-        for (const host of document.querySelectorAll("pie-theme")) {
-            this.themeObserver.observe(host, {
-                attributes: true,
-                attributeFilter: [
-                    "theme",
-                    "scheme",
-                    "provider",
-                    "variables",
-                    "style",
-                    "data-theme",
-                    "data-color-scheme",
-                ],
-            });
-        }
+        // Insertions, so a `<pie-theme>` mounted later is found. An insertion
+        // costs a walk of the live host list, which holds a handful at most.
+        observer.observe(document, { childList: true, subtree: true });
+        observeNewHosts();
     }
     parseColor(input) {
         if (!input)
@@ -511,6 +533,8 @@ export class HighlightCoordinator {
             : [0.8, 0.72, 0.68, 0.62, 0.56, 0.5];
         let selectedOpacity = opacityCandidates[opacityCandidates.length - 1];
         let bestScore = -Infinity;
+        // The first opacity whose blend clears 1.25:1 against the background and
+        // 2.4:1 against the text wins; otherwise the best weighted score.
         for (const opacity of opacityCandidates) {
             const blended = this.blend(accent, background, opacity);
             const backgroundDelta = this.contrastRatio(blended, background);
@@ -593,7 +617,6 @@ export class HighlightCoordinator {
             return;
         if (typeof document === "undefined")
             return; // SSR guard
-        // Check if styles already exist
         if (document.getElementById("pie-highlight-styles"))
             return;
         const style = document.createElement("style");
@@ -633,12 +656,10 @@ export class HighlightCoordinator {
      * lives in a font-driven pseudo-element a CSS range cannot paint) and
      * whole-expression fallbacks.
      *
-     * The supplied element is painted exactly; we deliberately do NOT walk up to
-     * a containing `<math>` / `<mjx-container>`. That escalation is what made
-     * MathJax-rendered math highlight as a full block while native MathML tracked
-     * per-token: a resolved single token must paint as a token, and only a
-     * genuine expression fallback (where the element already is the container)
-     * should paint the whole expression.
+     * The supplied element is painted exactly, with no walk up to a containing
+     * `<math>` / `<mjx-container>`: a resolved token paints as a token, and only
+     * an expression fallback, where the element already is the container, paints
+     * the whole expression.
      */
     highlightTTSWordElement(element) {
         if (!this.supported)
@@ -660,7 +681,6 @@ export class HighlightCoordinator {
         if (!this.supported)
             return;
         this.applyAdaptiveTTSStyle(startElementOf(ranges));
-        // Clear previous sentence highlight
         this.clearTTSSentence();
         const highlight = sharedHighlight(TTS_SENTENCE_HIGHLIGHT);
         for (const range of ranges) {
@@ -689,12 +709,11 @@ export class HighlightCoordinator {
     // The read-along (sentence) band legitimately covers whole equations and
     // replaced elements, so it escalates to them.
     static SENTENCE_FALLBACK_SELECTOR = "math, mjx-container, svg, img, canvas, [role='img']";
-    // The word layer must NOT escalate a multi-node range to the enclosing
-    // `<math>` / `<mjx-container>`: that is what made an equation flash as a
-    // whole block whenever a spoken word's visible range crossed several math
-    // glyph nodes. Math is tracked per token (or held / region) by the highlight
-    // pipeline instead. Replaced elements (svg/img/canvas) still need the element
-    // fallback because a CSS range cannot paint them.
+    // The word layer falls back to the element only for replaced elements
+    // (svg/img/canvas), which a CSS range cannot paint. Escalating to the
+    // enclosing `<math>` / `<mjx-container>` flashed the whole equation whenever
+    // a word crossed several glyph nodes, so math is tracked per token, held or
+    // by region in the highlight pipeline.
     static WORD_FALLBACK_SELECTOR = "svg, img, canvas, [role='img']";
     highlightTTSElementFallbacks(ranges) {
         if (typeof Element === "undefined")
@@ -796,10 +815,8 @@ export class HighlightCoordinator {
      */
     addAnnotation(range, color = HighlightColor.YELLOW) {
         const id = `annotation-${this.nextAnnotationId++}`;
-        // Clone the range to store
         const clonedRange = range.cloneRange();
         adoptHighlightStylesFor(clonedRange.startContainer);
-        // Store annotation data
         const annotation = {
             id,
             range: clonedRange,
@@ -913,44 +930,6 @@ export class HighlightCoordinator {
     // ============================================================================
     // HighlightCoordinatorApi interface implementation
     // ============================================================================
-    /**
-     * Highlight a range as the given type: the TTS types paint as
-     * {@link highlightTTSWord} and {@link highlightTTSSentence} do.
-     */
-    highlightRange(range, type, color = HighlightColor.YELLOW) {
-        if (!this.supported)
-            return;
-        switch (type) {
-            case HighlightType.TTS_WORD:
-                this.highlightTTSWord([range]);
-                break;
-            case HighlightType.TTS_SENTENCE:
-                this.highlightTTSSentence([range]);
-                break;
-            case HighlightType.ANNOTATION:
-                // For annotations, use the existing method
-                this.addAnnotation(range, color);
-                break;
-        }
-    }
-    /**
-     * Clear highlights of a specific type (interface method)
-     */
-    clearHighlights(type) {
-        if (!this.supported)
-            return;
-        switch (type) {
-            case HighlightType.TTS_WORD:
-                this.clearTTSWord();
-                break;
-            case HighlightType.TTS_SENTENCE:
-                this.clearTTSSentence();
-                break;
-            case HighlightType.ANNOTATION:
-                this.clearAnnotations();
-                break;
-        }
-    }
     /**
      * Clear all highlights (interface method)
      */
@@ -960,12 +939,6 @@ export class HighlightCoordinator {
         this.clearTTS();
         this.clearAnnotations();
     }
-    /**
-     * Check if CSS Highlight API is supported (interface method)
-     */
-    isSupported() {
-        return this.supported;
-    }
     /**
      * Update TTS highlight style dynamically
      *
@@ -980,7 +953,6 @@ export class HighlightCoordinator {
         const styleEl = document.getElementById("pie-highlight-styles");
         if (!styleEl)
             return;
-        // Convert hex to rgba
         const hexToRgb = (hex) => {
             const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
             return result

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}`;