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

package/dist/services/RangeSerializer.d.ts

@@ -5,7 +5,10 @@
  * 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; a path with no ` >>> ` is a plain
+ * selector path.
  */
 /**
  * Serialized form of a Range suitable for storage.
@@ -77,42 +80,17 @@ 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;
     /**
-     * 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 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;
+    /** 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

@@ -5,8 +5,14 @@
  * 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; 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. */
+const SHADOW_STEP = " >>> ";
 /**
  * RangeSerializer - Serialize and deserialize Range objects.
  */
@@ -64,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) {
@@ -83,116 +87,141 @@ 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.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}`);
     }
-    /**
-     * 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 "";
         }
-        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}`;
     }
     /**
-     * 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 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;
+    }
+    /** 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 [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
             const textNodes = Array.from(parent.childNodes).filter((n) => n.nodeType === Node.TEXT_NODE);
             return textNodes[textIndex] || null;
         }
-        // Handle element paths
         try {
-            return root.querySelector(path);
+            return this.resolveElementPath(path, root);
         }
         catch (error) {
             console.warn("Invalid selector path:", path, error);
             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}`;