@pie-players/pie-players-shared 0.3.73 → 0.3.75

package/dist/pie/elements-rendered.js

@@ -0,0 +1,96 @@
+/**
+ * When the PIE elements of a player have rendered.
+ *
+ * An element renders after its model and session are assigned, in a task of
+ * its own: legacy React elements debounce the render and commit through the
+ * React scheduler, so the commit lands tens of milliseconds after the
+ * assignment. No event marks it in both element generations — `model-set` is
+ * dispatched by about half of them, some before rendering — so this reads the
+ * DOM.
+ *
+ * An element has rendered once it holds content, and so has every custom
+ * element defined below it: an `ebsr` paints its parts, which then render
+ * themselves. Some elements render nothing, a rubric for a student among them,
+ * so an element still empty when the subtree has had no mutation for
+ * `quietMs` counts as rendered. A render slower than that window, with no
+ * mutation before it, is missed rather than waited for.
+ */
+/** Longer than the 50ms render debounce legacy elements use, plus a scheduler task. */
+export const ELEMENT_RENDER_QUIET_MS = 200;
+function hasContent(element) {
+    if (element.firstElementChild || element.shadowRoot?.firstChild)
+        return true;
+    return Boolean(element.textContent?.trim());
+}
+function isDefinedCustomElement(element) {
+    return (element.localName.includes("-") &&
+        customElements.get(element.localName) !== undefined);
+}
+function hasRendered(element) {
+    if (!element.isConnected)
+        return true;
+    if (!hasContent(element))
+        return false;
+    for (const nested of element.querySelectorAll("*")) {
+        if (isDefinedCustomElement(nested) && !hasContent(nested))
+            return false;
+    }
+    return true;
+}
+/** The elements of `configs` in `root`, found as `updatePieElements` finds them. */
+function renderedElements(root, configs) {
+    const elements = [];
+    for (const config of configs) {
+        const ids = new Set((config.models ?? []).map((model) => model?.id));
+        for (const tag of Object.keys(config.elements ?? {})) {
+            // An undefined tag renders nothing until its bundle loads.
+            if (!customElements.get(tag))
+                continue;
+            for (const element of root.querySelectorAll(tag)) {
+                if (ids.has(element.id))
+                    elements.push(element);
+            }
+        }
+    }
+    return elements;
+}
+/**
+ * Resolves once every element of `configs` in `root` has rendered, or when
+ * `signal` aborts. Never rejects.
+ */
+export function elementsRendered(root, configs, signal, quietMs = ELEMENT_RENDER_QUIET_MS) {
+    const elements = renderedElements(root, configs);
+    const allRendered = () => elements.every(hasRendered);
+    if (signal.aborted ||
+        allRendered() ||
+        typeof MutationObserver === "undefined") {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        let quiet;
+        const observer = new MutationObserver(() => {
+            if (allRendered()) {
+                done();
+                return;
+            }
+            armQuiet();
+        });
+        function armQuiet() {
+            clearTimeout(quiet);
+            quiet = setTimeout(done, quietMs);
+        }
+        function done() {
+            clearTimeout(quiet);
+            observer.disconnect();
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+        observer.observe(root, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+        });
+        signal.addEventListener("abort", done);
+        armQuiet();
+    });
+}

package/dist/pie/index.d.ts

@@ -14,28 +14,26 @@ export { observePieElements, pieElementContextsWithin, } from "./element-observe
 export type { PieElementContext, PieElementContextSource, } from "./element-observer.js";
 export { createAuthoringAssetEventManager, initializeAuthoringConfigures, resolveConfigureConfiguration, validateAuthoringModels, } from "./authoring.js";
 export type { AuthoringMediaHandlers, AuthoringValidationResult, InitializedConfigureModel, } from "./authoring.js";
-export { initializeMathRendering, renderMath, setMathRenderer, } from "./math-rendering.js";
+export { initializeMathRendering, setMathRenderer, } from "./math-rendering.js";
 export { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
 export type { AttachInstrumentationEventBridgeArgs } from "./instrumentation-event-bridge.js";
 export { resolveInstrumentationProvider } from "./instrumentation-provider-resolution.js";
-export { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
-export type { LoadingCompleteDetail, Stage, StageChangeDetail, StageSourceCe, StageStatus, } from "./stages.js";
-export { createStageTracker } from "./stage-tracker.js";
-export type { CreateStageTrackerOptions, StageTracker, } from "./stage-tracker.js";
+export { STAGES } from "./stages.js";
+export type { LoadingCompleteDetail, Stage, StageChangeDetail, StageStatus, } from "./stages.js";
 export { ASSESSMENT_INSTRUMENTATION_EVENT_MAP, ITEM_INSTRUMENTATION_EVENT_MAP, SECTION_INSTRUMENTATION_EVENT_MAP, TOOLKIT_INSTRUMENTATION_EVENT_MAP, } from "./instrumentation-event-map.js";
 export type { InstrumentationEventMapping } from "./instrumentation-event-map.js";
 export type { ItemControllerOptions } from "./item-controller.js";
 export { ItemController, normalizeItemSessionContainer, } from "./item-controller.js";
 export type { ItemSessionContainer as CanonicalItemSessionContainer, ItemSessionUpdateIntent, NormalizedItemSessionChange, } from "./item-session-contract.js";
-export { ensureHostSessionEntries, hasLearnerResponse, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
+export { ensureHostSessionEntries, hasLearnerResponse, hasResponseField, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
 export type { ItemSessionContainer, ItemSessionStorageStrategy, } from "./item-controller-storage.js";
 export { MemoryItemSessionStorage, SessionStorageItemSessionStorage, } from "./item-controller-storage.js";
-export { SESSION_COMMIT_METHOD, bindPageLifecycleCommit, commitPendingSessions, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
+export { SESSION_COMMIT_METHOD, bindPageLifecycleCommit, commitPendingSessions, flushPendingSessionNotifications, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
 export type { BindPageLifecycleCommitOptions, CommitPendingSessionsOptions, CommitPendingSessionsResult, SessionCommitReason, } from "./session-commit.js";
+export { createSessionSnapshot, isSessionSnapshotEnabled, isSnapshotIdentitySpecific, sessionSnapshotKey, sessionStorageSnapshotStore, } from "./session-snapshot.js";
+export type { SessionSnapshot, SessionSnapshotConfig, SessionSnapshotIdentity, SessionSnapshotRecord, SessionSnapshotStore, } from "./session-snapshot.js";
 export type { PieLogger } from "./logger.js";
-export { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
-export type { ItemData, PiePlayerConfig, PiePlayerElements, } from "./player-initializer.js";
-export { buildApiParams, buildEventListenersMap, ensurePiePlayerLoaded, extractPassageMarkup, fetchItemData, initializePiePlayer, } from "./player-initializer.js";
+export { createPieLogger, isGlobalDebugEnabled, isTtsDebugEnabled, } from "./logger.js";
 export { pieRegistry } from "./registry.js";
 export { findPieController, scorePieItem } from "./scoring.js";
 export type { Entry, EventListeners, EventListenersMap, LoadPieElementsOptions, PieElement, PieRegistry, UpdatePieElementOptions, } from "./types.js";

package/dist/pie/index.js

@@ -20,21 +20,20 @@ export { initializePiesFromLoadedBundle, loadBundleFromString, loadPieModule, lo
 // owns.
 export { observePieElements, pieElementContextsWithin, } from "./element-observer.js";
 export { createAuthoringAssetEventManager, initializeAuthoringConfigures, resolveConfigureConfiguration, validateAuthoringModels, } from "./authoring.js";
-export { initializeMathRendering, renderMath, setMathRenderer, } from "./math-rendering.js";
+export { initializeMathRendering, setMathRenderer, } from "./math-rendering.js";
 export { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
 export { resolveInstrumentationProvider } from "./instrumentation-provider-resolution.js";
-// Canonical stage vocabulary (M6). Both `<pie-section-player-*>` and
-// `<pie-assessment-toolkit>` share this primitive so the
-// `pie-stage-change` event family stays coherent across CE shapes.
-export { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
-export { createStageTracker } from "./stage-tracker.js";
+// Stage vocabulary of the section player's `pie-stage-change` event.
+export { STAGES } from "./stages.js";
 export { ASSESSMENT_INSTRUMENTATION_EVENT_MAP, ITEM_INSTRUMENTATION_EVENT_MAP, SECTION_INSTRUMENTATION_EVENT_MAP, TOOLKIT_INSTRUMENTATION_EVENT_MAP, } from "./instrumentation-event-map.js";
 export { ItemController, normalizeItemSessionContainer, } from "./item-controller.js";
-export { ensureHostSessionEntries, hasLearnerResponse, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
+export { ensureHostSessionEntries, hasLearnerResponse, hasResponseField, hasResponseValue, normalizeItemSessionChange, projectSessionIntoHostContainer, } from "./item-session-contract.js";
 export { MemoryItemSessionStorage, SessionStorageItemSessionStorage, } from "./item-controller-storage.js";
-export { SESSION_COMMIT_METHOD, bindPageLifecycleCommit, commitPendingSessions, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
-export { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
-export { buildApiParams, buildEventListenersMap, ensurePiePlayerLoaded, extractPassageMarkup, fetchItemData, initializePiePlayer, } from "./player-initializer.js";
+export { SESSION_COMMIT_METHOD, bindPageLifecycleCommit, commitPendingSessions, flushPendingSessionNotifications, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
+// Opt-in device-local snapshot of a committed session, offered back to the host
+// after a crash rather than applied.
+export { createSessionSnapshot, isSessionSnapshotEnabled, isSnapshotIdentitySpecific, sessionSnapshotKey, sessionStorageSnapshotStore, } from "./session-snapshot.js";
+export { createPieLogger, isGlobalDebugEnabled, isTtsDebugEnabled, } from "./logger.js";
 // Registry
 export { pieRegistry } from "./registry.js";
 // Scoring

package/dist/pie/initialization.js

@@ -11,7 +11,7 @@ import { editorPostFix } from "../types/index.js";
 import { initializePieElement } from "./initialize-element.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { initializeMathRendering } from "./math-rendering.js";
-import { pieRegistry } from "./registry.js";
+import { pieRegistry, writeRegistryEntry } from "./registry.js";
 import { defineCustomElementSafely } from "./custom-element-define.js";
 import { validateCustomElementTag } from "./tag-names.js";
 import { BundleType, isCustomElementConstructor, isPieAvailable, Status, } from "./types.js";
@@ -38,6 +38,7 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
         config,
         session,
         ...(omitEnv ? {} : { env: options.env }),
+        bundleType: options.bundleType,
         container: options.container,
         ...(options.eventListeners?.[elementTagName] && {
             eventListeners: options.eventListeners[elementTagName],
@@ -119,30 +120,21 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                 : [],
             bundleType: options.bundleType,
         });
-        // Validate controller presence based on bundle type
-        if (!elementData.controller) {
-            if (options.bundleType === BundleType.clientPlayer) {
-                logger.error(`[registerPieElementsFromBundle] ❌ CRITICAL: No controller found for ${pkgStripped}!`);
-                logger.error(`[registerPieElementsFromBundle] Bundle type: ${options.bundleType} (controllers required)`);
-                throw new Error(`No controller found for ${pkgStripped}. client-player.js bundles MUST include controllers!`);
-            }
-            else {
-                logger.debug(`[registerPieElementsFromBundle] ℹ️ No controller found for ${pkgStripped} - using server-processed models (player.js bundle)`);
-            }
-        }
         {
-            // Register the element in our registry
+            // Register the element in our registry. A package without a
+            // controller, such as a legacy `@pie-element/protractor`, renders
+            // the model it is given under client-player.js too.
             logger.debug(`[registerPieElementsFromBundle] Registering ${elName} in registry${elementData.controller
                 ? " with controller"
-                : " (no controller - server-processed models)"}`);
-            registry[elementTagName] = {
+                : " (no controller; its model is used as given)"}`);
+            writeRegistryEntry({
                 package: pkg,
                 status: Status.loading,
                 tagName: elementTagName,
                 controller: elementData.controller || null,
                 config: elementData.config,
                 bundleType: options.bundleType,
-            };
+            });
             if (isCustomElementConstructor(elementData.Element)) {
                 defineCustomElementSafely(elementTagName, elementData.Element, `element tag in config.elements for ${String(pkg)}`);
                 // Initialize existing elements
@@ -155,13 +147,13 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                         session,
                         env: options.env,
                         eventListeners: options.eventListeners?.[elementTagName],
+                        bundleType: options.bundleType,
                     });
                 });
-                // Update registry status
-                registry[elementTagName] = {
+                writeRegistryEntry({
                     ...registry[elementTagName],
                     status: Status.loaded,
-                };
+                });
                 promises.push(customElements.whenDefined(elementTagName).then(() => {
                     logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
                 }));
@@ -297,9 +289,8 @@ export const loadPieModule = async (config, session, opts = {}) => {
                 }
                 catch (error) {
                     // `registerPieElementsFromBundle` throws synchronously for a
-                    // package missing from the bundle and for a client-player
-                    // bundle with no controller. Inside a DOM event handler that
-                    // throw reaches the window instead of the caller.
+                    // package missing from the bundle. Inside a DOM event handler
+                    // that throw reaches the window instead of the caller.
                     fail(error instanceof Error ? error : new Error(String(error)));
                 }
             });

package/dist/pie/initialize-element.d.ts

@@ -6,6 +6,7 @@
  */
 import type { ConfigEntity, Env } from "../types/index.js";
 import type { EventListeners, PieElement } from "./types.js";
+import { BundleType } from "./types.js";
 /**
  * Bind `element` to the model in `options.config` whose `id` matches it.
  *
@@ -20,4 +21,6 @@ export declare const initializePieElement: (element: PieElement, options: {
     session: any[];
     env?: Env;
     eventListeners?: EventListeners;
+    /** The delivering player's bundle type, see `findPieController`. */
+    bundleType?: BundleType;
 }) => boolean;

package/dist/pie/initialize-element.js

@@ -4,7 +4,6 @@
  * Split out of `initialization.ts` so the late-arrival observer in
  * `element-observer.ts` can reuse it without importing the bundle loaders.
  */
-import { wrapModelRichContent } from "../security/wrap-model-rich-content.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { pieRegistry } from "./registry.js";
 import { findPieController } from "./scoring.js";
@@ -21,7 +20,7 @@ const logger = createPieLogger("pie-initialize-element", () => isGlobalDebugEnab
  * separately — uses that to stop at the config the element belongs to.
  */
 export const initializePieElement = (element, options) => {
-    const { config, session, env, eventListeners } = options;
+    const { config, session, env, eventListeners, bundleType } = options;
     if (element.__pieInitialized) {
         return true;
     }
@@ -45,7 +44,7 @@ export const initializePieElement = (element, options) => {
     element.__pieInitialized = true;
     logger.debug(`[initializePieElement] Session set for ${tagName}#${element.id}:`, elementSession);
     // Set model - use controller if available (client-player.js), or use server-processed model (player.js)
-    const controller = findPieController(tagName);
+    const controller = findPieController(tagName, bundleType);
     if (!env) {
         logger.error(`[initializePieElement] ❌ FATAL: No env provided for ${tagName}`);
         throw new Error(`No env provided for ${tagName}. PIE elements require an env object with mode and role.`);
@@ -61,7 +60,7 @@ export const initializePieElement = (element, options) => {
             role: env.role,
         });
         // Set model directly - server already processed it
-        element.model = wrapModelRichContent(model);
+        element.model = model;
     }
     else {
         // Controller available - run client-side processing (client-player.js bundle)

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

@@ -1,9 +1,31 @@
 import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 const logger = createPieLogger("instrumentation-event-bridge", () => isGlobalDebugEnabled());
+/**
+ * Telemetry attributes are data. A detail's live objects (a coordinator on
+ * `toolkit-ready`, an `Error` cause, a function) stay on the event for its
+ * listeners and are left out of the attributes; primitives, arrays and plain
+ * objects pass.
+ */
+function isAttributeValue(value) {
+    if (value === null)
+        return true;
+    const type = typeof value;
+    if (type === "function" || type === "symbol")
+        return false;
+    if (type !== "object" || Array.isArray(value))
+        return true;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
 function normalizeEventDetail(detail) {
     if (detail && typeof detail === "object") {
-        return detail;
+        const attributes = {};
+        for (const [key, value] of Object.entries(detail)) {
+            if (isAttributeValue(value))
+                attributes[key] = value;
+        }
+        return attributes;
     }
     if (typeof detail === "undefined") {
         return {};

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,12 +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.
+    // 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",
@@ -46,14 +40,6 @@ export const SECTION_INSTRUMENTATION_EVENT_MAP = [
         sourceEventName: "pie-loading-complete",
         instrumentationEventName: "pie-section-loading-complete",
     },
-    {
-        sourceEventName: "session-changed",
-        instrumentationEventName: "pie-section-session-changed",
-    },
-    {
-        sourceEventName: "composition-changed",
-        instrumentationEventName: "pie-section-composition-changed",
-    },
     {
         sourceEventName: "framework-error",
         instrumentationEventName: "pie-section-framework-error",

package/dist/pie/instrumentation-provider-resolution.d.ts

@@ -1,6 +1,7 @@
+import type { InstrumentationProvider } from "../instrumentation/types.js";
 export declare function resolveInstrumentationProvider(args: {
     runtimePlayer?: unknown;
     player?: unknown;
     debug?: boolean;
     component?: string;
-}): unknown;
+}): InstrumentationProvider | undefined;

package/dist/pie/instrumentation-provider-resolution.js

@@ -37,7 +37,6 @@ const logger = createPieLogger("instrumentation-provider-resolution", () => isGl
 function getDefaultInstrumentationProvider() {
     if (!defaultProvider) {
         defaultProvider = new NewRelicInstrumentationProvider();
-        // New Relic provider sets readiness based on window.newrelic.
         void defaultProvider.initialize();
     }
     return defaultProvider;

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.d.ts

@@ -1,3 +1,4 @@
+import type { SessionCommitReason } from "./session-commit.js";
 export type ItemSessionContainer = {
     id: string;
     data: unknown[];
@@ -8,7 +9,14 @@ export type NormalizedItemSessionChange = {
     session: ItemSessionContainer | null;
     intent: ItemSessionUpdateIntent;
     component?: string;
+    /**
+     * The id of the element whose change this is: the detail's `elementId`, or
+     * the `id` of an element session record carried as `session`.
+     */
+    elementId?: string;
     complete?: boolean;
+    /** The detail's `sessionCommitReason`, when the change is a commit. */
+    sessionCommitReason?: SessionCommitReason;
 };
 export declare function normalizeItemSessionContainer(input: unknown, fallbackSessionId?: string): ItemSessionContainer;
 export declare function hasResponseValue(value: unknown): boolean;

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

@@ -2,6 +2,7 @@ const DEFAULT_SESSION_ID = "";
 const METADATA_ONLY_SESSION_KEYS = new Set([
     "complete",
     "component",
+    "elementId",
     "timestamp",
     "sourceRuntimeId",
 ]);
@@ -162,6 +163,18 @@ function getMetadataComplete(sessionDetail, candidate) {
         return candidate.complete;
     return undefined;
 }
+/**
+ * `elementRecord` is an element's own session record, whose `id` is the
+ * element's; an item session container's `id` is the item session's.
+ */
+function withElementId(sessionDetail, elementRecord) {
+    const elementId = typeof sessionDetail.elementId === "string" && sessionDetail.elementId
+        ? sessionDetail.elementId
+        : typeof elementRecord?.id === "string" && elementRecord.id
+            ? elementRecord.id
+            : undefined;
+    return elementId ? { elementId } : {};
+}
 function isElementIdentityOnlyPayload(candidate) {
     const candidateKeys = Object.keys(candidate);
     const hasIdentityKey = "id" in candidate || "element" in candidate;
@@ -211,6 +224,14 @@ export function mergeElementIntoSession(itemId, previousItemSession, entryId, en
     };
 }
 export function normalizeItemSessionChange(args) {
+    const change = classifyItemSessionChange(args);
+    const reason = args.sessionDetail
+        ?.sessionCommitReason;
+    return typeof reason === "string" && reason
+        ? { ...change, sessionCommitReason: reason }
+        : change;
+}
+function classifyItemSessionChange(args) {
     const sessionDetail = (args.sessionDetail || {});
     const actualSession = sessionDetail &&
         typeof sessionDetail === "object" &&
@@ -229,6 +250,7 @@ export function normalizeItemSessionChange(args) {
             session: null,
             intent: "metadata-only",
             component: getMetadataComponent(sessionDetail),
+            ...withElementId(sessionDetail),
             complete: getMetadataComplete(sessionDetail),
         };
     }
@@ -241,11 +263,7 @@ export function normalizeItemSessionChange(args) {
         const previousForMetadataComparison = alignPreviousSessionIdForRendererSnapshot(normalizedCandidate, previousNormalized);
         const sessionDetailKeys = Object.keys(sessionDetail);
         const metadataWithSessionOnly = sessionDetailKeys.length > 0 &&
-            sessionDetailKeys.every((key) => key === "session" ||
-                key === "complete" ||
-                key === "component" ||
-                key === "timestamp" ||
-                key === "sourceRuntimeId");
+            sessionDetailKeys.every((key) => key === "session" || METADATA_ONLY_SESSION_KEYS.has(key));
         const hasMetadataBeyondSession = sessionDetailKeys.some((key) => key !== "session");
         if (metadataWithSessionOnly &&
             hasMetadataBeyondSession &&
@@ -256,6 +274,7 @@ export function normalizeItemSessionChange(args) {
                 session: null,
                 intent: "metadata-only",
                 component: getMetadataComponent(sessionDetail),
+                ...withElementId(sessionDetail),
                 complete: getMetadataComplete(sessionDetail),
             };
         }
@@ -266,6 +285,7 @@ export function normalizeItemSessionChange(args) {
                 session: null,
                 intent: "metadata-only",
                 component: getMetadataComponent(sessionDetail),
+                ...withElementId(sessionDetail),
                 complete: getMetadataComplete(sessionDetail),
             };
         }
@@ -274,21 +294,20 @@ export function normalizeItemSessionChange(args) {
             session: normalizedCandidate,
             intent: "replace-item-session",
             component: getMetadataComponent(sessionDetail),
+            ...withElementId(sessionDetail),
             complete: getMetadataComplete(sessionDetail),
         };
     }
     const candidateKeys = Object.keys(candidate);
     const isMetadataOnlyPayload = candidateKeys.length > 0 &&
-        candidateKeys.every((key) => key === "complete" ||
-            key === "component" ||
-            key === "timestamp" ||
-            key === "sourceRuntimeId");
+        candidateKeys.every((key) => METADATA_ONLY_SESSION_KEYS.has(key));
     if (isMetadataOnlyPayload) {
         return {
             itemId: safeItemId,
             session: null,
             intent: "metadata-only",
             component: getMetadataComponent(sessionDetail, candidate),
+            ...withElementId(sessionDetail),
             complete: getMetadataComplete(sessionDetail, candidate),
         };
     }
@@ -298,6 +317,7 @@ export function normalizeItemSessionChange(args) {
             session: null,
             intent: "metadata-only",
             component: getMetadataComponent(sessionDetail, candidate),
+            ...withElementId(sessionDetail, candidate),
             complete: getMetadataComplete(sessionDetail, candidate),
         };
     }
@@ -309,6 +329,7 @@ export function normalizeItemSessionChange(args) {
         session: merged,
         intent: "merge-element-session",
         component,
+        ...withElementId(sessionDetail, candidate),
         complete: getMetadataComplete(sessionDetail, candidate),
     };
 }

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/markup-math.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Math in an item's own markup: what the item and passage markup carry outside
+ * every PIE element.
+ *
+ * Each element typesets its own subtree, so the player hands its renderer only
+ * the markup around them. A renderer finds math below the element it is given,
+ * so no root holds a PIE element: the markup splits into the elements that hold
+ * none, and math sharing a parent with one is wrapped in a span of its own.
+ */
+import type { MathRenderer } from "./math-rendering.js";
+/**
+ * The parts of `container` holding math and no PIE element, each one a root to
+ * typeset. `pieTags` are the tag names of the PIE elements its markup places.
+ */
+export declare function collectMarkupMathRoots(container: HTMLElement, pieTags: ReadonlySet<string>): HTMLElement[];
+/**
+ * Typesets the math in `containers` outside every PIE element with `render`,
+ * one root at a time.
+ */
+export declare function typesetMarkupMath(containers: Iterable<HTMLElement>, pieTags: ReadonlySet<string>, render: MathRenderer): Promise<void>;