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

package/dist/services/AccessibilityCatalogResolver.js

@@ -1,3 +1,4 @@
+import { sanitizeSsmlString } from "./SSMLExtractor.js";
 /**
  * Accessibility Catalog Resolver Service
  *
@@ -27,8 +28,18 @@
 export class AccessibilityCatalogResolver {
     assessmentCatalogs = new Map();
     itemCatalogs = new Map();
-    defaultLanguage = "en";
-    constructor(assessmentCatalogs, defaultLanguage = "en") {
+    scopedCatalogs = new Map();
+    // Matches the language the extractor tags cards with and the TTSService
+    // passes on lookup ("en-US"), so the default-language fallback rung in
+    // findMatchingCard is actually reachable for the common case.
+    defaultLanguage = "en-US";
+    // Egress sanitization cache. Catalogs are sanitized at registration, but that
+    // is a no-op when indexing runs without a DOM (SSR). Sanitizing again as
+    // spoken content leaves the resolver guarantees no raw author SSML reaches a
+    // provider regardless of where indexing happened; the cache keeps it to one
+    // pass per unique string (sanitizeSsmlString is idempotent).
+    sanitizedSpokenCache = new Map();
+    constructor(assessmentCatalogs, defaultLanguage = "en-US") {
         this.defaultLanguage = defaultLanguage;
         this.indexCatalogs(assessmentCatalogs ?? [], "assessment");
     }
@@ -49,10 +60,47 @@ export class AccessibilityCatalogResolver {
      */
     indexCatalogs(catalogs, source) {
         const targetMap = source === "assessment" ? this.assessmentCatalogs : this.itemCatalogs;
-        for (const catalog of catalogs) {
+        for (const catalog of this.sanitizeCatalogs(catalogs)) {
+            if (targetMap.has(catalog.identifier)) {
+                console.warn(`[AccessibilityCatalogResolver] Duplicate ${source} catalog "${catalog.identifier}" ignored`);
+                continue;
+            }
             targetMap.set(catalog.identifier, catalog);
         }
     }
+    registerCatalogs(context, catalogs) {
+        if (!catalogs || catalogs.length === 0)
+            return () => { };
+        const key = this.getOwnerKey(context);
+        const existing = this.scopedCatalogs.get(key);
+        const scoped = existing?.catalogs ?? new Map();
+        const insertedIds = [];
+        for (const catalog of this.sanitizeCatalogs(catalogs)) {
+            if (scoped.has(catalog.identifier)) {
+                console.warn(`[AccessibilityCatalogResolver] Duplicate scoped catalog "${catalog.identifier}" ignored for ${key}`);
+                continue;
+            }
+            scoped.set(catalog.identifier, catalog);
+            insertedIds.push(catalog.identifier);
+        }
+        if (!existing) {
+            this.scopedCatalogs.set(key, {
+                context: { ...context },
+                catalogs: scoped,
+            });
+        }
+        return () => {
+            const current = this.scopedCatalogs.get(key);
+            if (current?.catalogs !== scoped)
+                return;
+            for (const insertedId of insertedIds) {
+                current.catalogs.delete(insertedId);
+            }
+            if (current.catalogs.size === 0) {
+                this.scopedCatalogs.delete(key);
+            }
+        };
+    }
     /**
      * Add item-level catalogs (called when rendering a new item)
      */
@@ -71,7 +119,9 @@ export class AccessibilityCatalogResolver {
      * Check if a catalog exists (checks both assessment and item levels)
      */
     hasCatalog(catalogId) {
-        return (this.itemCatalogs.has(catalogId) || this.assessmentCatalogs.has(catalogId));
+        return (this.itemCatalogs.has(catalogId) ||
+            this.assessmentCatalogs.has(catalogId) ||
+            Array.from(this.scopedCatalogs.values()).some((owner) => owner.catalogs.has(catalogId)));
     }
     /**
      * Get alternative content for a catalog identifier
@@ -79,36 +129,128 @@ export class AccessibilityCatalogResolver {
      * Priority: Item-level catalogs take precedence over assessment-level
      */
     getAlternative(catalogId, options) {
+        const scopedCatalog = options.context
+            ? this.scopedCatalogs
+                .get(this.getOwnerKey(options.context))
+                ?.catalogs.get(catalogId)
+            : null;
+        if (scopedCatalog) {
+            const card = this.findMatchingCard(scopedCatalog, options);
+            if (card)
+                return this.resolveCard(catalogId, card, "item");
+        }
+        if (options.context) {
+            const candidates = this.findScopedCandidates(catalogId, options.context);
+            if (candidates.length === 1) {
+                const card = this.findMatchingCard(candidates[0], options);
+                if (card)
+                    return this.resolveCard(catalogId, card, "item");
+            }
+            else if (candidates.length > 1) {
+                console.warn(`[AccessibilityCatalogResolver] Ambiguous scoped catalog "${catalogId}" for owner context`, options.context);
+                return null;
+            }
+        }
         // Check item-level first (higher precedence)
         const itemCatalog = this.itemCatalogs.get(catalogId);
         if (itemCatalog) {
             const card = this.findMatchingCard(itemCatalog, options);
-            if (card) {
-                return {
-                    catalogId,
-                    type: card.catalog,
-                    language: card.language,
-                    content: card.content,
-                    source: "item",
-                };
-            }
+            if (card)
+                return this.resolveCard(catalogId, card, "item");
         }
         // Fallback to assessment-level
         const assessmentCatalog = this.assessmentCatalogs.get(catalogId);
         if (assessmentCatalog) {
             const card = this.findMatchingCard(assessmentCatalog, options);
-            if (card) {
-                return {
-                    catalogId,
-                    type: card.catalog,
-                    language: card.language,
-                    content: card.content,
-                    source: "assessment",
-                };
-            }
+            if (card)
+                return this.resolveCard(catalogId, card, "assessment");
         }
         return null;
     }
+    resolveCard(catalogId, card, source) {
+        return {
+            catalogId,
+            type: card.catalog,
+            language: card.language,
+            content: card.catalog === "spoken"
+                ? this.ensureSpokenSanitized(card.content)
+                : card.content,
+            source,
+        };
+    }
+    ensureSpokenSanitized(content) {
+        const cached = this.sanitizedSpokenCache.get(content);
+        if (cached !== undefined)
+            return cached;
+        const sanitized = sanitizeSsmlString(content);
+        this.sanitizedSpokenCache.set(content, sanitized);
+        return sanitized;
+    }
+    getOwnerKey(context) {
+        return [
+            context.ownerKind,
+            context.assessmentId || "",
+            context.sectionId || "",
+            context.canonicalItemId || "",
+            context.itemId || "",
+            context.passageId || "",
+            context.modelId || "",
+        ].join("|");
+    }
+    // Flattened [id, catalog] pairs for every context-scoped owner. The primary
+    // runtime path registers catalogs as scoped, so enumeration APIs must include
+    // these or they silently under-report what TTS content exists.
+    scopedCatalogEntries() {
+        const entries = [];
+        for (const owner of this.scopedCatalogs.values()) {
+            for (const entry of owner.catalogs.entries()) {
+                entries.push(entry);
+            }
+        }
+        return entries;
+    }
+    findScopedCandidates(catalogId, context) {
+        return Array.from(this.scopedCatalogs.values())
+            .filter((owner) => this.isCompatibleOwnerContext(owner.context, context))
+            .map((owner) => owner.catalogs.get(catalogId))
+            .filter((catalog) => Boolean(catalog));
+    }
+    isCompatibleOwnerContext(registered, lookup) {
+        if (registered.ownerKind !== lookup.ownerKind)
+            return false;
+        if (lookup.assessmentId &&
+            registered.assessmentId !== lookup.assessmentId) {
+            return false;
+        }
+        if (lookup.sectionId && registered.sectionId !== lookup.sectionId) {
+            return false;
+        }
+        if (lookup.canonicalItemId &&
+            registered.canonicalItemId !== lookup.canonicalItemId) {
+            return false;
+        }
+        if (lookup.itemId && registered.itemId !== lookup.itemId) {
+            return false;
+        }
+        if (lookup.passageId && registered.passageId !== lookup.passageId) {
+            return false;
+        }
+        if (lookup.modelId && registered.modelId !== lookup.modelId) {
+            return false;
+        }
+        return true;
+    }
+    sanitizeCatalogs(catalogs) {
+        return catalogs.map((catalog) => ({
+            ...catalog,
+            cards: catalog.cards.map((card) => ({
+                ...card,
+                content: card.catalog === "spoken"
+                    ? sanitizeSsmlString(card.content)
+                    : card.content,
+            })),
+        }));
+    }
     /**
      * Find a matching catalog card based on lookup options
      */
@@ -167,16 +309,36 @@ export class AccessibilityCatalogResolver {
                 }
             }
         }
+        // Add scoped (context-registered) alternatives. These resolve as "item"
+        // in getAlternative, so report them the same way here.
+        for (const [id, catalog] of this.scopedCatalogEntries()) {
+            if (id !== catalogId)
+                continue;
+            for (const card of catalog.cards) {
+                const exists = results.some((r) => r.type === card.catalog && r.language === card.language);
+                if (!exists) {
+                    results.push({
+                        catalogId,
+                        type: card.catalog,
+                        language: card.language,
+                        content: card.content,
+                        source: "item",
+                    });
+                }
+            }
+        }
         return results;
     }
     /**
      * Get all catalog identifiers available (both assessment and item)
      */
     getAllCatalogIds() {
-        const itemIds = Array.from(this.itemCatalogs.keys());
-        const assessmentIds = Array.from(this.assessmentCatalogs.keys());
-        // Combine and deduplicate
-        return Array.from(new Set([...itemIds, ...assessmentIds]));
+        const scopedIds = this.scopedCatalogEntries().map(([id]) => id);
+        return Array.from(new Set([
+            ...this.itemCatalogs.keys(),
+            ...this.assessmentCatalogs.keys(),
+            ...scopedIds,
+        ]));
     }
     /**
      * Get statistics about available catalogs
@@ -201,9 +363,12 @@ export class AccessibilityCatalogResolver {
             }
         }
         return {
-            totalCatalogs: this.assessmentCatalogs.size + this.itemCatalogs.size,
+            totalCatalogs: this.assessmentCatalogs.size +
+                this.itemCatalogs.size +
+                Array.from(this.scopedCatalogs.values()).reduce((total, owner) => total + owner.catalogs.size, 0),
             assessmentCatalogs: this.assessmentCatalogs.size,
-            itemCatalogs: this.itemCatalogs.size,
+            itemCatalogs: this.itemCatalogs.size +
+                Array.from(this.scopedCatalogs.values()).reduce((total, owner) => total + owner.catalogs.size, 0),
             availableTypes: allTypes,
             availableLanguages: allLanguages,
         };
@@ -230,6 +395,11 @@ export class AccessibilityCatalogResolver {
                 catalogIds.add(id);
             }
         }
+        for (const [id, catalog] of this.scopedCatalogEntries()) {
+            if (catalog.cards.some((card) => card.catalog === type)) {
+                catalogIds.add(id);
+            }
+        }
         return Array.from(catalogIds);
     }
     /**
@@ -238,6 +408,8 @@ export class AccessibilityCatalogResolver {
     reset() {
         this.assessmentCatalogs.clear();
         this.itemCatalogs.clear();
+        this.scopedCatalogs.clear();
+        this.sanitizedSpokenCache.clear();
     }
     /**
      * Destroy and cleanup

package/dist/services/AccessibilityCatalogResolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"AccessibilityCatalogResolver.js","sourceRoot":"","sources":["../../src/services/AccessibilityCatalogResolver.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n\tAccessibilityCatalog,\n\tCatalogCard,\n} from \"@pie-players/pie-players-shared/types\";\n\n/**\n * Supported accessibility catalog types from QTI 3.0 / APIP\n */\nexport type CatalogType =\n\t| \"spoken\" // Text-to-speech scripts\n\t| \"sign-language\" // Video URLs for signed content\n\t| \"braille\" // Braille transcriptions\n\t| \"tactile\" // Tactile graphics descriptions\n\t| \"simplified-language\" // Plain language alternatives\n\t| \"audio-description\" // Extended audio descriptions\n\t| \"extended-description\" // Extended text descriptions\n\t| string; // Support custom types\n\n/**\n * Lookup options for catalog resolution\n */\nexport interface CatalogLookupOptions {\n\t/** Catalog type (e.g., 'spoken', 'sign-language') */\n\ttype: CatalogType;\n\t/** Language code (e.g., 'en-US', 'es-ES') */\n\tlanguage?: string;\n\t/** Fallback to default language if requested language not found */\n\tuseFallback?: boolean;\n}\n\n/**\n * Resolved catalog result\n */\nexport interface ResolvedCatalog {\n\t/** The catalog identifier */\n\tcatalogId: string;\n\t/** The catalog type */\n\ttype: CatalogType;\n\t/** The language code */\n\tlanguage?: string;\n\t/** The content (HTML, URL, or plain text) */\n\tcontent: string;\n\t/** Source of the catalog (assessment or item) */\n\tsource: \"assessment\" | \"item\";\n}\n\n/**\n * Statistics about available catalogs\n */\nexport interface CatalogStatistics {\n\t/** Total number of catalogs */\n\ttotalCatalogs: number;\n\t/** Number of assessment-level catalogs */\n\tassessmentCatalogs: number;\n\t/** Number of item-level catalogs */\n\titemCatalogs: number;\n\t/** Catalog types available */\n\tavailableTypes: Set<CatalogType>;\n\t/** Languages available */\n\tavailableLanguages: Set<string>;\n}\n\n/**\n * Accessibility Catalog Resolver Service\n *\n * Manages QTI 3.0 accessibility catalogs at both assessment and item levels.\n * Provides lookup and resolution services for alternative content representations.\n *\n * @example\n * ```typescript\n * // Initialize with assessment-level catalogs\n * const resolver = new AccessibilityCatalogResolver(assessment.accessibilityCatalogs);\n *\n * // Add item-level catalogs when rendering item\n * resolver.addItemCatalogs(item.accessibilityCatalogs);\n *\n * // Resolve catalog by identifier\n * const spokenContent = resolver.getAlternative('intro-passage', {\n *   type: 'spoken',\n *   language: 'en-US'\n * });\n *\n * // Check if catalog exists\n * if (resolver.hasCatalog('math-problem-1')) {\n *   const braille = resolver.getAlternative('math-problem-1', { type: 'braille' });\n * }\n * ```\n */\nexport class AccessibilityCatalogResolver {\n\tprivate assessmentCatalogs: Map<string, AccessibilityCatalog> = new Map();\n\tprivate itemCatalogs: Map<string, AccessibilityCatalog> = new Map();\n\tprivate defaultLanguage: string = \"en\";\n\n\tconstructor(\n\t\tassessmentCatalogs?: AccessibilityCatalog[],\n\t\tdefaultLanguage: string = \"en\",\n\t) {\n\t\tthis.defaultLanguage = defaultLanguage;\n\t\tthis.indexCatalogs(assessmentCatalogs ?? [], \"assessment\");\n\t}\n\n\t/**\n\t * Set the default language for fallback resolution\n\t */\n\tsetDefaultLanguage(language: string): void {\n\t\tthis.defaultLanguage = language;\n\t}\n\n\t/**\n\t * Get the default language\n\t */\n\tgetDefaultLanguage(): string {\n\t\treturn this.defaultLanguage;\n\t}\n\n\t/**\n\t * Index catalogs into the appropriate map\n\t */\n\tprivate indexCatalogs(\n\t\tcatalogs: AccessibilityCatalog[],\n\t\tsource: \"assessment\" | \"item\",\n\t): void {\n\t\tconst targetMap =\n\t\t\tsource === \"assessment\" ? this.assessmentCatalogs : this.itemCatalogs;\n\n\t\tfor (const catalog of catalogs) {\n\t\t\ttargetMap.set(catalog.identifier, catalog);\n\t\t}\n\t}\n\n\t/**\n\t * Add item-level catalogs (called when rendering a new item)\n\t */\n\taddItemCatalogs(catalogs?: AccessibilityCatalog[]): void {\n\t\tif (!catalogs || catalogs.length === 0) return;\n\t\tthis.indexCatalogs(catalogs, \"item\");\n\t}\n\n\t/**\n\t * Clear item-level catalogs (called when leaving an item)\n\t */\n\tclearItemCatalogs(): void {\n\t\tthis.itemCatalogs.clear();\n\t}\n\n\t/**\n\t * Check if a catalog exists (checks both assessment and item levels)\n\t */\n\thasCatalog(catalogId: string): boolean {\n\t\treturn (\n\t\t\tthis.itemCatalogs.has(catalogId) || this.assessmentCatalogs.has(catalogId)\n\t\t);\n\t}\n\n\t/**\n\t * Get alternative content for a catalog identifier\n\t *\n\t * Priority: Item-level catalogs take precedence over assessment-level\n\t */\n\tgetAlternative(\n\t\tcatalogId: string,\n\t\toptions: CatalogLookupOptions,\n\t): ResolvedCatalog | null {\n\t\t// Check item-level first (higher precedence)\n\t\tconst itemCatalog = this.itemCatalogs.get(catalogId);\n\t\tif (itemCatalog) {\n\t\t\tconst card = this.findMatchingCard(itemCatalog, options);\n\t\t\tif (card) {\n\t\t\t\treturn {\n\t\t\t\t\tcatalogId,\n\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\tcontent: card.content,\n\t\t\t\t\tsource: \"item\",\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\t// Fallback to assessment-level\n\t\tconst assessmentCatalog = this.assessmentCatalogs.get(catalogId);\n\t\tif (assessmentCatalog) {\n\t\t\tconst card = this.findMatchingCard(assessmentCatalog, options);\n\t\t\tif (card) {\n\t\t\t\treturn {\n\t\t\t\t\tcatalogId,\n\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\tcontent: card.content,\n\t\t\t\t\tsource: \"assessment\",\n\t\t\t\t};\n\t\t\t}\n\t\t}\n\n\t\treturn null;\n\t}\n\n\t/**\n\t * Find a matching catalog card based on lookup options\n\t */\n\tprivate findMatchingCard(\n\t\tcatalog: AccessibilityCatalog,\n\t\toptions: CatalogLookupOptions,\n\t): CatalogCard | null {\n\t\tconst { type, language, useFallback = true } = options;\n\n\t\t// Try exact match (type + language)\n\t\tif (language) {\n\t\t\tconst exactMatch = catalog.cards.find(\n\t\t\t\t(card) => card.catalog === type && card.language === language,\n\t\t\t);\n\t\t\tif (exactMatch) return exactMatch;\n\t\t}\n\n\t\t// Try type match with default language (if fallback enabled)\n\t\tif (useFallback) {\n\t\t\tconst defaultMatch = catalog.cards.find(\n\t\t\t\t(card) =>\n\t\t\t\t\tcard.catalog === type && card.language === this.defaultLanguage,\n\t\t\t);\n\t\t\tif (defaultMatch) return defaultMatch;\n\n\t\t\t// Try type match without language constraint\n\t\t\tconst typeMatch = catalog.cards.find((card) => card.catalog === type);\n\t\t\tif (typeMatch) return typeMatch;\n\t\t}\n\n\t\treturn null;\n\t}\n\n\t/**\n\t * Get all available alternatives for a catalog identifier\n\t */\n\tgetAllAlternatives(catalogId: string): ResolvedCatalog[] {\n\t\tconst results: ResolvedCatalog[] = [];\n\n\t\t// Add item-level alternatives\n\t\tconst itemCatalog = this.itemCatalogs.get(catalogId);\n\t\tif (itemCatalog) {\n\t\t\tfor (const card of itemCatalog.cards) {\n\t\t\t\tresults.push({\n\t\t\t\t\tcatalogId,\n\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\tcontent: card.content,\n\t\t\t\t\tsource: \"item\",\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\t// Add assessment-level alternatives (if not already provided by item)\n\t\tconst assessmentCatalog = this.assessmentCatalogs.get(catalogId);\n\t\tif (assessmentCatalog) {\n\t\t\tfor (const card of assessmentCatalog.cards) {\n\t\t\t\t// Only add if not already provided by item catalog\n\t\t\t\tconst exists = results.some(\n\t\t\t\t\t(r) => r.type === card.catalog && r.language === card.language,\n\t\t\t\t);\n\t\t\t\tif (!exists) {\n\t\t\t\t\tresults.push({\n\t\t\t\t\t\tcatalogId,\n\t\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\t\tcontent: card.content,\n\t\t\t\t\t\tsource: \"assessment\",\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn results;\n\t}\n\n\t/**\n\t * Get all catalog identifiers available (both assessment and item)\n\t */\n\tgetAllCatalogIds(): string[] {\n\t\tconst itemIds = Array.from(this.itemCatalogs.keys());\n\t\tconst assessmentIds = Array.from(this.assessmentCatalogs.keys());\n\n\t\t// Combine and deduplicate\n\t\treturn Array.from(new Set([...itemIds, ...assessmentIds]));\n\t}\n\n\t/**\n\t * Get statistics about available catalogs\n\t */\n\tgetStatistics(): CatalogStatistics {\n\t\tconst allTypes = new Set<CatalogType>();\n\t\tconst allLanguages = new Set<string>();\n\n\t\t// Collect from assessment catalogs\n\t\tfor (const catalog of this.assessmentCatalogs.values()) {\n\t\t\tfor (const card of catalog.cards) {\n\t\t\t\tallTypes.add(card.catalog);\n\t\t\t\tif (card.language) allLanguages.add(card.language);\n\t\t\t}\n\t\t}\n\n\t\t// Collect from item catalogs\n\t\tfor (const catalog of this.itemCatalogs.values()) {\n\t\t\tfor (const card of catalog.cards) {\n\t\t\t\tallTypes.add(card.catalog);\n\t\t\t\tif (card.language) allLanguages.add(card.language);\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\ttotalCatalogs: this.assessmentCatalogs.size + this.itemCatalogs.size,\n\t\t\tassessmentCatalogs: this.assessmentCatalogs.size,\n\t\t\titemCatalogs: this.itemCatalogs.size,\n\t\t\tavailableTypes: allTypes,\n\t\t\tavailableLanguages: allLanguages,\n\t\t};\n\t}\n\n\t/**\n\t * Check if a specific catalog type is available for a given catalog ID\n\t */\n\thasAlternativeType(catalogId: string, type: CatalogType): boolean {\n\t\tconst alternatives = this.getAllAlternatives(catalogId);\n\t\treturn alternatives.some((alt) => alt.type === type);\n\t}\n\n\t/**\n\t * Get all catalog IDs that have a specific type of alternative\n\t */\n\tgetCatalogsByType(type: CatalogType): string[] {\n\t\tconst catalogIds = new Set<string>();\n\n\t\tfor (const [id, catalog] of this.assessmentCatalogs.entries()) {\n\t\t\tif (catalog.cards.some((card) => card.catalog === type)) {\n\t\t\t\tcatalogIds.add(id);\n\t\t\t}\n\t\t}\n\n\t\tfor (const [id, catalog] of this.itemCatalogs.entries()) {\n\t\t\tif (catalog.cards.some((card) => card.catalog === type)) {\n\t\t\t\tcatalogIds.add(id);\n\t\t\t}\n\t\t}\n\n\t\treturn Array.from(catalogIds);\n\t}\n\n\t/**\n\t * Reset all catalogs (both assessment and item)\n\t */\n\treset(): void {\n\t\tthis.assessmentCatalogs.clear();\n\t\tthis.itemCatalogs.clear();\n\t}\n\n\t/**\n\t * Destroy and cleanup\n\t */\n\tdestroy(): void {\n\t\tthis.reset();\n\t}\n}\n"]}
+{"version":3,"file":"AccessibilityCatalogResolver.js","sourceRoot":"","sources":["../../src/services/AccessibilityCatalogResolver.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n\tAccessibilityCatalog,\n\tCatalogCard,\n} from \"@pie-players/pie-players-shared/types\";\nimport { sanitizeSsmlString } from \"./SSMLExtractor.js\";\n\nexport type CatalogOwnerKind = \"global\" | \"passage\" | \"itemModel\";\n\nexport interface CatalogOwnerContext {\n\townerKind: CatalogOwnerKind;\n\tassessmentId?: string;\n\tsectionId?: string;\n\tcanonicalItemId?: string;\n\titemId?: string;\n\tpassageId?: string;\n\tmodelId?: string;\n}\n\nexport type CatalogLookupContext = CatalogOwnerContext;\n\n/**\n * Supported accessibility catalog types from QTI 3.0 / APIP\n */\nexport type CatalogType =\n\t| \"spoken\" // Text-to-speech scripts\n\t| \"sign-language\" // Video URLs for signed content\n\t| \"braille\" // Braille transcriptions\n\t| \"tactile\" // Tactile graphics descriptions\n\t| \"simplified-language\" // Plain language alternatives\n\t| \"audio-description\" // Extended audio descriptions\n\t| \"extended-description\" // Extended text descriptions\n\t| string; // Support custom types\n\n/**\n * Lookup options for catalog resolution\n */\nexport interface CatalogLookupOptions {\n\t/** Catalog type (e.g., 'spoken', 'sign-language') */\n\ttype: CatalogType;\n\t/** Language code (e.g., 'en-US', 'es-ES') */\n\tlanguage?: string;\n\t/** Fallback to default language if requested language not found */\n\tuseFallback?: boolean;\n\t/** Scope used to resolve local catalog idrefs for rendered content */\n\tcontext?: CatalogLookupContext;\n}\n\n/**\n * Resolved catalog result\n */\nexport interface ResolvedCatalog {\n\t/** The catalog identifier */\n\tcatalogId: string;\n\t/** The catalog type */\n\ttype: CatalogType;\n\t/** The language code */\n\tlanguage?: string;\n\t/** The content (HTML, URL, or plain text) */\n\tcontent: string;\n\t/** Source of the catalog (assessment or item) */\n\tsource: \"assessment\" | \"item\";\n}\n\n/**\n * Statistics about available catalogs\n */\nexport interface CatalogStatistics {\n\t/** Total number of catalogs */\n\ttotalCatalogs: number;\n\t/** Number of assessment-level catalogs */\n\tassessmentCatalogs: number;\n\t/** Number of item-level catalogs */\n\titemCatalogs: number;\n\t/** Catalog types available */\n\tavailableTypes: Set<CatalogType>;\n\t/** Languages available */\n\tavailableLanguages: Set<string>;\n}\n\n/**\n * Accessibility Catalog Resolver Service\n *\n * Manages QTI 3.0 accessibility catalogs at both assessment and item levels.\n * Provides lookup and resolution services for alternative content representations.\n *\n * @example\n * ```typescript\n * // Initialize with assessment-level catalogs\n * const resolver = new AccessibilityCatalogResolver(assessment.accessibilityCatalogs);\n *\n * // Add item-level catalogs when rendering item\n * resolver.addItemCatalogs(item.accessibilityCatalogs);\n *\n * // Resolve catalog by identifier\n * const spokenContent = resolver.getAlternative('intro-passage', {\n *   type: 'spoken',\n *   language: 'en-US'\n * });\n *\n * // Check if catalog exists\n * if (resolver.hasCatalog('math-problem-1')) {\n *   const braille = resolver.getAlternative('math-problem-1', { type: 'braille' });\n * }\n * ```\n */\nexport class AccessibilityCatalogResolver {\n\tprivate assessmentCatalogs: Map<string, AccessibilityCatalog> = new Map();\n\tprivate itemCatalogs: Map<string, AccessibilityCatalog> = new Map();\n\tprivate scopedCatalogs = new Map<\n\t\tstring,\n\t\t{\n\t\t\tcontext: CatalogOwnerContext;\n\t\t\tcatalogs: Map<string, AccessibilityCatalog>;\n\t\t}\n\t>();\n\t// Matches the language the extractor tags cards with and the TTSService\n\t// passes on lookup (\"en-US\"), so the default-language fallback rung in\n\t// findMatchingCard is actually reachable for the common case.\n\tprivate defaultLanguage: string = \"en-US\";\n\t// Egress sanitization cache. Catalogs are sanitized at registration, but that\n\t// is a no-op when indexing runs without a DOM (SSR). Sanitizing again as\n\t// spoken content leaves the resolver guarantees no raw author SSML reaches a\n\t// provider regardless of where indexing happened; the cache keeps it to one\n\t// pass per unique string (sanitizeSsmlString is idempotent).\n\tprivate sanitizedSpokenCache = new Map<string, string>();\n\n\tconstructor(\n\t\tassessmentCatalogs?: AccessibilityCatalog[],\n\t\tdefaultLanguage: string = \"en-US\",\n\t) {\n\t\tthis.defaultLanguage = defaultLanguage;\n\t\tthis.indexCatalogs(assessmentCatalogs ?? [], \"assessment\");\n\t}\n\n\t/**\n\t * Set the default language for fallback resolution\n\t */\n\tsetDefaultLanguage(language: string): void {\n\t\tthis.defaultLanguage = language;\n\t}\n\n\t/**\n\t * Get the default language\n\t */\n\tgetDefaultLanguage(): string {\n\t\treturn this.defaultLanguage;\n\t}\n\n\t/**\n\t * Index catalogs into the appropriate map\n\t */\n\tprivate indexCatalogs(\n\t\tcatalogs: AccessibilityCatalog[],\n\t\tsource: \"assessment\" | \"item\",\n\t): void {\n\t\tconst targetMap =\n\t\t\tsource === \"assessment\" ? this.assessmentCatalogs : this.itemCatalogs;\n\n\t\tfor (const catalog of this.sanitizeCatalogs(catalogs)) {\n\t\t\tif (targetMap.has(catalog.identifier)) {\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`[AccessibilityCatalogResolver] Duplicate ${source} catalog \"${catalog.identifier}\" ignored`,\n\t\t\t\t);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\ttargetMap.set(catalog.identifier, catalog);\n\t\t}\n\t}\n\n\tregisterCatalogs(\n\t\tcontext: CatalogOwnerContext,\n\t\tcatalogs?: AccessibilityCatalog[],\n\t): () => void {\n\t\tif (!catalogs || catalogs.length === 0) return () => {};\n\t\tconst key = this.getOwnerKey(context);\n\t\tconst existing = this.scopedCatalogs.get(key);\n\t\tconst scoped =\n\t\t\texisting?.catalogs ?? new Map<string, AccessibilityCatalog>();\n\t\tconst insertedIds: string[] = [];\n\t\tfor (const catalog of this.sanitizeCatalogs(catalogs)) {\n\t\t\tif (scoped.has(catalog.identifier)) {\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`[AccessibilityCatalogResolver] Duplicate scoped catalog \"${catalog.identifier}\" ignored for ${key}`,\n\t\t\t\t);\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tscoped.set(catalog.identifier, catalog);\n\t\t\tinsertedIds.push(catalog.identifier);\n\t\t}\n\t\tif (!existing) {\n\t\t\tthis.scopedCatalogs.set(key, {\n\t\t\t\tcontext: { ...context },\n\t\t\t\tcatalogs: scoped,\n\t\t\t});\n\t\t}\n\t\treturn () => {\n\t\t\tconst current = this.scopedCatalogs.get(key);\n\t\t\tif (current?.catalogs !== scoped) return;\n\t\t\tfor (const insertedId of insertedIds) {\n\t\t\t\tcurrent.catalogs.delete(insertedId);\n\t\t\t}\n\t\t\tif (current.catalogs.size === 0) {\n\t\t\t\tthis.scopedCatalogs.delete(key);\n\t\t\t}\n\t\t};\n\t}\n\n\t/**\n\t * Add item-level catalogs (called when rendering a new item)\n\t */\n\taddItemCatalogs(catalogs?: AccessibilityCatalog[]): void {\n\t\tif (!catalogs || catalogs.length === 0) return;\n\t\tthis.indexCatalogs(catalogs, \"item\");\n\t}\n\n\t/**\n\t * Clear item-level catalogs (called when leaving an item)\n\t */\n\tclearItemCatalogs(): void {\n\t\tthis.itemCatalogs.clear();\n\t}\n\n\t/**\n\t * Check if a catalog exists (checks both assessment and item levels)\n\t */\n\thasCatalog(catalogId: string): boolean {\n\t\treturn (\n\t\t\tthis.itemCatalogs.has(catalogId) ||\n\t\t\tthis.assessmentCatalogs.has(catalogId) ||\n\t\t\tArray.from(this.scopedCatalogs.values()).some((owner) =>\n\t\t\t\towner.catalogs.has(catalogId),\n\t\t\t)\n\t\t);\n\t}\n\n\t/**\n\t * Get alternative content for a catalog identifier\n\t *\n\t * Priority: Item-level catalogs take precedence over assessment-level\n\t */\n\tgetAlternative(\n\t\tcatalogId: string,\n\t\toptions: CatalogLookupOptions,\n\t): ResolvedCatalog | null {\n\t\tconst scopedCatalog = options.context\n\t\t\t? this.scopedCatalogs\n\t\t\t\t\t.get(this.getOwnerKey(options.context))\n\t\t\t\t\t?.catalogs.get(catalogId)\n\t\t\t: null;\n\t\tif (scopedCatalog) {\n\t\t\tconst card = this.findMatchingCard(scopedCatalog, options);\n\t\t\tif (card) return this.resolveCard(catalogId, card, \"item\");\n\t\t}\n\t\tif (options.context) {\n\t\t\tconst candidates = this.findScopedCandidates(catalogId, options.context);\n\t\t\tif (candidates.length === 1) {\n\t\t\t\tconst card = this.findMatchingCard(candidates[0], options);\n\t\t\t\tif (card) return this.resolveCard(catalogId, card, \"item\");\n\t\t\t} else if (candidates.length > 1) {\n\t\t\t\tconsole.warn(\n\t\t\t\t\t`[AccessibilityCatalogResolver] Ambiguous scoped catalog \"${catalogId}\" for owner context`,\n\t\t\t\t\toptions.context,\n\t\t\t\t);\n\t\t\t\treturn null;\n\t\t\t}\n\t\t}\n\n\t\t// Check item-level first (higher precedence)\n\t\tconst itemCatalog = this.itemCatalogs.get(catalogId);\n\t\tif (itemCatalog) {\n\t\t\tconst card = this.findMatchingCard(itemCatalog, options);\n\t\t\tif (card) return this.resolveCard(catalogId, card, \"item\");\n\t\t}\n\n\t\t// Fallback to assessment-level\n\t\tconst assessmentCatalog = this.assessmentCatalogs.get(catalogId);\n\t\tif (assessmentCatalog) {\n\t\t\tconst card = this.findMatchingCard(assessmentCatalog, options);\n\t\t\tif (card) return this.resolveCard(catalogId, card, \"assessment\");\n\t\t}\n\n\t\treturn null;\n\t}\n\n\tprivate resolveCard(\n\t\tcatalogId: string,\n\t\tcard: CatalogCard,\n\t\tsource: ResolvedCatalog[\"source\"],\n\t): ResolvedCatalog {\n\t\treturn {\n\t\t\tcatalogId,\n\t\t\ttype: card.catalog,\n\t\t\tlanguage: card.language,\n\t\t\tcontent:\n\t\t\t\tcard.catalog === \"spoken\"\n\t\t\t\t\t? this.ensureSpokenSanitized(card.content)\n\t\t\t\t\t: card.content,\n\t\t\tsource,\n\t\t};\n\t}\n\n\tprivate ensureSpokenSanitized(content: string): string {\n\t\tconst cached = this.sanitizedSpokenCache.get(content);\n\t\tif (cached !== undefined) return cached;\n\t\tconst sanitized = sanitizeSsmlString(content);\n\t\tthis.sanitizedSpokenCache.set(content, sanitized);\n\t\treturn sanitized;\n\t}\n\n\tprivate getOwnerKey(context: CatalogOwnerContext): string {\n\t\treturn [\n\t\t\tcontext.ownerKind,\n\t\t\tcontext.assessmentId || \"\",\n\t\t\tcontext.sectionId || \"\",\n\t\t\tcontext.canonicalItemId || \"\",\n\t\t\tcontext.itemId || \"\",\n\t\t\tcontext.passageId || \"\",\n\t\t\tcontext.modelId || \"\",\n\t\t].join(\"|\");\n\t}\n\n\t// Flattened [id, catalog] pairs for every context-scoped owner. The primary\n\t// runtime path registers catalogs as scoped, so enumeration APIs must include\n\t// these or they silently under-report what TTS content exists.\n\tprivate scopedCatalogEntries(): Array<[string, AccessibilityCatalog]> {\n\t\tconst entries: Array<[string, AccessibilityCatalog]> = [];\n\t\tfor (const owner of this.scopedCatalogs.values()) {\n\t\t\tfor (const entry of owner.catalogs.entries()) {\n\t\t\t\tentries.push(entry);\n\t\t\t}\n\t\t}\n\t\treturn entries;\n\t}\n\n\tprivate findScopedCandidates(\n\t\tcatalogId: string,\n\t\tcontext: CatalogOwnerContext,\n\t): AccessibilityCatalog[] {\n\t\treturn Array.from(this.scopedCatalogs.values())\n\t\t\t.filter((owner) => this.isCompatibleOwnerContext(owner.context, context))\n\t\t\t.map((owner) => owner.catalogs.get(catalogId))\n\t\t\t.filter((catalog): catalog is AccessibilityCatalog => Boolean(catalog));\n\t}\n\n\tprivate isCompatibleOwnerContext(\n\t\tregistered: CatalogOwnerContext,\n\t\tlookup: CatalogOwnerContext,\n\t): boolean {\n\t\tif (registered.ownerKind !== lookup.ownerKind) return false;\n\t\tif (\n\t\t\tlookup.assessmentId &&\n\t\t\tregistered.assessmentId !== lookup.assessmentId\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\tif (lookup.sectionId && registered.sectionId !== lookup.sectionId) {\n\t\t\treturn false;\n\t\t}\n\t\tif (\n\t\t\tlookup.canonicalItemId &&\n\t\t\tregistered.canonicalItemId !== lookup.canonicalItemId\n\t\t) {\n\t\t\treturn false;\n\t\t}\n\t\tif (lookup.itemId && registered.itemId !== lookup.itemId) {\n\t\t\treturn false;\n\t\t}\n\t\tif (lookup.passageId && registered.passageId !== lookup.passageId) {\n\t\t\treturn false;\n\t\t}\n\t\tif (lookup.modelId && registered.modelId !== lookup.modelId) {\n\t\t\treturn false;\n\t\t}\n\t\treturn true;\n\t}\n\n\tprivate sanitizeCatalogs(\n\t\tcatalogs: AccessibilityCatalog[],\n\t): AccessibilityCatalog[] {\n\t\treturn catalogs.map((catalog) => ({\n\t\t\t...catalog,\n\t\t\tcards: catalog.cards.map((card) => ({\n\t\t\t\t...card,\n\t\t\t\tcontent:\n\t\t\t\t\tcard.catalog === \"spoken\"\n\t\t\t\t\t\t? sanitizeSsmlString(card.content)\n\t\t\t\t\t\t: card.content,\n\t\t\t})),\n\t\t}));\n\t}\n\n\t/**\n\t * Find a matching catalog card based on lookup options\n\t */\n\tprivate findMatchingCard(\n\t\tcatalog: AccessibilityCatalog,\n\t\toptions: CatalogLookupOptions,\n\t): CatalogCard | null {\n\t\tconst { type, language, useFallback = true } = options;\n\n\t\t// Try exact match (type + language)\n\t\tif (language) {\n\t\t\tconst exactMatch = catalog.cards.find(\n\t\t\t\t(card) => card.catalog === type && card.language === language,\n\t\t\t);\n\t\t\tif (exactMatch) return exactMatch;\n\t\t}\n\n\t\t// Try type match with default language (if fallback enabled)\n\t\tif (useFallback) {\n\t\t\tconst defaultMatch = catalog.cards.find(\n\t\t\t\t(card) =>\n\t\t\t\t\tcard.catalog === type && card.language === this.defaultLanguage,\n\t\t\t);\n\t\t\tif (defaultMatch) return defaultMatch;\n\n\t\t\t// Try type match without language constraint\n\t\t\tconst typeMatch = catalog.cards.find((card) => card.catalog === type);\n\t\t\tif (typeMatch) return typeMatch;\n\t\t}\n\n\t\treturn null;\n\t}\n\n\t/**\n\t * Get all available alternatives for a catalog identifier\n\t */\n\tgetAllAlternatives(catalogId: string): ResolvedCatalog[] {\n\t\tconst results: ResolvedCatalog[] = [];\n\n\t\t// Add item-level alternatives\n\t\tconst itemCatalog = this.itemCatalogs.get(catalogId);\n\t\tif (itemCatalog) {\n\t\t\tfor (const card of itemCatalog.cards) {\n\t\t\t\tresults.push({\n\t\t\t\t\tcatalogId,\n\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\tcontent: card.content,\n\t\t\t\t\tsource: \"item\",\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\t// Add assessment-level alternatives (if not already provided by item)\n\t\tconst assessmentCatalog = this.assessmentCatalogs.get(catalogId);\n\t\tif (assessmentCatalog) {\n\t\t\tfor (const card of assessmentCatalog.cards) {\n\t\t\t\t// Only add if not already provided by item catalog\n\t\t\t\tconst exists = results.some(\n\t\t\t\t\t(r) => r.type === card.catalog && r.language === card.language,\n\t\t\t\t);\n\t\t\t\tif (!exists) {\n\t\t\t\t\tresults.push({\n\t\t\t\t\t\tcatalogId,\n\t\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\t\tcontent: card.content,\n\t\t\t\t\t\tsource: \"assessment\",\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Add scoped (context-registered) alternatives. These resolve as \"item\"\n\t\t// in getAlternative, so report them the same way here.\n\t\tfor (const [id, catalog] of this.scopedCatalogEntries()) {\n\t\t\tif (id !== catalogId) continue;\n\t\t\tfor (const card of catalog.cards) {\n\t\t\t\tconst exists = results.some(\n\t\t\t\t\t(r) => r.type === card.catalog && r.language === card.language,\n\t\t\t\t);\n\t\t\t\tif (!exists) {\n\t\t\t\t\tresults.push({\n\t\t\t\t\t\tcatalogId,\n\t\t\t\t\t\ttype: card.catalog,\n\t\t\t\t\t\tlanguage: card.language,\n\t\t\t\t\t\tcontent: card.content,\n\t\t\t\t\t\tsource: \"item\",\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn results;\n\t}\n\n\t/**\n\t * Get all catalog identifiers available (both assessment and item)\n\t */\n\tgetAllCatalogIds(): string[] {\n\t\tconst scopedIds = this.scopedCatalogEntries().map(([id]) => id);\n\t\treturn Array.from(\n\t\t\tnew Set([\n\t\t\t\t...this.itemCatalogs.keys(),\n\t\t\t\t...this.assessmentCatalogs.keys(),\n\t\t\t\t...scopedIds,\n\t\t\t]),\n\t\t);\n\t}\n\n\t/**\n\t * Get statistics about available catalogs\n\t */\n\tgetStatistics(): CatalogStatistics {\n\t\tconst allTypes = new Set<CatalogType>();\n\t\tconst allLanguages = new Set<string>();\n\n\t\t// Collect from assessment catalogs\n\t\tfor (const catalog of this.assessmentCatalogs.values()) {\n\t\t\tfor (const card of catalog.cards) {\n\t\t\t\tallTypes.add(card.catalog);\n\t\t\t\tif (card.language) allLanguages.add(card.language);\n\t\t\t}\n\t\t}\n\n\t\t// Collect from item catalogs\n\t\tfor (const catalog of this.itemCatalogs.values()) {\n\t\t\tfor (const card of catalog.cards) {\n\t\t\t\tallTypes.add(card.catalog);\n\t\t\t\tif (card.language) allLanguages.add(card.language);\n\t\t\t}\n\t\t}\n\n\t\treturn {\n\t\t\ttotalCatalogs:\n\t\t\t\tthis.assessmentCatalogs.size +\n\t\t\t\tthis.itemCatalogs.size +\n\t\t\t\tArray.from(this.scopedCatalogs.values()).reduce(\n\t\t\t\t\t(total, owner) => total + owner.catalogs.size,\n\t\t\t\t\t0,\n\t\t\t\t),\n\t\t\tassessmentCatalogs: this.assessmentCatalogs.size,\n\t\t\titemCatalogs:\n\t\t\t\tthis.itemCatalogs.size +\n\t\t\t\tArray.from(this.scopedCatalogs.values()).reduce(\n\t\t\t\t\t(total, owner) => total + owner.catalogs.size,\n\t\t\t\t\t0,\n\t\t\t\t),\n\t\t\tavailableTypes: allTypes,\n\t\t\tavailableLanguages: allLanguages,\n\t\t};\n\t}\n\n\t/**\n\t * Check if a specific catalog type is available for a given catalog ID\n\t */\n\thasAlternativeType(catalogId: string, type: CatalogType): boolean {\n\t\tconst alternatives = this.getAllAlternatives(catalogId);\n\t\treturn alternatives.some((alt) => alt.type === type);\n\t}\n\n\t/**\n\t * Get all catalog IDs that have a specific type of alternative\n\t */\n\tgetCatalogsByType(type: CatalogType): string[] {\n\t\tconst catalogIds = new Set<string>();\n\n\t\tfor (const [id, catalog] of this.assessmentCatalogs.entries()) {\n\t\t\tif (catalog.cards.some((card) => card.catalog === type)) {\n\t\t\t\tcatalogIds.add(id);\n\t\t\t}\n\t\t}\n\n\t\tfor (const [id, catalog] of this.itemCatalogs.entries()) {\n\t\t\tif (catalog.cards.some((card) => card.catalog === type)) {\n\t\t\t\tcatalogIds.add(id);\n\t\t\t}\n\t\t}\n\n\t\tfor (const [id, catalog] of this.scopedCatalogEntries()) {\n\t\t\tif (catalog.cards.some((card) => card.catalog === type)) {\n\t\t\t\tcatalogIds.add(id);\n\t\t\t}\n\t\t}\n\n\t\treturn Array.from(catalogIds);\n\t}\n\n\t/**\n\t * Reset all catalogs (both assessment and item)\n\t */\n\treset(): void {\n\t\tthis.assessmentCatalogs.clear();\n\t\tthis.itemCatalogs.clear();\n\t\tthis.scopedCatalogs.clear();\n\t\tthis.sanitizedSpokenCache.clear();\n\t}\n\n\t/**\n\t * Destroy and cleanup\n\t */\n\tdestroy(): void {\n\t\tthis.reset();\n\t}\n}\n"]}

package/dist/services/HighlightCoordinator.d.ts

@@ -60,6 +60,8 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
     private config;
     private ttsWordHighlight;
     private ttsSentenceHighlight;
+    private ttsWordElementHighlights;
+    private ttsSentenceElementHighlights;
     private annotations;
     private colorHighlights;
     private nextAnnotationId;
@@ -91,6 +93,24 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
      * @param endOffset End position in text node
      */
     highlightTTSWord(textNode: Text, startOffset: number, endOffset: number): void;
+    /**
+     * Highlight a single element as the active TTS word (temporary).
+     *
+     * Unlike {@link highlightTTSWord} (which paints a CSS range over a text node)
+     * this marks the element itself via `data-pie-tts-word-element`. It is used
+     * for atomic targets that have no direct text node to range over — most
+     * notably MathJax CHTML tokens (e.g. `<mjx-mi><mjx-c/></mjx-mi>`, whose glyph
+     * lives in a font-driven pseudo-element a CSS range cannot paint) and
+     * whole-expression fallbacks.
+     *
+     * The supplied element is painted exactly; we deliberately do NOT walk up to
+     * a containing `<math>` / `<mjx-container>`. That escalation is what made
+     * MathJax-rendered math highlight as a full block while native MathML tracked
+     * per-token: a resolved single token must paint as a token, and only a
+     * genuine expression fallback (where the element already is the container)
+     * should paint the whole expression.
+     */
+    highlightTTSWordElement(element: Element): void;
     /**
      * Highlight the coarse TTS read-along band (temporary).
      * Usually one Range per visual line; CSS layer `tts-sentence` for compatibility.
@@ -98,6 +118,11 @@ export declare class HighlightCoordinator implements HighlightCoordinatorApi {
      * @param ranges Line (or sentence) ranges to paint with `--pie-tts-line-highlight`
      */
     highlightTTSSentence(ranges: Range[]): void;
+    private static readonly SENTENCE_FALLBACK_SELECTOR;
+    private static readonly WORD_FALLBACK_SELECTOR;
+    private highlightTTSElementFallbacks;
+    private highlightTTSWordElementFallbacks;
+    private highlightElementFallbacks;
     /**
      * Clear TTS word highlight
      */

package/dist/services/HighlightCoordinator.js

@@ -46,6 +46,8 @@ export class HighlightCoordinator {
     config;
     ttsWordHighlight = null;
     ttsSentenceHighlight = null;
+    ttsWordElementHighlights = new Set();
+    ttsSentenceElementHighlights = new Set();
     annotations = new Map();
     // Shared highlights per color (one Highlight object per color, contains all ranges)
     colorHighlights = new Map();
@@ -285,6 +287,25 @@ export class HighlightCoordinator {
         color: inherit;
       }
 
+      [data-pie-tts-sentence-element="true"] {
+        background-color: var(--pie-tts-line-highlight, var(--pie-tts-sentence-highlight, color-mix(in srgb, var(--pie-missing, #ffeb3b) 38%, transparent)));
+        border-radius: 0.12em;
+        box-decoration-break: clone;
+        -webkit-box-decoration-break: clone;
+      }
+
+      [data-pie-tts-word-element="true"] {
+        background-color: var(--pie-tts-word-highlight, color-mix(in srgb, var(--pie-missing, #ffeb3b) 68%, transparent));
+        text-decoration: underline 2px solid var(--pie-tts-word-underline, color-mix(in srgb, var(--pie-text, #111827) 70%, transparent));
+        text-underline-offset: 2px;
+        text-shadow: 0 0 1px var(--pie-tts-word-shadow, color-mix(in srgb, var(--pie-text, #111827) 35%, transparent));
+        border-bottom: 2px solid var(--pie-tts-word-underline, color-mix(in srgb, var(--pie-text, #111827) 70%, transparent));
+        padding-bottom: 1px;
+        border-radius: 0.12em;
+        box-decoration-break: clone;
+        -webkit-box-decoration-break: clone;
+      }
+
       /* Annotation highlights - persistent */
       ::highlight(annotation-yellow) {
         background-color: color-mix(in srgb, var(--pie-missing, #ffff00) 35%, transparent);
@@ -340,6 +361,32 @@ export class HighlightCoordinator {
         // Add to highlight
         this.ttsWordHighlight.add(range);
     }
+    /**
+     * Highlight a single element as the active TTS word (temporary).
+     *
+     * Unlike {@link highlightTTSWord} (which paints a CSS range over a text node)
+     * this marks the element itself via `data-pie-tts-word-element`. It is used
+     * for atomic targets that have no direct text node to range over — most
+     * notably MathJax CHTML tokens (e.g. `<mjx-mi><mjx-c/></mjx-mi>`, whose glyph
+     * lives in a font-driven pseudo-element a CSS range cannot paint) and
+     * whole-expression fallbacks.
+     *
+     * The supplied element is painted exactly; we deliberately do NOT walk up to
+     * a containing `<math>` / `<mjx-container>`. That escalation is what made
+     * MathJax-rendered math highlight as a full block while native MathML tracked
+     * per-token: a resolved single token must paint as a token, and only a
+     * genuine expression fallback (where the element already is the container)
+     * should paint the whole expression.
+     */
+    highlightTTSWordElement(element) {
+        if (!this.ttsWordHighlight)
+            return;
+        this.applyAdaptiveTTSStyle(element);
+        // Clear previous word highlight (CSS range and any element attributes)
+        this.clearTTSWord();
+        element.setAttribute("data-pie-tts-word-element", "true");
+        this.ttsWordElementHighlights.add(element);
+    }
     /**
      * Highlight the coarse TTS read-along band (temporary).
      * Usually one Range per visual line; CSS layer `tts-sentence` for compatibility.
@@ -360,6 +407,69 @@ export class HighlightCoordinator {
         for (const range of ranges) {
             this.ttsSentenceHighlight.add(range);
         }
+        this.highlightTTSElementFallbacks(ranges);
+    }
+    // The read-along (sentence) band legitimately covers whole equations and
+    // replaced elements, so it escalates to them.
+    static SENTENCE_FALLBACK_SELECTOR = "math, mjx-container, svg, img, canvas, [role='img']";
+    // The word layer must NOT escalate a multi-node range to the enclosing
+    // `<math>` / `<mjx-container>`: that is what made an equation flash as a
+    // whole block whenever a spoken word's visible range crossed several math
+    // glyph nodes. Math is tracked per token (or held / region) by the highlight
+    // pipeline instead. Replaced elements (svg/img/canvas) still need the element
+    // fallback because a CSS range cannot paint them.
+    static WORD_FALLBACK_SELECTOR = "svg, img, canvas, [role='img']";
+    highlightTTSElementFallbacks(ranges) {
+        if (typeof Element === "undefined")
+            return;
+        this.highlightElementFallbacks(ranges, "data-pie-tts-sentence-element", this.ttsSentenceElementHighlights, HighlightCoordinator.SENTENCE_FALLBACK_SELECTOR);
+    }
+    highlightTTSWordElementFallbacks(ranges) {
+        if (typeof Element === "undefined")
+            return;
+        this.highlightElementFallbacks(ranges, "data-pie-tts-word-element", this.ttsWordElementHighlights, HighlightCoordinator.WORD_FALLBACK_SELECTOR);
+    }
+    highlightElementFallbacks(ranges, attributeName, trackedElements, selector) {
+        for (const range of ranges) {
+            const root = range.commonAncestorContainer.nodeType === Node.ELEMENT_NODE
+                ? range.commonAncestorContainer
+                : range.commonAncestorContainer.parentElement;
+            if (!root)
+                continue;
+            const candidates = [];
+            const rangeStartElement = range.startContainer.nodeType === Node.ELEMENT_NODE
+                ? range.startContainer
+                : range.startContainer.parentElement;
+            const rangeEndElement = range.endContainer.nodeType === Node.ELEMENT_NODE
+                ? range.endContainer
+                : range.endContainer.parentElement;
+            for (const element of [rangeStartElement, rangeEndElement]) {
+                let current = element;
+                while (current) {
+                    if (current.matches?.(selector))
+                        candidates.push(current);
+                    current = current.parentElement;
+                }
+            }
+            if (root.matches?.(selector)) {
+                candidates.push(root);
+            }
+            candidates.push(...Array.from(root.querySelectorAll(selector)));
+            for (const element of new Set(candidates)) {
+                try {
+                    if (!range.intersectsNode(element) &&
+                        !element.contains(rangeStartElement) &&
+                        !element.contains(rangeEndElement)) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+                element.setAttribute(attributeName, "true");
+                trackedElements.add(element);
+            }
+        }
     }
     /**
      * Clear TTS word highlight
@@ -368,6 +478,10 @@ export class HighlightCoordinator {
         if (!this.ttsWordHighlight)
             return;
         this.ttsWordHighlight.clear();
+        for (const element of this.ttsWordElementHighlights) {
+            element.removeAttribute("data-pie-tts-word-element");
+        }
+        this.ttsWordElementHighlights.clear();
     }
     /**
      * Clear TTS sentence highlight
@@ -376,6 +490,10 @@ export class HighlightCoordinator {
         if (!this.ttsSentenceHighlight)
             return;
         this.ttsSentenceHighlight.clear();
+        for (const element of this.ttsSentenceElementHighlights) {
+            element.removeAttribute("data-pie-tts-sentence-element");
+        }
+        this.ttsSentenceElementHighlights.clear();
     }
     /**
      * Clear all TTS highlights
@@ -539,6 +657,13 @@ export class HighlightCoordinator {
                 if (highlight) {
                     highlight.clear();
                     highlight.add(range);
+                    if (type === HighlightType.TTS_WORD) {
+                        for (const element of this.ttsWordElementHighlights) {
+                            element.removeAttribute("data-pie-tts-word-element");
+                        }
+                        this.ttsWordElementHighlights.clear();
+                        this.highlightTTSWordElementFallbacks([range]);
+                    }
                 }
                 break;
             }