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

package/dist/services/tools-config-normalizer.js

@@ -1,12 +1,10 @@
 import { DEFAULT_TOOL_PLACEMENT } from "./tool-config-defaults.js";
+import { isPlainRecord } from "@pie-players/pie-players-shared/object";
 const DEFAULT_PLACEMENT = {
     section: [...DEFAULT_TOOL_PLACEMENT.section],
     item: [...DEFAULT_TOOL_PLACEMENT.item],
     passage: [...DEFAULT_TOOL_PLACEMENT.passage],
 };
-function isPlainObject(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function assertStringArray(value, fieldPath) {
     if (value == null)
         return [];
@@ -22,7 +20,7 @@ function assertStringArray(value, fieldPath) {
 function assertPlacementConfig(value) {
     if (value == null)
         return undefined;
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error('Invalid tools config at "placement": expected an object with section/item/passage arrays.');
     }
     return value;
@@ -30,7 +28,7 @@ function assertPlacementConfig(value) {
 function assertPolicyConfig(value) {
     if (value == null)
         return undefined;
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error('Invalid tools config at "policy": expected an object with allowed/blocked arrays.');
     }
     return value;
@@ -38,7 +36,7 @@ function assertPolicyConfig(value) {
 function assertProviderConfig(providerId, value) {
     if (value == null)
         return undefined;
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error(`Invalid tools config at "providers.${providerId}": expected an object.`);
     }
     const config = value;
@@ -49,12 +47,12 @@ function assertProviderConfig(providerId, value) {
     }
     if ("settings" in config &&
         config.settings !== undefined &&
-        !isPlainObject(config.settings)) {
+        !isPlainRecord(config.settings)) {
         throw new Error(`Invalid tools config at "providers.${providerId}.settings": expected an object.`);
     }
     if ("provider" in config &&
         config.provider !== undefined &&
-        !isPlainObject(config.provider)) {
+        !isPlainRecord(config.provider)) {
         throw new Error(`Invalid tools config at "providers.${providerId}.provider": expected an object.`);
     }
     return config;
@@ -62,7 +60,7 @@ function assertProviderConfig(providerId, value) {
 function assertProvidersConfig(value) {
     if (value == null)
         return {};
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         throw new Error('Invalid tools config at "providers": expected an object keyed by tool id.');
     }
     const normalized = {};
@@ -71,6 +69,10 @@ function assertProvidersConfig(value) {
     }
     return normalized;
 }
+/**
+ * Tool ids trimmed, with empty ones dropped and duplicates removed in
+ * first-seen order. Throws on a non-string entry.
+ */
 export function normalizeToolList(toolIds) {
     if (!toolIds || toolIds.length === 0)
         return [];
@@ -101,8 +103,18 @@ function assertPnpEnforcement(value, fieldPath) {
         return value;
     throw new Error(`Invalid tools config at "${fieldPath}": expected "on" or "off", got ${JSON.stringify(value)}.`);
 }
+/** A placement level's tool ids, or the level's default when it names none. */
+function normalizePlacementLevel(placement, level) {
+    const toolIds = normalizeToolList(assertStringArray(placement?.[level], `placement.${level}`));
+    return toolIds.length ? toolIds : [...DEFAULT_PLACEMENT[level]];
+}
+/**
+ * Check a host's tools config shape, throwing at the first malformed field, and
+ * return it canonical: tool lists trimmed and deduplicated, and every placement
+ * level that names no tool filled with its default.
+ */
 export function normalizeToolsConfig(input) {
-    if (input != null && !isPlainObject(input)) {
+    if (input != null && !isPlainRecord(input)) {
         throw new Error('Invalid tools config: expected an object with "policy", "placement", and "providers".');
     }
     const policy = assertPolicyConfig(input?.policy);
@@ -115,15 +127,9 @@ export function normalizeToolsConfig(input) {
             blocked: normalizeToolList(assertStringArray(policy?.blocked, "policy.blocked")),
         },
         placement: {
-            section: normalizeToolList(assertStringArray(placement?.section, "placement.section")).length
-                ? normalizeToolList(assertStringArray(placement?.section, "placement.section"))
-                : [...DEFAULT_PLACEMENT.section],
-            item: normalizeToolList(assertStringArray(placement?.item, "placement.item")).length
-                ? normalizeToolList(assertStringArray(placement?.item, "placement.item"))
-                : [...DEFAULT_PLACEMENT.item],
-            passage: normalizeToolList(assertStringArray(placement?.passage, "placement.passage")).length
-                ? normalizeToolList(assertStringArray(placement?.passage, "placement.passage"))
-                : [...DEFAULT_PLACEMENT.passage],
+            section: normalizePlacementLevel(placement, "section"),
+            item: normalizePlacementLevel(placement, "item"),
+            passage: normalizePlacementLevel(placement, "passage"),
         },
         providers,
     };

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

@@ -3,16 +3,15 @@
  *
  * Text-to-speech provider using the browser's Web Speech API.
  * Works in all modern browsers that support SpeechSynthesis.
- *
- * Part of PIE Assessment Toolkit.
  */
 import type { ITTSProvider, ITTSProviderImplementation, TTSConfig, TTSProviderCapabilities } from "@pie-players/pie-tts";
+import type { ToolkitTTSConfig } from "./provider-options.js";
 /**
  * The part of another provider's configuration that keeps its meaning on
  * browser speech. Every path that replaces a provider with browser speech
  * starts it with this.
  */
-export declare const browserFallbackConfig: (config: Partial<TTSConfig>) => Partial<TTSConfig>;
+export declare const browserFallbackConfig: (config: Partial<ToolkitTTSConfig>) => Partial<ToolkitTTSConfig>;
 /**
  * The voice traits browser voice selection reads. A `SpeechSynthesisVoice` has
  * them all; a host's own voice list may carry a subset.
@@ -51,8 +50,6 @@ export declare const waitForBrowserVoices: (synth: SpeechSynthesis, timeoutMs: n
  */
 export declare class BrowserTTSProvider implements ITTSProvider {
     readonly providerId = "browser";
-    readonly providerName = "Browser Speech Synthesis";
-    readonly version = "1.0.0";
     initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
     getCapabilities(): TTSProviderCapabilities;
     destroy(): void;

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

@@ -3,8 +3,6 @@
  *
  * Text-to-speech provider using the browser's Web Speech API.
  * Works in all modern browsers that support SpeechSynthesis.
- *
- * Part of PIE Assessment Toolkit.
  */
 import { createPieLogger, isTtsDebugEnabled, } from "@pie-players/pie-players-shared/pie";
 import { extractSpokenText, isSsmlDocument } from "./ssml/spoken-text.js";
@@ -12,6 +10,9 @@ import { segmentSentences as segmentTextToSentences } from "./text-segmentation.
 const logger = createPieLogger("browser-tts-provider", isTtsDebugEnabled);
 const NATIVE_START_TIMEOUT_MS = 5_000;
 const VOICE_INVENTORY_TIMEOUT_MS = 2_000;
+const MAX_CHUNK_LENGTH = 260;
+// A longer reported word length falls back to the inferred one.
+const MAX_TRUSTED_REPORTED_WORD_LENGTH = 80;
 // The provider options the toolkit and this provider read. Every other option,
 // and `voice`, belongs to the provider it was configured for: a Polly voice such
 // as "Joanna" resolves to no browser voice, and an unresolved voice fails speak.
@@ -36,6 +37,8 @@ export const browserFallbackConfig = (config) => {
         fallback.rate = config.rate;
     if (config.pitch !== undefined)
         fallback.pitch = config.pitch;
+    if (config.volume !== undefined)
+        fallback.volume = config.volume;
     if (config.mathTokenHighlighting !== undefined) {
         fallback.mathTokenHighlighting = config.mathTokenHighlighting;
     }
@@ -192,14 +195,11 @@ const shouldAssignBrowserVoice = (voice) => !voice.default;
  */
 export class BrowserTTSProvider {
     providerId = "browser";
-    providerName = "Browser Speech Synthesis";
-    version = "1.0.0";
     async initialize(config) {
         // SSR guard
         if (typeof window === "undefined") {
             throw new Error("BrowserTTSProvider requires browser environment");
         }
-        // Check browser support
         if (!("speechSynthesis" in window)) {
             throw new Error("Browser does not support Speech Synthesis API");
         }
@@ -212,14 +212,9 @@ export class BrowserTTSProvider {
     }
     getCapabilities() {
         return {
-            supportsPause: true,
-            supportsResume: true,
             supportsWordBoundary: true,
             // Boundary events depend on the voice: several network voices send none.
             defaultHighlightMode: "sentence",
-            supportsVoiceSelection: true,
-            supportsRateControl: true,
-            supportsPitchControl: true,
             // The Web Speech API voices plain text only; SSML tags are read aloud.
             supportsSSML: false,
         };
@@ -351,7 +346,6 @@ class BrowserTTSProviderImpl {
         return runId === this.speakRunId;
     }
     splitIntoChunks(text) {
-        const MAX_CHUNK_LENGTH = 260;
         if (text.length <= MAX_CHUNK_LENGTH) {
             return [{ text, offset: 0 }];
         }
@@ -408,7 +402,6 @@ class BrowserTTSProviderImpl {
                 : undefined;
         return {
             useSentenceSegmenter: useSegmenter,
-            useWordSegmenter: useSegmenter,
             locale,
         };
     }
@@ -446,8 +439,10 @@ class BrowserTTSProviderImpl {
                 utterance.voice = voice;
             if (this.config?.rate)
                 utterance.rate = this.config.rate;
-            if (this.config?.pitch)
+            if (this.config?.pitch !== undefined)
                 utterance.pitch = this.config.pitch;
+            if (this.config?.volume !== undefined)
+                utterance.volume = this.config.volume;
             let didStart = false;
             let settled = false;
             let startTimeout = null;
@@ -558,7 +553,7 @@ class BrowserTTSProviderImpl {
                 const inferredLength = this.inferWordLength(chunkText, charIndex);
                 const wordLength = Number.isFinite(reportedLength) &&
                     reportedLength > 0 &&
-                    reportedLength <= 80 &&
+                    reportedLength <= MAX_TRUSTED_REPORTED_WORD_LENGTH &&
                     charIndex + reportedLength <= chunkText.length
                     ? reportedLength
                     : inferredLength;
@@ -624,27 +619,23 @@ class BrowserTTSProviderImpl {
         this._isPaused = false;
         this.releaseHold();
     }
-    isPlaying() {
-        return this._isPlaying && !this._isPaused;
-    }
-    isPaused() {
-        return this._isPaused;
-    }
     /**
-     * Update settings dynamically (rate, pitch, voice)
+     * Update settings dynamically (rate, pitch, volume, voice)
      * Changes take effect on the next speak() call
      */
     updateSettings(settings) {
         if (!this.config) {
             this.config = {};
         }
-        // Update config with new settings
         if (settings.rate !== undefined) {
             this.config.rate = settings.rate;
         }
         if (settings.pitch !== undefined) {
             this.config.pitch = settings.pitch;
         }
+        if (settings.volume !== undefined) {
+            this.config.volume = settings.volume;
+        }
         if (settings.voice !== undefined) {
             this.config.voice = settings.voice;
         }

package/dist/services/tts/catalog-span-alignment.js

@@ -1,5 +1,9 @@
 import { tokenizeAlignmentText, tokenizeSpeechSource, } from "./math-alignment/speech-tokenizer.js";
 import { normalizeTextForSpeech } from "./text-processing.js";
+// A spoken token equal to a visible token; phrase targets score below it.
+const EXACT_TOKEN_SCORE = 10;
+// Below this, an anchored chunk highlights its region instead of spans.
+const MIN_ANCHOR_SPAN_CONFIDENCE = 0.12;
 // LIMITATION (i18n): the phrase table is English, so multi-word operator
 // phrases ("plus or minus", "divided by") only align for English speech; other
 // locales degrade to coarse region highlighting.
@@ -29,7 +33,7 @@ const createCandidates = (spokenTokens, visibleTokens) => {
                     spokenStartToken: spokenIndex,
                     spokenEndToken: spokenIndex + 1,
                     visibleToken: visibleIndex,
-                    score: 10,
+                    score: EXACT_TOKEN_SCORE,
                 });
             }
         }
@@ -57,6 +61,9 @@ const createCandidates = (spokenTokens, visibleTokens) => {
     }
     return candidates;
 };
+// The highest-scoring chain of candidates monotonic in both spoken and visible
+// order (O(n²) DP). A gap whose spoken and visible token counts differ by more
+// than 2 pays the excess.
 const computeAnchors = (spokenTokens, visibleTokens) => {
     const candidates = createCandidates(spokenTokens, visibleTokens).sort((left, right) => spokenTokens[left.spokenStartToken].start -
         spokenTokens[right.spokenStartToken].start ||
@@ -116,7 +123,7 @@ const scoreConfidence = (anchors, spokenTokens, visibleTokens) => {
         Math.max(1, Math.min(spokenTokens.length, visibleTokens.length));
     const averageScore = anchors.reduce((total, anchor) => total + anchor.score, 0) /
         anchors.length /
-        10;
+        EXACT_TOKEN_SCORE;
     return Math.min(1, tokenCoverage * averageScore);
 };
 export const createCatalogSpanAlignment = (args) => {
@@ -130,17 +137,17 @@ export const createCatalogSpanAlignment = (args) => {
     const confidence = scoreConfidence(anchors, spokenTokens, visibleTokens);
     const isExact = speech.spokenText === visibleText && speech.spokenText.length > 0;
     const hasShortSingleExactAnchor = anchors.length === 1 &&
-        anchors[0].score === 10 &&
+        anchors[0].score === EXACT_TOKEN_SCORE &&
         spokenTokens.length <= 2 &&
         visibleTokens.length <= 2;
+    const anchorsAreTrusted = (anchors.length >= 2 || hasShortSingleExactAnchor) &&
+        confidence >= MIN_ANCHOR_SPAN_CONFIDENCE;
     const playbackMode = speech.unsupportedSemantic
         ? "region-fallback"
         : isExact
             ? "exact-word"
-            : anchors.length >= 2 || hasShortSingleExactAnchor
-                ? confidence >= 0.12
-                    ? "anchor-span"
-                    : "region-fallback"
+            : anchorsAreTrusted
+                ? "anchor-span"
                 : "region-fallback";
     return {
         speech,

package/dist/services/tts/flat-tree.d.ts

@@ -17,8 +17,6 @@
  * global, at import or at call time.
  */
 export declare const isShadowRootNode: (node: Node | null | undefined) => node is ShadowRoot;
-/** Toolbars, tool elements and debug panels: chrome around content, never content. */
-export declare const isToolkitChromeElement: (element: Element) => boolean;
 /** `node`'s children in the flat tree, with skipped elements left out. */
 export declare const flatTreeChildNodes: (node: Node) => Node[];
 /**
@@ -35,11 +33,6 @@ export declare const flatTextContent: (root: Node) => string;
 /** Elements under `root` matching `selector`, in rendering order. */
 export declare const flatQuerySelectorAll: (root: Node, selector: string) => Element[];
 export declare const flatQuerySelector: (root: Node, selector: string) => Element | null;
-/**
- * `node`'s parent in the flat tree: the slot rendering it, else its parent, with
- * a shadow root standing for its host.
- */
-export declare const flatTreeParentNode: (node: Node) => Node | null;
 export declare const flatTreeParentElement: (node: Node) => Element | null;
 /** The nearest element at or above `node` in the flat tree that matches `selector`. */
 export declare const flatTreeClosest: (node: Node, selector: string) => Element | null;

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

@@ -35,7 +35,7 @@ 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 isToolkitChromeElement = (element) => {
     const tag = element.localName?.toLowerCase() || "";
     if (CHROME_TAGS.has(tag))
         return true;
@@ -143,7 +143,7 @@ export const flatQuerySelector = (root, selector) => {
  * `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 flatTreeParentNode = (node) => {
     const slot = node.assignedSlot;
     if (slot)
         return slot;

package/dist/services/tts/generated-speech/dom/to-chunk-inputs.d.ts

@@ -3,8 +3,8 @@ import type { DomAnchor, GeneratedSpeechChunk } from "./types.js";
 export interface PlanToChunksOptions {
     /**
      * Playback format:
-     *   - "plain" (default): plain spoken text for every chunk (Phase A, the
-     *     stable generated-speech behavior).
+     *   - "plain" (default): plain spoken text for every chunk (the stable
+     *     generated-speech behavior).
      *   - "ssml": math chunks with SRE SSML send that SSML to the provider (with
      *     a plain fallback attached); prose chunks always stay plain.
      */

package/dist/services/tts/generated-speech/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Generated-speech module (PIE-623): runtime speech composition for math items
+ * Generated-speech module: runtime speech composition for math items
  * that ship without authored SSML / `accessibilityCatalogs`.
  *
  * Layering:

package/dist/services/tts/generated-speech/index.js

@@ -1,5 +1,5 @@
 /**
- * Generated-speech module (PIE-623): runtime speech composition for math items
+ * Generated-speech module: runtime speech composition for math items
  * that ship without authored SSML / `accessibilityCatalogs`.
  *
  * Layering:

package/dist/services/tts/generated-speech/types.d.ts

@@ -2,7 +2,7 @@
  * Generated-speech plan model (PURE core).
  *
  * This module is the speech-composition core for items that contain math but
- * ship without authored SSML / `accessibilityCatalogs` (PIE-623). It is
+ * ship without authored SSML / `accessibilityCatalogs`. It is
  * deliberately free of any imports from `TTSService`, the highlight renderer,
  * `HighlightCoordinator`, Svelte, or custom-element entrypoints
  * (`scripts/check-speech-composition-purity.mjs` enforces this). DOM primitive

package/dist/services/tts/generated-speech/types.js

@@ -2,7 +2,7 @@
  * Generated-speech plan model (PURE core).
  *
  * This module is the speech-composition core for items that contain math but
- * ship without authored SSML / `accessibilityCatalogs` (PIE-623). It is
+ * ship without authored SSML / `accessibilityCatalogs`. It is
  * deliberately free of any imports from `TTSService`, the highlight renderer,
  * `HighlightCoordinator`, Svelte, or custom-element entrypoints
  * (`scripts/check-speech-composition-purity.mjs` enforces this). DOM primitive

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

@@ -67,11 +67,10 @@ const TEXT_NODE = 3;
 // the last token — painting it would be a likely false positive, and "false
 // positives are worse than coarse highlighting." A single-text-node prose range
 // is kept: it underlines one token cleanly and usefully fills in any token the
-// math resolver missed. (The highlight coordinator no longer escalates word
-// ranges to the whole <math> / <mjx-container>, so this is now a precision
-// policy rather than flash-suppression — see HighlightCoordinator
-// WORD_FALLBACK_SELECTOR.)
-const wouldEscalateInsideTokenMath = (planned, target, candidates) => {
+// math resolver missed. The word layer never escalates a range to the enclosing
+// <math>/<mjx-container> (HighlightCoordinator WORD_FALLBACK_SELECTOR), so this
+// is a precision policy.
+const isMultiNodeRangeInsideTokenMath = (planned, target, candidates) => {
     if (!target || target.type !== "range")
         return false;
     const { startContainer, endContainer } = target.range;
@@ -128,8 +127,7 @@ export const createTTSHighlightPlan = (args) => {
             const planned = plannedChunksById.get(chunkId);
             if (!planned)
                 return missingChunkDecision();
-            const alignments = planned.chunk.mathAlignments;
-            const soleElement = alignments.length === 1 ? alignments[0].element : null;
+            const soleElement = soleEquationElement(planned.chunk.mathAlignments);
             const capability = soleElement
                 ? planned.mathCapabilityByElement.get(soleElement)
                 : null;
@@ -164,9 +162,9 @@ export const createTTSHighlightPlan = (args) => {
             const normalized = normalizeBoundaryEvent(chunk, event);
             const proseTarget = resolveProseBoundaryTarget(chunk, normalized);
             const mathCandidates = mathCandidatesForTarget(proseTarget, chunk);
-            const resolvedMathTarget = (!proseTarget || mathCandidates.length > 0
+            const resolvedMathTarget = !proseTarget || mathCandidates.length > 0
                 ? resolveMathBoundaryTarget(chunk, normalized, event, mathCandidates, planned.renderedMathTargetResolver)
-                : null) || null;
+                : null;
             const mathTarget = resolvedMathTarget?.quality === "semantic-token"
                 ? resolvedMathTarget
                 : (renderHiddenProseTarget(planned, proseTarget) ??
@@ -195,15 +193,15 @@ export const createTTSHighlightPlan = (args) => {
             }
             // (2) A spoken word that maps to visible prose. The prose anchor is
             // precise; a coarse math expression fallback must never override it.
-            // Exception: a multi-node prose range inside a token-mode equation
-            // would escalate to the whole expression, so it is rejected here and
+            // Exception: a multi-node prose range inside a token-mode equation is
+            // an untrustworthy glyph-level match, so it is rejected here and
             // falls through to the token hold below. When per-token math
             // highlighting is disabled, any prose range that lands inside a
             // formula is likewise rejected so the formula stays a single block.
             if (proseTarget &&
                 !isHiddenRange(proseTarget) &&
                 (mathTokenHighlighting
-                    ? !wouldEscalateInsideTokenMath(planned, proseTarget, mathCandidates)
+                    ? !isMultiNodeRangeInsideTokenMath(planned, proseTarget, mathCandidates)
                     : mathCandidates.length === 0)) {
                 return createHighlightDecision({
                     semanticTarget: proseTarget,

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.js

@@ -74,18 +74,16 @@ const TEXT_CHUNK_SOURCE_ROLES = new Set([
 ]);
 const resolveTextChunkSourceElement = (textNode, root) => {
     let current = flatTreeParentElement(textNode);
-    let best = null;
     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 = flatTreeParentElement(current);
     }
-    return best || root;
+    return root;
 };
 const hasMathCandidate = (element) => Boolean(typeof element.querySelector === "function" &&
     flatQuerySelector(element, "math, [data-mathml], .MathJax, mjx-container, mjx-assistive-mml")) ||
@@ -158,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)
@@ -173,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) => {
@@ -376,9 +360,6 @@ const collectMathAware = (root, options, range) => {
     trimTrailingWhitespace(acc);
     flushTextChunk();
     const visibleText = acc.chars.join("");
-    while (acc.map.has(visibleText.length)) {
-        acc.map.delete(visibleText.length);
-    }
     return {
         visibleText,
         map: acc.map,

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.
      */

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

@@ -3,6 +3,9 @@ import { setSreStartupLocaleSource, sreLocaleSource } from "./sre-locales.js";
 import { normalizeTextForSpeech } from "./text-processing.js";
 // 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";
 /**

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)