@pie-players/pie-assessment-toolkit 0.3.44 → 0.3.45

package/dist/services/tts/highlight-pipeline/boundary-normalizer.js

@@ -0,0 +1,106 @@
+import { resolveSpokenBoundaryOffset } from "../catalog-span-alignment.js";
+import { resolveBoundaryToSpeechToken, tokenizeSpeechSource, } from "../math-alignment/speech-tokenizer.js";
+const normalizeBoundaryWord = (word) => {
+    if (!word || /^<[^>]+>$/.test(word.trim()))
+        return null;
+    return (tokenizeSpeechSource({ speechText: word }).tokens[0]?.normalized || null);
+};
+// Resolve a provider boundary for a chunk that carries no catalog span
+// alignment — notably the generated-SSML math path, whose `speechText` is a
+// raw `<speak>` document. The provider's offset is an index into `speechText`
+// exactly as it was sent (which may include SSML tags), so we tokenize that
+// same string and let the shared speech tokenizer translate the offset into the
+// extracted spoken text. Returns the boundary in spoken-text space alongside
+// that spoken text, so the downstream word/offset checks share one coordinate
+// system. The previous "direct" path treated the raw-SSML offset as a
+// spoken-text offset and rejected every math boundary (PIE-623 regression).
+const speechSourceBoundary = (chunk, event) => {
+    const tokenization = tokenizeSpeechSource({ speechText: chunk.speechText });
+    if (!Number.isFinite(event.position)) {
+        return { boundary: null, spokenText: tokenization.spokenText };
+    }
+    const resolved = resolveBoundaryToSpeechToken({
+        tokenization,
+        position: event.position,
+        length: event.length,
+        boundaryWord: event.word,
+    });
+    return {
+        boundary: resolved
+            ? { start: resolved.start, length: resolved.length }
+            : null,
+        spokenText: tokenization.spokenText,
+    };
+};
+const tokenAtOffsetMatches = (speechText, start, normalizedWord) => {
+    if (!normalizedWord)
+        return true;
+    const token = tokenizeSpeechSource({ speechText }).tokens.find((candidate) => candidate.start <= start && start < candidate.end);
+    return token?.normalized === normalizedWord;
+};
+export const normalizeBoundaryEvent = (chunk, event) => {
+    const normalizedWord = normalizeBoundaryWord(event.word);
+    if (chunk.id !== event.chunkId) {
+        return {
+            chunkId: event.chunkId,
+            normalizedWord,
+            chunkSpokenStart: null,
+            chunkSpokenEnd: null,
+            confidence: 0,
+            reason: "boundary chunk id did not match highlight chunk",
+        };
+    }
+    if (event.providerOffsetSpace === "unknown" ||
+        chunk.offsetSpace === "unsupported") {
+        return {
+            chunkId: chunk.id,
+            normalizedWord,
+            chunkSpokenStart: null,
+            chunkSpokenEnd: null,
+            confidence: 0,
+            reason: "boundary offset space is unsupported",
+        };
+    }
+    let boundary;
+    let spokenText;
+    if (chunk.catalogAlignment) {
+        boundary = resolveSpokenBoundaryOffset(chunk.catalogAlignment, event.position, event.length, event.word);
+        spokenText = chunk.catalogAlignment.spokenText;
+    }
+    else {
+        const resolved = speechSourceBoundary(chunk, event);
+        boundary = resolved.boundary;
+        spokenText = resolved.spokenText;
+    }
+    if (!boundary) {
+        return {
+            chunkId: chunk.id,
+            normalizedWord,
+            chunkSpokenStart: null,
+            chunkSpokenEnd: null,
+            confidence: 0,
+            reason: "could not resolve provider boundary to chunk speech",
+        };
+    }
+    if (!tokenAtOffsetMatches(spokenText, boundary.start, normalizedWord)) {
+        return {
+            chunkId: chunk.id,
+            normalizedWord,
+            chunkSpokenStart: null,
+            chunkSpokenEnd: null,
+            confidence: 0,
+            reason: "could not resolve provider boundary to matching word",
+        };
+    }
+    return {
+        chunkId: chunk.id,
+        normalizedWord,
+        chunkSpokenStart: boundary.start,
+        chunkSpokenEnd: boundary.start + boundary.length,
+        confidence: normalizedWord ? 1 : 0.75,
+        reason: chunk.catalogAlignment
+            ? "resolved through catalog alignment"
+            : "resolved through speech tokenization",
+    };
+};
+//# sourceMappingURL=boundary-normalizer.js.map

package/dist/services/tts/highlight-pipeline/boundary-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-normalizer.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/boundary-normalizer.ts"],"names":[],"mappings":"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","sourcesContent":["import { resolveSpokenBoundaryOffset } from \"../catalog-span-alignment.js\";\nimport {\n\tresolveBoundaryToSpeechToken,\n\ttokenizeSpeechSource,\n} from \"../math-alignment/speech-tokenizer.js\";\nimport type {\n\tNormalizedBoundaryEvent,\n\tTTSBoundaryEvent,\n\tTTSHighlightChunk,\n} from \"./types.js\";\n\nconst normalizeBoundaryWord = (word: string): string | null => {\n\tif (!word || /^<[^>]+>$/.test(word.trim())) return null;\n\treturn (\n\t\ttokenizeSpeechSource({ speechText: word }).tokens[0]?.normalized || null\n\t);\n};\n\n// Resolve a provider boundary for a chunk that carries no catalog span\n// alignment — notably the generated-SSML math path, whose `speechText` is a\n// raw `<speak>` document. The provider's offset is an index into `speechText`\n// exactly as it was sent (which may include SSML tags), so we tokenize that\n// same string and let the shared speech tokenizer translate the offset into the\n// extracted spoken text. Returns the boundary in spoken-text space alongside\n// that spoken text, so the downstream word/offset checks share one coordinate\n// system. The previous \"direct\" path treated the raw-SSML offset as a\n// spoken-text offset and rejected every math boundary (PIE-623 regression).\nconst speechSourceBoundary = (\n\tchunk: TTSHighlightChunk,\n\tevent: TTSBoundaryEvent,\n): { boundary: { start: number; length: number } | null; spokenText: string } => {\n\tconst tokenization = tokenizeSpeechSource({ speechText: chunk.speechText });\n\tif (!Number.isFinite(event.position)) {\n\t\treturn { boundary: null, spokenText: tokenization.spokenText };\n\t}\n\tconst resolved = resolveBoundaryToSpeechToken({\n\t\ttokenization,\n\t\tposition: event.position,\n\t\tlength: event.length,\n\t\tboundaryWord: event.word,\n\t});\n\treturn {\n\t\tboundary: resolved\n\t\t\t? { start: resolved.start, length: resolved.length }\n\t\t\t: null,\n\t\tspokenText: tokenization.spokenText,\n\t};\n};\n\nconst tokenAtOffsetMatches = (\n\tspeechText: string,\n\tstart: number,\n\tnormalizedWord: string | null,\n): boolean => {\n\tif (!normalizedWord) return true;\n\tconst token = tokenizeSpeechSource({ speechText }).tokens.find(\n\t\t(candidate) => candidate.start <= start && start < candidate.end,\n\t);\n\treturn token?.normalized === normalizedWord;\n};\n\nexport const normalizeBoundaryEvent = (\n\tchunk: TTSHighlightChunk,\n\tevent: TTSBoundaryEvent,\n): NormalizedBoundaryEvent => {\n\tconst normalizedWord = normalizeBoundaryWord(event.word);\n\tif (chunk.id !== event.chunkId) {\n\t\treturn {\n\t\t\tchunkId: event.chunkId,\n\t\t\tnormalizedWord,\n\t\t\tchunkSpokenStart: null,\n\t\t\tchunkSpokenEnd: null,\n\t\t\tconfidence: 0,\n\t\t\treason: \"boundary chunk id did not match highlight chunk\",\n\t\t};\n\t}\n\tif (\n\t\tevent.providerOffsetSpace === \"unknown\" ||\n\t\tchunk.offsetSpace === \"unsupported\"\n\t) {\n\t\treturn {\n\t\t\tchunkId: chunk.id,\n\t\t\tnormalizedWord,\n\t\t\tchunkSpokenStart: null,\n\t\t\tchunkSpokenEnd: null,\n\t\t\tconfidence: 0,\n\t\t\treason: \"boundary offset space is unsupported\",\n\t\t};\n\t}\n\tlet boundary: { start: number; length: number } | null;\n\tlet spokenText: string;\n\tif (chunk.catalogAlignment) {\n\t\tboundary = resolveSpokenBoundaryOffset(\n\t\t\tchunk.catalogAlignment,\n\t\t\tevent.position,\n\t\t\tevent.length,\n\t\t\tevent.word,\n\t\t);\n\t\tspokenText = chunk.catalogAlignment.spokenText;\n\t} else {\n\t\tconst resolved = speechSourceBoundary(chunk, event);\n\t\tboundary = resolved.boundary;\n\t\tspokenText = resolved.spokenText;\n\t}\n\tif (!boundary) {\n\t\treturn {\n\t\t\tchunkId: chunk.id,\n\t\t\tnormalizedWord,\n\t\t\tchunkSpokenStart: null,\n\t\t\tchunkSpokenEnd: null,\n\t\t\tconfidence: 0,\n\t\t\treason: \"could not resolve provider boundary to chunk speech\",\n\t\t};\n\t}\n\tif (!tokenAtOffsetMatches(spokenText, boundary.start, normalizedWord)) {\n\t\treturn {\n\t\t\tchunkId: chunk.id,\n\t\t\tnormalizedWord,\n\t\t\tchunkSpokenStart: null,\n\t\t\tchunkSpokenEnd: null,\n\t\t\tconfidence: 0,\n\t\t\treason: \"could not resolve provider boundary to matching word\",\n\t\t};\n\t}\n\treturn {\n\t\tchunkId: chunk.id,\n\t\tnormalizedWord,\n\t\tchunkSpokenStart: boundary.start,\n\t\tchunkSpokenEnd: boundary.start + boundary.length,\n\t\tconfidence: normalizedWord ? 1 : 0.75,\n\t\treason: chunk.catalogAlignment\n\t\t\t? \"resolved through catalog alignment\"\n\t\t\t: \"resolved through speech tokenization\",\n\t};\n};\n"]}

package/dist/services/tts/highlight-pipeline/create-highlight-plan.d.ts

@@ -0,0 +1,6 @@
+import type { TTSHighlightChunk, TTSHighlightPlan } from "./types.js";
+export interface CreateTTSHighlightPlanArgs {
+    chunks: TTSHighlightChunk[];
+    mathTokenHighlighting?: boolean;
+}
+export declare const createTTSHighlightPlan: (args: CreateTTSHighlightPlanArgs) => TTSHighlightPlan;

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

@@ -0,0 +1,217 @@
+import { normalizeBoundaryEvent } from "./boundary-normalizer.js";
+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";
+const regionTargetFor = (chunk) => chunk.regionRange
+    ? {
+        type: "range",
+        quality: "region",
+        range: chunk.regionRange,
+    }
+    : chunk.regionElement
+        ? {
+            type: "element",
+            quality: "region",
+            element: chunk.regionElement,
+        }
+        : null;
+const expressionTargetFor = (planned, candidates = planned.chunk
+    .mathAlignments) => {
+    if (candidates.length !== 1)
+        return null;
+    const fallback = candidates[0]?.alignment.result.fallbackTarget;
+    return fallback ? planned.renderedMathTargetResolver(fallback) : null;
+};
+const mathCandidatesForTarget = (target, chunk) => {
+    if (!target)
+        return chunk.mathAlignments;
+    return chunk.mathAlignments.filter(({ element }) => {
+        try {
+            if (target.type === "range")
+                return target.range.intersectsNode(element);
+            if (target.type === "element") {
+                return target.element === element || target.element.contains(element);
+            }
+            return target.node.parentElement?.contains(element) || false;
+        }
+        catch {
+            return false;
+        }
+    });
+};
+const missingChunkDecision = () => ({
+    activeTarget: null,
+    regionTarget: null,
+    quality: "region",
+    confidence: 0,
+    reason: "boundary chunk id was not found",
+});
+const soleEquationElement = (candidates) => (candidates.length === 1 ? candidates[0].element : null);
+const everyCandidateIsTokenMode = (planned, candidates) => candidates.length > 0 &&
+    candidates.every(({ element }) => planned.mathCapabilityByElement.get(element) === "token");
+const TEXT_NODE = 3;
+// Safety policy for token-mode equations. A prose "range" target comes from the
+// catalog span aligner, whose spoken→visible mapping inside an equation is
+// heuristic and not trustworthy at glyph granularity. A multi-node range fully
+// inside a token-mode equation is therefore rejected here in favor of holding
+// 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) => {
+    if (!target || target.type !== "range")
+        return false;
+    const { startContainer, endContainer } = target.range;
+    const singleTextNode = startContainer === endContainer && startContainer.nodeType === TEXT_NODE;
+    if (singleTextNode)
+        return false;
+    return candidates.some(({ element }) => planned.mathCapabilityByElement.get(element) === "token" &&
+        element.contains(startContainer) &&
+        element.contains(endContainer));
+};
+const createPlannedChunk = (chunk, mathTokenHighlighting) => ({
+    chunk,
+    regionTarget: regionTargetFor(chunk),
+    renderedMathTargetResolver: createRenderedMathTargetResolver(),
+    mathCapabilityByElement: new Map(chunk.mathAlignments.map(({ element }) => [
+        element,
+        // Forcing "expression" when per-token math highlighting is disabled
+        // routes every equation through the sticky whole-block path, so the
+        // formula is highlighted as one unit instead of glyph by glyph.
+        mathTokenHighlighting
+            ? classifyMathHighlightCapability(element)
+            : "expression",
+    ])),
+    heldTokenByElement: new Map(),
+});
+export const createTTSHighlightPlan = (args) => {
+    const mathTokenHighlighting = args.mathTokenHighlighting !== false;
+    const plannedChunksById = new Map(args.chunks.map((chunk) => [
+        chunk.id,
+        createPlannedChunk(chunk, mathTokenHighlighting),
+    ]));
+    return {
+        chunks: args.chunks,
+        resolveInitial(chunkId) {
+            const planned = plannedChunksById.get(chunkId);
+            if (!planned)
+                return missingChunkDecision();
+            const alignments = planned.chunk.mathAlignments;
+            const soleElement = alignments.length === 1 ? alignments[0].element : null;
+            const capability = soleElement
+                ? planned.mathCapabilityByElement.get(soleElement)
+                : null;
+            // Sticky mode. Only an equation we already know cannot be tracked per
+            // token gets the whole-expression paint up front. A token-mode equation
+            // stays on the region layer until its first token resolves, so the full
+            // equation never flashes before (or between) tokens.
+            if (capability === "expression") {
+                return createHighlightDecision({
+                    semanticTarget: null,
+                    expressionTarget: expressionTargetFor(planned),
+                    regionTarget: planned.regionTarget,
+                    confidence: 0.5,
+                    reason: "initial expression (sticky expression mode)",
+                });
+            }
+            return createHighlightDecision({
+                semanticTarget: null,
+                expressionTarget: null,
+                regionTarget: planned.regionTarget,
+                confidence: 0,
+                reason: capability === "token"
+                    ? "initial region (sticky token mode, awaiting first token)"
+                    : "initial region fallback",
+            });
+        },
+        resolveBoundary(event) {
+            const planned = plannedChunksById.get(event.chunkId);
+            if (!planned)
+                return missingChunkDecision();
+            const { chunk } = planned;
+            const normalized = normalizeBoundaryEvent(chunk, event);
+            const proseTarget = resolveProseBoundaryTarget(chunk, normalized);
+            const mathCandidates = mathCandidatesForTarget(proseTarget, chunk);
+            const mathTarget = (!proseTarget || mathCandidates.length > 0
+                ? resolveMathBoundaryTarget(chunk, normalized, event, mathCandidates, planned.renderedMathTargetResolver)
+                : null) || null;
+            const mathTokenTarget = mathTokenHighlighting &&
+                mathTarget &&
+                mathTarget.quality !== "expression"
+                ? mathTarget
+                : null;
+            const mathExpressionFallback = mathTarget && mathTarget.quality === "expression" ? mathTarget : null;
+            // (1) A precise token always wins, and becomes the held target for its
+            // equation so a later gap can keep it lit instead of flashing the whole
+            // expression.
+            if (mathTokenTarget) {
+                const equationElement = soleEquationElement(mathCandidates);
+                if (equationElement) {
+                    planned.heldTokenByElement.set(equationElement, mathTokenTarget);
+                }
+                return createHighlightDecision({
+                    semanticTarget: mathTokenTarget,
+                    expressionTarget: null,
+                    regionTarget: planned.regionTarget,
+                    confidence: normalized.confidence,
+                    reason: normalized.reason,
+                });
+            }
+            // (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
+            // 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 &&
+                (mathTokenHighlighting
+                    ? !wouldEscalateInsideTokenMath(planned, proseTarget, mathCandidates)
+                    : mathCandidates.length === 0)) {
+                return createHighlightDecision({
+                    semanticTarget: proseTarget,
+                    expressionTarget: null,
+                    regionTarget: planned.regionTarget,
+                    confidence: normalized.confidence,
+                    reason: normalized.reason,
+                });
+            }
+            // (3) A boundary inside a token-mode equation that did not map to a
+            // token — an SSML break, a pause, or a gap between spoken tokens. Hold
+            // the last token instead of flashing the whole expression; before the
+            // first token there is nothing to hold, so fall to the region layer.
+            // The whole expression is deliberately never painted in token mode.
+            if (everyCandidateIsTokenMode(planned, mathCandidates)) {
+                const equationElement = soleEquationElement(mathCandidates);
+                const heldToken = equationElement
+                    ? (planned.heldTokenByElement.get(equationElement) ?? null)
+                    : null;
+                return createHighlightDecision({
+                    semanticTarget: heldToken,
+                    expressionTarget: null,
+                    regionTarget: planned.regionTarget,
+                    confidence: normalized.confidence,
+                    reason: heldToken
+                        ? "hold last token (sticky token mode)"
+                        : "region (sticky token mode, awaiting first token)",
+                });
+            }
+            // (4) An expression-mode (or mixed/ambiguous) math region: paint the
+            // whole equation. Stable for the equation's full duration because
+            // tokens never resolve here, so there is no flicker.
+            return createHighlightDecision({
+                semanticTarget: null,
+                expressionTarget: mathExpressionFallback ??
+                    expressionTargetFor(planned, mathCandidates),
+                regionTarget: planned.regionTarget,
+                confidence: normalized.confidence,
+                reason: normalized.reason,
+            });
+        },
+    };
+};
+//# sourceMappingURL=create-highlight-plan.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-highlight-plan.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/create-highlight-plan.ts"],"names":[],"mappings":"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","sourcesContent":["import { normalizeBoundaryEvent } from \"./boundary-normalizer.js\";\nimport { createHighlightDecision } from \"./highlight-policy.js\";\nimport { resolveMathBoundaryTarget } from \"./math-semantic-resolver.js\";\nimport { resolveProseBoundaryTarget } from \"./prose-boundary-resolver.js\";\nimport {\n\tclassifyMathHighlightCapability,\n\tcreateRenderedMathTargetResolver,\n\ttype MathHighlightCapability,\n\ttype RenderedMathTargetResolver,\n} from \"./rendered-math-target-resolver.js\";\nimport type {\n\tHighlightDecision,\n\tRenderableHighlightTarget,\n\tTTSBoundaryEvent,\n\tTTSHighlightChunk,\n\tTTSHighlightPlan,\n} from \"./types.js\";\n\nexport interface CreateTTSHighlightPlanArgs {\n\tchunks: TTSHighlightChunk[];\n\t// When false, math is never broken into per-token highlights: every equation\n\t// is painted as a single block — the same expression/region fallback used\n\t// whenever token alignment is not confident. Prose word tracking is\n\t// unaffected. Defaults to true.\n\tmathTokenHighlighting?: boolean;\n}\n\ninterface PlannedChunk {\n\tchunk: TTSHighlightChunk;\n\tregionTarget: RenderableHighlightTarget | null;\n\trenderedMathTargetResolver: RenderedMathTargetResolver;\n\t// Capability decided once per equation (keyed by its source math element).\n\t// Sticky for the whole chunk so the same equation never switches between\n\t// token tracking and whole-expression highlighting mid-read.\n\tmathCapabilityByElement: Map<Element, MathHighlightCapability>;\n\t// The last precise token painted for each token-mode equation. Lets a gap\n\t// (SSML break / pause / unmappable boundary) hold the last token instead of\n\t// flashing the whole expression.\n\theldTokenByElement: Map<Element, RenderableHighlightTarget>;\n}\n\nconst regionTargetFor = (\n\tchunk: TTSHighlightChunk,\n): RenderableHighlightTarget | null =>\n\tchunk.regionRange\n\t\t? {\n\t\t\t\ttype: \"range\",\n\t\t\t\tquality: \"region\",\n\t\t\t\trange: chunk.regionRange,\n\t\t\t}\n\t\t: chunk.regionElement\n\t\t\t? {\n\t\t\t\t\ttype: \"element\",\n\t\t\t\t\tquality: \"region\",\n\t\t\t\t\telement: chunk.regionElement,\n\t\t\t\t}\n\t\t\t: null;\n\nconst expressionTargetFor = (\n\tplanned: PlannedChunk,\n\tcandidates: TTSHighlightChunk[\"mathAlignments\"] = planned.chunk\n\t\t.mathAlignments,\n): RenderableHighlightTarget | null => {\n\tif (candidates.length !== 1) return null;\n\tconst fallback = candidates[0]?.alignment.result.fallbackTarget;\n\treturn fallback ? planned.renderedMathTargetResolver(fallback) : null;\n};\n\nconst mathCandidatesForTarget = (\n\ttarget: RenderableHighlightTarget | null,\n\tchunk: TTSHighlightChunk,\n): TTSHighlightChunk[\"mathAlignments\"] => {\n\tif (!target) return chunk.mathAlignments;\n\treturn chunk.mathAlignments.filter(({ element }) => {\n\t\ttry {\n\t\t\tif (target.type === \"range\") return target.range.intersectsNode(element);\n\t\t\tif (target.type === \"element\") {\n\t\t\t\treturn target.element === element || target.element.contains(element);\n\t\t\t}\n\t\t\treturn target.node.parentElement?.contains(element) || false;\n\t\t} catch {\n\t\t\treturn false;\n\t\t}\n\t});\n};\n\nconst missingChunkDecision = (): HighlightDecision => ({\n\tactiveTarget: null,\n\tregionTarget: null,\n\tquality: \"region\",\n\tconfidence: 0,\n\treason: \"boundary chunk id was not found\",\n});\n\nconst soleEquationElement = (\n\tcandidates: TTSHighlightChunk[\"mathAlignments\"],\n): Element | null => (candidates.length === 1 ? candidates[0].element : null);\n\nconst everyCandidateIsTokenMode = (\n\tplanned: PlannedChunk,\n\tcandidates: TTSHighlightChunk[\"mathAlignments\"],\n): boolean =>\n\tcandidates.length > 0 &&\n\tcandidates.every(\n\t\t({ element }) => planned.mathCapabilityByElement.get(element) === \"token\",\n\t);\n\nconst TEXT_NODE = 3;\n\n// Safety policy for token-mode equations. A prose \"range\" target comes from the\n// catalog span aligner, whose spoken→visible mapping inside an equation is\n// heuristic and not trustworthy at glyph granularity. A multi-node range fully\n// inside a token-mode equation is therefore rejected here in favor of holding\n// the last token — painting it would be a likely false positive, and \"false\n// positives are worse than coarse highlighting.\" A single-text-node prose range\n// is kept: it underlines one token cleanly and usefully fills in any token the\n// math resolver missed. (The highlight coordinator no longer escalates word\n// ranges to the whole <math> / <mjx-container>, so this is now a precision\n// policy rather than flash-suppression — see HighlightCoordinator\n// WORD_FALLBACK_SELECTOR.)\nconst wouldEscalateInsideTokenMath = (\n\tplanned: PlannedChunk,\n\ttarget: RenderableHighlightTarget | null,\n\tcandidates: TTSHighlightChunk[\"mathAlignments\"],\n): boolean => {\n\tif (!target || target.type !== \"range\") return false;\n\tconst { startContainer, endContainer } = target.range;\n\tconst singleTextNode =\n\t\tstartContainer === endContainer && startContainer.nodeType === TEXT_NODE;\n\tif (singleTextNode) return false;\n\treturn candidates.some(\n\t\t({ element }) =>\n\t\t\tplanned.mathCapabilityByElement.get(element) === \"token\" &&\n\t\t\telement.contains(startContainer) &&\n\t\t\telement.contains(endContainer),\n\t);\n};\n\nconst createPlannedChunk = (\n\tchunk: TTSHighlightChunk,\n\tmathTokenHighlighting: boolean,\n): PlannedChunk => ({\n\tchunk,\n\tregionTarget: regionTargetFor(chunk),\n\trenderedMathTargetResolver: createRenderedMathTargetResolver(),\n\tmathCapabilityByElement: new Map(\n\t\tchunk.mathAlignments.map(({ element }) => [\n\t\t\telement,\n\t\t\t// Forcing \"expression\" when per-token math highlighting is disabled\n\t\t\t// routes every equation through the sticky whole-block path, so the\n\t\t\t// formula is highlighted as one unit instead of glyph by glyph.\n\t\t\tmathTokenHighlighting\n\t\t\t\t? classifyMathHighlightCapability(element)\n\t\t\t\t: \"expression\",\n\t\t]),\n\t),\n\theldTokenByElement: new Map(),\n});\n\nexport const createTTSHighlightPlan = (\n\targs: CreateTTSHighlightPlanArgs,\n): TTSHighlightPlan => {\n\tconst mathTokenHighlighting = args.mathTokenHighlighting !== false;\n\tconst plannedChunksById = new Map(\n\t\targs.chunks.map((chunk) => [\n\t\t\tchunk.id,\n\t\t\tcreatePlannedChunk(chunk, mathTokenHighlighting),\n\t\t]),\n\t);\n\treturn {\n\t\tchunks: args.chunks,\n\t\tresolveInitial(chunkId: string): HighlightDecision {\n\t\t\tconst planned = plannedChunksById.get(chunkId);\n\t\t\tif (!planned) return missingChunkDecision();\n\t\t\tconst alignments = planned.chunk.mathAlignments;\n\t\t\tconst soleElement = alignments.length === 1 ? alignments[0].element : null;\n\t\t\tconst capability = soleElement\n\t\t\t\t? planned.mathCapabilityByElement.get(soleElement)\n\t\t\t\t: null;\n\t\t\t// Sticky mode. Only an equation we already know cannot be tracked per\n\t\t\t// token gets the whole-expression paint up front. A token-mode equation\n\t\t\t// stays on the region layer until its first token resolves, so the full\n\t\t\t// equation never flashes before (or between) tokens.\n\t\t\tif (capability === \"expression\") {\n\t\t\t\treturn createHighlightDecision({\n\t\t\t\t\tsemanticTarget: null,\n\t\t\t\t\texpressionTarget: expressionTargetFor(planned),\n\t\t\t\t\tregionTarget: planned.regionTarget,\n\t\t\t\t\tconfidence: 0.5,\n\t\t\t\t\treason: \"initial expression (sticky expression mode)\",\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn createHighlightDecision({\n\t\t\t\tsemanticTarget: null,\n\t\t\t\texpressionTarget: null,\n\t\t\t\tregionTarget: planned.regionTarget,\n\t\t\t\tconfidence: 0,\n\t\t\t\treason:\n\t\t\t\t\tcapability === \"token\"\n\t\t\t\t\t\t? \"initial region (sticky token mode, awaiting first token)\"\n\t\t\t\t\t\t: \"initial region fallback\",\n\t\t\t});\n\t\t},\n\t\tresolveBoundary(event: TTSBoundaryEvent): HighlightDecision {\n\t\t\tconst planned = plannedChunksById.get(event.chunkId);\n\t\t\tif (!planned) return missingChunkDecision();\n\t\t\tconst { chunk } = planned;\n\t\t\tconst normalized = normalizeBoundaryEvent(chunk, event);\n\t\t\tconst proseTarget = resolveProseBoundaryTarget(chunk, normalized);\n\t\t\tconst mathCandidates = mathCandidatesForTarget(proseTarget, chunk);\n\t\t\tconst mathTarget =\n\t\t\t\t(!proseTarget || mathCandidates.length > 0\n\t\t\t\t\t? resolveMathBoundaryTarget(\n\t\t\t\t\t\t\tchunk,\n\t\t\t\t\t\t\tnormalized,\n\t\t\t\t\t\t\tevent,\n\t\t\t\t\t\t\tmathCandidates,\n\t\t\t\t\t\t\tplanned.renderedMathTargetResolver,\n\t\t\t\t\t\t)\n\t\t\t\t\t: null) || null;\n\t\t\tconst mathTokenTarget =\n\t\t\t\tmathTokenHighlighting &&\n\t\t\t\tmathTarget &&\n\t\t\t\tmathTarget.quality !== \"expression\"\n\t\t\t\t\t? mathTarget\n\t\t\t\t\t: null;\n\t\t\tconst mathExpressionFallback =\n\t\t\t\tmathTarget && mathTarget.quality === \"expression\" ? mathTarget : null;\n\n\t\t\t// (1) A precise token always wins, and becomes the held target for its\n\t\t\t// equation so a later gap can keep it lit instead of flashing the whole\n\t\t\t// expression.\n\t\t\tif (mathTokenTarget) {\n\t\t\t\tconst equationElement = soleEquationElement(mathCandidates);\n\t\t\t\tif (equationElement) {\n\t\t\t\t\tplanned.heldTokenByElement.set(equationElement, mathTokenTarget);\n\t\t\t\t}\n\t\t\t\treturn createHighlightDecision({\n\t\t\t\t\tsemanticTarget: mathTokenTarget,\n\t\t\t\t\texpressionTarget: null,\n\t\t\t\t\tregionTarget: planned.regionTarget,\n\t\t\t\t\tconfidence: normalized.confidence,\n\t\t\t\t\treason: normalized.reason,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// (2) A spoken word that maps to visible prose. The prose anchor is\n\t\t\t// precise; a coarse math expression fallback must never override it.\n\t\t\t// Exception: a multi-node prose range inside a token-mode equation\n\t\t\t// would escalate to the whole expression, so it is rejected here and\n\t\t\t// falls through to the token hold below. When per-token math\n\t\t\t// highlighting is disabled, any prose range that lands inside a\n\t\t\t// formula is likewise rejected so the formula stays a single block.\n\t\t\tif (\n\t\t\t\tproseTarget &&\n\t\t\t\t(mathTokenHighlighting\n\t\t\t\t\t? !wouldEscalateInsideTokenMath(planned, proseTarget, mathCandidates)\n\t\t\t\t\t: mathCandidates.length === 0)\n\t\t\t) {\n\t\t\t\treturn createHighlightDecision({\n\t\t\t\t\tsemanticTarget: proseTarget,\n\t\t\t\t\texpressionTarget: null,\n\t\t\t\t\tregionTarget: planned.regionTarget,\n\t\t\t\t\tconfidence: normalized.confidence,\n\t\t\t\t\treason: normalized.reason,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// (3) A boundary inside a token-mode equation that did not map to a\n\t\t\t// token — an SSML break, a pause, or a gap between spoken tokens. Hold\n\t\t\t// the last token instead of flashing the whole expression; before the\n\t\t\t// first token there is nothing to hold, so fall to the region layer.\n\t\t\t// The whole expression is deliberately never painted in token mode.\n\t\t\tif (everyCandidateIsTokenMode(planned, mathCandidates)) {\n\t\t\t\tconst equationElement = soleEquationElement(mathCandidates);\n\t\t\t\tconst heldToken = equationElement\n\t\t\t\t\t? (planned.heldTokenByElement.get(equationElement) ?? null)\n\t\t\t\t\t: null;\n\t\t\t\treturn createHighlightDecision({\n\t\t\t\t\tsemanticTarget: heldToken,\n\t\t\t\t\texpressionTarget: null,\n\t\t\t\t\tregionTarget: planned.regionTarget,\n\t\t\t\t\tconfidence: normalized.confidence,\n\t\t\t\t\treason: heldToken\n\t\t\t\t\t\t? \"hold last token (sticky token mode)\"\n\t\t\t\t\t\t: \"region (sticky token mode, awaiting first token)\",\n\t\t\t\t});\n\t\t\t}\n\n\t\t\t// (4) An expression-mode (or mixed/ambiguous) math region: paint the\n\t\t\t// whole equation. Stable for the equation's full duration because\n\t\t\t// tokens never resolve here, so there is no flicker.\n\t\t\treturn createHighlightDecision({\n\t\t\t\tsemanticTarget: null,\n\t\t\t\texpressionTarget:\n\t\t\t\t\tmathExpressionFallback ??\n\t\t\t\t\texpressionTargetFor(planned, mathCandidates),\n\t\t\t\tregionTarget: planned.regionTarget,\n\t\t\t\tconfidence: normalized.confidence,\n\t\t\t\treason: normalized.reason,\n\t\t\t});\n\t\t},\n\t};\n};\n"]}

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

@@ -0,0 +1,2 @@
+import type { HighlightDecision, HighlightDecisionInput } from "./types.js";
+export declare const createHighlightDecision: (input: HighlightDecisionInput) => HighlightDecision;

package/dist/services/tts/highlight-pipeline/highlight-policy.js

@@ -0,0 +1,32 @@
+export const createHighlightDecision = (input) => {
+    if (input.semanticTarget) {
+        return {
+            activeTarget: input.semanticTarget,
+            regionTarget: input.regionTarget,
+            quality: input.semanticTarget.quality === "exact-word"
+                ? "exact-word"
+                : input.semanticTarget.quality === "expression"
+                    ? "expression"
+                    : "semantic-token",
+            confidence: input.confidence,
+            reason: input.reason,
+        };
+    }
+    if (input.expressionTarget) {
+        return {
+            activeTarget: input.expressionTarget,
+            regionTarget: input.regionTarget,
+            quality: "expression",
+            confidence: input.confidence,
+            reason: input.reason,
+        };
+    }
+    return {
+        activeTarget: null,
+        regionTarget: input.regionTarget,
+        quality: "region",
+        confidence: input.confidence,
+        reason: input.reason,
+    };
+};
+//# sourceMappingURL=highlight-policy.js.map

package/dist/services/tts/highlight-pipeline/highlight-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlight-policy.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/highlight-policy.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACtC,KAA6B,EACT,EAAE;IACtB,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QAC1B,OAAO;YACN,YAAY,EAAE,KAAK,CAAC,cAAc;YAClC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,OAAO,EACN,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,YAAY;gBAC5C,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,YAAY;oBAC9C,CAAC,CAAC,YAAY;oBACd,CAAC,CAAC,gBAAgB;YACrB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;SACpB,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC5B,OAAO;YACN,YAAY,EAAE,KAAK,CAAC,gBAAgB;YACpC,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,OAAO,EAAE,YAAY;YACrB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;SACpB,CAAC;IACH,CAAC;IACD,OAAO;QACN,YAAY,EAAE,IAAI;QAClB,YAAY,EAAE,KAAK,CAAC,YAAY;QAChC,OAAO,EAAE,QAAQ;QACjB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;KACpB,CAAC;AACH,CAAC,CAAC","sourcesContent":["import type { HighlightDecision, HighlightDecisionInput } from \"./types.js\";\n\nexport const createHighlightDecision = (\n\tinput: HighlightDecisionInput,\n): HighlightDecision => {\n\tif (input.semanticTarget) {\n\t\treturn {\n\t\t\tactiveTarget: input.semanticTarget,\n\t\t\tregionTarget: input.regionTarget,\n\t\t\tquality:\n\t\t\t\tinput.semanticTarget.quality === \"exact-word\"\n\t\t\t\t\t? \"exact-word\"\n\t\t\t\t\t: input.semanticTarget.quality === \"expression\"\n\t\t\t\t\t\t? \"expression\"\n\t\t\t\t\t\t: \"semantic-token\",\n\t\t\tconfidence: input.confidence,\n\t\t\treason: input.reason,\n\t\t};\n\t}\n\tif (input.expressionTarget) {\n\t\treturn {\n\t\t\tactiveTarget: input.expressionTarget,\n\t\t\tregionTarget: input.regionTarget,\n\t\t\tquality: \"expression\",\n\t\t\tconfidence: input.confidence,\n\t\t\treason: input.reason,\n\t\t};\n\t}\n\treturn {\n\t\tactiveTarget: null,\n\t\tregionTarget: input.regionTarget,\n\t\tquality: \"region\",\n\t\tconfidence: input.confidence,\n\t\treason: input.reason,\n\t};\n};\n"]}

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

@@ -0,0 +1,9 @@
+export * from "./boundary-normalizer.js";
+export * from "./create-highlight-plan.js";
+export * from "./highlight-policy.js";
+export * from "./math-semantic-resolver.js";
+export * from "./normalize-speech-chunks.js";
+export * from "./prose-boundary-resolver.js";
+export * from "./readable-region.js";
+export * from "./rendered-math-target-resolver.js";
+export type * from "./types.js";

package/dist/services/tts/highlight-pipeline/index.js

@@ -0,0 +1,9 @@
+export * from "./boundary-normalizer.js";
+export * from "./create-highlight-plan.js";
+export * from "./highlight-policy.js";
+export * from "./math-semantic-resolver.js";
+export * from "./normalize-speech-chunks.js";
+export * from "./prose-boundary-resolver.js";
+export * from "./readable-region.js";
+export * from "./rendered-math-target-resolver.js";
+//# sourceMappingURL=index.js.map

package/dist/services/tts/highlight-pipeline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,sBAAsB,CAAC;AACrC,cAAc,oCAAoC,CAAC","sourcesContent":["export * from \"./boundary-normalizer.js\";\nexport * from \"./create-highlight-plan.js\";\nexport * from \"./highlight-policy.js\";\nexport * from \"./math-semantic-resolver.js\";\nexport * from \"./normalize-speech-chunks.js\";\nexport * from \"./prose-boundary-resolver.js\";\nexport * from \"./readable-region.js\";\nexport * from \"./rendered-math-target-resolver.js\";\nexport type * from \"./types.js\";\n"]}

package/dist/services/tts/highlight-pipeline/math-semantic-resolver.d.ts

@@ -0,0 +1,3 @@
+import { type RenderedMathTargetResolver } from "./rendered-math-target-resolver.js";
+import type { NormalizedBoundaryEvent, RenderableHighlightTarget, TTSBoundaryEvent, TTSHighlightChunk } from "./types.js";
+export declare const resolveMathBoundaryTarget: (chunk: TTSHighlightChunk, boundary: NormalizedBoundaryEvent, event: TTSBoundaryEvent, candidates?: TTSHighlightChunk["mathAlignments"], renderedResolver?: RenderedMathTargetResolver) => RenderableHighlightTarget | null;

package/dist/services/tts/highlight-pipeline/math-semantic-resolver.js

@@ -0,0 +1,32 @@
+import { resolveMatchedHighlightTargetForSpokenBoundary, resolveUniqueMathTargetForBoundaryWord, } from "../math-alignment/index.js";
+import { resolveRenderedMathTarget, } from "./rendered-math-target-resolver.js";
+export const resolveMathBoundaryTarget = (chunk, boundary, event, candidates = chunk.mathAlignments, renderedResolver = resolveRenderedMathTarget) => {
+    if (boundary.chunkSpokenStart === null || boundary.chunkSpokenEnd === null) {
+        return null;
+    }
+    // Prefer a precise per-token target across all candidate equations before
+    // settling for a coarse expression fallback: scan every candidate for a
+    // semantic-token first, remembering the first expression-quality hit only as
+    // a last resort.
+    let expressionFallback = null;
+    for (const mathAlignment of candidates) {
+        const target = resolveMatchedHighlightTargetForSpokenBoundary(mathAlignment.alignment, {
+            position: boundary.chunkSpokenStart,
+            length: Math.max(1, boundary.chunkSpokenEnd - boundary.chunkSpokenStart),
+            boundaryWord: event.word,
+        }) ||
+            resolveUniqueMathTargetForBoundaryWord(mathAlignment.alignment, {
+                boundaryWord: event.word,
+            });
+        if (!target)
+            continue;
+        const rendered = renderedResolver(target);
+        if (!rendered)
+            continue;
+        if (rendered.quality === "semantic-token")
+            return rendered;
+        expressionFallback ??= rendered;
+    }
+    return expressionFallback;
+};
+//# sourceMappingURL=math-semantic-resolver.js.map

package/dist/services/tts/highlight-pipeline/math-semantic-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math-semantic-resolver.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/math-semantic-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,8CAA8C,EAC9C,sCAAsC,GACtC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACN,yBAAyB,GAEzB,MAAM,oCAAoC,CAAC;AAQ5C,MAAM,CAAC,MAAM,yBAAyB,GAAG,CACxC,KAAwB,EACxB,QAAiC,EACjC,KAAuB,EACvB,aAAkD,KAAK,CAAC,cAAc,EACtE,mBAA+C,yBAAyB,EACrC,EAAE;IACrC,IAAI,QAAQ,CAAC,gBAAgB,KAAK,IAAI,IAAI,QAAQ,CAAC,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5E,OAAO,IAAI,CAAC;IACb,CAAC;IACD,0EAA0E;IAC1E,wEAAwE;IACxE,6EAA6E;IAC7E,iBAAiB;IACjB,IAAI,kBAAkB,GAAqC,IAAI,CAAC;IAChE,KAAK,MAAM,aAAa,IAAI,UAAU,EAAE,CAAC;QACxC,MAAM,MAAM,GACX,8CAA8C,CAAC,aAAa,CAAC,SAAS,EAAE;YACvE,QAAQ,EAAE,QAAQ,CAAC,gBAAgB;YACnC,MAAM,EAAE,IAAI,CAAC,GAAG,CACf,CAAC,EACD,QAAQ,CAAC,cAAc,GAAG,QAAQ,CAAC,gBAAgB,CACnD;YACD,YAAY,EAAE,KAAK,CAAC,IAAI;SACxB,CAAC;YACF,sCAAsC,CAAC,aAAa,CAAC,SAAS,EAAE;gBAC/D,YAAY,EAAE,KAAK,CAAC,IAAI;aACxB,CAAC,CAAC;QACJ,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,IAAI,QAAQ,CAAC,OAAO,KAAK,gBAAgB;YAAE,OAAO,QAAQ,CAAC;QAC3D,kBAAkB,KAAK,QAAQ,CAAC;IACjC,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC3B,CAAC,CAAC","sourcesContent":["import {\n\tresolveMatchedHighlightTargetForSpokenBoundary,\n\tresolveUniqueMathTargetForBoundaryWord,\n} from \"../math-alignment/index.js\";\nimport {\n\tresolveRenderedMathTarget,\n\ttype RenderedMathTargetResolver,\n} from \"./rendered-math-target-resolver.js\";\nimport type {\n\tNormalizedBoundaryEvent,\n\tRenderableHighlightTarget,\n\tTTSBoundaryEvent,\n\tTTSHighlightChunk,\n} from \"./types.js\";\n\nexport const resolveMathBoundaryTarget = (\n\tchunk: TTSHighlightChunk,\n\tboundary: NormalizedBoundaryEvent,\n\tevent: TTSBoundaryEvent,\n\tcandidates: TTSHighlightChunk[\"mathAlignments\"] = chunk.mathAlignments,\n\trenderedResolver: RenderedMathTargetResolver = resolveRenderedMathTarget,\n): RenderableHighlightTarget | null => {\n\tif (boundary.chunkSpokenStart === null || boundary.chunkSpokenEnd === null) {\n\t\treturn null;\n\t}\n\t// Prefer a precise per-token target across all candidate equations before\n\t// settling for a coarse expression fallback: scan every candidate for a\n\t// semantic-token first, remembering the first expression-quality hit only as\n\t// a last resort.\n\tlet expressionFallback: RenderableHighlightTarget | null = null;\n\tfor (const mathAlignment of candidates) {\n\t\tconst target =\n\t\t\tresolveMatchedHighlightTargetForSpokenBoundary(mathAlignment.alignment, {\n\t\t\t\tposition: boundary.chunkSpokenStart,\n\t\t\t\tlength: Math.max(\n\t\t\t\t\t1,\n\t\t\t\t\tboundary.chunkSpokenEnd - boundary.chunkSpokenStart,\n\t\t\t\t),\n\t\t\t\tboundaryWord: event.word,\n\t\t\t}) ||\n\t\t\tresolveUniqueMathTargetForBoundaryWord(mathAlignment.alignment, {\n\t\t\t\tboundaryWord: event.word,\n\t\t\t});\n\t\tif (!target) continue;\n\t\tconst rendered = renderedResolver(target);\n\t\tif (!rendered) continue;\n\t\tif (rendered.quality === \"semantic-token\") return rendered;\n\t\texpressionFallback ??= rendered;\n\t}\n\treturn expressionFallback;\n};\n"]}

package/dist/services/tts/highlight-pipeline/normalize-speech-chunks.d.ts

@@ -0,0 +1,29 @@
+import type { CatalogSpanAlignment } from "../catalog-span-alignment.js";
+import type { MathAwareAlignment } from "../math-alignment/index.js";
+import type { NormalizedTextMap } from "../text-processing.js";
+import type { TTSHighlightChunk } from "./types.js";
+export interface SpeechCompositionChunkInput {
+    speechText: string;
+    visibleText: string;
+    sourceElement: Element | null;
+    regionElement?: Element | null;
+    regionRange?: Range;
+    alignment?: CatalogSpanAlignment;
+    mathAlignment?: MathAwareAlignment;
+    mathAlignments?: Array<{
+        element: Element;
+        alignment: MathAwareAlignment;
+    }>;
+    visibleMap?: NormalizedTextMap;
+}
+export interface NormalizeSpeechChunksArgs {
+    contentRoot: Element;
+    chunks?: SpeechCompositionChunkInput[];
+    speechText?: string;
+    visibleText?: string;
+    sourceElement?: Element | null;
+    regionElement?: Element | null;
+    regionRange?: Range;
+    visibleMap?: NormalizedTextMap;
+}
+export declare const normalizeSpeechChunks: (args: NormalizeSpeechChunksArgs) => TTSHighlightChunk[];

package/dist/services/tts/highlight-pipeline/normalize-speech-chunks.js

@@ -0,0 +1,44 @@
+const chunkOffsetSpaceFor = (chunk) => {
+    if (chunk.alignment?.boundaryOffsetMode)
+        return chunk.alignment.boundaryOffsetMode;
+    const mathOffsetSpace = chunk.mathAlignment?.speech.boundaryOffsetSpace;
+    if (mathOffsetSpace)
+        return mathOffsetSpace;
+    return "plain-spoken-text";
+};
+const mathAlignmentsFor = (chunk) => {
+    if (chunk.mathAlignments?.length)
+        return chunk.mathAlignments;
+    if (chunk.mathAlignment && chunk.sourceElement) {
+        return [{ element: chunk.sourceElement, alignment: chunk.mathAlignment }];
+    }
+    return [];
+};
+export const normalizeSpeechChunks = (args) => {
+    const sourceChunks = args.chunks && args.chunks.length
+        ? args.chunks
+        : [
+            {
+                speechText: args.speechText || "",
+                visibleText: args.visibleText || args.speechText || "",
+                sourceElement: args.sourceElement || args.contentRoot,
+                regionElement: args.regionElement || args.sourceElement || args.contentRoot,
+                regionRange: args.regionRange,
+                visibleMap: args.visibleMap,
+            },
+        ];
+    return sourceChunks.map((chunk, index) => ({
+        id: `tts-chunk-${index}`,
+        speechText: chunk.speechText,
+        visibleText: chunk.visibleText,
+        sourceElement: chunk.sourceElement,
+        contentRoot: args.contentRoot,
+        regionElement: chunk.regionElement ?? chunk.sourceElement,
+        regionRange: chunk.regionRange,
+        visibleMap: chunk.visibleMap,
+        catalogAlignment: chunk.alignment,
+        mathAlignments: mathAlignmentsFor(chunk),
+        offsetSpace: chunkOffsetSpaceFor(chunk),
+    }));
+};
+//# sourceMappingURL=normalize-speech-chunks.js.map

package/dist/services/tts/highlight-pipeline/normalize-speech-chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-speech-chunks.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/normalize-speech-chunks.ts"],"names":[],"mappings":"AA4BA,MAAM,mBAAmB,GAAG,CAC3B,KAAkC,EACf,EAAE;IACrB,IAAI,KAAK,CAAC,SAAS,EAAE,kBAAkB;QACtC,OAAO,KAAK,CAAC,SAAS,CAAC,kBAAkB,CAAC;IAC3C,MAAM,eAAe,GAAG,KAAK,CAAC,aAAa,EAAE,MAAM,CAAC,mBAAmB,CAAC;IACxE,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAC5C,OAAO,mBAAmB,CAAC;AAC5B,CAAC,CAAC;AAEF,MAAM,iBAAiB,GAAG,CACzB,KAAkC,EAC2B,EAAE;IAC/D,IAAI,KAAK,CAAC,cAAc,EAAE,MAAM;QAAE,OAAO,KAAK,CAAC,cAAc,CAAC;IAC9D,IAAI,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QAChD,OAAO,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,aAAa,EAAE,SAAS,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,EAAE,CAAC;AACX,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACpC,IAA+B,EACT,EAAE;IACxB,MAAM,YAAY,GACjB,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM;QAChC,CAAC,CAAC,IAAI,CAAC,MAAM;QACb,CAAC,CAAC;YACA;gBACC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,EAAE;gBACjC,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,UAAU,IAAI,EAAE;gBACtD,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,WAAW;gBACrD,aAAa,EACZ,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,WAAW;gBAC7D,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;aAC3B;SACD,CAAC;IACL,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC1C,EAAE,EAAE,aAAa,KAAK,EAAE;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,aAAa;QACzD,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,gBAAgB,EAAE,KAAK,CAAC,SAAS;QACjC,cAAc,EAAE,iBAAiB,CAAC,KAAK,CAAC;QACxC,WAAW,EAAE,mBAAmB,CAAC,KAAK,CAAC;KACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC","sourcesContent":["import type { CatalogSpanAlignment } from \"../catalog-span-alignment.js\";\nimport type { MathAwareAlignment } from \"../math-alignment/index.js\";\nimport type { NormalizedTextMap } from \"../text-processing.js\";\nimport type { ChunkOffsetSpace, TTSHighlightChunk } from \"./types.js\";\n\nexport interface SpeechCompositionChunkInput {\n\tspeechText: string;\n\tvisibleText: string;\n\tsourceElement: Element | null;\n\tregionElement?: Element | null;\n\tregionRange?: Range;\n\talignment?: CatalogSpanAlignment;\n\tmathAlignment?: MathAwareAlignment;\n\tmathAlignments?: Array<{ element: Element; alignment: MathAwareAlignment }>;\n\tvisibleMap?: NormalizedTextMap;\n}\n\nexport interface NormalizeSpeechChunksArgs {\n\tcontentRoot: Element;\n\tchunks?: SpeechCompositionChunkInput[];\n\tspeechText?: string;\n\tvisibleText?: string;\n\tsourceElement?: Element | null;\n\tregionElement?: Element | null;\n\tregionRange?: Range;\n\tvisibleMap?: NormalizedTextMap;\n}\n\nconst chunkOffsetSpaceFor = (\n\tchunk: SpeechCompositionChunkInput,\n): ChunkOffsetSpace => {\n\tif (chunk.alignment?.boundaryOffsetMode)\n\t\treturn chunk.alignment.boundaryOffsetMode;\n\tconst mathOffsetSpace = chunk.mathAlignment?.speech.boundaryOffsetSpace;\n\tif (mathOffsetSpace) return mathOffsetSpace;\n\treturn \"plain-spoken-text\";\n};\n\nconst mathAlignmentsFor = (\n\tchunk: SpeechCompositionChunkInput,\n): Array<{ element: Element; alignment: MathAwareAlignment }> => {\n\tif (chunk.mathAlignments?.length) return chunk.mathAlignments;\n\tif (chunk.mathAlignment && chunk.sourceElement) {\n\t\treturn [{ element: chunk.sourceElement, alignment: chunk.mathAlignment }];\n\t}\n\treturn [];\n};\n\nexport const normalizeSpeechChunks = (\n\targs: NormalizeSpeechChunksArgs,\n): TTSHighlightChunk[] => {\n\tconst sourceChunks =\n\t\targs.chunks && args.chunks.length\n\t\t\t? args.chunks\n\t\t\t: [\n\t\t\t\t\t{\n\t\t\t\t\t\tspeechText: args.speechText || \"\",\n\t\t\t\t\t\tvisibleText: args.visibleText || args.speechText || \"\",\n\t\t\t\t\t\tsourceElement: args.sourceElement || args.contentRoot,\n\t\t\t\t\t\tregionElement:\n\t\t\t\t\t\t\targs.regionElement || args.sourceElement || args.contentRoot,\n\t\t\t\t\t\tregionRange: args.regionRange,\n\t\t\t\t\t\tvisibleMap: args.visibleMap,\n\t\t\t\t\t},\n\t\t\t\t];\n\treturn sourceChunks.map((chunk, index) => ({\n\t\tid: `tts-chunk-${index}`,\n\t\tspeechText: chunk.speechText,\n\t\tvisibleText: chunk.visibleText,\n\t\tsourceElement: chunk.sourceElement,\n\t\tcontentRoot: args.contentRoot,\n\t\tregionElement: chunk.regionElement ?? chunk.sourceElement,\n\t\tregionRange: chunk.regionRange,\n\t\tvisibleMap: chunk.visibleMap,\n\t\tcatalogAlignment: chunk.alignment,\n\t\tmathAlignments: mathAlignmentsFor(chunk),\n\t\toffsetSpace: chunkOffsetSpaceFor(chunk),\n\t}));\n};\n"]}

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

@@ -0,0 +1,2 @@
+import type { NormalizedBoundaryEvent, RenderableHighlightTarget, TTSHighlightChunk } from "./types.js";
+export declare const resolveProseBoundaryTarget: (chunk: TTSHighlightChunk, boundary: NormalizedBoundaryEvent) => RenderableHighlightTarget | null;

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

@@ -0,0 +1,20 @@
+import { resolveVisibleSpanForBoundary } from "../catalog-span-alignment.js";
+import { createRangeFromVisibleMap } 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)
+        return null;
+    return {
+        type: "range",
+        quality: chunk.catalogAlignment.playbackMode === "exact-word"
+            ? "exact-word"
+            : "semantic-token",
+        range,
+    };
+};
+//# sourceMappingURL=prose-boundary-resolver.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prose-boundary-resolver.js","sourceRoot":"","sources":["../../../../src/services/tts/highlight-pipeline/prose-boundary-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAOnE,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACzC,KAAwB,EACxB,QAAiC,EACE,EAAE;IACrC,IAAI,CAAC,KAAK,CAAC,gBAAgB,IAAI,QAAQ,CAAC,gBAAgB,KAAK,IAAI;QAChE,OAAO,IAAI,CAAC;IACb,MAAM,WAAW,GAAG,6BAA6B,CAChD,KAAK,CAAC,gBAAgB,EACtB,QAAQ,CAAC,gBAAgB,CACzB,CAAC;IACF,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,MAAM,KAAK,GAAG,yBAAyB,CACtC,KAAK,CAAC,UAAU,EAChB,WAAW,CAAC,KAAK,EACjB,WAAW,CAAC,GAAG,CACf,CAAC;IACF,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,OAAO;QACN,IAAI,EAAE,OAAO;QACb,OAAO,EACN,KAAK,CAAC,gBAAgB,CAAC,YAAY,KAAK,YAAY;YACnD,CAAC,CAAC,YAAY;YACd,CAAC,CAAC,gBAAgB;QACpB,KAAK;KACL,CAAC;AACH,CAAC,CAAC","sourcesContent":["import { resolveVisibleSpanForBoundary } from \"../catalog-span-alignment.js\";\nimport { createRangeFromVisibleMap } from \"./visible-map-range.js\";\nimport type {\n\tNormalizedBoundaryEvent,\n\tRenderableHighlightTarget,\n\tTTSHighlightChunk,\n} from \"./types.js\";\n\nexport const resolveProseBoundaryTarget = (\n\tchunk: TTSHighlightChunk,\n\tboundary: NormalizedBoundaryEvent,\n): RenderableHighlightTarget | null => {\n\tif (!chunk.catalogAlignment || boundary.chunkSpokenStart === null)\n\t\treturn null;\n\tconst visibleSpan = resolveVisibleSpanForBoundary(\n\t\tchunk.catalogAlignment,\n\t\tboundary.chunkSpokenStart,\n\t);\n\tif (!visibleSpan) return null;\n\tconst range = createRangeFromVisibleMap(\n\t\tchunk.visibleMap,\n\t\tvisibleSpan.start,\n\t\tvisibleSpan.end,\n\t);\n\tif (!range) return null;\n\treturn {\n\t\ttype: \"range\",\n\t\tquality:\n\t\t\tchunk.catalogAlignment.playbackMode === \"exact-word\"\n\t\t\t\t? \"exact-word\"\n\t\t\t\t: \"semantic-token\",\n\t\trange,\n\t};\n};\n"]}

package/dist/services/tts/highlight-pipeline/readable-region.d.ts

@@ -0,0 +1 @@
+export declare const resolveReadableRegion: (sourceElement: Element, contentRoot: Element) => Element;