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

package/dist/i18n/messages/en-US.d.ts

@@ -95,6 +95,8 @@ declare const enUS: {
         assessment: {
             sectionPosition: string;
             noSections: string;
+            loadFailed: string;
+            restoreFailed: string;
         };
         /** Formative delivery: check-answer control and its outcome announcements. */
         formative: {

package/dist/i18n/messages/en-US.js

@@ -95,6 +95,8 @@ const enUS = {
         assessment: {
             sectionPosition: "Section {position} of {total}",
             noSections: "No sections",
+            loadFailed: "The assessment could not be loaded. Try again.",
+            restoreFailed: "Your saved answers for this section could not be restored. Try again.",
         },
         /** Formative delivery: check-answer control and its outcome announcements. */
         formative: {

package/dist/i18n/messages/nl-NL.d.ts

@@ -76,6 +76,8 @@ declare const nlNL: {
         assessment: {
             sectionPosition: string;
             noSections: string;
+            loadFailed: string;
+            restoreFailed: string;
         };
         formative: {
             checkAnswer: string;

package/dist/i18n/messages/nl-NL.js

@@ -76,6 +76,8 @@ const nlNL = {
         assessment: {
             sectionPosition: "Onderdeel {position} van {total}",
             noSections: "Geen onderdelen",
+            loadFailed: "De toets kon niet worden geladen. Probeer het opnieuw.",
+            restoreFailed: "Je opgeslagen antwoorden voor dit onderdeel konden niet worden hersteld. Probeer het opnieuw.",
         },
         formative: {
             checkAnswer: "Antwoord controleren",

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[];