@pie-players/pie-players-shared 0.3.74 → 1.0.0-beta.0

package/dist/pie/instrumentation-event-map.js

@@ -1,15 +1,7 @@
 export const TOOLKIT_INSTRUMENTATION_EVENT_MAP = [
-    // M6 canonical readiness vocabulary. The four-stage canonical list
-    // (`composed`, `engine-ready`, `interactive`, `disposed`) is identical
-    // across the toolkit CE and the layout CEs — the M6 retro removed the
-    // `attached`, `runtime-bound`, and `ui-rendered` stages because they
-    // had zero internal or external consumers. Hosts listen for the
-    // DOM-prefixed name directly (`pie-stage-change`); the instrumentation
-    // bridge forwards the same name to telemetry.
-    {
-        sourceEventName: "pie-stage-change",
-        instrumentationEventName: "pie-toolkit-stage-change",
-    },
+    // The toolkit emits no stage events: the section player's runtime
+    // engine dispatches `pie-stage-change` on the layout element, above the
+    // toolkit, and the section map tracks it there.
     {
         sourceEventName: "runtime-owned",
         instrumentationEventName: "pie-toolkit-runtime-owned",
@@ -18,6 +10,10 @@ export const TOOLKIT_INSTRUMENTATION_EVENT_MAP = [
         sourceEventName: "runtime-inherited",
         instrumentationEventName: "pie-toolkit-runtime-inherited",
     },
+    {
+        sourceEventName: "runtime-ready",
+        instrumentationEventName: "pie-toolkit-runtime-ready",
+    },
     {
         sourceEventName: "toolkit-ready",
         instrumentationEventName: "pie-toolkit-ready",
@@ -32,13 +28,10 @@ export const TOOLKIT_INSTRUMENTATION_EVENT_MAP = [
     },
 ];
 export const SECTION_INSTRUMENTATION_EVENT_MAP = [
-    // M6 canonical readiness vocabulary. Hosts listen for the DOM-prefixed
-    // names directly (`pie-stage-change`, `pie-loading-complete`); the
-    // instrumentation bridge forwards the same names to telemetry. The
-    // readiness alias mappings (`readiness-change`, `interaction-ready`,
-    // `ready`) and the `section-controller-ready` mapping were removed
-    // alongside their DOM-event surfaces. `session-changed` stays off the
-    // bridge for the reason the item map gives below.
+    // The runtime engine dispatches `pie-stage-change` and
+    // `pie-loading-complete` on the layout element; `framework-error`
+    // bubbles to it from the player's toolkit. `session-changed` stays off
+    // the bridge for the reason the item map gives below.
     {
         sourceEventName: "pie-stage-change",
         instrumentationEventName: "pie-section-stage-change",

package/dist/pie/item-controller.js

@@ -45,7 +45,11 @@ export class ItemController {
     setSession(input, options = {}) {
         const next = normalizeSessionContainer(input, this.sessionId);
         const allowMetadataOverwrite = options.allowMetadataOverwrite ?? false;
+        // The guard keeps a response from metadata churn on the same session. A
+        // session with another id is a new attempt or item, and replaces it.
+        const sameSession = next.id === "" || this.session.id === "" || next.id === this.session.id;
         if (!allowMetadataOverwrite &&
+            sameSession &&
             hasResponseValue(this.session) &&
             !hasResponseValue(next) &&
             !hasResponseField(next)) {

package/dist/pie/item-session-contract.js

@@ -1,3 +1,4 @@
+import { isPlainRecord } from "../object/index.js";
 const DEFAULT_SESSION_ID = "";
 const METADATA_ONLY_SESSION_KEYS = new Set([
     "complete",
@@ -146,9 +147,6 @@ export function hasResponseField(value) {
     }
     return false;
 }
-function isPlainObject(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function getMetadataComponent(sessionDetail, candidate) {
     if (typeof sessionDetail.component === "string")
         return sessionDetail.component;
@@ -194,7 +192,7 @@ function mergeSessionEntry(existing, incoming) {
     for (const [key, value] of Object.entries(incoming)) {
         const previous = merged[key];
         merged[key] =
-            isPlainObject(previous) && isPlainObject(value)
+            isPlainRecord(previous) && isPlainRecord(value)
                 ? mergeSessionEntry(previous, value)
                 : value;
     }
@@ -334,7 +332,7 @@ function classifyItemSessionChange(args) {
     };
 }
 function hostContainerEntries(hostContainer) {
-    if (!isPlainObject(hostContainer)) {
+    if (!isPlainRecord(hostContainer)) {
         return null;
     }
     // A frozen container is not a live view of anything, and a shared immutable
@@ -355,7 +353,7 @@ function hostContainerEntries(hostContainer) {
     return null;
 }
 function sessionEntryId(value) {
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         return null;
     }
     const id = value.id;
@@ -405,7 +403,7 @@ export function ensureHostSessionEntries(hostContainer, entryIds) {
  */
 export function projectSessionIntoHostContainer(hostContainer, liveSession) {
     const entries = hostContainerEntries(hostContainer);
-    if (!entries || !isPlainObject(hostContainer)) {
+    if (!entries || !isPlainRecord(hostContainer)) {
         return false;
     }
     const live = normalizeItemSessionContainer(liveSession);
@@ -417,11 +415,11 @@ export function projectSessionIntoHostContainer(hostContainer, liveSession) {
     }
     for (const nextEntry of live.data) {
         const id = sessionEntryId(nextEntry);
-        if (!id || !isPlainObject(nextEntry)) {
+        if (!id || !isPlainRecord(nextEntry)) {
             continue;
         }
         const target = entries.find((entry) => sessionEntryId(entry) === id);
-        if (!isPlainObject(target)) {
+        if (!isPlainRecord(target)) {
             entries.push({ ...nextEntry });
             wrote = true;
             continue;

package/dist/pie/logger.d.ts

@@ -61,3 +61,9 @@ declare global {
  * Check if debug mode is enabled globally
  */
 export declare function isGlobalDebugEnabled(): boolean;
+/**
+ * Read-aloud's debug flag: `PIE_TTS_DEBUG=1` in the environment, or
+ * `globalThis.__PIE_TTS_DEBUG__ = true` in a page. Every read-aloud logger is
+ * created with it, and reads it on each debug line.
+ */
+export declare function isTtsDebugEnabled(): boolean;

package/dist/pie/logger.js

@@ -42,3 +42,13 @@ export function createPieLogger(namespace, debugEnabledFn) {
 export function isGlobalDebugEnabled() {
     return typeof window !== "undefined" && window.PIE_DEBUG === true;
 }
+/**
+ * Read-aloud's debug flag: `PIE_TTS_DEBUG=1` in the environment, or
+ * `globalThis.__PIE_TTS_DEBUG__ = true` in a page. Every read-aloud logger is
+ * created with it, and reads it on each debug line.
+ */
+export function isTtsDebugEnabled() {
+    const scope = globalThis;
+    return (scope.process?.env?.PIE_TTS_DEBUG === "1" ||
+        scope.__PIE_TTS_DEBUG__ === true);
+}

package/dist/pie/math-assets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where the MathJax adapter's copies load MathJax's fonts, speech worker and,
+ * on its npm build, MathJax itself from, and whether math is in the tab order.
+ * Every copy of `@pie-element/shared-math-rendering-mathjax` reads these from
+ * the legacy renderer's page options as it starts MathJax, on its first render,
+ * so they are set before any element renders. See
+ * https://github.com/pie-framework/pie-elements-ng/blob/develop/docs/MATH-RENDERING.md#assets
+ */
+export interface MathAssetOptions {
+    /**
+     * An npm root: a URL under which `<package>@<version>/<path>` serves that
+     * file of the package, such as `https://cdn.jsdelivr.net/npm`. A relative URL
+     * resolves against the page.
+     */
+    assetRoot?: string | URL;
+    /**
+     * The directory of `speech-worker.js` and its `mathmaps/`, by default
+     * `mathjax@<version>/sre` under the asset root.
+     */
+    speechPath?: string | URL;
+    /**
+     * The URL of individual files by npm path, `<package>@<version>/<path>`: a
+     * listed file loads from its URL, the rest from the asset root. A bundle lists
+     * each file it ships as `new URL("./…", import.meta.url)`, which its host's
+     * bundler emits, and needs no root. Read by the adapter's browser build, for
+     * its fonts, speech worker and speech rules.
+     */
+    assetUrls?: Readonly<Record<string, string | URL>>;
+    /**
+     * The speech locales the MathJax menu lists, by id (`["en", "es"]`), or by id
+     * with the label it shows. Unset, it lists every locale SRE ships.
+     */
+    speechLocales?: readonly string[] | Readonly<Record<string, string>>;
+    /**
+     * Puts typeset math in the keyboard tab order, for the MathJax menu and its
+     * explorer. Off by default.
+     */
+    inTabOrder?: boolean;
+}
+/** Why `options` is not a `MathAssetOptions`, or `undefined` when it is. */
+export declare function mathAssetOptionsError(options: unknown): string | undefined;
+/**
+ * Writes `options` to the page options, keeping the ones it leaves unset and
+ * the files of `assetUrls` it does not list.
+ */
+export declare function setMathAssetOptions(options: MathAssetOptions): void;
+/** The asset root the page options set, if any. */
+export declare function pageMathAssetRoot(): string | undefined;

package/dist/pie/math-assets.js

@@ -0,0 +1,81 @@
+/**
+ * Where the MathJax adapter's copies load MathJax's fonts, speech worker and,
+ * on its npm build, MathJax itself from, and whether math is in the tab order.
+ * Every copy of `@pie-element/shared-math-rendering-mathjax` reads these from
+ * the legacy renderer's page options as it starts MathJax, on its first render,
+ * so they are set before any element renders. See
+ * https://github.com/pie-framework/pie-elements-ng/blob/develop/docs/MATH-RENDERING.md#assets
+ */
+/** The legacy renderer's page options, which the adapter reads as well. */
+const PAGE_OPTIONS_KEY = "@pie-lib/math-rendering@2";
+const isUrl = (value) => (typeof value === "string" && value !== "") || value instanceof URL;
+/** Why `options` is not a `MathAssetOptions`, or `undefined` when it is. */
+export function mathAssetOptionsError(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        return "must be an object";
+    }
+    const { assetRoot, speechPath, assetUrls, speechLocales, inTabOrder } = options;
+    if (assetRoot !== undefined && !isUrl(assetRoot)) {
+        return `assetRoot must be a URL, got ${JSON.stringify(assetRoot)}`;
+    }
+    if (speechPath !== undefined && !isUrl(speechPath)) {
+        return `speechPath must be a URL, got ${JSON.stringify(speechPath)}`;
+    }
+    if (assetUrls !== undefined &&
+        (!assetUrls ||
+            typeof assetUrls !== "object" ||
+            Array.isArray(assetUrls) ||
+            !Object.values(assetUrls).every(isUrl))) {
+        return "assetUrls must map npm paths to URLs";
+    }
+    if (speechLocales !== undefined) {
+        const listed = Array.isArray(speechLocales)
+            ? speechLocales
+            : speechLocales && typeof speechLocales === "object"
+                ? Object.values(speechLocales)
+                : null;
+        if (!listed || listed.some((entry) => typeof entry !== "string" || !entry)) {
+            return "speechLocales must be locale ids, or locale ids mapped to their labels";
+        }
+    }
+    if (inTabOrder !== undefined && typeof inTabOrder !== "boolean") {
+        return `inTabOrder must be a boolean, got ${JSON.stringify(inTabOrder)}`;
+    }
+    return undefined;
+}
+/**
+ * Writes `options` to the page options, keeping the ones it leaves unset and
+ * the files of `assetUrls` it does not list.
+ */
+export function setMathAssetOptions(options) {
+    if (typeof window === "undefined")
+        return;
+    const host = window;
+    const page = (host[PAGE_OPTIONS_KEY] ??= {});
+    const opts = (page.opts ??= {});
+    if (options.assetRoot !== undefined)
+        opts.assetRoot = String(options.assetRoot);
+    if (options.speechPath !== undefined)
+        opts.speechPath = String(options.speechPath);
+    if (options.assetUrls !== undefined) {
+        const listed = opts.assetUrls && typeof opts.assetUrls === "object" ? opts.assetUrls : {};
+        opts.assetUrls = {
+            ...listed,
+            ...Object.fromEntries(Object.entries(options.assetUrls).map(([path, url]) => [path, String(url)])),
+        };
+    }
+    if (options.speechLocales !== undefined) {
+        opts.speechLocales = Array.isArray(options.speechLocales)
+            ? [...options.speechLocales]
+            : { ...options.speechLocales };
+    }
+    if (options.inTabOrder !== undefined)
+        opts.inTabOrder = options.inTabOrder;
+}
+/** The asset root the page options set, if any. */
+export function pageMathAssetRoot() {
+    if (typeof window === "undefined")
+        return undefined;
+    const root = window[PAGE_OPTIONS_KEY]?.opts?.assetRoot;
+    return typeof root === "string" && root ? root : undefined;
+}

package/dist/pie/resource-monitor.d.ts

@@ -69,7 +69,9 @@ export interface MediaRetryReadyDetail extends ResourceMonitorEventDetail {
     mediaTag: "audio" | "video";
 }
 /**
- * Tracks resource loads and provides retry capability
+ * Tracks the resource loads of one container and retries failed ones with
+ * exponential backoff and cache-busting URLs. The events it dispatches are
+ * listed in the event contract above.
  */
 export declare class ResourceMonitor {
     private config;
@@ -77,13 +79,20 @@ export declare class ResourceMonitor {
     private observer;
     private mutationObserver;
     private errorHandler;
+    /** Retries scheduled so far, keyed by the URL without retry parameters. */
     private retryAttempts;
+    /** Elements that failed to load each URL; a retry reloads the first one. */
     private retryTargets;
     private container;
-    private isBrowser;
+    private readonly isBrowser;
+    /** URLs referenced inside the container; timing entries for others are ignored. */
     private containerResources;
     private provider;
     private started;
+    /**
+     * Bumped on every start and stop, so timers and listeners captured in an
+     * earlier lifecycle see themselves as stale.
+     */
     private lifecycleVersion;
     private pendingRetryTimers;
     private retryInFlight;
@@ -116,13 +125,10 @@ export declare class ResourceMonitor {
      * Start monitoring resources in the given container
      */
     start(container: HTMLElement): void;
-    /**
-     * Stop monitoring and clean up
-     */
     stop(): void;
     /**
-     * Set up MutationObserver to track DOM changes within container
-     * This allows us to know which resources belong to our container
+     * Tracks resources added to the container, or retargeted inside it, so
+     * timing entries can be attributed to this container.
      */
     private setupMutationObserver;
     /**
@@ -137,45 +143,38 @@ export declare class ResourceMonitor {
      * Set up PerformanceObserver to track resource loading timing
      */
     private setupPerformanceObserver;
-    /**
-     * Handle resource timing entry
-     */
     private handleResourceTiming;
+    private logResourceTiming;
     private isLifecycleActive;
     private clearRetryTracking;
     private clearPendingMediaCheck;
     private getRetryTargets;
     private getPrimaryRetryTarget;
-    /**
-     * Handle successful resource load
-     */
     private handleSuccessfulLoad;
     private resolveMediaTarget;
     private resolveMediaTargetsForUrl;
     private normalizeRetrySuccessResourceType;
     private isMediaRetryRecovered;
     private finalizeRetrySuccess;
+    /**
+     * A retried media fetch that succeeds does not mean the element recovered:
+     * it can still hold an error or no source. Success waits until a media
+     * target reports metadata, checked on `loadedmetadata`/`canplay` and by
+     * polling, and the reconciliation timeout bounds the wait.
+     */
     private reconcileMediaRetrySuccess;
+    private completeMediaRetry;
     private handleMediaRetryReconciliationTimeout;
     private dispatchMediaRetryReady;
-    /**
-     * Handle failed resource load
-     */
     private handleFailedLoad;
     /**
-     * Check if resource is relevant to our container
-     * Uses container-scoped tracking via MutationObserver
-     * Also retroactively checks if resource belongs to container if not yet tracked
+     * Whether a timing entry belongs to this container. Timing entries carry
+     * absolute URLs, so a suffix match against a tracked URL also counts. The
+     * buffered observer also reports resources that loaded before the scan
+     * tracked them; those are looked up in the container's DOM.
      */
     private isRelevantResource;
-    /**
-     * Check if a resource URL actually belongs to our container by checking DOM elements
-     * This is a fallback for resources that loaded before MutationObserver scanned
-     */
     private isResourceInContainer;
-    /**
-     * Set up error event handler for resource loading failures
-     */
     private setupErrorHandler;
     /**
      * Check if element is a resource element
@@ -189,18 +188,21 @@ export declare class ResourceMonitor {
      * Handle permanent resource failure after all retries exhausted
      */
     private handlePermanentFailure;
-    /**
-     * Log retry schedule information
-     */
+    /** Exponential backoff, capped at `maxRetryDelay`. */
+    private retryDelay;
     private logRetrySchedule;
     /**
-     * Retry loading a failed resource with exponential backoff
+     * Reloads one element under a cache-busting URL. Media elements also need
+     * `load()`, since changing a `<source>` alone does not restart the fetch.
      */
     private performRetryLoadAttempt;
-    private retryResourceLoad;
     /**
-     * Dispatch a custom event from the container
+     * Schedules the next retry of a failed resource with exponential backoff,
+     * or fails it permanently once `maxRetries` is spent. Every failing element
+     * joins the URL's retry targets; concurrent errors for one URL share the
+     * retry already in flight.
      */
+    private retryResourceLoad;
     private dispatchEvent;
     /**
      * Get current retry statistics