@pie-players/pie-players-shared 0.3.30 → 0.3.32

package/dist/loaders/iife-adapter.js

@@ -0,0 +1,365 @@
+/**
+ * IIFE backend adapter for the ElementLoader primitive.
+ *
+ * Loads PIE elements from IIFE bundles served by the PIE build service,
+ * then registers them with `customElements`. On any per-tag failure
+ * (missing package, non-constructor element class, define failure),
+ * throws `AdapterFailure` with a structured `reasons` map that the
+ * primitive unpacks into `ElementLoaderError.reasons`.
+ *
+ * This adapter deliberately does *not* gate its own promise on
+ * `customElements.whenDefined` — the primitive performs that verification
+ * uniformly for every backend, so the adapter's job is narrowly:
+ *
+ *   1. Fetch the bundle.
+ *   2. Extract per-tag element classes from `window.pie.default`.
+ *   3. Validate each class is a custom-element constructor.
+ *   4. Call `customElements.define` via `defineCustomElementSafely`.
+ *   5. Collect structured per-tag reasons for anything that failed.
+ *   6. Resolve (everything OK) or throw `AdapterFailure` (anything failed).
+ */
+import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
+import { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG, } from "../loader-config.js";
+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 } from "../pie/utils.js";
+import { AdapterFailure, } from "./element-loader-types.js";
+/**
+ * Default PIE bundle service base URL. Exported so widgets can use it as
+ * the fallback when the host does not supply `loaderOptions.bundleHost`.
+ */
+export const DEFAULT_BUNDLE_HOST = "https://proxy.pie-api.com/bundles/";
+export function createIifeBackend(config) {
+    const bundleType = config.bundleType ?? BundleType.clientPlayer;
+    const needsControllers = config.needsControllers ?? true;
+    let loadBundleScript = defaultLoadBundleScript;
+    const inFlightBundleLoads = new Map();
+    const __seams = {
+        replaceLoadBundleScript(fn) {
+            loadBundleScript = fn;
+            inFlightBundleLoads.clear();
+        },
+        restore() {
+            loadBundleScript = defaultLoadBundleScript;
+            inFlightBundleLoads.clear();
+        },
+    };
+    async function ensureBundleLoaded(url, doc) {
+        const existing = inFlightBundleLoads.get(url);
+        if (existing)
+            return existing;
+        const promise = loadBundleScriptWithRetry(url, doc).finally(() => {
+            inFlightBundleLoads.delete(url);
+        });
+        inFlightBundleLoads.set(url, promise);
+        return promise;
+    }
+    /**
+     * Wrap the single-shot script loader with poll-until-ready retry.
+     *
+     * The PIE bundle service may return a transient failure while it
+     * builds a bundle on demand. Retry with fixed-interval polling until
+     * the bundle is ready or the cumulative deadline elapses. Emits
+     * retry lifecycle events to the host via `onBundleRetryStatus` and to
+     * the instrumentation provider (if configured and ready).
+     */
+    async function loadBundleScriptWithRetry(url, doc) {
+        const { retryDelayMs, timeoutMs } = resolveBundleRetryConfig(config.bundleRetry);
+        const startedAt = Date.now();
+        let attempt = 0;
+        while (true) {
+            attempt += 1;
+            try {
+                await loadBundleScript(url, doc);
+                const elapsedMs = Date.now() - startedAt;
+                if (attempt > 1) {
+                    config.onBundleRetryStatus?.({
+                        state: "completed",
+                        url,
+                        attempt,
+                        elapsedMs,
+                        timeoutMs,
+                    });
+                    trackRetryEvent("pie-iife-bundle-retry-success", {
+                        url,
+                        attempt,
+                        elapsedMs,
+                        timeoutMs,
+                    });
+                }
+                return;
+            }
+            catch (error) {
+                const elapsedMs = Date.now() - startedAt;
+                const remainingMs = timeoutMs - elapsedMs;
+                const reason = error instanceof Error ? error.message : String(error);
+                if (remainingMs <= 0) {
+                    const timeoutError = new Error(`IIFE bundle load timed out after ${timeoutMs}ms: ${url}`);
+                    config.onBundleRetryStatus?.({
+                        state: "timeout",
+                        url,
+                        attempt,
+                        elapsedMs,
+                        timeoutMs,
+                        reason,
+                    });
+                    trackRetryEvent("pie-iife-bundle-retry-timeout", {
+                        url,
+                        attempt,
+                        elapsedMs,
+                        timeoutMs,
+                        lastError: reason,
+                    });
+                    trackRetryError(timeoutError, {
+                        url,
+                        attempt,
+                        elapsedMs,
+                        timeoutMs,
+                        lastError: reason,
+                    });
+                    throw timeoutError;
+                }
+                const nextDelay = Math.min(retryDelayMs, remainingMs);
+                config.onBundleRetryStatus?.({
+                    state: "retrying",
+                    url,
+                    attempt,
+                    elapsedMs,
+                    timeoutMs,
+                    retryDelayMs: nextDelay,
+                    reason,
+                });
+                trackRetryEvent("pie-iife-bundle-retry", {
+                    url,
+                    attempt,
+                    elapsedMs,
+                    retryDelayMs: nextDelay,
+                    timeoutMs,
+                    lastError: reason,
+                });
+                await waitMs(nextDelay);
+            }
+        }
+    }
+    function getInstrumentationProvider() {
+        if (!config.trackPageActions)
+            return undefined;
+        const provider = config.instrumentationProvider;
+        if (!isInstrumentationProvider(provider))
+            return undefined;
+        if (!provider.isReady())
+            return undefined;
+        return provider;
+    }
+    function trackRetryEvent(eventName, attributes) {
+        const provider = getInstrumentationProvider();
+        if (!provider)
+            return;
+        try {
+            provider.trackEvent(eventName, attributes);
+        }
+        catch {
+            // Swallow: instrumentation must never break loading.
+        }
+    }
+    function trackRetryError(error, attributes) {
+        const provider = getInstrumentationProvider();
+        if (!provider)
+            return;
+        try {
+            provider.trackError(error, {
+                ...attributes,
+                component: "iife-adapter",
+                errorType: "IifeBundleRetryError",
+            });
+        }
+        catch {
+            // Swallow: instrumentation must never break loading.
+        }
+    }
+    async function load(elements, context) {
+        if (!elements || Object.keys(elements).length === 0)
+            return;
+        const bundleUrl = buildBundleUrl(elements, bundleType, config);
+        try {
+            await ensureBundleLoaded(bundleUrl, context.doc);
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.message : String(err);
+            const reasons = new Map();
+            for (const tag of Object.keys(elements)) {
+                reasons.set(tag, {
+                    kind: "bundle-load-failed",
+                    tag,
+                    url: bundleUrl,
+                    cause,
+                });
+            }
+            throw new AdapterFailure(reasons);
+        }
+        const pieModule = readPieModule();
+        if (!pieModule) {
+            const reasons = new Map();
+            for (const tag of Object.keys(elements)) {
+                reasons.set(tag, {
+                    kind: "bundle-load-failed",
+                    tag,
+                    url: bundleUrl,
+                    cause: "window.pie.default missing after bundle load",
+                });
+            }
+            throw new AdapterFailure(reasons);
+        }
+        const reasons = new Map();
+        const isEditorBundle = bundleType === BundleType.editor;
+        const registry = pieRegistry();
+        for (const [tag, packageVersion] of Object.entries(elements)) {
+            const packageName = getPackageWithoutVersion(packageVersion);
+            const elementData = pieModule[packageName];
+            if (!elementData) {
+                reasons.set(tag, {
+                    kind: "package-not-in-bundle",
+                    tag,
+                    packageName,
+                    availablePackages: Object.keys(pieModule),
+                });
+                continue;
+            }
+            const ElementClass = isEditorBundle
+                ? (elementData.Configure ?? createEmptyConfigure())
+                : elementData.Element;
+            if (!ElementClass) {
+                reasons.set(tag, {
+                    kind: "no-element-class",
+                    tag,
+                    packageName,
+                });
+                continue;
+            }
+            if (!isCustomElementConstructor(ElementClass)) {
+                reasons.set(tag, {
+                    kind: "not-a-constructor",
+                    tag,
+                    packageName,
+                });
+                continue;
+            }
+            let actualTag;
+            try {
+                actualTag = validateCustomElementTag(isEditorBundle ? `${tag}-config` : tag, `element tag for ${packageName}`);
+            }
+            catch (err) {
+                reasons.set(tag, {
+                    kind: "define-failed",
+                    tag,
+                    cause: err instanceof Error ? err.message : String(err),
+                });
+                continue;
+            }
+            try {
+                defineCustomElementSafely(actualTag, class extends ElementClass {
+                }, `element tag for ${packageName}`);
+            }
+            catch (err) {
+                reasons.set(tag, {
+                    kind: "define-failed",
+                    tag,
+                    cause: err instanceof Error ? err.message : String(err),
+                });
+                continue;
+            }
+            registry[actualTag] = {
+                package: packageVersion,
+                status: Status.loaded,
+                tagName: actualTag,
+                element: ElementClass,
+                controller: needsControllers ? (elementData.controller ?? null) : null,
+                config: elementData.config ?? null,
+                bundleType,
+            };
+        }
+        if (reasons.size > 0) {
+            throw new AdapterFailure(reasons);
+        }
+    }
+    return {
+        load,
+        get __seams() {
+            return __seams;
+        },
+    };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function defaultLoadBundleScript(url, doc) {
+    return new Promise((resolve, reject) => {
+        const script = doc.createElement("script");
+        script.src = url;
+        script.defer = true;
+        script.setAttribute("data-pie-bundle", "true");
+        script.onload = () => resolve();
+        script.onerror = () => reject(new Error(`Failed to load IIFE bundle from: ${url}`));
+        doc.head.appendChild(script);
+    });
+}
+function readPieModule() {
+    const maybeWindow = globalThis
+        .window;
+    const pieDefault = maybeWindow?.pie?.default;
+    if (!pieDefault || typeof pieDefault !== "object")
+        return undefined;
+    return pieDefault;
+}
+function buildBundleUrl(elements, bundleType, config) {
+    const elementTags = Object.keys(elements).sort().join(",");
+    if (config.bundleInfo?.url) {
+        const separator = config.bundleInfo.url.includes("?") ? "&" : "?";
+        return elementTags
+            ? `${config.bundleInfo.url}${separator}elements=${encodeURIComponent(elementTags)}`
+            : config.bundleInfo.url;
+    }
+    const packageVersions = Object.values(elements).join("+");
+    const host = normalizeBundleHost(config.bundleHost);
+    const base = `${host}${encodeURI(packageVersions)}/${bundleType}`;
+    return elementTags
+        ? `${base}?elements=${encodeURIComponent(elementTags)}`
+        : base;
+}
+function normalizeBundleHost(host) {
+    return `${host.trim().replace(/\/+$/, "")}/`;
+}
+function resolveBundleRetryConfig(configured) {
+    const retryDelayMs = typeof configured?.retryDelayMs === "number" && configured.retryDelayMs > 0
+        ? configured.retryDelayMs
+        : DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.retryDelayMs;
+    const timeoutMs = typeof configured?.timeoutMs === "number" && configured.timeoutMs > 0
+        ? configured.timeoutMs
+        : DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
+    return { retryDelayMs, timeoutMs };
+}
+function waitMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function createEmptyConfigure() {
+    // Minimal configure fallback used for editor bundles that omit a Configure
+    // export. Intentionally silent; the host will see a blank configuration UI
+    // rather than a hard failure.
+    return class EmptyConfigureElement extends HTMLElement {
+        _model;
+        _configuration;
+        get model() {
+            return this._model;
+        }
+        set model(v) {
+            this._model = v;
+        }
+        get configuration() {
+            return this._configuration;
+        }
+        set configuration(v) {
+            this._configuration = v;
+        }
+    };
+}
+//# sourceMappingURL=iife-adapter.js.map

package/dist/loaders/iife-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iife-adapter.js","sourceRoot":"","sources":["../../src/loaders/iife-adapter.ts"],"names":[],"mappings":"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"}

package/dist/loaders/index.d.ts

@@ -1,28 +1,41 @@
 /**
  * PIE Element Loaders
  *
- * Element-level loading abstractions for PIE players.
- * Provides both IIFE and ESM loaders with element aggregation capabilities.
+ * Deep `ElementLoader` primitive — the public entry point for registering
+ * PIE custom elements at runtime. Exposes `ensureRegistered` (async) and
+ * `assertRegistered` (sync) with a truthful promise contract: the returned
+ * promise resolves iff every requested tag is actually in `customElements`.
+ *
+ * Backends (IIFE, ESM) are internal adapter modules; they implement the
+ * `ElementLoaderBackend` interface and are wired via `{ backend: ... }`
+ * options.
  *
  * @example
  * ```typescript
- * // ESM (modern, preferred)
- * import { EsmElementLoader } from '@pie-players/pie-players-shared/loaders';
- *
- * const loader = new EsmElementLoader({ esmCdnUrl: 'https://esm.sh' });
- * await loader.loadFromItems(section.items);
- *
- * // IIFE (legacy compatibility)
- * import { IifeElementLoader } from '@pie-players/pie-players-shared/loaders';
+ * import {
+ *   ensureRegistered,
+ *   BundleType,
+ * } from "@pie-players/pie-players-shared/loaders";
  *
- * const loader = new IifeElementLoader({ bundleHost: 'https://bundles.pie.org' });
- * await loader.loadFromItems(section.items);
+ * await ensureRegistered(
+ *   { "pie-multiple-choice": "@pie-element/multiple-choice@11.0.1" },
+ *   {
+ *     backend: {
+ *       kind: "iife",
+ *       bundleHost: "https://proxy.pie-api.com/bundles/",
+ *       bundleType: BundleType.clientPlayer,
+ *       needsControllers: true,
+ *     },
+ *   },
+ * );
  * ```
  */
-export type { ElementLoaderInterface, ElementMap, LoadOptions, } from "./ElementLoader.js";
+export type { ElementMap } from "./ElementLoader.js";
 export { aggregateElements } from "./ElementLoader.js";
-export type { EsmElementLoaderConfig } from "./EsmElementLoader.js";
-export { EsmElementLoader } from "./EsmElementLoader.js";
-export type { IifeElementLoaderConfig } from "./IifeElementLoader.js";
-export { IifeElementLoader } from "./IifeElementLoader.js";
+export type { BackendContext, BackendOption, ElementLoaderBackend, ElementTag, EnsureRegisteredOptions, EsmBackendConfig, IifeBackendConfig, RegistrationFailureReason, } from "./element-loader.js";
+export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, ensureRegistered, } from "./element-loader.js";
+export type { EsmBackend, ViewConfig } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend } from "./esm-adapter.js";
+export type { IifeBackend, IifeBundleRetryStatus, } from "./iife-adapter.js";
+export { createIifeBackend, DEFAULT_BUNDLE_HOST } from "./iife-adapter.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/loaders/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loaders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,YAAY,EACX,sBAAsB,EACtB,UAAU,EACV,WAAW,GACX,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loaders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAIvD,YAAY,EACX,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,UAAU,EACV,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,yBAAyB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GAChB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpE,YAAY,EACX,WAAW,EACX,qBAAqB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/loaders/index.js

@@ -1,25 +1,37 @@
 /**
  * PIE Element Loaders
  *
- * Element-level loading abstractions for PIE players.
- * Provides both IIFE and ESM loaders with element aggregation capabilities.
+ * Deep `ElementLoader` primitive — the public entry point for registering
+ * PIE custom elements at runtime. Exposes `ensureRegistered` (async) and
+ * `assertRegistered` (sync) with a truthful promise contract: the returned
+ * promise resolves iff every requested tag is actually in `customElements`.
+ *
+ * Backends (IIFE, ESM) are internal adapter modules; they implement the
+ * `ElementLoaderBackend` interface and are wired via `{ backend: ... }`
+ * options.
  *
  * @example
  * ```typescript
- * // ESM (modern, preferred)
- * import { EsmElementLoader } from '@pie-players/pie-players-shared/loaders';
- *
- * const loader = new EsmElementLoader({ esmCdnUrl: 'https://esm.sh' });
- * await loader.loadFromItems(section.items);
- *
- * // IIFE (legacy compatibility)
- * import { IifeElementLoader } from '@pie-players/pie-players-shared/loaders';
+ * import {
+ *   ensureRegistered,
+ *   BundleType,
+ * } from "@pie-players/pie-players-shared/loaders";
  *
- * const loader = new IifeElementLoader({ bundleHost: 'https://bundles.pie.org' });
- * await loader.loadFromItems(section.items);
+ * await ensureRegistered(
+ *   { "pie-multiple-choice": "@pie-element/multiple-choice@11.0.1" },
+ *   {
+ *     backend: {
+ *       kind: "iife",
+ *       bundleHost: "https://proxy.pie-api.com/bundles/",
+ *       bundleType: BundleType.clientPlayer,
+ *       needsControllers: true,
+ *     },
+ *   },
+ * );
  * ```
  */
 export { aggregateElements } from "./ElementLoader.js";
-export { EsmElementLoader } from "./EsmElementLoader.js";
-export { IifeElementLoader } from "./IifeElementLoader.js";
+export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, ensureRegistered, } from "./element-loader.js";
+export { BUILT_IN_VIEWS, createEsmBackend } from "./esm-adapter.js";
+export { createIifeBackend, DEFAULT_BUNDLE_HOST } from "./iife-adapter.js";
 //# sourceMappingURL=index.js.map

package/dist/loaders/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/loaders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/loaders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAcvD,OAAO,EACN,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GAChB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAKpE,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/pie/index.d.ts

@@ -13,15 +13,15 @@
  * - `pie/initialization` - Bundle loading and element initialization
  */
 export { assertPieConfigContract, addMarkupForPackage, addRubricIfNeeded, elementForPackage, makeUniqueTags, modelsForPackage, validatePieConfigContract, } from "./config.js";
-export type { EsmLoaderConfig } from "./esm-loader.js";
-export { EsmPieLoader } from "./esm-loader.js";
-export type { IifeBundleRetryStatus, IifeLoaderConfig } from "./iife-loader.js";
-export { DEFAULT_BUNDLE_HOST, IifePieLoader } from "./iife-loader.js";
 export { initializePiesFromLoadedBundle, loadBundleFromString, loadPieModule, loadPieModuleFromString, } from "./initialization.js";
 export { initializeMathRendering, renderMath, 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 { ASSESSMENT_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";

package/dist/pie/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pie/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pie/index.ts"],"names":[],"mappings":"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"}

package/dist/pie/index.js

@@ -14,13 +14,18 @@
  */
 // Config
 export { assertPieConfigContract, addMarkupForPackage, addRubricIfNeeded, elementForPackage, makeUniqueTags, modelsForPackage, validatePieConfigContract, } from "./config.js";
-export { EsmPieLoader } from "./esm-loader.js";
-export { DEFAULT_BUNDLE_HOST, IifePieLoader } from "./iife-loader.js";
+// Loaders — the deep `ElementLoader` primitive (async `ensureRegistered` /
+// sync `assertRegistered`) lives under `pie-players-shared/loaders`.
 // Initialization
 export { initializePiesFromLoadedBundle, loadBundleFromString, loadPieModule, loadPieModuleFromString, } from "./initialization.js";
 export { initializeMathRendering, renderMath, 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";
 export { ASSESSMENT_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";

package/dist/pie/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pie/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,SAAS;AACT,OAAO,EACN,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,yBAAyB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtE,iBAAiB;AACjB,OAAO,EACN,8BAA8B,EAC9B,oBAAoB,EACpB,aAAa,EACb,uBAAuB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,uBAAuB,EACvB,UAAU,EACV,eAAe,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AAErF,OAAO,EAAE,8BAA8B,EAAE,MAAM,0CAA0C,CAAC;AAC1F,OAAO,EACN,oCAAoC,EACpC,iCAAiC,EACjC,iCAAiC,GACjC,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAAE,cAAc,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAMrF,OAAO,EACN,gBAAgB,EAChB,0BAA0B,GAC1B,MAAM,4BAA4B,CAAC;AAKpC,OAAO,EACN,wBAAwB,EACxB,gCAAgC,GAChC,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAOpE,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,GACnB,MAAM,yBAAyB,CAAC;AACjC,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,UAAU;AACV,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAW/D,OAAO,EACN,UAAU,EACV,wBAAwB,EACxB,0BAA0B;AAC1B,0BAA0B;AAC1B,cAAc,EACd,sBAAsB,EACtB,MAAM,GACN,MAAM,YAAY,CAAC;AACpB,qBAAqB;AACrB,OAAO,EACN,yBAAyB,GAGzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACN,gBAAgB,EAChB,SAAS,EACT,wBAAwB,EACxB,eAAe,GACf,MAAM,gBAAgB,CAAC;AAExB,UAAU;AACV,OAAO,EACN,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,wBAAwB,EACxB,qBAAqB,EACrB,wCAAwC,EACxC,kBAAkB,EAClB,0BAA0B,EAC1B,mCAAmC,EACnC,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,QAAQ;AACR,OAAO,EACN,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,GAChB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pie/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,SAAS;AACT,OAAO,EACN,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,yBAAyB,GACzB,MAAM,aAAa,CAAC;AACrB,2EAA2E;AAC3E,qEAAqE;AACrE,iBAAiB;AACjB,OAAO,EACN,8BAA8B,EAC9B,oBAAoB,EACpB,aAAa,EACb,uBAAuB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,uBAAuB,EACvB,UAAU,EACV,eAAe,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gCAAgC,EAAE,MAAM,mCAAmC,CAAC;AAErF,OAAO,EAAE,8BAA8B,EAAE,MAAM,0CAA0C,CAAC;AAC1F,qEAAqE;AACrE,yDAAyD;AACzD,mEAAmE;AACnE,OAAO,EACN,MAAM,EACN,gBAAgB,EAChB,YAAY,GACZ,MAAM,aAAa,CAAC;AAQrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAKxD,OAAO,EACN,oCAAoC,EACpC,iCAAiC,EACjC,iCAAiC,GACjC,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAAE,cAAc,EAAE,6BAA6B,EAAE,MAAM,sBAAsB,CAAC;AAMrF,OAAO,EACN,gBAAgB,EAChB,0BAA0B,GAC1B,MAAM,4BAA4B,CAAC;AAKpC,OAAO,EACN,wBAAwB,EACxB,gCAAgC,GAChC,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAOpE,OAAO,EACN,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,GACnB,MAAM,yBAAyB,CAAC;AACjC,WAAW;AACX,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,UAAU;AACV,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAW/D,OAAO,EACN,UAAU,EACV,wBAAwB,EACxB,0BAA0B;AAC1B,0BAA0B;AAC1B,cAAc,EACd,sBAAsB,EACtB,MAAM,GACN,MAAM,YAAY,CAAC;AACpB,qBAAqB;AACrB,OAAO,EACN,yBAAyB,GAGzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACN,gBAAgB,EAChB,SAAS,EACT,wBAAwB,EACxB,eAAe,GACf,MAAM,gBAAgB,CAAC;AAExB,UAAU;AACV,OAAO,EACN,gBAAgB,EAChB,iBAAiB,EACjB,uBAAuB,GACvB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACN,wBAAwB,EACxB,qBAAqB,EACrB,wCAAwC,EACxC,kBAAkB,EAClB,0BAA0B,EAC1B,mCAAmC,EACnC,4BAA4B,GAC5B,MAAM,gBAAgB,CAAC;AACxB,QAAQ;AACR,OAAO,EACN,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,GAChB,MAAM,YAAY,CAAC"}

package/dist/pie/initialization.d.ts

@@ -18,7 +18,32 @@ declare global {
     }
 }
 /**
- * Initialize PIE elements from a bundle already loaded into window.pie
+ * Initialize PIE elements from a bundle that may already be loaded.
+ *
+ * `window.pie` is the legacy bundle-loading global populated by
+ * `loadPieModule` / `loadBundleFromString`. When the host loaded the
+ * bundle through the deep `ElementLoader` primitive instead — as
+ * `pie-section-player` does — the global is irrelevant: the loader
+ * registers tags directly with `customElements`, so this function only
+ * needs to bind models/sessions to whatever is already registered.
+ *
+ * Behavior:
+ * - `window.pie` available → register any new tags from the bundle and
+ *   update bindings for already-registered tags (legacy fast path).
+ * - `window.pie` missing → fall back to the update-only path. Tags that
+ *   are already registered get their model/session updated; tags that
+ *   are not yet registered are logged at `warn` and left alone — the
+ *   host's loader is expected to register them imminently, after which
+ *   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.
  */
 export declare const initializePiesFromLoadedBundle: (config: ConfigEntity, session: any[], opts?: LoadPieElementsOptions) => void;
 /**

package/dist/pie/initialization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initialization.d.ts","sourceRoot":"","sources":["../../src/pie/initialization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAY,MAAM,mBAAmB,CAAC;AAQrE,OAAO,KAAK,EAEX,sBAAsB,EAGtB,MAAM,YAAY,CAAC;AA2BpB,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;QACvC,kBAAkB,CAAC,EAAE;YACpB,MAAM,EAAE,YAAY,CAAC;YACrB,OAAO,EAAE,GAAG,EAAE,CAAC;YACf,GAAG,CAAC,EAAE,GAAG,CAAC;YACV,SAAS,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;SAC/B,CAAC;KACF;CACD;AA8YD;;GAEG;AACH,eAAO,MAAM,8BAA8B,GAC1C,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,OAAM,sBAA2B,KAC/B,IAqBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GACzB,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,OAAM,sBAA2B,KAC/B,OAAO,CAAC;IACV,OAAO,EAAE,GAAG,EAAE,CAAC;CACf,CAiDA,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,IAAI,CAoBzE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,UAAU,MAAM,EAChB,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,OAAM,sBAA2B,KAC/B,OAAO,CAAC,IAAI,CAKd,CAAC"}
+{"version":3,"file":"initialization.d.ts","sourceRoot":"","sources":["../../src/pie/initialization.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,GAAG,EAAY,MAAM,mBAAmB,CAAC;AAQrE,OAAO,KAAK,EAEX,sBAAsB,EAGtB,MAAM,YAAY,CAAC;AA2BpB,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,MAAM;QACf,mBAAmB,CAAC,EAAE,gBAAgB,CAAC;QACvC,kBAAkB,CAAC,EAAE;YACpB,MAAM,EAAE,YAAY,CAAC;YACrB,OAAO,EAAE,GAAG,EAAE,CAAC;YACf,GAAG,CAAC,EAAE,GAAG,CAAC;YACV,SAAS,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;SAC/B,CAAC;KACF;CACD;AAsbD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,8BAA8B,GAC1C,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,OAAM,sBAA2B,KAC/B,IAqBF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GACzB,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,OAAM,sBAA2B,KAC/B,OAAO,CAAC;IACV,OAAO,EAAE,GAAG,EAAE,CAAC;CACf,CAiDA,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAU,UAAU,MAAM,KAAG,OAAO,CAAC,IAAI,CAoBzE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GACnC,UAAU,MAAM,EAChB,QAAQ,YAAY,EACpB,SAAS,GAAG,EAAE,EACd,OAAM,sBAA2B,KAC/B,OAAO,CAAC,IAAI,CAKd,CAAC"}