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

package/dist/pie/use-resource-monitor.svelte.js

@@ -22,7 +22,7 @@
  * </script>
  * ```
  */
-import { onDestroy } from "svelte";
+import { onDestroy, untrack } from "svelte";
 import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
 import { DEFAULT_LOADER_CONFIG } from "../loader-config.js";
 import { createPieLogger } from "./logger.js";
@@ -45,85 +45,98 @@ export function useResourceMonitor(getHostElement, getLoaderConfig, getDebugEnab
     let activeHostElement = $state(null);
     let monitorConfigKey = $state("");
     let activeProvider = $state(undefined);
-    // Initialize resource monitor when conditions are met
+    // Initialize resource monitor when conditions are met.
+    //
+    // The body of this effect both reads and writes the local `$state`
+    // latches (`monitor`, `isInitialized`, `activeHostElement`,
+    // `monitorConfigKey`, `activeProvider`) — those latches exist so the
+    // public `instance`/`isActive` getters stay reactive for downstream
+    // consumers, but the same-effect read+write would otherwise trip
+    // `effect_update_depth_exceeded` on every host/config/provider change
+    // (observed in the assessment-player smoke flow during instrumentation
+    // provider rebinding). Per `.cursor/rules/svelte-subscription-safety.mdc`,
+    // we explicitly track only the input getters and run the body inside
+    // `untrack(...)` so the self-mutations don't re-trigger the effect.
     $effect(() => {
-        const hostElement = getHostElement();
-        const loaderConfig = getLoaderConfig();
-        const debugEnabled = getDebugEnabled();
-        const resolvedTrackPageActions = loaderConfig?.trackPageActions ?? false;
-        const resolvedMaxRetries = loaderConfig?.maxResourceRetries ??
-            DEFAULT_LOADER_CONFIG.maxResourceRetries;
-        const resolvedRetryDelay = loaderConfig?.resourceRetryDelay ??
-            DEFAULT_LOADER_CONFIG.resourceRetryDelay;
-        const resolvedInstrumentationProvider = isInstrumentationProvider(loaderConfig?.instrumentationProvider)
-            ? loaderConfig?.instrumentationProvider
-            : undefined;
-        if (debugEnabled &&
-            loaderConfig?.instrumentationProvider &&
-            !resolvedInstrumentationProvider) {
-            logger.warn(`Ignoring invalid instrumentation provider for ${componentName}; expected InstrumentationProvider contract`);
-        }
-        const nextConfigKey = JSON.stringify({
-            trackPageActions: resolvedTrackPageActions,
-            maxRetries: resolvedMaxRetries,
-            retryDelay: resolvedRetryDelay,
-            debugEnabled,
-        });
-        const providerChanged = activeProvider !== resolvedInstrumentationProvider;
-        const hostChanged = activeHostElement !== hostElement;
-        const configChanged = monitorConfigKey !== nextConfigKey;
-        const shouldReinitialize = hostElement && isInitialized && (hostChanged || configChanged || providerChanged);
-        // Clean up existing monitor if host element becomes null
-        if (!hostElement && monitor) {
-            logger.debug(`Host element removed, stopping resource monitor for ${componentName}`);
-            monitor.stop();
-            monitor = null;
-            isInitialized = false;
-            activeHostElement = null;
-            activeProvider = undefined;
-            monitorConfigKey = "";
-            return;
-        }
-        if (shouldReinitialize && monitor) {
-            logger.debug(`Reinitializing resource monitor for ${componentName}`, {
-                hostChanged,
-                configChanged,
-                providerChanged,
-            });
-            monitor.stop();
-            monitor = null;
-            isInitialized = false;
-        }
-        // Initialize if we have a host element (retry logic works independently of trackPageActions)
-        if (hostElement && !isInitialized) {
-            logger.debug(`Initializing resource monitor for ${componentName}`, {
+        void getHostElement();
+        void getLoaderConfig();
+        void getDebugEnabled();
+        untrack(() => {
+            const hostElement = getHostElement();
+            const loaderConfig = getLoaderConfig();
+            const debugEnabled = getDebugEnabled();
+            const resolvedTrackPageActions = loaderConfig?.trackPageActions ?? false;
+            const resolvedMaxRetries = loaderConfig?.maxResourceRetries ??
+                DEFAULT_LOADER_CONFIG.maxResourceRetries;
+            const resolvedRetryDelay = loaderConfig?.resourceRetryDelay ??
+                DEFAULT_LOADER_CONFIG.resourceRetryDelay;
+            const resolvedInstrumentationProvider = isInstrumentationProvider(loaderConfig?.instrumentationProvider)
+                ? loaderConfig?.instrumentationProvider
+                : undefined;
+            if (debugEnabled &&
+                loaderConfig?.instrumentationProvider &&
+                !resolvedInstrumentationProvider) {
+                logger.warn(`Ignoring invalid instrumentation provider for ${componentName}; expected InstrumentationProvider contract`);
+            }
+            const nextConfigKey = JSON.stringify({
                 trackPageActions: resolvedTrackPageActions,
                 maxRetries: resolvedMaxRetries,
                 retryDelay: resolvedRetryDelay,
-                hasCustomProvider: !!resolvedInstrumentationProvider,
-                hasContainer: !!hostElement,
+                debugEnabled,
             });
-            // Create and start resource monitor with config from loaderConfig
-            monitor = new ResourceMonitor({
-                trackPageActions: resolvedTrackPageActions,
-                instrumentationProvider: resolvedInstrumentationProvider,
-                maxRetries: resolvedMaxRetries,
-                initialRetryDelay: resolvedRetryDelay,
-                maxRetryDelay: DEFAULT_MAX_RETRY_DELAY,
-                debug: debugEnabled,
-            });
-            monitor.start(hostElement);
-            isInitialized = true;
-            activeHostElement = hostElement;
-            activeProvider = resolvedInstrumentationProvider;
-            monitorConfigKey = nextConfigKey;
-            logger.info(`✅ Resource monitoring enabled for ${componentName}` +
-                (resolvedTrackPageActions
-                    ? resolvedInstrumentationProvider
-                        ? " (with custom instrumentation provider)"
-                        : " (with New Relic tracking)"
-                    : " (retry only)"));
-        }
+            const providerChanged = activeProvider !== resolvedInstrumentationProvider;
+            const hostChanged = activeHostElement !== hostElement;
+            const configChanged = monitorConfigKey !== nextConfigKey;
+            const shouldReinitialize = hostElement && isInitialized && (hostChanged || configChanged || providerChanged);
+            if (!hostElement && monitor) {
+                logger.debug(`Host element removed, stopping resource monitor for ${componentName}`);
+                monitor.stop();
+                monitor = null;
+                isInitialized = false;
+                activeHostElement = null;
+                activeProvider = undefined;
+                monitorConfigKey = "";
+                return;
+            }
+            if (shouldReinitialize && monitor) {
+                logger.debug(`Reinitializing resource monitor for ${componentName}`, {
+                    hostChanged,
+                    configChanged,
+                    providerChanged,
+                });
+                monitor.stop();
+                monitor = null;
+                isInitialized = false;
+            }
+            if (hostElement && !isInitialized) {
+                logger.debug(`Initializing resource monitor for ${componentName}`, {
+                    trackPageActions: resolvedTrackPageActions,
+                    maxRetries: resolvedMaxRetries,
+                    retryDelay: resolvedRetryDelay,
+                    hasCustomProvider: !!resolvedInstrumentationProvider,
+                    hasContainer: !!hostElement,
+                });
+                monitor = new ResourceMonitor({
+                    trackPageActions: resolvedTrackPageActions,
+                    instrumentationProvider: resolvedInstrumentationProvider,
+                    maxRetries: resolvedMaxRetries,
+                    initialRetryDelay: resolvedRetryDelay,
+                    maxRetryDelay: DEFAULT_MAX_RETRY_DELAY,
+                    debug: debugEnabled,
+                });
+                monitor.start(hostElement);
+                isInitialized = true;
+                activeHostElement = hostElement;
+                activeProvider = resolvedInstrumentationProvider;
+                monitorConfigKey = nextConfigKey;
+                logger.info(`✅ Resource monitoring enabled for ${componentName}` +
+                    (resolvedTrackPageActions
+                        ? resolvedInstrumentationProvider
+                            ? " (with custom instrumentation provider)"
+                            : " (with New Relic tracking)"
+                        : " (retry only)"));
+            }
+        });
     });
     // Cleanup on component destroy
     onDestroy(() => {

package/dist/pie/use-resource-monitor.svelte.js.map

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

package/dist/ui/use-promise.svelte.ts

@@ -0,0 +1,109 @@
+/**
+ * Svelte 5 composable that turns a promise factory into a reactive lifecycle
+ * value with four explicit states. Consumers read `handle.current` in a
+ * `$derived`/template and get race-free status transitions.
+ *
+ * Why this exists
+ * ---------------
+ *
+ * Svelte 5's reactivity is runes-based, and placing a promise directly inside
+ * a `$derived` is awkward: the derived value is the promise itself, and the
+ * component needs to await it indirectly, usually via an ad-hoc `$state` flag
+ * set from a `$effect`. That pattern is the root cause of the section-swap
+ * readiness race fixed as part of the deep ElementLoader architecture work:
+ *
+ *   let ready = $state(false);
+ *   $effect(() => { loader(args).then(() => ready = true); });
+ *   {#if ready} <Items /> {/if}
+ *
+ * When `args` change under a live component, `ready` can be stale while the
+ * template has already re-rendered with the new inputs. The fix is to treat
+ * the loader call as a lifecycle value that (a) carries its own status,
+ * (b) invalidates instantly when its inputs change, and (c) ignores late
+ * resolutions from stale invocations.
+ *
+ * Contract
+ * --------
+ *
+ * - The factory is called reactively; every tracked read inside the factory
+ *   participates in the effect's dependencies.
+ * - When the factory returns `null`, the handle moves back to `idle`.
+ * - Each invocation is tagged with a monotonic token; only the most-recent
+ *   invocation can transition the handle out of `pending`. Earlier
+ *   resolutions are silently dropped.
+ * - `handle.current` is the single read surface; the underlying `$state` is
+ *   not exposed. Templates use `{#if handle.current.status === "resolved"}`.
+ *
+ * Example
+ * -------
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { usePromise } from "@pie-players/pie-players-shared/ui";
+ *
+ *   let { items } = $props();
+ *
+ *   const readiness = usePromise(() =>
+ *     items.length === 0 ? null : loader.ensureRegistered(aggregate(items)),
+ *   );
+ * </script>
+ *
+ * {#if readiness.current.status === "resolved"}
+ *   {#each items as item}<item-card {item} />{/each}
+ * {:else if readiness.current.status === "rejected"}
+ *   <ErrorBanner error={readiness.current.error} />
+ * {:else}
+ *   <LoadingSpinner />
+ * {/if}
+ * ```
+ */
+
+export type PromiseState<T> =
+	| { status: "idle" }
+	| { status: "pending" }
+	| { status: "resolved"; data: T }
+	| { status: "rejected"; error: unknown };
+
+export type PromiseHandle<T> = {
+	readonly current: PromiseState<T>;
+};
+
+/**
+ * Reactive promise lifecycle helper.
+ *
+ * @param factory Function that returns the promise to track, or `null` to
+ *   return to `idle`. Called inside a `$effect`, so every reactive read
+ *   participates in the invalidation graph.
+ */
+export function usePromise<T>(
+	factory: () => Promise<T> | null | undefined,
+): PromiseHandle<T> {
+	let state = $state<PromiseState<T>>({ status: "idle" });
+	let token = 0;
+
+	$effect(() => {
+		const promise = factory();
+		if (!promise) {
+			state = { status: "idle" };
+			return;
+		}
+		const thisToken = ++token;
+		state = { status: "pending" };
+		promise.then(
+			(data) => {
+				if (thisToken !== token) return;
+				state = { status: "resolved", data };
+			},
+			(error) => {
+				if (thisToken !== token) return;
+				state = { status: "rejected", error };
+			},
+		);
+	});
+
+	return {
+		get current() {
+			return state;
+		},
+	};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-players-shared",
-	"version": "0.3.30",
+	"version": "0.3.31",
 	"type": "module",
 	"description": "Shared runtime + UI utilities for PIE players",
 	"license": "MIT",
@@ -101,6 +101,11 @@
 			"types": "./dist/i18n/use-i18n-standalone.svelte.ts",
 			"import": "./dist/i18n/use-i18n-standalone.svelte.ts",
 			"svelte": "./dist/i18n/use-i18n-standalone.svelte.ts"
+		},
+		"./ui/use-promise": {
+			"types": "./dist/ui/use-promise.svelte.ts",
+			"import": "./dist/ui/use-promise.svelte.ts",
+			"svelte": "./dist/ui/use-promise.svelte.ts"
 		}
 	},
 	"files": [

package/dist/loaders/EsmElementLoader.d.ts

@@ -1,69 +0,0 @@
-/**
- * ESM Element Loader
- *
- * Wraps EsmPieLoader to provide element-level loading abstraction.
- * Aggregates elements from multiple items and loads them once using ESM modules.
- */
-import type { ItemEntity } from "../types/index.js";
-import { type ElementLoaderInterface, type ElementMap, type LoadOptions } from "./ElementLoader.js";
-/**
- * Configuration for ESM element loader
- */
-export interface EsmElementLoaderConfig {
-    /** Base URL for ESM CDN (e.g., "https://esm.sh") */
-    esmCdnUrl: string;
-    /** Module resolution mode (default: "url") */
-    moduleResolution?: "url" | "import-map";
-    /** Optional function to check if debug mode is enabled */
-    debugEnabled?: () => boolean;
-}
-/**
- * Element loader for ESM (ES Modules) bundles
- *
- * This loader wraps EsmPieLoader and provides element aggregation capabilities.
- * It eliminates duplicate bundle loads when multiple items use the same PIE elements.
- * ESM is the modern, preferred loading mechanism with better browser support and features.
- *
- * @example
- * ```typescript
- * const loader = new EsmElementLoader({
- *   esmCdnUrl: 'https://esm.sh'
- * });
- *
- * // Load elements from multiple items at once
- * await loader.loadFromItems(section.items, {
- *   view: 'delivery',
- *   needsControllers: true
- * });
- *
- * // Or load specific elements directly
- * await loader.loadElements({
- *   'pie-multiple-choice': '@pie-element/multiple-choice@11.0.1',
- *   'pie-hotspot': '@pie-element/hotspot@9.0.0'
- * }, {
- *   view: 'author' // Load author view for editing
- * });
- * ```
- */
-export declare class EsmElementLoader implements ElementLoaderInterface {
-    private loader;
-    constructor(config: EsmElementLoaderConfig);
-    /**
-     * Load elements directly from an element map
-     *
-     * @param elements - Map of element tag names to package versions
-     * @param options - Loading options
-     */
-    loadElements(elements: ElementMap, options?: LoadOptions): Promise<void>;
-    /**
-     * Extract and load elements from items
-     *
-     * Automatically aggregates unique elements from all items and loads them once.
-     *
-     * @param items - Array of items to extract elements from
-     * @param options - Loading options
-     * @throws Error if element version conflicts are detected
-     */
-    loadFromItems(items: ItemEntity[], options?: LoadOptions): Promise<void>;
-}
-//# sourceMappingURL=EsmElementLoader.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"EsmElementLoader.d.ts","sourceRoot":"","sources":["../../src/loaders/EsmElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAElB,8CAA8C;IAC9C,gBAAgB,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC;IAExC,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAiB,YAAW,sBAAsB;IAC9D,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,EAAE,sBAAsB;IAQ1C;;;;;OAKG;IACG,YAAY,CACjB,QAAQ,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;IAOhB;;;;;;;;OAQG;IACG,aAAa,CAClB,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;CAIhB"}

package/dist/loaders/EsmElementLoader.js

@@ -1,72 +0,0 @@
-/**
- * ESM Element Loader
- *
- * Wraps EsmPieLoader to provide element-level loading abstraction.
- * Aggregates elements from multiple items and loads them once using ESM modules.
- */
-import { EsmPieLoader } from "../pie/esm-loader.js";
-import { aggregateElements, } from "./ElementLoader.js";
-/**
- * Element loader for ESM (ES Modules) bundles
- *
- * This loader wraps EsmPieLoader and provides element aggregation capabilities.
- * It eliminates duplicate bundle loads when multiple items use the same PIE elements.
- * ESM is the modern, preferred loading mechanism with better browser support and features.
- *
- * @example
- * ```typescript
- * const loader = new EsmElementLoader({
- *   esmCdnUrl: 'https://esm.sh'
- * });
- *
- * // Load elements from multiple items at once
- * await loader.loadFromItems(section.items, {
- *   view: 'delivery',
- *   needsControllers: true
- * });
- *
- * // Or load specific elements directly
- * await loader.loadElements({
- *   'pie-multiple-choice': '@pie-element/multiple-choice@11.0.1',
- *   'pie-hotspot': '@pie-element/hotspot@9.0.0'
- * }, {
- *   view: 'author' // Load author view for editing
- * });
- * ```
- */
-export class EsmElementLoader {
-    loader;
-    constructor(config) {
-        this.loader = new EsmPieLoader({
-            cdnBaseUrl: config.esmCdnUrl,
-            moduleResolution: config.moduleResolution,
-            debugEnabled: config.debugEnabled,
-        });
-    }
-    /**
-     * Load elements directly from an element map
-     *
-     * @param elements - Map of element tag names to package versions
-     * @param options - Loading options
-     */
-    async loadElements(elements, options) {
-        await this.loader.load({ elements }, document, {
-            view: options?.view || "delivery",
-            loadControllers: options?.needsControllers ?? true,
-        });
-    }
-    /**
-     * Extract and load elements from items
-     *
-     * Automatically aggregates unique elements from all items and loads them once.
-     *
-     * @param items - Array of items to extract elements from
-     * @param options - Loading options
-     * @throws Error if element version conflicts are detected
-     */
-    async loadFromItems(items, options) {
-        const elements = aggregateElements(items);
-        await this.loadElements(elements, options);
-    }
-}
-//# sourceMappingURL=EsmElementLoader.js.map

package/dist/loaders/EsmElementLoader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"EsmElementLoader.js","sourceRoot":"","sources":["../../src/loaders/EsmElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EACN,iBAAiB,GAIjB,MAAM,oBAAoB,CAAC;AAgB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,gBAAgB;IACpB,MAAM,CAAe;IAE7B,YAAY,MAA8B;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC;YAC9B,UAAU,EAAE,MAAM,CAAC,SAAS;YAC5B,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;YACzC,YAAY,EAAE,MAAM,CAAC,YAAY;SACjC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CACjB,QAAoB,EACpB,OAAqB;QAErB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE;YAC9C,IAAI,EAAE,OAAO,EAAE,IAAI,IAAI,UAAU;YACjC,eAAe,EAAE,OAAO,EAAE,gBAAgB,IAAI,IAAI;SAClD,CAAC,CAAC;IACJ,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,aAAa,CAClB,KAAmB,EACnB,OAAqB;QAErB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;CACD"}

package/dist/loaders/IifeElementLoader.d.ts

@@ -1,61 +0,0 @@
-/**
- * IIFE Element Loader
- *
- * Wraps IifePieLoader to provide element-level loading abstraction.
- * Aggregates elements from multiple items and loads them once using IIFE bundles.
- */
-import type { ItemEntity } from "../types/index.js";
-import { type ElementLoaderInterface, type ElementMap, type LoadOptions } from "./ElementLoader.js";
-/**
- * Configuration for IIFE element loader
- */
-export interface IifeElementLoaderConfig {
-    /** Base URL for bundle service (e.g., "https://bundles.pie.org") */
-    bundleHost: string;
-    /** Optional function to check if debug mode is enabled */
-    debugEnabled?: () => boolean;
-}
-/**
- * Element loader for IIFE (Immediately Invoked Function Expression) bundles
- *
- * This loader wraps IifePieLoader and provides element aggregation capabilities.
- * It eliminates duplicate bundle loads when multiple items use the same PIE elements.
- *
- * @example
- * ```typescript
- * const loader = new IifeElementLoader({
- *   bundleHost: 'https://bundles.pie.org'
- * });
- *
- * // Load elements from multiple items at once
- * await loader.loadFromItems(section.items);
- *
- * // Or load specific elements directly
- * await loader.loadElements({
- *   'pie-multiple-choice': '@pie-element/multiple-choice@11.0.1',
- *   'pie-hotspot': '@pie-element/hotspot@9.0.0'
- * });
- * ```
- */
-export declare class IifeElementLoader implements ElementLoaderInterface {
-    private loader;
-    constructor(config: IifeElementLoaderConfig);
-    /**
-     * Load elements directly from an element map
-     *
-     * @param elements - Map of element tag names to package versions
-     * @param options - Loading options
-     */
-    loadElements(elements: ElementMap, options?: LoadOptions): Promise<void>;
-    /**
-     * Extract and load elements from items
-     *
-     * Automatically aggregates unique elements from all items and loads them once.
-     *
-     * @param items - Array of items to extract elements from
-     * @param options - Loading options
-     * @throws Error if element version conflicts are detected
-     */
-    loadFromItems(items: ItemEntity[], options?: LoadOptions): Promise<void>;
-}
-//# sourceMappingURL=IifeElementLoader.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"IifeElementLoader.d.ts","sourceRoot":"","sources":["../../src/loaders/IifeElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAEN,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IAEnB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAkB,YAAW,sBAAsB;IAC/D,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,uBAAuB;IAO3C;;;;;OAKG;IACG,YAAY,CACjB,QAAQ,EAAE,UAAU,EACpB,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;;;;OAQG;IACG,aAAa,CAClB,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC;CAIhB"}

package/dist/loaders/IifeElementLoader.js

@@ -1,63 +0,0 @@
-/**
- * IIFE Element Loader
- *
- * Wraps IifePieLoader to provide element-level loading abstraction.
- * Aggregates elements from multiple items and loads them once using IIFE bundles.
- */
-import { IifePieLoader } from "../pie/iife-loader.js";
-import { BundleType } from "../pie/types.js";
-import { aggregateElements, } from "./ElementLoader.js";
-/**
- * Element loader for IIFE (Immediately Invoked Function Expression) bundles
- *
- * This loader wraps IifePieLoader and provides element aggregation capabilities.
- * It eliminates duplicate bundle loads when multiple items use the same PIE elements.
- *
- * @example
- * ```typescript
- * const loader = new IifeElementLoader({
- *   bundleHost: 'https://bundles.pie.org'
- * });
- *
- * // Load elements from multiple items at once
- * await loader.loadFromItems(section.items);
- *
- * // Or load specific elements directly
- * await loader.loadElements({
- *   'pie-multiple-choice': '@pie-element/multiple-choice@11.0.1',
- *   'pie-hotspot': '@pie-element/hotspot@9.0.0'
- * });
- * ```
- */
-export class IifeElementLoader {
-    loader;
-    constructor(config) {
-        this.loader = new IifePieLoader({
-            bundleHost: config.bundleHost,
-            debugEnabled: config.debugEnabled,
-        });
-    }
-    /**
-     * Load elements directly from an element map
-     *
-     * @param elements - Map of element tag names to package versions
-     * @param options - Loading options
-     */
-    async loadElements(elements, options) {
-        await this.loader.load({ elements }, document, options?.bundleType || BundleType.clientPlayer, options?.needsControllers ?? true);
-    }
-    /**
-     * Extract and load elements from items
-     *
-     * Automatically aggregates unique elements from all items and loads them once.
-     *
-     * @param items - Array of items to extract elements from
-     * @param options - Loading options
-     * @throws Error if element version conflicts are detected
-     */
-    async loadFromItems(items, options) {
-        const elements = aggregateElements(items);
-        await this.loadElements(elements, options);
-    }
-}
-//# sourceMappingURL=IifeElementLoader.js.map

package/dist/loaders/IifeElementLoader.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"IifeElementLoader.js","sourceRoot":"","sources":["../../src/loaders/IifeElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EACN,iBAAiB,GAIjB,MAAM,oBAAoB,CAAC;AAa5B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,iBAAiB;IACrB,MAAM,CAAgB;IAE9B,YAAY,MAA+B;QAC1C,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC;YAC/B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;SACjC,CAAC,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,YAAY,CACjB,QAAoB,EACpB,OAAqB;QAErB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACrB,EAAE,QAAQ,EAAE,EACZ,QAAQ,EACR,OAAO,EAAE,UAAU,IAAI,UAAU,CAAC,YAAY,EAC9C,OAAO,EAAE,gBAAgB,IAAI,IAAI,CACjC,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,aAAa,CAClB,KAAmB,EACnB,OAAqB;QAErB,MAAM,QAAQ,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;CACD"}