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

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/highlight-target-resolver.d.ts

@@ -1,3 +1,7 @@
+/**
+ * What the host knows about the content being highlighted. `scopeElement`
+ * falls back to the content element being read.
+ */
 export interface TTSHighlightContext {
     scopeElement?: HTMLElement | null;
     itemId?: string;
@@ -6,12 +10,20 @@ export interface TTSHighlightContext {
     contentKind?: string;
     regionPolicy?: string;
 }
+/**
+ * Host remap of TTS highlight targets. A null or undefined result keeps the
+ * native targets, and so does a result outside `scopeElement` or a throw. For
+ * sentences, one out-of-scope or non-Range/Element entry keeps all native
+ * ranges.
+ */
 export interface TTSHighlightTargetResolver {
     resolveWordRange?(range: Range, context: TTSHighlightContext): Range | null | undefined;
     resolveSentenceRanges?(ranges: Range[], context: TTSHighlightContext): Array<Range | HTMLElement> | null | undefined;
 }
+/** A resolver with the context it is called with. */
 export interface TTSHighlightTargetResolverRuntime {
     context: TTSHighlightContext;
     resolver?: TTSHighlightTargetResolver | null;
 }
+/** Read at every highlight; a throw counts as no resolver. */
 export type TTSHighlightTargetResolverProvider = () => TTSHighlightTargetResolverRuntime | null | undefined;

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;

package/dist/services/tts/math-aware-text-processing.js

@@ -1,5 +1,6 @@
+import { flatQuerySelector, flatTreeChildNodes, flatTreeParentElement, rangeIntersectsComposedNode, } from "./flat-tree.js";
 import { canonicalizeMathML } from "./mathml-sanitization.js";
-import { collectVisibleTextAndMap, isNodeExcludedFromSpeech, normalizeTextForSpeech, shouldInsertWordBoundarySpace, } from "./text-processing.js";
+import { collectVisibleTextAndMap, isNodeExcludedFromSpeech, normalizeTextForSpeech, rangeHoldsSpeakableElement, shouldInsertWordBoundarySpace, } from "./text-processing.js";
 const createAccumulator = (options) => ({
     chars: [],
     map: new Map(),
@@ -21,7 +22,7 @@ const getDataMathML = (element) => {
     return value && value.trim() ? value : null;
 };
 const findAssistiveMathML = (element) => {
-    const assistive = element.querySelector("mjx-assistive-mml math");
+    const assistive = flatQuerySelector(element, "mjx-assistive-mml math");
     return assistive?.outerHTML || null;
 };
 const findCanonicalMathML = (element) => {
@@ -72,22 +73,20 @@ const TEXT_CHUNK_SOURCE_ROLES = new Set([
     "rowheader",
 ]);
 const resolveTextChunkSourceElement = (textNode, root) => {
-    let current = textNode.parentElement;
-    let best = null;
+    let current = flatTreeParentElement(textNode);
     while (current && current !== root) {
         const role = (current.getAttribute("role") || "").toLowerCase();
         const tagName = current.tagName.toUpperCase();
         if (TEXT_CHUNK_SOURCE_TAGS.has(tagName) ||
             TEXT_CHUNK_SOURCE_ROLES.has(role)) {
-            best = current;
-            break;
+            return current;
         }
-        current = current.parentElement;
+        current = flatTreeParentElement(current);
     }
-    return best || root;
+    return root;
 };
 const hasMathCandidate = (element) => Boolean(typeof element.querySelector === "function" &&
-    element.querySelector("math, [data-mathml], .MathJax, mjx-container, mjx-assistive-mml")) ||
+    flatQuerySelector(element, "math, [data-mathml], .MathJax, mjx-container, mjx-assistive-mml")) ||
     element.tagName?.toLowerCase() === "math" ||
     element.hasAttribute?.("data-mathml") ||
     isMathJaxElement(element);
@@ -121,10 +120,11 @@ const shouldInsertBoundarySpace = (acc, nextCharacter) => {
     // visible-text collector, instead of an ASCII-only heuristic.
     return shouldInsertWordBoundarySpace(previous, nextCharacter, acc.options);
 };
-const appendTextNode = (acc, textNode) => {
+/** `start` and `end` bound the part of the node appended, for a selection. */
+const appendTextNode = (acc, textNode, start = 0, end = (textNode.textContent || "").length) => {
     const raw = textNode.textContent || "";
     let appendedNonWhitespaceInNode = false;
-    for (let i = 0; i < raw.length; i++) {
+    for (let i = start; i < end; i++) {
         const character = raw[i];
         const isWhitespace = /\s/.test(character);
         if (acc.inLeadingWhitespace) {
@@ -156,13 +156,12 @@ const appendCollectedText = (acc, collected) => {
     for (let i = 0; i < collected.text.length; i++) {
         const character = collected.text[i];
         const isWhitespace = /\s/.test(character);
-        const mapping = collected.map.get(i) || null;
-        const syntheticNode = mapping?.node || acc.lastMapped?.node || null;
-        const syntheticOffset = mapping?.offset ?? acc.lastMapped?.offset ?? 0;
-        const normalizedMapping = mapping
+        const mapping = collected.map.get(i);
+        // An unmapped character borrows the last mapped position.
+        const characterMapping = mapping
             ? { node: mapping.node, offset: mapping.offset }
-            : syntheticNode
-                ? { node: syntheticNode, offset: syntheticOffset }
+            : acc.lastMapped
+                ? { node: acc.lastMapped.node, offset: acc.lastMapped.offset }
                 : null;
         if (acc.inLeadingWhitespace) {
             if (isWhitespace)
@@ -171,29 +170,16 @@ const appendCollectedText = (acc, collected) => {
         }
         if (isWhitespace) {
             if (!acc.lastCharWasWhitespace) {
-                appendCharacter(acc, " ", normalizedMapping);
+                appendCharacter(acc, " ", characterMapping);
             }
             acc.lastCharWasWhitespace = true;
             continue;
         }
         if (i === 0 && shouldInsertBoundarySpace(acc, character)) {
-            appendCharacter(acc, " ", normalizedMapping);
+            appendCharacter(acc, " ", characterMapping);
         }
-        appendCharacter(acc, character, normalizedMapping);
+        appendCharacter(acc, character, characterMapping);
         acc.lastCharWasWhitespace = false;
-        if (mapping) {
-            acc.map.set(acc.position - 1, {
-                node: mapping.node,
-                offset: mapping.offset,
-            });
-            acc.lastMapped = { node: mapping.node, offset: mapping.offset };
-        }
-        else if (syntheticNode) {
-            acc.map.set(acc.position - 1, {
-                node: syntheticNode,
-                offset: syntheticOffset,
-            });
-        }
     }
 };
 const textFallbackFromMathML = (mathml) => {
@@ -230,7 +216,7 @@ const textFallbackFromMathML = (mathml) => {
 const mapFallbackToAssistiveMath = (element, fallbackText) => {
     const map = new Map();
     const sourceMath = isMathJaxElement(element)
-        ? element.querySelector("mjx-assistive-mml math")
+        ? flatQuerySelector(element, "mjx-assistive-mml math")
         : null;
     if (!sourceMath)
         return map;
@@ -247,7 +233,7 @@ const mapFallbackToAssistiveMath = (element, fallbackText) => {
         }
         if (node.nodeType !== 1 || isAnnotationElement(node))
             return;
-        for (const child of Array.from(node.childNodes)) {
+        for (const child of flatTreeChildNodes(node)) {
             visit(child);
         }
     };
@@ -281,7 +267,7 @@ const collectVisibleMathFallback = (element, canonicalMathML, options) => {
             isAnnotationElement(childElement)) {
             return;
         }
-        for (const child of Array.from(childElement.childNodes)) {
+        for (const child of flatTreeChildNodes(childElement)) {
             visit(child);
         }
     };
@@ -307,7 +293,7 @@ const trimTrailingWhitespace = (acc) => {
         acc.map.delete(acc.position);
     }
 };
-const collectMathAware = (root, options) => {
+const collectMathAware = (root, options, range) => {
     const acc = createAccumulator(options);
     const chunks = [];
     let textChunkStart = 0;
@@ -328,22 +314,28 @@ const collectMathAware = (root, options) => {
     const processNode = (node) => {
         if (isNodeExcludedFromSpeech(node, root))
             return;
-        if (node.nodeType === Node.TEXT_NODE) {
+        if (range && !rangeIntersectsComposedNode(range, node))
+            return;
+        if (node.nodeType === 3) {
             const sourceElement = resolveTextChunkSourceElement(node, root);
             if (textChunkSourceElement && sourceElement !== textChunkSourceElement) {
                 flushTextChunk();
             }
             textChunkSourceElement = sourceElement;
-            appendTextNode(acc, node);
+            const textNode = node;
+            appendTextNode(acc, textNode, range?.startContainer === textNode ? range.startOffset : undefined, range?.endContainer === textNode ? range.endOffset : undefined);
             return;
         }
-        if (node.nodeType !== Node.ELEMENT_NODE)
+        if (node.nodeType !== 1)
             return;
         const element = node;
         if (isAssistiveMathElement(element))
             return;
         const canonicalMathML = findCanonicalMathML(element);
-        if (canonicalMathML) {
+        // An equation is spoken as math only when the selection holds all of it;
+        // a part of one reads as the text selected.
+        if (canonicalMathML &&
+            (!range || rangeHoldsSpeakableElement(range, element, root))) {
             flushTextChunk();
             const collected = collectVisibleMathFallback(element, canonicalMathML, options);
             appendCollectedText(acc, collected);
@@ -358,19 +350,16 @@ const collectMathAware = (root, options) => {
             containsMathMarkup = true;
             return;
         }
-        for (const child of Array.from(element.childNodes)) {
+        for (const child of flatTreeChildNodes(element)) {
             processNode(child);
         }
     };
-    for (const child of Array.from(root.childNodes)) {
+    for (const child of flatTreeChildNodes(root)) {
         processNode(child);
     }
     trimTrailingWhitespace(acc);
     flushTextChunk();
     const visibleText = acc.chars.join("");
-    while (acc.map.has(visibleText.length)) {
-        acc.map.delete(visibleText.length);
-    }
     return {
         visibleText,
         map: acc.map,
@@ -378,7 +367,13 @@ const collectMathAware = (root, options) => {
         containsMathMarkup,
     };
 };
-export const collectMathAwareTextAndMap = (element, options) => {
+/**
+ * With `range`, only the part of `element` the range selects: text it selects
+ * and equations it holds whole.
+ */
+export const collectMathAwareTextAndMap = (element, options, range) => {
+    if (range)
+        return collectMathAware(element, options, range);
     if (!hasMathCandidate(element)) {
         const { text, map } = collectVisibleTextAndMap(element, options);
         return {

package/dist/services/tts/math-control-names.d.ts

@@ -0,0 +1,21 @@
+import { type ResolveMathSpeechOptions, type SREMathSpeechOptions } from "./math-speech.js";
+export interface MathControlNamesOptions {
+    /**
+     * The host's math speech options. Names take only `engineOptions`, where
+     * SRE's locale tables load from: their domain and style are fixed.
+     */
+    getMathSpeech?: () => SREMathSpeechOptions | undefined;
+    /** The host's `content-language`, read when an expression is named. */
+    getContentLanguage?: () => string | null | undefined;
+    loadSre?: ResolveMathSpeechOptions["loadSre"];
+}
+/**
+ * Labels each typeset expression inside a control under `root`, open shadow
+ * roots included, with SRE's speech, as MathJax adds it and again whenever
+ * MathJax replaces it. An `aria-label` on the role-less `mjx-container` puts
+ * that speech in the name of the control around it, among the control's other
+ * text. English reads ClearSpeak, other languages MathSpeak, in the language of
+ * the content. The label replaces the elements' own; it stays when SRE cannot
+ * speak the math. Returns the function that stops observing.
+ */
+export declare function observeMathControlNames(root: Element, options?: MathControlNamesOptions): () => void;

package/dist/services/tts/math-control-names.js

@@ -0,0 +1,142 @@
+import { resolveContentLanguage } from "../../runtime/content-language.js";
+import { flatQuerySelector, flatTreeClosest, walkFlatTree, } from "./flat-tree.js";
+import { resolveMathSpeechFromChunks, } from "./math-speech.js";
+import { canonicalizeMathML } from "./mathml-sanitization.js";
+/**
+ * Elements that take their accessible name from their content. Browsers leave
+ * MathML out of that name, so a choice labelled with math is named from its
+ * bare symbols ("4 12" for 4 over 12). The elements' renderer labels the math
+ * in the same set of controls with its own English speech.
+ */
+const CONTROLS = [
+    "a[href]",
+    "button",
+    "label",
+    "summary",
+    ...[
+        "button",
+        "checkbox",
+        "combobox",
+        "link",
+        "menuitem",
+        "menuitemcheckbox",
+        "menuitemradio",
+        "option",
+        "radio",
+        "switch",
+        "tab",
+        "treeitem",
+    ].map((role) => `[role="${role}"]`),
+].join(", ");
+const TOKENS = new Set(["mi", "mn", "mtext"]);
+const isToken = (element) => TOKENS.has(element.localName) ||
+    (element.localName === "mrow" &&
+        element.children.length === 1 &&
+        TOKENS.has(element.children[0].localName));
+/**
+ * ClearSpeak's fraction preference for a name. "4 over 12" keeps the numerals
+ * as written, where the default says "four fourths" for 4 over 4 (WCAG 2.5.3:
+ * a name does not put words in place of the formula). "Over" between longer
+ * parts is ambiguous, so an expression holding such a fraction reads every
+ * fraction by numerator and denominator.
+ */
+const fractionStyle = (math) => Array.from(math.getElementsByTagName("mfrac")).every((fraction) => Array.from(fraction.children).every(isToken))
+    ? "Fraction_Over"
+    : "Fraction_General";
+const isEnglish = (language) => !language || language.toLowerCase().split("-")[0] === "en";
+/**
+ * Labels each typeset expression inside a control under `root`, open shadow
+ * roots included, with SRE's speech, as MathJax adds it and again whenever
+ * MathJax replaces it. An `aria-label` on the role-less `mjx-container` puts
+ * that speech in the name of the control around it, among the control's other
+ * text. English reads ClearSpeak, other languages MathSpeak, in the language of
+ * the content. The label replaces the elements' own; it stays when SRE cannot
+ * speak the math. Returns the function that stops observing.
+ */
+export function observeMathControlNames(root, options = {}) {
+    if (typeof MutationObserver === "undefined")
+        return () => { };
+    const speech = new Map();
+    let stopped = false;
+    const speak = async (mathml, math, language) => {
+        const result = await resolveMathSpeechFromChunks([{ type: "math", mathml, fallbackText: "" }], {
+            language,
+            loadSre: options.loadSre,
+            mathSpeech: {
+                ...(isEnglish(language) ? { style: fractionStyle(math) } : {}),
+                engineOptions: options.getMathSpeech?.()?.engineOptions,
+            },
+        });
+        return result.usedMathSpeech ? result.speechText : null;
+    };
+    const name = (container) => {
+        if (!flatTreeClosest(container, CONTROLS))
+            return;
+        const math = flatQuerySelector(container, "math");
+        const mathml = math && canonicalizeMathML(math.outerHTML);
+        if (!math || !mathml)
+            return;
+        const language = resolveContentLanguage(container, {
+            contentLanguage: options.getContentLanguage?.(),
+        });
+        const key = `${language ?? ""}\u0000${mathml}`;
+        let pending = speech.get(key);
+        if (!pending) {
+            pending = speak(mathml, math, language);
+            speech.set(key, pending);
+        }
+        void pending.then((label) => {
+            if (stopped || !label || !container.isConnected)
+                return;
+            if (container.getAttribute("aria-label") !== label) {
+                container.setAttribute("aria-label", label);
+            }
+        });
+    };
+    // A shadow root is a tree of its own, which an observer on `root` does not
+    // see into, so each one found is observed as well. One attached after its
+    // host was visited is not found until something is added around the host.
+    const observed = new WeakSet();
+    const observeTree = (tree) => {
+        if (observed.has(tree))
+            return;
+        observed.add(tree);
+        observer.observe(tree, { childList: true, subtree: true });
+    };
+    const visit = (node) => {
+        if (node.nodeType !== 1)
+            return;
+        const element = node;
+        const container = flatTreeClosest(element, "mjx-container");
+        if (container) {
+            name(container);
+            return;
+        }
+        if (element.shadowRoot)
+            observeTree(element.shadowRoot);
+        walkFlatTree(element, (descendant) => {
+            if (descendant.nodeType !== 1)
+                return "skip";
+            const found = descendant;
+            if (found.localName === "mjx-container") {
+                name(found);
+                return "skip";
+            }
+            if (found.shadowRoot)
+                observeTree(found.shadowRoot);
+            return undefined;
+        });
+    };
+    const observer = new MutationObserver((records) => {
+        for (const record of records) {
+            for (const node of record.addedNodes)
+                visit(node);
+        }
+    });
+    observeTree(root);
+    visit(root);
+    return () => {
+        stopped = true;
+        observer.disconnect();
+    };
+}

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

@@ -14,7 +14,7 @@ export interface ResolveMathSpeechOptions {
     mathSpeech?: SREMathSpeechOptions;
     /**
      * Also produce SRE's SSML rendering (markup: "ssml") for the equation, for
-     * the runtime generated-SSML path (PIE-623). Only populated when the input
+     * the runtime generated-SSML path. Only populated when the input
      * is a single math chunk and SRE succeeds. The plain `speechText` is always
      * computed with markup: "none" so the plain path is unaffected.
      */
@@ -43,6 +43,17 @@ export interface ResolvedMathSpeech {
      */
     ssml?: string;
 }
+/**
+ * Loads the speech-rule-engine once per page. A failed load is dropped, so the
+ * next call tries again; meanwhile math reads as its visible text. The first
+ * failure warns, later ones log at debug.
+ */
+export declare const createSreLoader: (importEngine: () => Promise<SpeechRuleEngineApi>) => ((engineOptions?: Record<string, unknown>) => Promise<SpeechRuleEngineApi>);
+/**
+ * One speech-rule-engine load for a whole read: its equations share the
+ * attempt, so a failed load costs a read one attempt.
+ */
+export declare const createReadSreLoad: (mathSpeech?: SREMathSpeechOptions) => (() => Promise<SpeechRuleEngineApi>);
 export declare const normalizeSREMathSpeechOptions: (options: unknown) => SREMathSpeechOptions | undefined;
 export declare const resolveMathSpeechFromChunks: (chunks: MathAwareSpeechChunk[], options?: ResolveMathSpeechOptions) => Promise<ResolvedMathSpeech>;
 export {};