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

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

@@ -1,19 +1,56 @@
+import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { setSreStartupLocaleSource, sreLocaleSource } from "./sre-locales.js";
 import { normalizeTextForSpeech } from "./text-processing.js";
-let sreLoadPromise = null;
+// Debug lines need PIE_TTS_DEBUG=1 or globalThis.__PIE_TTS_DEBUG__ = true.
+const logger = createPieLogger("tts-math-speech", isTtsDebugEnabled);
+// SRE configures one global engine, so each setupEngine + toSpeech pair runs to
+// completion before the next starts; concurrent reads would otherwise speak
+// under each other's settings.
 let sreOperationQueue = Promise.resolve();
 const normalizeLocale = (language) => (language || "en").split("-")[0].toLowerCase() || "en";
-const defaultLoadSre = async (engineOptions) => {
-    if (!sreLoadPromise) {
-        setSreStartupLocaleSource(engineOptions);
-        sreLoadPromise = import("./sre-engine.js").then(({ default: candidate }) => {
-            if (!candidate || typeof candidate.toSpeech !== "function") {
-                throw new Error("speech-rule-engine did not expose toSpeech");
-            }
-            return candidate;
-        });
+/**
+ * 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 const createSreLoader = (importEngine) => {
+    let load = null;
+    let warned = false;
+    return (engineOptions) => {
+        if (!load) {
+            setSreStartupLocaleSource(engineOptions);
+            const attempt = importEngine();
+            load = attempt;
+            attempt.catch((error) => {
+                if (load === attempt)
+                    load = null;
+                if (warned) {
+                    logger.debug("speech-rule-engine failed to load again", error);
+                    return;
+                }
+                warned = true;
+                logger.warn("speech-rule-engine failed to load; math reads as its visible text until a later read loads it.", error);
+            });
+        }
+        return load;
+    };
+};
+const defaultLoadSre = createSreLoader(() => import("./sre-engine.js").then(({ default: candidate }) => {
+    if (!candidate || typeof candidate.toSpeech !== "function") {
+        throw new Error("speech-rule-engine did not expose toSpeech");
     }
-    return sreLoadPromise;
+    return candidate;
+}));
+/**
+ * One speech-rule-engine load for a whole read: its equations share the
+ * attempt, so a failed load costs a read one attempt.
+ */
+export const createReadSreLoad = (mathSpeech) => {
+    let attempt = null;
+    return () => {
+        attempt ??= defaultLoadSre(normalizeSREMathSpeechOptions(mathSpeech)?.engineOptions);
+        return attempt;
+    };
 };
 // SRE's ClearSpeak rule set is English-only; MathSpeak is localized to many more
 // locales. Use ClearSpeak for English (highest-quality math prose) and MathSpeak
@@ -47,9 +84,9 @@ const setupSre = async (sre, language, markup, mathSpeech) => {
         ...engineOptions,
         locale,
         domain: normalizedMathSpeech?.domain || domainForLocale(locale),
-        ...(normalizedMathSpeech?.style
-            ? { style: normalizedMathSpeech.style }
-            : {}),
+        // SRE keeps a style it was given until it is given another, so a call
+        // without one resets it: math control names set ClearSpeak preferences.
+        style: normalizedMathSpeech?.style || "default",
         modality: "speech",
         markup,
     });
@@ -80,7 +117,7 @@ const generateMathSsml = async (sre, mathml, language, mathSpeech) => {
         return ssml.includes("<speak") ? ssml : null;
     }
     catch (error) {
-        console.debug("[TTSService] Math SSML generation failed; using plain", {
+        logger.debug("math SSML generation failed; using plain", {
             message: error instanceof Error ? error.message : String(error),
         });
         return null;
@@ -99,8 +136,7 @@ export const resolveMathSpeechFromChunks = async (chunks, options = {}) => {
     let sre = null;
     let usedMathSpeech = false;
     let usedFallback = false;
-    const loadSre = options.loadSre ||
-        (() => defaultLoadSre(normalizeSREMathSpeechOptions(options.mathSpeech)?.engineOptions));
+    const loadSre = options.loadSre || createReadSreLoad(options.mathSpeech);
     const speechParts = [];
     for (const chunk of chunks) {
         if (chunk.type === "text") {
@@ -122,7 +158,7 @@ export const resolveMathSpeechFromChunks = async (chunks, options = {}) => {
         }
         catch (error) {
             usedFallback = true;
-            console.debug("[TTSService] Math speech generation failed; using visible fallback", {
+            logger.debug("math speech generation failed; using visible fallback", {
                 message: error instanceof Error ? error.message : String(error),
             });
             speechParts.push(chunk.fallbackText);

package/dist/services/tts/mathml-sanitization.d.ts

@@ -1 +1,8 @@
+/**
+ * MathML re-serialized from an allow-list, with a MathML xmlns on the root.
+ * Null for empty or unparseable input, no DOMParser, a non-<math> root, a
+ * disallowed element or a node other than element/text/comment, or an xmlns
+ * other than MathML's. Comments, attributes off the allow-list and values
+ * containing javascript: or data:text/html are dropped.
+ */
 export declare const canonicalizeMathML: (input: string) => string | null;

package/dist/services/tts/mathml-sanitization.js

@@ -1,4 +1,5 @@
 const MATHML_NAMESPACE = "http://www.w3.org/1998/Math/MathML";
+const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
 const ALLOWED_MATHML_ELEMENTS = new Set([
     "math",
     "maction",
@@ -109,7 +110,7 @@ const isAllowedMathElement = (element) => {
     const namespace = element.namespaceURI;
     return (!namespace ||
         namespace === MATHML_NAMESPACE ||
-        namespace === "http://www.w3.org/1999/xhtml");
+        namespace === XHTML_NAMESPACE);
 };
 const serializeMathNode = (node) => {
     if (node.nodeType === Node.TEXT_NODE) {
@@ -153,6 +154,13 @@ const parseMathML = (input) => {
     }
     return null;
 };
+/**
+ * MathML re-serialized from an allow-list, with a MathML xmlns on the root.
+ * Null for empty or unparseable input, no DOMParser, a non-<math> root, a
+ * disallowed element or a node other than element/text/comment, or an xmlns
+ * other than MathML's. Comments, attributes off the allow-list and values
+ * containing javascript: or data:text/html are dropped.
+ */
 export const canonicalizeMathML = (input) => {
     const trimmed = String(input || "").trim();
     if (!trimmed)

package/dist/services/tts/provider-options.d.ts

@@ -0,0 +1,52 @@
+import type { TTSConfig, TTSProviderOptions } from "@pie-players/pie-tts";
+import type { SREMathSpeechOptions } from "./math-speech.js";
+import type { BoundarySpacingMode } from "./text-processing.js";
+/**
+ * The provider options the toolkit reads, on top of the ones every provider
+ * receives. Hosts configure them as free-form options, so readers still check
+ * each value at runtime.
+ */
+export interface ToolkitTTSProviderOptions extends TTSProviderOptions {
+    /**
+     * Highlight words or sentences while reading. Defaults by provider
+     * capability. A playback that sends no word boundaries highlights its
+     * sentence in either mode.
+     */
+    highlightMode?: "word" | "sentence";
+    /** Locale for text processing; the toolkit sets it per speak. */
+    locale?: string;
+    /** Speech-rule-engine options for math speech. */
+    mathSpeech?: SREMathSpeechOptions;
+    /** Sentence and word segmentation of the browser provider. */
+    segmenter?: {
+        /** `regexOnly` segments without `Intl.Segmenter`. */
+        mode?: "regexOnly";
+        locale?: string;
+    };
+    /** Pauses at structural boundaries: `baseMs` scaled by a strength unit, clamped. */
+    structuralPauses?: {
+        baseMs?: number | string;
+        units?: {
+            minor?: number | string;
+            section?: number | string;
+            major?: number | string;
+        };
+        minMs?: number | string;
+        maxMs?: number | string;
+    };
+    textNormalization?: {
+        boundarySpacingMode?: BoundarySpacingMode;
+        locale?: string;
+    };
+}
+/** A provider configuration as the toolkit reads it. */
+export interface ToolkitTTSConfig extends TTSConfig {
+    providerOptions?: ToolkitTTSProviderOptions;
+    /**
+     * Highlight math token by token; `false` highlights each formula as one
+     * block. The highlight pipeline reads it, and providers ignore it.
+     *
+     * @default true
+     */
+    mathTokenHighlighting?: boolean;
+}

package/dist/services/tts/provider-options.js

@@ -0,0 +1 @@
+export {};

package/dist/services/tts/ssml/spoken-text.d.ts

@@ -1,29 +1,5 @@
-/**
- * Shared SSML → spoken-text extractor.
- *
- * Strips SSML markup to the words a TTS engine would actually voice, while
- * recording a `rawToSpokenOffsetMap` from raw-SSML character offsets to
- * normalized spoken-text offsets. This is the single source of truth for SSML
- * stripping used by:
- *   - the catalog span aligner (`catalog-span-alignment.ts`),
- *   - the math speech tokenizer (`math-alignment/speech-tokenizer.ts`),
- *   - the runtime generated-speech path (PIE-623).
- *
- * Keeping one implementation guarantees provider word-boundary offsets (which
- * are into the raw SSML string) map to the same spoken text on every path.
- *
- * Tag handling:
- *   - Structural tags (`speak`, `p`, `s`, `emphasis`, `prosody`, `say-as`,
- *     `voice`, `lang`) are transparent; their text content flows through.
- *     `p`/`s` open tags inject a word boundary space.
- *   - `break` injects a space (a pause is a word boundary).
- *   - `sub alias="…"` substitutes the alias text (and skips the original).
- *     `sub` with no alias marks the content unsupported for word tracking.
- *   - Semantic tags that change *what* is spoken without leaving trackable
- *     text (`audio`, `phoneme`) mark the content unsupported.
- *   - Any other unknown element marks the content unsupported (degrade to
- *     coarse region highlighting rather than mis-track).
- */
+/** Whether `text` is an SSML document: it opens with a `<speak>` element. */
+export declare const isSsmlDocument: (text: string) => boolean;
 export interface ExtractedSpokenText {
     spokenText: string;
     rawToSpokenOffsetMap: Map<number, number>;

package/dist/services/tts/ssml/spoken-text.js

@@ -1,4 +1,33 @@
 import { normalizeTextForSpeech } from "../text-processing.js";
+/**
+ * Shared SSML → spoken-text extractor.
+ *
+ * Strips SSML markup to the words a TTS engine would actually voice, while
+ * recording a `rawToSpokenOffsetMap` from raw-SSML character offsets to
+ * normalized spoken-text offsets. This is the single source of truth for SSML
+ * stripping used by:
+ *   - the catalog span aligner (`catalog-span-alignment.ts`),
+ *   - the math speech tokenizer (`math-alignment/speech-tokenizer.ts`),
+ *   - the runtime generated-speech path.
+ *
+ * Keeping one implementation guarantees provider word-boundary offsets (which
+ * are into the raw SSML string) map to the same spoken text on every path.
+ *
+ * Tag handling:
+ *   - Structural tags (`speak`, `p`, `s`, `emphasis`, `prosody`, `say-as`,
+ *     `voice`, `lang`) are transparent; their text content flows through.
+ *     `p`/`s` open tags inject a word boundary space.
+ *   - `break` injects a space (a pause is a word boundary).
+ *   - `sub alias="…"` substitutes the alias text (and skips the original).
+ *     `sub` with no alias marks the content unsupported for word tracking.
+ *   - Semantic tags that change *what* is spoken without leaving trackable
+ *     text (`audio`, `phoneme`) mark the content unsupported.
+ *   - Any other unknown element marks the content unsupported (degrade to
+ *     coarse region highlighting rather than mis-track).
+ */
+const SSML_DOCUMENT = /^\s*<speak[\s/>]/i;
+/** Whether `text` is an SSML document: it opens with a `<speak>` element. */
+export const isSsmlDocument = (text) => SSML_DOCUMENT.test(text);
 const STRUCTURAL_SSML_TAGS = new Set([
     "speak",
     "p",

package/dist/services/tts/start-failure.d.ts

@@ -0,0 +1,4 @@
+/** Whether a speak rejected because speech could not start. */
+export declare function isTTSStartFailure(error: unknown): boolean;
+/** Marks `cause` as a start failure, keeping its message and stack. */
+export declare function toTTSStartFailure(cause: unknown): Error;

package/dist/services/tts/start-failure.js

@@ -0,0 +1,19 @@
+/**
+ * The `code` a speak's rejection carries when speech could not start, as
+ * distinct from a failure while speaking. Read by shape: several copies of the
+ * toolkit can share a page, so an error class from one fails `instanceof` in
+ * another.
+ */
+const TTS_START_FAILED_CODE = "tts-start-failed";
+/** Whether a speak rejected because speech could not start. */
+export function isTTSStartFailure(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.code === TTS_START_FAILED_CODE);
+}
+/** Marks `cause` as a start failure, keeping its message and stack. */
+export function toTTSStartFailure(cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    error.code = TTS_START_FAILED_CODE;
+    return error;
+}

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

@@ -62,6 +62,15 @@ export declare const collectRangeTextForSpeech: (range: Range, root: Element) =>
     text: string;
     filtered: boolean;
 };
+/** The part of `textNode`'s text that `range` holds, for a node it intersects. */
+export declare const textInRange: (textNode: Text, range: Range) => string;
+/**
+ * Whether `range` holds all of `element`'s speakable text: its first and last
+ * speakable characters, which a contiguous range holding both holds everything
+ * between. An element with no speakable text, an image for one, is held when the
+ * range touches it, since no part of it can be selected alone.
+ */
+export declare const rangeHoldsSpeakableElement: (range: Range, element: Element, root?: Element | null) => boolean;
 export declare const shouldInsertWordBoundarySpace: (previousChar: string | null, nextChar: string | null, options?: TextProcessingOptions) => boolean;
 export declare const collectVisibleTextAndMap: (element: Element, options?: TextProcessingOptions) => {
     text: string;

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

@@ -1,3 +1,4 @@
+import { flatTreeParentElement, flatTreeTextNodes, rangeHoldsTextPosition, rangeIntersectsComposedNode, } from "./flat-tree.js";
 export const normalizeTextForSpeech = (text) => text.trim().replace(/\s+/g, " ");
 // Single source of truth for aligning spoken text to visible / math text.
 // Letters are matched with `\p{L}` so the tokenizer is Unicode-aware — accented
@@ -50,15 +51,15 @@ export const isElementHiddenForTTS = (element) => {
     return false;
 };
 export const isNodeHiddenForTTS = (node, root) => {
-    let current = node.nodeType === 1
-        ? node
-        : node.parentElement;
+    // Up the flat tree, so a node in a shadow root inherits its host's
+    // visibility and a slotted node the visibility of the slot rendering it.
+    let current = node.nodeType === 1 ? node : flatTreeParentElement(node);
     while (current) {
         if (isElementHiddenForTTS(current))
             return true;
         if (root && current === root)
             break;
-        current = current.parentElement;
+        current = flatTreeParentElement(current);
     }
     return false;
 };
@@ -112,15 +113,14 @@ export const isElementSuppressedForTTS = (element) => {
     return true;
 };
 export const isNodeSuppressedForTTS = (node, root) => {
-    let current = node.nodeType === 1
-        ? node
-        : node.parentElement;
+    // Through shadow hosts as well: suppression on a host covers its shadow tree.
+    let current = node.nodeType === 1 ? node : flatTreeParentElement(node);
     while (current) {
         if (isElementSuppressedForTTS(current))
             return true;
         if (root && current === root)
             break;
-        current = current.parentElement;
+        current = flatTreeParentElement(current);
     }
     return false;
 };
@@ -146,11 +146,7 @@ export const isNodeExcludedFromSpeech = (node, root) => isNodeHiddenForTTS(node,
  * nothing".
  */
 export const collectRangeTextForSpeech = (range, root) => {
-    if (typeof document === "undefined" ||
-        typeof document.createTreeWalker !==
-            "function" ||
-        typeof NodeFilter === "undefined" ||
-        typeof range.intersectsNode !== "function") {
+    if (typeof range.intersectsNode !== "function") {
         // Degraded, and deliberately not silent about the difference: callers still
         // enforce whole-selection suppression from the range's common ancestor, so
         // the construct guard holds even here. What is lost is per-node filtering
@@ -159,25 +155,49 @@ export const collectRangeTextForSpeech = (range, root) => {
     }
     const parts = [];
     let filtered = false;
-    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
-    let current = walker.nextNode();
-    while (current) {
-        const textNode = current;
-        if (range.intersectsNode(textNode)) {
+    for (const textNode of flatTreeTextNodes(root)) {
+        if (rangeIntersectsComposedNode(range, textNode)) {
             if (isNodeExcludedFromSpeech(textNode, root)) {
                 filtered = true;
             }
             else {
-                const raw = textNode.textContent || "";
-                const start = textNode === range.startContainer ? range.startOffset : 0;
-                const end = textNode === range.endContainer ? range.endOffset : raw.length;
-                parts.push(raw.slice(start, end));
+                parts.push(textInRange(textNode, range));
             }
         }
-        current = walker.nextNode();
     }
     return { text: parts.join(""), filtered };
 };
+/** The part of `textNode`'s text that `range` holds, for a node it intersects. */
+export const textInRange = (textNode, range) => {
+    const raw = textNode.textContent || "";
+    const start = textNode === range.startContainer ? range.startOffset : 0;
+    const end = textNode === range.endContainer ? range.endOffset : raw.length;
+    return raw.slice(start, end);
+};
+/**
+ * Whether `range` holds all of `element`'s speakable text: its first and last
+ * speakable characters, which a contiguous range holding both holds everything
+ * between. An element with no speakable text, an image for one, is held when the
+ * range touches it, since no part of it can be selected alone.
+ */
+export const rangeHoldsSpeakableElement = (range, element, root) => {
+    let first = null;
+    let last = null;
+    for (const textNode of flatTreeTextNodes(element)) {
+        if (isNodeExcludedFromSpeech(textNode, root))
+            continue;
+        const raw = textNode.textContent || "";
+        const firstOffset = raw.search(/\S/);
+        if (firstOffset === -1)
+            continue;
+        first ??= { node: textNode, offset: firstOffset };
+        last = { node: textNode, offset: raw.trimEnd().length - 1 };
+    }
+    if (!first || !last)
+        return rangeIntersectsComposedNode(range, element);
+    return (rangeHoldsTextPosition(range, first.node, first.offset) &&
+        rangeHoldsTextPosition(range, last.node, last.offset));
+};
 export const shouldInsertWordBoundarySpace = (previousChar, nextChar, options) => {
     if (!previousChar || !nextChar)
         return false;
@@ -210,10 +230,7 @@ export const shouldInsertWordBoundarySpace = (previousChar, nextChar, options) =
 };
 export const collectVisibleTextAndMap = (element, options) => {
     const map = new Map();
-    if (typeof document === "undefined" ||
-        typeof document.createTreeWalker !==
-            "function" ||
-        typeof NodeFilter === "undefined") {
+    if (typeof document === "undefined") {
         return { text: "", map };
     }
     const outChars = [];
@@ -222,11 +239,8 @@ export const collectVisibleTextAndMap = (element, options) => {
     let lastCharWasWhitespace = false;
     let lastMapped = null;
     let previousVisibleChar = null;
-    const walker = document.createTreeWalker(element, NodeFilter.SHOW_TEXT);
-    let current = walker.nextNode();
-    while (current) {
-        const textNode = current;
-        const parent = textNode.parentElement;
+    for (const textNode of flatTreeTextNodes(element)) {
+        const parent = flatTreeParentElement(textNode);
         if (parent && !isNodeExcludedFromSpeech(textNode, element)) {
             const raw = textNode.textContent || "";
             const firstVisibleMatch = raw.match(/\S/);
@@ -274,7 +288,6 @@ export const collectVisibleTextAndMap = (element, options) => {
                 }
             }
         }
-        current = walker.nextNode();
     }
     const text = outChars.join("").trimEnd();
     while (map.has(text.length)) {

package/dist/services/tts/text-segmentation.d.ts

@@ -6,4 +6,16 @@ export interface SentenceSegmentationOptions {
     locale?: string;
     useSentenceSegmenter?: boolean;
 }
+/**
+ * `text` split into sentences at their offsets in it, by Intl.Segmenter unless
+ * the policy disables it or it is missing. The segmenter path drops
+ * whitespace-only segments; the regex fallback keeps every match.
+ */
 export declare const segmentSentences: (text: string, options?: SentenceSegmentationOptions) => SentenceSegment[];
+/**
+ * `text` in pieces of at most `maxLength` characters: whole sentences while they
+ * fit, a sentence too long for one piece cut at its last space that fits, and a
+ * word too long for one piece cut where the limit falls. Each piece is a trimmed
+ * substring of `text`, at its offset there.
+ */
+export declare const splitTextToLength: (text: string, maxLength: number, options?: SentenceSegmentationOptions) => SentenceSegment[];

package/dist/services/tts/text-segmentation.js

@@ -1,11 +1,14 @@
+/**
+ * `text` split into sentences at their offsets in it, by Intl.Segmenter unless
+ * the policy disables it or it is missing. The segmenter path drops
+ * whitespace-only segments; the regex fallback keeps every match.
+ */
 export const segmentSentences = (text, options) => {
-    const useSentenceSegmenter = options?.useSentenceSegmenter !== false;
-    try {
-        if (!useSentenceSegmenter) {
-            throw new Error("Segmenter disabled by policy");
-        }
-        const Segmenter = globalThis.Intl?.Segmenter;
-        if (typeof Segmenter === "function") {
+    const Segmenter = options?.useSentenceSegmenter === false
+        ? undefined
+        : globalThis.Intl?.Segmenter;
+    if (typeof Segmenter === "function") {
+        try {
             const segmenter = new Segmenter(options?.locale, {
                 granularity: "sentence",
             });
@@ -18,9 +21,9 @@ export const segmentSentences = (text, options) => {
             if (parsed.length > 0)
                 return parsed;
         }
-    }
-    catch {
-        // Fall through to regex segmentation.
+        catch {
+            // Fall through to regex segmentation.
+        }
     }
     const sentenceRegex = /[^.!?]+(?:[.!?]+|$)/g;
     const raw = text.match(sentenceRegex) || [text];
@@ -35,3 +38,50 @@ export const segmentSentences = (text, options) => {
     }
     return parsed.length > 0 ? parsed : [{ text, offset: 0 }];
 };
+/**
+ * `text` in pieces of at most `maxLength` characters: whole sentences while they
+ * fit, a sentence too long for one piece cut at its last space that fits, and a
+ * word too long for one piece cut where the limit falls. Each piece is a trimmed
+ * substring of `text`, at its offset there.
+ */
+export const splitTextToLength = (text, maxLength, options) => {
+    const limit = Math.max(1, Math.floor(maxLength));
+    const pieces = [];
+    let start = -1;
+    let end = -1;
+    const flush = () => {
+        if (start >= 0)
+            pieces.push({ text: text.slice(start, end), offset: start });
+        start = -1;
+    };
+    const append = (spanStart, spanEnd) => {
+        if (start >= 0 && spanEnd - start <= limit) {
+            end = spanEnd;
+            return;
+        }
+        flush();
+        let cursor = spanStart;
+        while (spanEnd - cursor > limit) {
+            const window = text.slice(cursor, cursor + limit + 1);
+            const space = window.search(/\s\S*$/);
+            const cut = space > 0 ? cursor + space : cursor + limit;
+            pieces.push({ text: text.slice(cursor, cut).trimEnd(), offset: cursor });
+            cursor = cut;
+            while (cursor < spanEnd && /\s/.test(text[cursor]))
+                cursor++;
+        }
+        if (cursor < spanEnd) {
+            start = cursor;
+            end = spanEnd;
+        }
+    };
+    for (const sentence of segmentSentences(text, options)) {
+        const leading = sentence.text.search(/\S/);
+        if (leading === -1)
+            continue;
+        const spanStart = sentence.offset + leading;
+        append(spanStart, sentence.offset + sentence.text.trimEnd().length);
+    }
+    flush();
+    return pieces;
+};