@pie-players/pie-assessment-toolkit 0.3.65 → 0.3.67

package/dist/services/AccessibilityCatalogResolver.js

@@ -1,3 +1,4 @@
+import { catalogOwnerContextFor, collectOwnerCatalogRegistrations, } from "./catalog-owner.js";
 import { sanitizeSsmlString } from "./SSMLExtractor.js";
 /**
  * The catalog types PIE names, plus the rule for the ones it does not.
@@ -39,6 +40,39 @@ export function isKnownCatalogType(type) {
 // "this token is not a thing", and repeating it per card or per lookup would bury
 // it under itself.
 const reportedUnknownTypes = new Set();
+function cloneAndFreezeCatalogValue(value, seen = new Set()) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "undefined") {
+        return value;
+    }
+    if (typeof value !== "object") {
+        throw new TypeError("catalog cards must contain JSON-compatible values");
+    }
+    if (seen.has(value)) {
+        throw new TypeError("catalog cards must not contain cycles");
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return Object.freeze(value.map((entry) => cloneAndFreezeCatalogValue(entry, seen)));
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("catalog cards must contain only plain objects and arrays");
+        }
+        const cloned = {};
+        for (const [key, entry] of Object.entries(value)) {
+            cloned[key] = cloneAndFreezeCatalogValue(entry, seen);
+        }
+        return Object.freeze(cloned);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
 function reportUnknownCatalogType(type, side, where) {
     const key = `${side}|${type}`;
     if (reportedUnknownTypes.has(key))
@@ -93,6 +127,7 @@ export class AccessibilityCatalogResolver {
     // pass per unique string (sanitizeSsmlString is idempotent).
     sanitizedSpokenCache = new Map();
     catalogChangeListeners = new Set();
+    reportedSnapshotProblems = new Set();
     constructor(assessmentCatalogs, defaultLanguage = "en-US") {
         this.defaultLanguage = defaultLanguage;
         this.indexCatalogs(assessmentCatalogs ?? [], "assessment");
@@ -162,9 +197,9 @@ export class AccessibilityCatalogResolver {
             targetMap.set(catalog.identifier, catalog);
         }
     }
-    registerCatalogs(context, catalogs) {
+    insertScopedCatalogs(context, catalogs) {
         if (!catalogs || catalogs.length === 0)
-            return () => { };
+            return null;
         const key = this.getOwnerKey(context);
         const existing = this.scopedCatalogs.get(key);
         const scoped = existing?.catalogs ?? new Map();
@@ -177,33 +212,102 @@ export class AccessibilityCatalogResolver {
             scoped.set(catalog.identifier, catalog);
             insertedIds.push(catalog.identifier);
         }
-        if (!existing) {
+        if (!existing && insertedIds.length > 0) {
             this.scopedCatalogs.set(key, {
                 context: { ...context },
                 catalogs: scoped,
             });
         }
+        return { key, context: { ...context }, catalogs: scoped, insertedIds };
+    }
+    removeScopedInsertion(insertion) {
+        const current = this.scopedCatalogs.get(insertion.key);
+        if (current?.catalogs !== insertion.catalogs)
+            return false;
+        let removed = false;
+        for (const insertedId of insertion.insertedIds) {
+            removed = current.catalogs.delete(insertedId) || removed;
+        }
+        if (current.catalogs.size === 0) {
+            this.scopedCatalogs.delete(insertion.key);
+        }
+        return removed;
+    }
+    registerCatalogs(context, catalogs) {
+        const insertion = this.insertScopedCatalogs(context, catalogs);
         // Only when something was actually inserted: an all-duplicates call changes
         // nothing, and waking every reader to re-resolve for that would make the
         // signal untrustworthy.
-        if (insertedIds.length > 0) {
+        if (insertion && insertion.insertedIds.length > 0) {
             this.emitCatalogsChange({ reason: "scoped-registered", context });
         }
+        let active = true;
         return () => {
-            const current = this.scopedCatalogs.get(key);
-            if (current?.catalogs !== scoped)
+            if (!active)
                 return;
-            for (const insertedId of insertedIds) {
-                current.catalogs.delete(insertedId);
+            active = false;
+            if (insertion && this.removeScopedInsertion(insertion)) {
+                this.emitCatalogsChange({ reason: "scoped-removed", context });
+            }
+        };
+    }
+    /**
+     * Register every catalog carried by one mounted item or passage as one
+     * owner-level transaction.
+     *
+     * The resolver owns the entity walk and emits one post-mutation signal, so a
+     * reader never observes only the root or only the model half of an owner.
+     */
+    registerOwner(registration) {
+        const { owner, entity } = registration;
+        const context = catalogOwnerContextFor(owner);
+        const insertions = [];
+        let registrations = [];
+        try {
+            registrations = collectOwnerCatalogRegistrations(entity, owner);
+        }
+        catch (error) {
+            console.warn("[AccessibilityCatalogResolver] A mounted content owner could not be traversed for catalogs; the primary content remains available.", error);
+        }
+        for (const entry of registrations) {
+            try {
+                const insertion = this.insertScopedCatalogs(entry.context, entry.catalogs);
+                if (insertion)
+                    insertions.push(insertion);
             }
-            if (current.catalogs.size === 0) {
-                this.scopedCatalogs.delete(key);
+            catch (error) {
+                console.warn("[AccessibilityCatalogResolver] Invalid catalogs on a mounted content owner were ignored; the primary content and other valid catalogs remain available.", error);
             }
-            if (insertedIds.length > 0) {
+        }
+        const changed = insertions.some((insertion) => insertion.insertedIds.length > 0);
+        if (changed) {
+            this.emitCatalogsChange({ reason: "scoped-registered", context });
+        }
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            let removed = false;
+            for (const insertion of insertions) {
+                removed = this.removeScopedInsertion(insertion) || removed;
+            }
+            if (removed) {
                 this.emitCatalogsChange({ reason: "scoped-removed", context });
             }
         };
     }
+    /** Bind catalog reads and change observation to one content owner. */
+    forOwner(context) {
+        const ownerContext = { ...context };
+        return Object.freeze({
+            snapshot: () => this.createOwnerSnapshot(ownerContext),
+            onChange: (listener) => this.onCatalogsChange((event) => {
+                if (this.catalogChangeAffectsOwner(event, ownerContext))
+                    listener();
+            }),
+        });
+    }
     /**
      * Add item-level catalogs (called when rendering a new item)
      */
@@ -353,6 +457,61 @@ export class AccessibilityCatalogResolver {
         }
         return true;
     }
+    ownerScopedCatalogEntries(context) {
+        const entries = [];
+        const exact = this.scopedCatalogs.get(this.getOwnerKey(context));
+        if (exact)
+            entries.push(...exact.catalogs.entries());
+        for (const owner of this.scopedCatalogs.values()) {
+            if (owner === exact)
+                continue;
+            if (!this.isCompatibleOwnerContext(owner.context, context))
+                continue;
+            entries.push(...owner.catalogs.entries());
+        }
+        return entries;
+    }
+    createOwnerSnapshot(context) {
+        const cards = [];
+        const entries = this.ownerScopedCatalogEntries(context);
+        if (context.ownerKind === "global") {
+            entries.push(...this.assessmentCatalogs.entries());
+        }
+        for (const [catalogId, catalog] of entries) {
+            for (const card of catalog.cards) {
+                try {
+                    cards.push(Object.freeze({
+                        catalogId,
+                        card: cloneAndFreezeCatalogValue(card),
+                    }));
+                }
+                catch (error) {
+                    const key = `${this.getOwnerKey(context)}\u0000${catalogId}`;
+                    if (!this.reportedSnapshotProblems.has(key)) {
+                        this.reportedSnapshotProblems.add(key);
+                        console.warn(`[AccessibilityCatalogResolver] Catalog "${catalogId}" contains a card that cannot be exposed in an owner snapshot; that card was ignored.`, error);
+                    }
+                }
+            }
+        }
+        return Object.freeze({ cards: Object.freeze(cards) });
+    }
+    catalogChangeAffectsOwner(event, context) {
+        if (!event.context)
+            return false;
+        if (this.isCompatibleOwnerContext(event.context, context))
+            return true;
+        // `registerOwner` emits once at the entity root after registering root and
+        // model catalogs transactionally. A model-bound reader belongs to that same
+        // owner family and must observe the root event too.
+        if (context.ownerKind === "itemModel" &&
+            context.modelId &&
+            event.context.ownerKind === "itemModel" &&
+            !event.context.modelId) {
+            return this.isCompatibleOwnerContext({ ...event.context, modelId: context.modelId }, context);
+        }
+        return false;
+    }
     // The single funnel every registration path runs through — the constructor and
     // `addItemCatalogs` by way of `indexCatalogs`, and `registerCatalogs`
     // directly — which is why the unknown-type report lives here rather than at
@@ -487,6 +646,15 @@ export class AccessibilityCatalogResolver {
                     allLanguages.add(card.language);
             }
         }
+        for (const owner of this.scopedCatalogs.values()) {
+            for (const catalog of owner.catalogs.values()) {
+                for (const card of catalog.cards) {
+                    allTypes.add(card.catalog);
+                    if (card.language)
+                        allLanguages.add(card.language);
+                }
+            }
+        }
         return {
             totalCatalogs: this.assessmentCatalogs.size +
                 this.itemCatalogs.size +
@@ -535,6 +703,7 @@ export class AccessibilityCatalogResolver {
         this.itemCatalogs.clear();
         this.scopedCatalogs.clear();
         this.sanitizedSpokenCache.clear();
+        this.reportedSnapshotProblems.clear();
     }
     /**
      * Destroy and cleanup

package/dist/services/TTSService.d.ts

@@ -68,6 +68,13 @@ export declare class TTSService {
     private sentenceHighlightSegments;
     private currentSeekSegmentIndex;
     private activeSentenceStartOffset;
+    private playbackStartDeferredRunId;
+    private pendingPlaybackStartHighlights;
+    private playbackStartBarrierCleanup;
+    private playbackRateWriteQueue;
+    private playbackRateRequestId;
+    private pendingPlaybackRateRequest;
+    private activePlaybackRate;
     private activeHighlightMode;
     private lastRenderedRegionTarget;
     private telemetryReporter;
@@ -75,6 +82,10 @@ export declare class TTSService {
     private static readonly debugEnabled;
     constructor();
     private debugLog;
+    private clearPlaybackStartBarrier;
+    private notifyPlaybackStarted;
+    private installPlaybackStartBarrier;
+    private runWhenPlaybackStarts;
     private emitTelemetry;
     /**
      * Initialize TTS service with a provider