@pie-players/pie-assessment-toolkit 0.3.74 → 0.3.75

package/dist/services/tts/flat-tree.js

@@ -0,0 +1,269 @@
+/**
+ * The tree read-aloud walks: the flat tree, which is the tree the page renders.
+ *
+ * An element with an open shadow root contributes that root's children in place
+ * of its own light children, and a `<slot>` inside a shadow root contributes the
+ * nodes assigned to it, flattened through nested slots, so a host's light
+ * children are reached once, at the slot that renders them. Closed shadow roots
+ * are invisible to script, so their hosts are walked as light DOM.
+ *
+ * Toolkit chrome is skipped wherever it appears: toolbars and tool elements
+ * render their controls into open shadow roots, and descending into them would
+ * read button labels as content. So are the empty `aria-hidden` anchors the
+ * shells and the toolkit keep beside their slots, and elements whose text never
+ * renders (`style`, `script`, `noscript`, `template`).
+ *
+ * Node types are compared as the spec's numbers, so this module reads no DOM
+ * global, at import or at call time.
+ */
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const DOCUMENT_FRAGMENT_NODE = 11;
+const CHROME_TAGS = new Set([
+    "pie-item-toolbar",
+    "pie-section-toolbar",
+    "pie-item-player-session-debugger",
+]);
+const CHROME_TAG_PREFIXES = ["pie-tool-", "pie-section-player-tools-"];
+const UNRENDERED_TEXT_TAGS = new Set([
+    "style",
+    "script",
+    "noscript",
+    "template",
+]);
+export const isShadowRootNode = (node) => !!node &&
+    node.nodeType === DOCUMENT_FRAGMENT_NODE &&
+    node.host?.nodeType === ELEMENT_NODE;
+/** Toolbars, tool elements and debug panels: chrome around content, never content. */
+export const isToolkitChromeElement = (element) => {
+    const tag = element.localName?.toLowerCase() || "";
+    if (CHROME_TAGS.has(tag))
+        return true;
+    return CHROME_TAG_PREFIXES.some((prefix) => tag.startsWith(prefix));
+};
+const isSkippedElement = (element) => {
+    const tag = element.localName?.toLowerCase() || "";
+    if (UNRENDERED_TEXT_TAGS.has(tag))
+        return true;
+    if (isToolkitChromeElement(element))
+        return true;
+    // A shell's anchor: an `aria-hidden` element at the top of a shadow root,
+    // there to reach the host's context and holding nothing to read.
+    return (isShadowRootNode(element.parentNode) &&
+        element.getAttribute("aria-hidden") === "true");
+};
+const slotFlattenedNodes = (slot) => {
+    if (!isShadowRootNode(slot.getRootNode?.()))
+        return null;
+    const assignedNodes = slot.assignedNodes;
+    if (typeof assignedNodes !== "function")
+        return null;
+    try {
+        return assignedNodes.call(slot, { flatten: true });
+    }
+    catch {
+        return null;
+    }
+};
+/** `node`'s children in the flat tree, with skipped elements left out. */
+export const flatTreeChildNodes = (node) => {
+    let children = node.childNodes;
+    if (node.nodeType === ELEMENT_NODE) {
+        const element = node;
+        const shadowRoot = element.shadowRoot;
+        if (shadowRoot) {
+            children = shadowRoot.childNodes;
+        }
+        else if (element.localName?.toLowerCase() === "slot") {
+            children = slotFlattenedNodes(element) ?? element.childNodes;
+        }
+    }
+    const result = [];
+    for (const child of Array.from(children || [])) {
+        if (child.nodeType === ELEMENT_NODE && isSkippedElement(child)) {
+            continue;
+        }
+        result.push(child);
+    }
+    return result;
+};
+/** Visits `root`'s flat-tree descendants in rendering order; `root` itself is not visited. */
+export const walkFlatTree = (root, visit) => {
+    const descend = (node) => {
+        for (const child of flatTreeChildNodes(node)) {
+            const result = visit(child);
+            if (result === "stop")
+                return false;
+            if (result === "skip")
+                continue;
+            if (!descend(child))
+                return false;
+        }
+        return true;
+    };
+    descend(root);
+};
+/** `root`'s text nodes in rendering order. */
+export const flatTreeTextNodes = (root) => {
+    const nodes = [];
+    walkFlatTree(root, (node) => {
+        if (node.nodeType === TEXT_NODE)
+            nodes.push(node);
+        return undefined;
+    });
+    return nodes;
+};
+/** `textContent` over the flat tree: shadow content in, skipped elements out. */
+export const flatTextContent = (root) => flatTreeTextNodes(root)
+    .map((node) => node.data)
+    .join("");
+/** Elements under `root` matching `selector`, in rendering order. */
+export const flatQuerySelectorAll = (root, selector) => {
+    const matches = [];
+    walkFlatTree(root, (node) => {
+        if (node.nodeType === ELEMENT_NODE && node.matches(selector)) {
+            matches.push(node);
+        }
+        return undefined;
+    });
+    return matches;
+};
+export const flatQuerySelector = (root, selector) => {
+    let match = null;
+    walkFlatTree(root, (node) => {
+        if (node.nodeType === ELEMENT_NODE && node.matches(selector)) {
+            match = node;
+            return "stop";
+        }
+        return undefined;
+    });
+    return match;
+};
+/**
+ * `node`'s parent in the flat tree: the slot rendering it, else its parent, with
+ * a shadow root standing for its host.
+ */
+export const flatTreeParentNode = (node) => {
+    const slot = node.assignedSlot;
+    if (slot)
+        return slot;
+    const parent = node.parentNode;
+    if (isShadowRootNode(parent))
+        return parent.host;
+    return parent;
+};
+export const flatTreeParentElement = (node) => {
+    let parent = flatTreeParentNode(node);
+    while (parent && parent.nodeType !== ELEMENT_NODE) {
+        parent = flatTreeParentNode(parent);
+    }
+    return parent;
+};
+/** The nearest element at or above `node` in the flat tree that matches `selector`. */
+export const flatTreeClosest = (node, selector) => {
+    let current = node.nodeType === ELEMENT_NODE
+        ? node
+        : flatTreeParentElement(node);
+    while (current) {
+        if (current.matches(selector))
+            return current;
+        current = flatTreeParentElement(current);
+    }
+    return null;
+};
+/**
+ * `node`'s parent element, continuing from a shadow root to its host. This is the
+ * chain inheritance follows (`lang`, regions an author marks up), and for slotted
+ * content it stays in the light tree the author wrote.
+ */
+export const composedParentElement = (node) => {
+    if (node.parentElement)
+        return node.parentElement;
+    const parent = node.parentNode;
+    return isShadowRootNode(parent) ? parent.host : null;
+};
+/**
+ * The nearest element at or above `node` on the composed chain that matches
+ * `selector`, or null. With `boundary`, the climb ends after testing it.
+ */
+export const composedClosest = (node, selector, boundary) => {
+    let current = node.nodeType === ELEMENT_NODE
+        ? node
+        : composedParentElement(node);
+    while (current) {
+        if (current.matches(selector))
+            return current;
+        if (boundary && current === boundary)
+            return null;
+        current = composedParentElement(current);
+    }
+    return null;
+};
+/** `contains` across shadow boundaries: whether `node` is `container` or below it. */
+export const composedContains = (container, node) => {
+    if (!container || !node)
+        return false;
+    let current = node;
+    while (current) {
+        if (current === container || container.contains(current))
+            return true;
+        const root = current.getRootNode?.();
+        current = isShadowRootNode(root) ? root.host : null;
+    }
+    return false;
+};
+/**
+ * `node`, or the shadow host above it, that lies in the tree rooted at
+ * `treeRoot`; null when `node` is not inside that tree at any depth.
+ */
+export const retargetToTree = (node, treeRoot) => {
+    let current = node;
+    while (current) {
+        const root = current.getRootNode?.();
+        if (root === treeRoot)
+            return current;
+        current = isShadowRootNode(root) ? root.host : null;
+    }
+    return null;
+};
+/**
+ * Whether the character at `offset` in `node` lies inside `range`. A live range
+ * holds nodes of one tree only, so a node in a shadow tree below it counts as
+ * inside when the range holds that tree's host whole.
+ */
+export const rangeHoldsTextPosition = (range, node, offset) => {
+    try {
+        const treeRoot = range.startContainer.getRootNode?.();
+        if (!treeRoot || node.getRootNode?.() === treeRoot) {
+            return (range.comparePoint(node, offset) === 0 &&
+                range.comparePoint(node, Math.min(offset + 1, node.length)) === 0);
+        }
+        return rangeHoldsNodeWhole(range, retargetToTree(node, treeRoot));
+    }
+    catch {
+        return false;
+    }
+};
+/** Whether `range` intersects `node`, counting a shadow tree below the range as {@link rangeHoldsTextPosition} does. */
+export const rangeIntersectsComposedNode = (range, node) => {
+    try {
+        const treeRoot = range.startContainer.getRootNode?.();
+        if (!treeRoot || node.getRootNode?.() === treeRoot) {
+            return range.intersectsNode(node);
+        }
+        return rangeHoldsNodeWhole(range, retargetToTree(node, treeRoot));
+    }
+    catch {
+        return false;
+    }
+};
+const rangeHoldsNodeWhole = (range, node) => {
+    const parent = node?.parentNode;
+    if (!node || !parent)
+        return false;
+    const index = Array.prototype.indexOf.call(parent.childNodes, node);
+    if (index < 0)
+        return false;
+    return (range.comparePoint(parent, index) === 0 &&
+        range.comparePoint(parent, index + 1) === 0);
+};

package/dist/services/tts/generated-speech/assemble-plan.d.ts

@@ -1,5 +1,5 @@
 import type { MathAwareSpeechChunk } from "../math-aware-text-processing.js";
-import { type ResolvedMathSpeech, type SREMathSpeechOptions } from "../math-speech.js";
+import { type ResolveMathSpeechOptions, type ResolvedMathSpeech, type SREMathSpeechOptions } from "../math-speech.js";
 import type { AssembledSpeech } from "./types.js";
 type MathChunk = Extract<MathAwareSpeechChunk, {
     type: "math";
@@ -13,6 +13,8 @@ export type MathSpeechResolver = (chunk: MathChunk, options: {
     language?: string;
     produceSsml?: boolean;
     mathSpeech?: SREMathSpeechOptions;
+    /** The read's one engine load, shared by its equations. */
+    loadSre?: ResolveMathSpeechOptions["loadSre"];
 }) => Promise<ResolvedMathSpeech>;
 /**
  * Assemble an anchor-free speech plan from already-collected math-aware chunks.

package/dist/services/tts/generated-speech/assemble-plan.js

@@ -1,4 +1,4 @@
-import { resolveMathSpeechFromChunks, } from "../math-speech.js";
+import { createReadSreLoad, resolveMathSpeechFromChunks, } from "../math-speech.js";
 import { normalizeTextForSpeech } from "../text-processing.js";
 import { segmentSentences as segmentTextToSentences } from "../text-segmentation.js";
 const defaultMathSpeechResolver = (chunk, options) => resolveMathSpeechFromChunks([chunk], options);
@@ -37,6 +37,7 @@ const shouldPreserveProseChunk = (chunk) => {
  */
 export const assembleGeneratedSpeech = async (args) => {
     const resolveMathSpeech = args.resolveMathSpeech ?? defaultMathSpeechResolver;
+    const loadSre = createReadSreLoad(args.mathSpeech);
     const { visibleText } = args;
     const segments = [];
     // Cursor-based span tracking:
@@ -84,6 +85,7 @@ export const assembleGeneratedSpeech = async (args) => {
             language: args.language,
             produceSsml: args.produceSsml,
             mathSpeech: args.mathSpeech,
+            loadSre,
         });
         const usedFallback = !generated.speechText;
         const spokenText = generated.speechText || chunk.fallbackText;

package/dist/services/tts/generated-speech/dom/build-dom-plan.d.ts

@@ -16,6 +16,8 @@ export interface BuildGeneratedSpeechResult {
  */
 export declare const buildGeneratedSpeechFromRoot: (args: {
     contentRoot: Element;
+    /** Limit the plan to the part of `contentRoot` this range selects. */
+    range?: Range;
     language?: string;
     mathSpeech?: SREMathSpeechOptions;
     textProcessingOptions?: TextProcessingOptions;

package/dist/services/tts/generated-speech/dom/build-dom-plan.js

@@ -17,7 +17,7 @@ const sliceVisibleMap = (map, start, end) => {
  * entry point that touches the DOM; assembly and serialization stay pure.
  */
 export const buildGeneratedSpeechFromRoot = async (args) => {
-    const extracted = collectMathAwareTextAndMap(args.contentRoot, args.textProcessingOptions);
+    const extracted = collectMathAwareTextAndMap(args.contentRoot, args.textProcessingOptions, args.range);
     const assembled = await assembleGeneratedSpeech({
         chunks: extracted.chunks,
         visibleText: extracted.visibleText,

package/dist/services/tts/generated-speech/math-speech-cache.d.ts

@@ -7,7 +7,9 @@ export interface MathSpeechCacheOptions {
 /**
  * Build a memoized {@link MathSpeechResolver}.
  *
- * Caches only DOM-free spoken-text results keyed by
+ * Caches only DOM-free spoken-text results that SRE produced, so an equation
+ * read as its visible text after a failed engine load is resolved again on
+ * the next read. Keyed by
  * `(SRE version, locale, output mode, SRE mathSpeech options, MathML source)`.
  * Never caches DOM nodes or maps. Bounded by a simple LRU so long sessions do
  * not grow unbounded.

package/dist/services/tts/generated-speech/math-speech-cache.js

@@ -35,7 +35,9 @@ const cacheKeyFor = (language, produceSsml, mathSpeech, mathml) => `${SRE_CACHE_
 /**
  * Build a memoized {@link MathSpeechResolver}.
  *
- * Caches only DOM-free spoken-text results keyed by
+ * Caches only DOM-free spoken-text results that SRE produced, so an equation
+ * read as its visible text after a failed engine load is resolved again on
+ * the next read. Keyed by
  * `(SRE version, locale, output mode, SRE mathSpeech options, MathML source)`.
  * Never caches DOM nodes or maps. Bounded by a simple LRU so long sessions do
  * not grow unbounded.
@@ -66,6 +68,8 @@ export const createMemoizedMathSpeechResolver = (options = {}) => {
             return cached;
         }
         const resolved = await resolve(chunk, { ...opts, mathSpeech });
+        if (resolved.usedFallback)
+            return resolved;
         if (produceSsml && resolved.ssml && maxEntries > 1) {
             setCached(cacheKeyFor(opts.language, false, mathSpeech, chunk.mathml), {
                 speechText: resolved.speechText,

package/dist/services/tts/highlight-pipeline/create-highlight-plan.js

@@ -3,12 +3,19 @@ import { createHighlightDecision } from "./highlight-policy.js";
 import { resolveMathBoundaryTarget } from "./math-semantic-resolver.js";
 import { resolveProseBoundaryTarget } from "./prose-boundary-resolver.js";
 import { classifyMathHighlightCapability, createRenderedMathTargetResolver, } from "./rendered-math-target-resolver.js";
+import { composedContains, composedParentElement, rangeIntersectsComposedNode, } from "../flat-tree.js";
 import { isNodeHiddenForTTS } from "../text-processing.js";
+import { createRangesFromVisibleMap } from "./visible-map-range.js";
+const regionRangesFor = (chunk) => {
+    const ranges = createRangesFromVisibleMap(chunk.visibleMap, 0, chunk.visibleText.length);
+    return ranges.length > 1 ? ranges : undefined;
+};
 const regionTargetFor = (chunk) => chunk.regionRange
     ? {
         type: "range",
         quality: "region",
         range: chunk.regionRange,
+        ranges: regionRangesFor(chunk),
     }
     : chunk.regionElement
         ? {
@@ -29,12 +36,13 @@ const mathCandidatesForTarget = (target, chunk) => {
         return chunk.mathAlignments;
     return chunk.mathAlignments.filter(({ element }) => {
         try {
-            if (target.type === "range")
-                return target.range.intersectsNode(element);
+            if (target.type === "range") {
+                return (target.ranges ?? [target.range]).some((range) => rangeIntersectsComposedNode(range, element));
+            }
             if (target.type === "element") {
-                return target.element === element || target.element.contains(element);
+                return composedContains(target.element, element);
             }
-            return target.node.parentElement?.contains(element) || false;
+            return composedContains(composedParentElement(target.node), element);
         }
         catch {
             return false;

package/dist/services/tts/highlight-pipeline/prose-boundary-resolver.js

@@ -1,19 +1,21 @@
 import { resolveVisibleSpanForBoundary } from "../catalog-span-alignment.js";
-import { createRangeFromVisibleMap } from "./visible-map-range.js";
+import { createRangesFromVisibleMap } from "./visible-map-range.js";
 export const resolveProseBoundaryTarget = (chunk, boundary) => {
     if (!chunk.catalogAlignment || boundary.chunkSpokenStart === null)
         return null;
     const visibleSpan = resolveVisibleSpanForBoundary(chunk.catalogAlignment, boundary.chunkSpokenStart);
     if (!visibleSpan)
         return null;
-    const range = createRangeFromVisibleMap(chunk.visibleMap, visibleSpan.start, visibleSpan.end);
-    if (!range)
+    // One range per tree, as the uncataloged word path builds them.
+    const ranges = createRangesFromVisibleMap(chunk.visibleMap, visibleSpan.start, visibleSpan.end);
+    if (ranges.length === 0)
         return null;
     return {
         type: "range",
         quality: chunk.catalogAlignment.playbackMode === "exact-word"
             ? "exact-word"
             : "semantic-token",
-        range,
+        range: ranges[0],
+        ranges: ranges.length > 1 ? ranges : undefined,
     };
 };

package/dist/services/tts/highlight-pipeline/readable-region.js

@@ -1,3 +1,4 @@
+import { composedClosest, composedContains } from "../flat-tree.js";
 const READABLE_REGION_SELECTOR = [
     "[data-pie-tts-region]",
     "[data-catalog-region]",
@@ -10,8 +11,8 @@ const READABLE_REGION_SELECTOR = [
     "div",
 ].join(",");
 export const resolveReadableRegion = (sourceElement, contentRoot) => {
-    const region = sourceElement.closest(READABLE_REGION_SELECTOR);
-    if (region && contentRoot.contains(region)) {
+    const region = composedClosest(sourceElement, READABLE_REGION_SELECTOR);
+    if (region && composedContains(contentRoot, region)) {
         return region;
     }
     return sourceElement;

package/dist/services/tts/highlight-pipeline/types.d.ts

@@ -44,6 +44,11 @@ export type RenderableHighlightTarget = {
     type: "range";
     quality: "exact-word" | "semantic-token" | "expression" | "region";
     range: Range;
+    /**
+     * Every range to paint when the target crosses shadow boundaries, one per
+     * tree, `range` among them; absent when `range` covers the target.
+     */
+    ranges?: Range[];
 } | {
     type: "element";
     quality: "semantic-token" | "expression" | "region";

package/dist/services/tts/highlight-pipeline/visible-map-range.d.ts

@@ -1,2 +1,14 @@
 import type { NormalizedTextMap } from "../text-processing.js";
+/**
+ * The range over visible characters `start` to `end` (exclusive). A live range
+ * holds one tree, so when the span runs into a shadow tree, or out of one, the
+ * range ends at the last character in the tree it starts in.
+ */
 export declare const createRangeFromVisibleMap: (visibleMap: NormalizedTextMap | undefined, start: number, end: number) => Range | null;
+/**
+ * The ranges over visible characters `start` to `end` (exclusive), one per run of
+ * characters in the same tree, so a span crossing shadow boundaries paints in
+ * each tree it covers. A span within one tree gives exactly
+ * {@link createRangeFromVisibleMap}'s range.
+ */
+export declare const createRangesFromVisibleMap: (visibleMap: NormalizedTextMap | undefined, start: number, end: number) => Range[];

package/dist/services/tts/highlight-pipeline/visible-map-range.js

@@ -1,3 +1,20 @@
+const treeOf = (mapping) => mapping.node.getRootNode?.() ?? mapping.node;
+const rangeBetween = (start, end) => {
+    try {
+        const range = document.createRange();
+        range.setStart(start.node, start.offset);
+        range.setEnd(end.node, end.offset + 1);
+        return range;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The range over visible characters `start` to `end` (exclusive). A live range
+ * holds one tree, so when the span runs into a shadow tree, or out of one, the
+ * range ends at the last character in the tree it starts in.
+ */
 export const createRangeFromVisibleMap = (visibleMap, start, end) => {
     if (!visibleMap || typeof document === "undefined")
         return null;
@@ -9,13 +26,62 @@ export const createRangeFromVisibleMap = (visibleMap, start, end) => {
         return null;
     if (!endMapping)
         endMapping = startMapping;
-    try {
-        const range = document.createRange();
-        range.setStart(startMapping.node, startMapping.offset);
-        range.setEnd(endMapping.node, endMapping.offset + 1);
-        return range;
+    if (treeOf(endMapping) !== treeOf(startMapping)) {
+        const tree = treeOf(startMapping);
+        endMapping = startMapping;
+        for (let index = start + 1; index < end; index++) {
+            const mapping = visibleMap.get(index);
+            if (mapping && treeOf(mapping) === tree)
+                endMapping = mapping;
+        }
     }
-    catch {
-        return null;
+    return rangeBetween(startMapping, endMapping);
+};
+/**
+ * The ranges over visible characters `start` to `end` (exclusive), one per run of
+ * characters in the same tree, so a span crossing shadow boundaries paints in
+ * each tree it covers. A span within one tree gives exactly
+ * {@link createRangeFromVisibleMap}'s range.
+ */
+export const createRangesFromVisibleMap = (visibleMap, start, end) => {
+    if (!visibleMap || typeof document === "undefined" || end <= start)
+        return [];
+    const startMapping = visibleMap.get(start);
+    if (!startMapping)
+        return [];
+    const tree = treeOf(startMapping);
+    let crossesTrees = false;
+    for (let index = start + 1; index < end && !crossesTrees; index++) {
+        const mapping = visibleMap.get(index);
+        if (mapping && treeOf(mapping) !== tree)
+            crossesTrees = true;
+    }
+    if (!crossesTrees) {
+        const range = createRangeFromVisibleMap(visibleMap, start, end);
+        return range ? [range] : [];
+    }
+    const ranges = [];
+    let runStart = null;
+    let runEnd = null;
+    const closeRun = () => {
+        if (runStart && runEnd) {
+            const range = rangeBetween(runStart, runEnd);
+            if (range)
+                ranges.push(range);
+        }
+        runStart = null;
+        runEnd = null;
+    };
+    for (let index = start; index < end; index++) {
+        const mapping = visibleMap.get(index);
+        if (!mapping)
+            continue;
+        if (runStart && treeOf(runStart) !== treeOf(mapping))
+            closeRun();
+        if (!runStart)
+            runStart = mapping;
+        runEnd = mapping;
     }
+    closeRun();
+    return ranges;
 };

package/dist/services/tts/math-aware-text-processing.d.ts

@@ -15,4 +15,8 @@ export interface MathAwareTextResult {
     chunks: MathAwareSpeechChunk[];
     containsMathMarkup: boolean;
 }
-export declare const collectMathAwareTextAndMap: (element: Element, options?: TextProcessingOptions) => MathAwareTextResult;
+/**
+ * With `range`, only the part of `element` the range selects: text it selects
+ * and equations it holds whole.
+ */
+export declare const collectMathAwareTextAndMap: (element: Element, options?: TextProcessingOptions, range?: Range) => MathAwareTextResult;