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

package/dist/object/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * A problem using the spread operator merging objects is that undefined properties may override
- * defined properties, which is often NOT what you want (e.g. when providing default values). This
- * function merges objects, but ignores properties that are null or undefined.
+ * Merges objects left to right, skipping properties whose value is `null` or
+ * `undefined`, so a later object's unset field never overrides an earlier
+ * default the way object spread does.
  * @param objects The objects to merge.
  */
 export declare const mergeObjectsIgnoringNullUndefined: <T extends object>(...objects: T[]) => T;
@@ -9,3 +9,8 @@ export declare const mergeObjectsIgnoringNullUndefined: <T extends object>(...ob
  * Deep clone an object.
  */
 export declare const cloneDeep: <T>(value: T) => T;
+/**
+ * A non-null object that is not an array. The prototype is not checked, so
+ * class instances pass.
+ */
+export declare const isPlainRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/object/index.js

@@ -1,7 +1,7 @@
 /**
- * A problem using the spread operator merging objects is that undefined properties may override
- * defined properties, which is often NOT what you want (e.g. when providing default values). This
- * function merges objects, but ignores properties that are null or undefined.
+ * Merges objects left to right, skipping properties whose value is `null` or
+ * `undefined`, so a later object's unset field never overrides an earlier
+ * default the way object spread does.
  * @param objects The objects to merge.
  */
 export const mergeObjectsIgnoringNullUndefined = (...objects) => {
@@ -21,14 +21,11 @@ export const mergeObjectsIgnoringNullUndefined = (...objects) => {
  */
 export const cloneDeep = (value) => {
     if (value === null || typeof value !== "object") {
-        // Primitive value (or null), just return it
         return value;
     }
     if (Array.isArray(value)) {
-        // Array: clone each element recursively
         return value.map(cloneDeep);
     }
-    // Object: create a new object and clone its properties
     const copy = {};
     for (const key in value) {
         if (Object.hasOwn(value, key)) {
@@ -37,3 +34,8 @@ export const cloneDeep = (value) => {
     }
     return copy;
 };
+/**
+ * A non-null object that is not an array. The prototype is not checked, so
+ * class instances pass.
+ */
+export const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/pie/asset-handler.d.ts

@@ -5,23 +5,6 @@
  * Provides default DataURL-based implementation and event management.
  */
 import { type ImageHandler, type SoundHandler } from "../types/index.js";
-import type { AssetHandler } from "./types.js";
-/**
- * DataURL-based asset handler (default implementation)
- *
- * Converts uploaded files to base64 data URLs.
- * Suitable for demos and local development.
- */
-export declare class DataURLAssetHandler implements AssetHandler {
-    private onComplete;
-    private cancelled;
-    private fileReader;
-    constructor(onComplete: (src: string) => void);
-    cancel(): void;
-    done(err?: Error, src?: string): void;
-    fileChosen(file: File): void;
-    progress(percent: number, bytes: number, total: number): void;
-}
 /**
  * Asset Event Manager
  *

package/dist/pie/asset-handler.js

@@ -13,7 +13,7 @@ const logger = createPieLogger("asset-handler", () => isGlobalDebugEnabled());
  * Converts uploaded files to base64 data URLs.
  * Suitable for demos and local development.
  */
-export class DataURLAssetHandler {
+class DataURLAssetHandler {
     onComplete;
     cancelled = false;
     fileReader = null;

package/dist/pie/authoring.js

@@ -2,10 +2,8 @@ import { AssetEventManager } from "./asset-handler.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { findPieController } from "./scoring.js";
 import { parsePackageName } from "./utils.js";
+import { isPlainRecord } from "../object/index.js";
 const logger = createPieLogger("authoring", () => isGlobalDebugEnabled());
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
 function packageNameWithoutVersion(packageSpec) {
     try {
         return parsePackageName(packageSpec).name;
@@ -19,7 +17,7 @@ function packageBaseName(packageName) {
     return lastSegment || packageName;
 }
 function lookupOwn(source, keys) {
-    if (!isRecord(source))
+    if (!isPlainRecord(source))
         return undefined;
     for (const key of keys) {
         if (Object.hasOwn(source, key)) {
@@ -32,7 +30,7 @@ function mergeConfiguration(deliveryConfig, authoringConfig) {
     if (authoringConfig === undefined) {
         return deliveryConfig ?? {};
     }
-    if (isRecord(deliveryConfig) && isRecord(authoringConfig)) {
+    if (isPlainRecord(deliveryConfig) && isPlainRecord(authoringConfig)) {
         return {
             ...deliveryConfig,
             ...authoringConfig,
@@ -108,9 +106,9 @@ function resolveValidationController(configureElement) {
 // A controller's `validate` returns a field → message map. ebsr returns one map
 // per part, so an empty ebsr result is `{ partA: {}, partB: {} }`.
 function hasValidationErrors(errors) {
-    if (!isRecord(errors))
+    if (!isPlainRecord(errors))
         return false;
-    if (isRecord(errors.partA) && isRecord(errors.partB)) {
+    if (isPlainRecord(errors.partA) && isPlainRecord(errors.partB)) {
         return (Object.keys(errors.partA).length > 0 ||
             Object.keys(errors.partB).length > 0);
     }

package/dist/pie/elements-rendered.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+import type { ConfigEntity } from "../types/index.js";
+/**
+ * Resolves once every element of `configs` in `root` has rendered, or when
+ * `signal` aborts. Never rejects.
+ */
+export declare function elementsRendered(root: Element, configs: ConfigEntity[], signal: AbortSignal, quietMs?: number): Promise<void>;

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. */
+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

@@ -18,16 +18,14 @@ 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, flushPendingSessionNotifications, noteSessionBaseline, noteSessionObserved, } from "./session-commit.js";
@@ -35,7 +33,7 @@ export type { BindPageLifecycleCommitOptions, CommitPendingSessionsOptions, Comm
 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 { 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

@@ -23,20 +23,17 @@ export { createAuthoringAssetEventManager, initializeAuthoringConfigures, resolv
 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, 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 } from "./logger.js";
+export { createPieLogger, isGlobalDebugEnabled, isTtsDebugEnabled, } from "./logger.js";
 // Registry
 export { pieRegistry } from "./registry.js";
 // Scoring

package/dist/pie/initialization.d.ts

@@ -1,8 +1,9 @@
 /**
  * PIE Initialization Module
  *
- * Bundle loading and element initialization logic.
- * This is the core of the PIE player system.
+ * Loads IIFE bundles into `window.pie`, defines their elements and records
+ * them in the PIE registry, and binds config and session to the elements in
+ * the container.
  */
 import type { ConfigEntity } from "../types/index.js";
 import type { LoadPieElementsOptions } from "./types.js";
@@ -26,13 +27,11 @@ import type { LoadPieElementsOptions } from "./types.js";
  *   the existing `MutationObserver` / `updatePieElements` flow binds
  *   them on the next reactive pass.
  *
- * The original blanket `window.pie not found; was the bundle inlined
- * correctly?` error has been removed: in the section-player + item-player
- * composition it produced a confusing red stack trace for a routine
- * timing condition that the host already handles. Genuine failures
- * (bundle not loaded by *anyone*) still surface — every unregistered tag
- * gets its own warning, and `updatePieElements` later reports any tag
- * that never resolves.
+ * A missing `window.pie` raises no error: in the section-player and
+ * item-player composition it is a routine timing condition the host already
+ * handles. A bundle nobody loaded still surfaces, as a warning per
+ * unregistered tag and as an `updatePieElements` report for any tag that
+ * never resolves.
  *
  * Binds the elements present in `opts.container` now. Elements that arrive
  * later are the container owner's concern: a player with a lifecycle calls
@@ -53,13 +52,13 @@ export declare const loadPieModule: (config: ConfigEntity, session: any[], opts?
     session: any[];
 }>;
 /**
- * Load a PIE bundle from a JavaScript string into window.pie (IIFE bundles only)
- * This only registers elements and controllers - does NOT initialize them.
- * For initialization, use initializePiesFromLoadedBundle after loading.
+ * Executes an IIFE bundle from a JavaScript string, which populates
+ * `window.pie`. Defines no elements: `initializePiesFromLoadedBundle`
+ * registers and binds them afterwards.
  */
 export declare const loadBundleFromString: (bundleJs: string) => Promise<void>;
 /**
- * Load a PIE bundle from a JavaScript string and initialize elements
- * Convenience wrapper around loadBundleFromString + loadPieModule
+ * Loads a PIE bundle from a JavaScript string and initializes its elements:
+ * `loadPieModule` over a blob URL of the source.
  */
 export declare const loadPieModuleFromString: (bundleJs: string, config: ConfigEntity, session: any[], opts?: LoadPieElementsOptions) => Promise<void>;

package/dist/pie/initialization.js

@@ -1,8 +1,9 @@
 /**
  * PIE Initialization Module
  *
- * Bundle loading and element initialization logic.
- * This is the core of the PIE player system.
+ * Loads IIFE bundles into `window.pie`, defines their elements and records
+ * them in the PIE registry, and binds config and session to the elements in
+ * the container.
  */
 import { BUILDER_BUNDLE_URL } from "../config/profile.js";
 import { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG } from "../loader-config.js";
@@ -17,7 +18,6 @@ import { validateCustomElementTag } from "./tag-names.js";
 import { BundleType, isCustomElementConstructor, isPieAvailable, Status, } from "./types.js";
 import { updatePieElement } from "./updates.js";
 import { getPackageWithoutVersion, getPieElementBundlesUrl, } from "./utils.js";
-// Create module-level logger (respects global debug flag - pass function for dynamic checking)
 const logger = createPieLogger("pie-initialization", () => isGlobalDebugEnabled());
 /**
  * Deadline for `loadPieModule`'s bundle `<script>` load when the caller
@@ -26,7 +26,6 @@ const logger = createPieLogger("pie-initialization", () => isGlobalDebugEnabled(
  * path a host loads it through.
  */
 const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
-// Default options for loading PIE elements
 const defaultOptions = {
     buildServiceBase: BUILDER_BUNDLE_URL,
     bundleType: BundleType.player, // Default to player.js (no controllers, server-processed models)
@@ -46,12 +45,10 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
     });
 };
 /**
- * Shared element registration logic
- * Extracted from initializePiesFromLoadedBundle and loadPieModule to eliminate ~200 lines of duplication
- *
- * Binds the elements already present in `options.container`. Elements that
- * arrive later are bound by the container owner's observer — see
- * `element-observer.ts`.
+ * Defines the bundle's elements for `config.elements`, records them in the
+ * registry, and binds the elements already present in `options.container`.
+ * Elements that arrive later are bound by the container owner's observer —
+ * see `element-observer.ts`. Returns one promise per defined tag.
  *
  * `elementModule` may be `null`. In that case we cannot register *new*
  * tags (no element constructor source), but we can still update tags
@@ -120,59 +117,55 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                 : [],
             bundleType: options.bundleType,
         });
-        {
-            // 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; its model is used as given)"}`);
-            writeRegistryEntry({
-                package: pkg,
-                status: Status.loading,
-                tagName: elementTagName,
-                controller: elementData.controller || null,
-                config: elementData.config,
+        // 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; 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)) {
+            logger.error(`[registerPieElementsFromBundle] pie.Element for ${pkgStripped} is not a valid custom element constructor.`);
+            return;
+        }
+        defineCustomElementSafely(elementTagName, elementData.Element, `element tag in config.elements for ${String(pkg)}`);
+        // Initialize existing elements
+        const searchRoot = options.container || document;
+        const elements = searchRoot.querySelectorAll(elementTagName);
+        logger.debug(`[registerPieElementsFromBundle] Found ${elements.length} elements for tag '${elementTagName}'`);
+        elements.forEach((el) => {
+            initializePieElement(el, {
+                config,
+                session,
+                env: options.env,
+                eventListeners: options.eventListeners?.[elementTagName],
                 bundleType: options.bundleType,
             });
-            if (isCustomElementConstructor(elementData.Element)) {
-                defineCustomElementSafely(elementTagName, elementData.Element, `element tag in config.elements for ${String(pkg)}`);
-                // Initialize existing elements
-                const searchRoot = options.container || document;
-                const elements = searchRoot.querySelectorAll(elementTagName);
-                logger.debug(`[registerPieElementsFromBundle] Found ${elements.length} elements for tag '${elementTagName}'`);
-                elements.forEach((el) => {
-                    initializePieElement(el, {
-                        config,
-                        session,
-                        env: options.env,
-                        eventListeners: options.eventListeners?.[elementTagName],
-                        bundleType: options.bundleType,
-                    });
-                });
-                writeRegistryEntry({
-                    ...registry[elementTagName],
-                    status: Status.loaded,
-                });
-                promises.push(customElements.whenDefined(elementTagName).then(() => {
-                    logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
+        });
+        writeRegistryEntry({
+            ...registry[elementTagName],
+            status: Status.loaded,
+        });
+        promises.push(customElements.whenDefined(elementTagName).then(() => {
+            logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
+        }));
+        if (options.bundleType === BundleType.editor) {
+            if (isCustomElementConstructor(elementData.Configure)) {
+                const editorElName = getEditorElementTagName(elementTagName, String(pkg));
+                defineCustomElementSafely(editorElName, elementData.Configure, `editor element tag for ${String(pkg)}`);
+                promises.push(customElements.whenDefined(editorElName).then(() => {
+                    logger.debug(`[registerPieElementsFromBundle] defined custom PIE editor element: ${editorElName}`);
                 }));
-                // Handle editor elements if needed
-                if (options.bundleType === BundleType.editor) {
-                    if (isCustomElementConstructor(elementData.Configure)) {
-                        const editorElName = getEditorElementTagName(elementTagName, String(pkg));
-                        defineCustomElementSafely(editorElName, elementData.Configure, `editor element tag for ${String(pkg)}`);
-                        promises.push(customElements.whenDefined(editorElName).then(() => {
-                            logger.debug(`[registerPieElementsFromBundle] defined custom PIE editor element: ${editorElName}`);
-                        }));
-                    }
-                    else {
-                        logger.error(`[registerPieElementsFromBundle] pie.Configure for ${pkgStripped} is not a valid custom element constructor.`, elementData.configure);
-                    }
-                }
             }
             else {
-                logger.error(`[registerPieElementsFromBundle] pie.Element for ${pkgStripped} is not a valid custom element constructor.`);
+                logger.error(`[registerPieElementsFromBundle] pie.Configure for ${pkgStripped} is not a valid custom element constructor.`, elementData.configure);
             }
         }
     });
@@ -198,13 +191,11 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
  *   the existing `MutationObserver` / `updatePieElements` flow binds
  *   them on the next reactive pass.
  *
- * The original blanket `window.pie not found; was the bundle inlined
- * correctly?` error has been removed: in the section-player + item-player
- * composition it produced a confusing red stack trace for a routine
- * timing condition that the host already handles. Genuine failures
- * (bundle not loaded by *anyone*) still surface — every unregistered tag
- * gets its own warning, and `updatePieElements` later reports any tag
- * that never resolves.
+ * A missing `window.pie` raises no error: in the section-player and
+ * item-player composition it is a routine timing condition the host already
+ * handles. A bundle nobody loaded still surfaces, as a warning per
+ * unregistered tag and as an `updatePieElements` report for any tag that
+ * never resolves.
  *
  * Binds the elements present in `opts.container` now. Elements that arrive
  * later are the container owner's concern: a player with a lifecycle calls
@@ -282,9 +273,7 @@ export const loadPieModule = async (config, session, opts = {}) => {
                 logger.debug("[loadPieModule] window.pie available");
                 const elementModule = window.pie.default;
                 try {
-                    // Use shared registration logic (returns array of promises)
                     const registrationPromises = registerPieElementsFromBundle(elementModule, config, session, registry, options);
-                    // Wait for all element definitions to complete
                     Promise.all(registrationPromises).then(succeed, fail);
                 }
                 catch (error) {
@@ -321,18 +310,16 @@ export const loadPieModule = async (config, session, opts = {}) => {
     return { session };
 };
 /**
- * Load a PIE bundle from a JavaScript string into window.pie (IIFE bundles only)
- * This only registers elements and controllers - does NOT initialize them.
- * For initialization, use initializePiesFromLoadedBundle after loading.
+ * Executes an IIFE bundle from a JavaScript string, which populates
+ * `window.pie`. Defines no elements: `initializePiesFromLoadedBundle`
+ * registers and binds them afterwards.
  */
 export const loadBundleFromString = async (bundleJs) => {
     await initializeMathRendering();
     await withBlobBundleUrl(bundleJs, { stripSourceMapComment: true }, async (bundleUrl) => {
-        // Create a script tag to execute the bundle
         const script = document.createElement("script");
         script.src = bundleUrl;
         script.type = "text/javascript"; // IIFE bundles are standard JS
-        // Wait for script to load
         await new Promise((resolve, reject) => {
             script.onload = () => resolve();
             script.onerror = () => reject(new Error("Failed to load bundle"));
@@ -342,12 +329,11 @@ export const loadBundleFromString = async (bundleJs) => {
     });
 };
 /**
- * Load a PIE bundle from a JavaScript string and initialize elements
- * Convenience wrapper around loadBundleFromString + loadPieModule
+ * Loads a PIE bundle from a JavaScript string and initializes its elements:
+ * `loadPieModule` over a blob URL of the source.
  */
 export const loadPieModuleFromString = async (bundleJs, config, session, opts = {}) => {
     await withBlobBundleUrl(bundleJs, {}, async (bundleUrl) => {
-        // Use existing loadPieModule with the blob URL
         await loadPieModule(config, session, { ...opts, bundleUrl });
     });
 };

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 {};