@pie-players/pie-players-shared 0.3.69 → 0.3.70

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";
 export * from "./ui/pointer-drag.js";
+export * from "./ui/overlay-containment.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/debug-panel-persistence.js";

package/dist/index.js

@@ -11,6 +11,7 @@ export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";
 export * from "./ui/content-styles.js";
 export * from "./ui/pointer-drag.js";
+export * from "./ui/overlay-containment.js";
 export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/debug-panel-persistence.js";

package/dist/loaders/iife-adapter.js

@@ -24,7 +24,7 @@ import { defineCustomElementSafely } from "../pie/custom-element-define.js";
 import { pieRegistry } from "../pie/registry.js";
 import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js";
-import { getPackageWithoutVersion, parsePackageName } from "../pie/utils.js";
+import { encodeElementPackageSpecs, getPackageWithoutVersion, parsePackageName, } from "../pie/utils.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 /**
  * Default PIE bundle service base URL. Exported so widgets can use it as
@@ -352,9 +352,13 @@ function buildBundleUrl(elements, bundleType, config) {
             ? `${config.bundleInfo.url}${separator}elements=${encodeURIComponent(elementTags)}`
             : config.bundleInfo.url;
     }
-    const packageVersions = Object.values(elements).join("+");
+    // The two encoders here are deliberately different: the path takes
+    // per-spec encoding because a scoped spec's `/` and `@` must stay literal
+    // for the route to match, while the `elements=` value is an ordinary query
+    // parameter. See `encodeElementPackageSpec`.
+    const packageVersions = encodeElementPackageSpecs(Object.values(elements));
     const host = normalizeBundleHost(config.bundleHost);
-    const base = `${host}${encodeURI(packageVersions)}/${bundleType}`;
+    const base = `${host}${packageVersions}/${bundleType}`;
     return elementTags
         ? `${base}?elements=${encodeURIComponent(elementTags)}`
         : base;

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

@@ -0,0 +1,59 @@
+/**
+ * Binding PIE elements that arrive after their bundle was registered.
+ *
+ * A bundle registration binds models and sessions to the PIE elements present
+ * in its container at registration time. Elements that arrive afterwards — ones
+ * a host appends to authored markup after the player mounted, or ones a tag's
+ * own render pass paints into its subtree — are bound by a `MutationObserver`.
+ *
+ * The observer is scoped to the registration's container, so a mutation
+ * elsewhere on the host page never reaches the callback and no `contains()`
+ * walk is needed to reject one. One observer serves every registration made
+ * against the same container — an item player registers its item config and its
+ * passage config separately — and it disconnects when the last of those
+ * registrations is released.
+ *
+ * This replaces a pair of `window` globals: one observer on `document.body` for
+ * the lifetime of the page, and one context slot that every registration
+ * overwrote. With a single slot the second registration displaced the first, so
+ * a late passage element, or any element in a player that was not the most
+ * recently registered, silently never bound.
+ */
+import type { ConfigEntity, Env } from "../types/index.js";
+import type { EventListenersMap } from "./types.js";
+/**
+ * What one registration binds a PIE element with.
+ */
+export interface PieElementContext {
+    config: ConfigEntity;
+    session: any[];
+    env?: Env;
+    eventListeners?: EventListenersMap;
+}
+/**
+ * Reads the context to bind with.
+ *
+ * Called when an element arrives, not when the registration is made: a player
+ * recomputes its session and env on render, so a value captured at
+ * registration time is stale by the time a late element needs it.
+ */
+export type PieElementContextSource = () => PieElementContext;
+/**
+ * Watch `container` for late-arriving PIE elements and bind them with whatever
+ * `getContext` returns at that moment. `container` defaults to `document.body`,
+ * matching an unscoped `LoadPieElementsOptions.container`.
+ *
+ * Returns the release for this registration. Calling it more than once is a
+ * no-op; the observer disconnects once every registration against the container
+ * has been released, so the caller that acquired it owns it.
+ */
+export declare const observePieElements: (container: Element | Document | undefined, getContext: PieElementContextSource) => (() => void);
+/**
+ * The contexts registered for `root` or for any container inside it, resolved
+ * now, in registration order.
+ *
+ * A host holds the custom element it mounted while the player registers its own
+ * inner root as the container, so the lookup accepts an ancestor of the
+ * container.
+ */
+export declare const pieElementContextsWithin: (root: Element | Document) => PieElementContext[];

package/dist/pie/element-observer.js

@@ -0,0 +1,131 @@
+/**
+ * Binding PIE elements that arrive after their bundle was registered.
+ *
+ * A bundle registration binds models and sessions to the PIE elements present
+ * in its container at registration time. Elements that arrive afterwards — ones
+ * a host appends to authored markup after the player mounted, or ones a tag's
+ * own render pass paints into its subtree — are bound by a `MutationObserver`.
+ *
+ * The observer is scoped to the registration's container, so a mutation
+ * elsewhere on the host page never reaches the callback and no `contains()`
+ * walk is needed to reject one. One observer serves every registration made
+ * against the same container — an item player registers its item config and its
+ * passage config separately — and it disconnects when the last of those
+ * registrations is released.
+ *
+ * This replaces a pair of `window` globals: one observer on `document.body` for
+ * the lifetime of the page, and one context slot that every registration
+ * overwrote. With a single slot the second registration displaced the first, so
+ * a late passage element, or any element in a player that was not the most
+ * recently registered, silently never bound.
+ */
+import { initializePieElement } from "./initialize-element.js";
+import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
+import { pieRegistry } from "./registry.js";
+const logger = createPieLogger("pie-element-observer", () => isGlobalDebugEnabled());
+const observed = new Map();
+const resolveContexts = (sources) => {
+    const contexts = [];
+    for (const source of sources) {
+        try {
+            contexts.push(source());
+        }
+        catch (error) {
+            logger.error("[pieElementObserver] A context source threw; skipping it.", error);
+        }
+    }
+    return contexts;
+};
+const bindElement = (element, contexts) => {
+    const tagName = element.tagName.toLowerCase();
+    if (!pieRegistry()[tagName])
+        return;
+    for (const context of contexts) {
+        const bound = initializePieElement(element, {
+            config: context.config,
+            session: context.session,
+            env: context.env,
+            eventListeners: context.eventListeners?.[tagName],
+        });
+        if (bound)
+            return;
+    }
+};
+const handleMutations = (sources, mutations) => {
+    // Resolved once per delivery, not per element.
+    const contexts = resolveContexts(sources);
+    if (contexts.length === 0)
+        return;
+    for (const mutation of mutations) {
+        if (mutation.type !== "childList")
+            continue;
+        for (const node of mutation.addedNodes) {
+            if (node.nodeType !== Node.ELEMENT_NODE)
+                continue;
+            const element = node;
+            bindElement(element, contexts);
+            for (const descendant of Array.from(element.querySelectorAll("*"))) {
+                bindElement(descendant, contexts);
+            }
+        }
+    }
+};
+/**
+ * Watch `container` for late-arriving PIE elements and bind them with whatever
+ * `getContext` returns at that moment. `container` defaults to `document.body`,
+ * matching an unscoped `LoadPieElementsOptions.container`.
+ *
+ * Returns the release for this registration. Calling it more than once is a
+ * no-op; the observer disconnects once every registration against the container
+ * has been released, so the caller that acquired it owns it.
+ */
+export const observePieElements = (container, getContext) => {
+    if (typeof document === "undefined" ||
+        typeof MutationObserver === "undefined") {
+        return () => { };
+    }
+    const target = container ?? document.body;
+    if (!target)
+        return () => { };
+    let entry = observed.get(target);
+    if (!entry) {
+        const sources = new Set();
+        const observer = new MutationObserver((mutations) => handleMutations(sources, mutations));
+        observer.observe(target, { childList: true, subtree: true });
+        entry = { sources, observer };
+        observed.set(target, entry);
+        logger.debug("[observePieElements] Observing a new container");
+    }
+    const { sources, observer } = entry;
+    sources.add(getContext);
+    logger.debug(`[observePieElements] Container now has ${sources.size} registration(s)`);
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        sources.delete(getContext);
+        if (sources.size > 0)
+            return;
+        observer.disconnect();
+        observed.delete(target);
+        logger.debug("[observePieElements] Released the last registration, disconnected");
+    };
+};
+/**
+ * The contexts registered for `root` or for any container inside it, resolved
+ * now, in registration order.
+ *
+ * A host holds the custom element it mounted while the player registers its own
+ * inner root as the container, so the lookup accepts an ancestor of the
+ * container.
+ */
+export const pieElementContextsWithin = (root) => {
+    const sources = [];
+    for (const [container, entry] of observed) {
+        if (container !== root && !root.contains(container))
+            continue;
+        sources.push(...entry.sources);
+    }
+    return resolveContexts(sources);
+};

package/dist/pie/index.d.ts

@@ -10,6 +10,8 @@
  */
 export { assertPieConfigContract, addMarkupForPackage, addRubricIfNeeded, elementForPackage, makeUniqueTags, modelsForPackage, validatePieConfigContract, } from "./config.js";
 export { initializePiesFromLoadedBundle, loadBundleFromString, loadPieModule, loadPieModuleFromString, } from "./initialization.js";
+export { observePieElements, pieElementContextsWithin, } from "./element-observer.js";
+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";
@@ -20,7 +22,7 @@ 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 { ASSESSMENT_INSTRUMENTATION_EVENT_MAP, SECTION_INSTRUMENTATION_EVENT_MAP, TOOLKIT_INSTRUMENTATION_EVENT_MAP, } from "./instrumentation-event-map.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";
@@ -42,4 +44,4 @@ export type { PieViewMode } from "./tag-names.js";
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";
 export type { ElementOverrides } from "./overrides.js";
 export { addOrUpdateOverrideInUrl, applyElementOverrides, applyElementVersionOverridesPreserveTags, extractPackageInfo, formatElementOverrideParam, parseElementOverridesFromCurrentUrl, parseElementOverridesFromUrl, } from "./overrides.js";
-export { findOrAddSession, getPackageWithoutVersion, getPieElementBundlesUrl, parsePackageName, } from "./utils.js";
+export { encodeElementPackageSpecs, findOrAddSession, getPackageWithoutVersion, getPieElementBundlesUrl, parsePackageName, } from "./utils.js";

package/dist/pie/index.js

@@ -14,6 +14,11 @@ export { assertPieConfigContract, addMarkupForPackage, addRubricIfNeeded, elemen
 // sync `assertRegistered`) lives under `pie-players-shared/loaders`.
 // Initialization
 export { initializePiesFromLoadedBundle, loadBundleFromString, loadPieModule, loadPieModuleFromString, } from "./initialization.js";
+// Late-arrival element binding. The owner of a container observes it and
+// releases the observer on teardown; a host reads `pieElementContextsWithin` to
+// recover the config and session a mounted player registered for a container it
+// 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 { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
@@ -23,7 +28,7 @@ export { resolveInstrumentationProvider } from "./instrumentation-provider-resol
 // `pie-stage-change` event family stays coherent across CE shapes.
 export { STAGES, applicableStages, stageOrdinal, } from "./stages.js";
 export { createStageTracker } from "./stage-tracker.js";
-export { ASSESSMENT_INSTRUMENTATION_EVENT_MAP, SECTION_INSTRUMENTATION_EVENT_MAP, TOOLKIT_INSTRUMENTATION_EVENT_MAP, } from "./instrumentation-event-map.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 { hasResponseValue, normalizeItemSessionChange, } from "./item-session-contract.js";
 export { MemoryItemSessionStorage, SessionStorageItemSessionStorage, } from "./item-controller-storage.js";
@@ -43,4 +48,4 @@ export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX,
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";
 export { addOrUpdateOverrideInUrl, applyElementOverrides, applyElementVersionOverridesPreserveTags, extractPackageInfo, formatElementOverrideParam, parseElementOverridesFromCurrentUrl, parseElementOverridesFromUrl, } from "./overrides.js";
 // Utils
-export { findOrAddSession, getPackageWithoutVersion, getPieElementBundlesUrl, parsePackageName, } from "./utils.js";
+export { encodeElementPackageSpecs, findOrAddSession, getPackageWithoutVersion, getPieElementBundlesUrl, parsePackageName, } from "./utils.js";

package/dist/pie/initialization.d.ts

@@ -4,19 +4,8 @@
  * Bundle loading and element initialization logic.
  * This is the core of the PIE player system.
  */
-import type { ConfigEntity, Env } from "../types/index.js";
+import type { ConfigEntity } from "../types/index.js";
 import type { LoadPieElementsOptions } from "./types.js";
-declare global {
-    interface Window {
-        _pieElementObserver?: MutationObserver;
-        _pieCurrentContext?: {
-            config: ConfigEntity;
-            session: any[];
-            env?: Env;
-            container?: Element | Document;
-        };
-    }
-}
 /**
  * Initialize PIE elements from a bundle that may already be loaded.
  *
@@ -44,10 +33,21 @@ declare global {
  * (bundle not loaded by *anyone*) still surface — every unregistered tag
  * gets its own warning, and `updatePieElements` later reports 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
+ * `observePieElements` and releases it on teardown.
  */
 export declare const initializePiesFromLoadedBundle: (config: ConfigEntity, session: any[], opts?: LoadPieElementsOptions) => void;
 /**
- * Load a PIE bundle from a URL and initialize elements
+ * Load a PIE bundle from a URL and initialize elements.
+ *
+ * Rejects — rather than hanging or throwing on the window — for every way
+ * the load can fail: the `error` event (404, blocked request, CSP refusal),
+ * the `loadTimeoutMs` deadline (a stalled request that never fires either
+ * event), a bundle whose script ran without populating `window.pie`, and a
+ * throw out of registration. Every rejection names the bundle URL and drops
+ * the injected `<script>`.
  */
 export declare const loadPieModule: (config: ConfigEntity, session: any[], opts?: LoadPieElementsOptions) => Promise<{
     session: any[];

package/dist/pie/initialization.js

@@ -5,84 +5,33 @@
  * This is the core of the PIE player system.
  */
 import { BUILDER_BUNDLE_URL } from "../config/profile.js";
+import { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG } from "../loader-config.js";
 import { mergeObjectsIgnoringNullUndefined } from "../object/index.js";
-import { wrapModelRichContent } from "../security/wrap-model-rich-content.js";
 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 { findPieController } from "./scoring.js";
 import { defineCustomElementSafely } from "./custom-element-define.js";
 import { validateCustomElementTag } from "./tag-names.js";
 import { BundleType, isCustomElementConstructor, isPieAvailable, Status, } from "./types.js";
 import { updatePieElement } from "./updates.js";
-import { findOrAddSession, getPackageWithoutVersion, getPieElementBundlesUrl, } from "./utils.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
+ * sets no `loadTimeoutMs`. Shared with the `ElementLoader` primitive's
+ * `DEFAULT_LOAD_TIMEOUT_MS` so a bundle gets the same budget whichever
+ * 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)
     env: { mode: "gather", role: "student" },
 };
-/**
- * Helper function to initialize a PIE element
- */
-const initializePieElement = (element, options) => {
-    const { config, session, env, eventListeners } = options;
-    if (element.__pieInitialized) {
-        return;
-    }
-    const tagName = element.tagName.toLowerCase();
-    logger.debug(`[initializePieElement] Initializing ${tagName}#${element.id}`);
-    // Find model for this element
-    let model = config?.models?.find((m) => m.id === element.id);
-    if (!model) {
-        // Only warn if this element is from a client-player.js bundle (where models are expected)
-        // player.js bundles use server-processed models, so missing models are expected there
-        const registry = pieRegistry();
-        const registryEntry = registry[tagName];
-        if (registryEntry && registryEntry.bundleType === BundleType.clientPlayer) {
-            logger.warn(`[initializePieElement] Model not found for PIE element ${tagName}#${element.id} (client-player.js bundle)`);
-        }
-        return;
-    }
-    // Set session (with element property for updateSession callback)
-    const elementSession = findOrAddSession(session, model.id, model.element);
-    element.session = elementSession;
-    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);
-    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.`);
-    }
-    if (!controller) {
-        // No controller available - using server-processed model (player.js bundle)
-        logger.debug(`[initializePieElement] ℹ️ No controller for ${tagName}, using server-processed model`);
-        logger.debug(`[initializePieElement] Model already processed by server:`, {
-            id: model.id,
-            element: model.element,
-            hasCorrectResponse: "correctResponse" in model,
-            mode: env.mode,
-            role: env.role,
-        });
-        // Set model directly - server already processed it
-        element.model = wrapModelRichContent(model);
-    }
-    else {
-        // Controller available - run client-side processing (client-player.js bundle)
-        // Note: updatePieElementWithRef handles controller invocation
-        logger.debug(`[initializePieElement] Controller found for ${tagName}, will invoke model() function`);
-    }
-    // Add event listeners
-    if (eventListeners) {
-        Object.entries(eventListeners).forEach(([evt, fn]) => {
-            element.addEventListener(evt, fn);
-        });
-    }
-};
 const getEditorElementTagName = (elementTagName, pkg) => validateCustomElementTag(elementTagName + editorPostFix, `editor element tag for ${pkg}`);
 const updateRegisteredElement = (elementTagName, config, session, options, omitEnv = false) => {
     updatePieElement(elementTagName, {
@@ -98,7 +47,10 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
 /**
  * Shared element registration logic
  * Extracted from initializePiesFromLoadedBundle and loadPieModule to eliminate ~200 lines of duplication
- * Also fixes MutationObserver memory leak by storing latest config/session in window context
+ *
+ * Binds the elements already present in `options.container`. Elements that
+ * arrive later are bound by the container owner's observer — see
+ * `element-observer.ts`.
  *
  * `elementModule` may be `null`. In that case we cannot register *new*
  * tags (no element constructor source), but we can still update tags
@@ -111,11 +63,6 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
  */
 const registerPieElementsFromBundle = (elementModule, config, session, registry, options) => {
     const promises = [];
-    const isNodeWithinContainer = (node, container) => {
-        if (!container || container === document)
-            return true;
-        return node instanceof Node && container.contains(node);
-    };
     if (elementModule) {
         logger.debug("[registerPieElementsFromBundle] Available packages in bundle:", Object.keys(elementModule));
     }
@@ -123,15 +70,6 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
         logger.debug("[registerPieElementsFromBundle] No bundle module supplied; will only update tags already registered with customElements.");
     }
     logger.debug("[registerPieElementsFromBundle] config.elements:", config.elements);
-    // Store latest config/session in window so MutationObserver can access current values
-    if (typeof window !== "undefined") {
-        window._pieCurrentContext = {
-            config,
-            session,
-            env: options.env,
-            container: options.container,
-        };
-    }
     Object.entries(config.elements).forEach(([elName, pkg]) => {
         const elementTagName = validateCustomElementTag(elName, `element tag in config.elements for ${String(pkg)}`);
         logger.debug(`[registerPieElementsFromBundle] Processing element: ${elementTagName} -> ${pkg}`);
@@ -227,58 +165,6 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                 promises.push(customElements.whenDefined(elementTagName).then(() => {
                     logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
                 }));
-                // Setup MutationObserver that uses current context (only once)
-                if (!window._pieElementObserver) {
-                    window._pieElementObserver = new MutationObserver((mutations) => {
-                        // Use current context from window instead of stale closure
-                        const context = window._pieCurrentContext;
-                        if (!context) {
-                            logger.warn("[MutationObserver] No current context available");
-                            return;
-                        }
-                        mutations.forEach((mutation) => {
-                            if (mutation.type === "childList") {
-                                mutation.addedNodes.forEach((node) => {
-                                    if (node.nodeType === Node.ELEMENT_NODE) {
-                                        if (!isNodeWithinContainer(node, context.container)) {
-                                            return;
-                                        }
-                                        const tagName = node.tagName.toLowerCase();
-                                        if (registry[tagName]) {
-                                            initializePieElement(node, {
-                                                config: context.config,
-                                                session: context.session,
-                                                env: context.env,
-                                                eventListeners: options.eventListeners?.[tagName],
-                                            });
-                                        }
-                                        // Check children of added nodes
-                                        node
-                                            .querySelectorAll("*")
-                                            .forEach((childNode) => {
-                                            if (!isNodeWithinContainer(childNode, context.container)) {
-                                                return;
-                                            }
-                                            const childTagName = childNode.tagName.toLowerCase();
-                                            if (registry[childTagName]) {
-                                                initializePieElement(childNode, {
-                                                    config: context.config,
-                                                    session: context.session,
-                                                    env: context.env,
-                                                    eventListeners: options.eventListeners?.[childTagName],
-                                                });
-                                            }
-                                        });
-                                    }
-                                });
-                            }
-                        });
-                    });
-                    window._pieElementObserver.observe(document.body, {
-                        childList: true,
-                        subtree: true,
-                    });
-                }
                 // Handle editor elements if needed
                 if (options.bundleType === BundleType.editor) {
                     if (isCustomElementConstructor(elementData.Configure)) {
@@ -327,6 +213,10 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
  * (bundle not loaded by *anyone*) still surface — every unregistered tag
  * gets its own warning, and `updatePieElements` later reports 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
+ * `observePieElements` and releases it on teardown.
  */
 export const initializePiesFromLoadedBundle = (config, session, opts = {}) => {
     const registry = pieRegistry();
@@ -341,7 +231,14 @@ export const initializePiesFromLoadedBundle = (config, session, opts = {}) => {
     registerPieElementsFromBundle(null, config, session, registry, options);
 };
 /**
- * Load a PIE bundle from a URL and initialize elements
+ * Load a PIE bundle from a URL and initialize elements.
+ *
+ * Rejects — rather than hanging or throwing on the window — for every way
+ * the load can fail: the `error` event (404, blocked request, CSP refusal),
+ * the `loadTimeoutMs` deadline (a stalled request that never fires either
+ * event), a bundle whose script ran without populating `window.pie`, and a
+ * throw out of registration. Every rejection names the bundle URL and drops
+ * the injected `<script>`.
  */
 export const loadPieModule = async (config, session, opts = {}) => {
     if (!session) {
@@ -352,31 +249,84 @@ export const loadPieModule = async (config, session, opts = {}) => {
     const registry = pieRegistry();
     const options = mergeObjectsIgnoringNullUndefined(defaultOptions, opts);
     const url = opts.bundleUrl || getPieElementBundlesUrl(config, options);
+    const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
     const script = document.createElement("script");
     script.src = url;
     script.defer = true;
-    script.onerror = () => {
-        throw new Error(`failed to load script: ${url}`);
-    };
-    const loadPromise = new Promise((loadResolve) => {
-        script.addEventListener("load", () => {
-            logger.debug("[loadPieModule] Script loaded from:", url);
-            if (isPieAvailable(window)) {
+    let timer;
+    // Removing a `<script>` does not abort a request already in flight, so a
+    // late `load` can still fire after the deadline rejected. Each handler
+    // checks this so registration never runs for a load the caller has
+    // already been told failed.
+    let settled = false;
+    try {
+        await new Promise((resolve, reject) => {
+            const succeed = () => {
+                settled = true;
+                resolve();
+            };
+            const fail = (error) => {
+                settled = true;
+                reject(error);
+            };
+            script.addEventListener("load", () => {
+                if (settled)
+                    return;
+                logger.debug("[loadPieModule] Script loaded from:", url);
+                if (!isPieAvailable(window)) {
+                    // Deliberately a rejection, not a resolve. The script executed
+                    // and registered nothing, so the URL did not serve a PIE IIFE
+                    // bundle; resolving would report a successful load to a caller
+                    // that then waits on elements which never arrive.
+                    // `initializePiesFromLoadedBundle` tolerates the same missing
+                    // global because there the host's own loader owns registration.
+                    // Here this function owns it, so there is no other party to
+                    // wait for. Matches the IIFE `ElementLoader` adapter, which
+                    // fails with `cause: "window.pie.default missing after bundle
+                    // load"`.
+                    fail(new Error(`PIE bundle loaded but window.pie is absent; is ${url} a proper PIE IIFE module?`));
+                    return;
+                }
                 logger.debug("[loadPieModule] window.pie available");
                 const elementModule = window.pie.default;
-                // 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(() => loadResolve());
-            }
-            else {
-                logger.error("[loadPieModule] pie var not found; is %s a proper PIE IIFE module?", url);
-                loadResolve();
+                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) {
+                    // `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.
+                    fail(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+            script.addEventListener("error", () => {
+                if (settled)
+                    return;
+                fail(new Error(`failed to load PIE bundle script: ${url}`));
+            });
+            if (loadTimeoutMs > 0) {
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    fail(new Error(`PIE bundle script load timed out after ${loadTimeoutMs}ms: ${url}`));
+                }, loadTimeoutMs);
             }
+            document.head.appendChild(script);
         });
-    });
-    document.head.appendChild(script);
-    await loadPromise;
+    }
+    catch (error) {
+        // Drop the injected node so a retry starts from a clean head.
+        script.remove();
+        throw error;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
     return { session };
 };
 /**