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

package/dist/index.js

@@ -12,4 +12,8 @@ export * from "./ui/focus-trap.js";
 export * from "./ui/first-focusable.js";
 export * from "./ui/debug-panel-persistence.js";
 export * from "./ui/safe-storage.js";
+// use-promise is a Svelte 5 runes module and is shipped as raw source via
+// the `./ui/use-promise` subpath export. It is not re-exported here because
+// tsc cannot compile `.svelte.ts` runes correctly; the consumer's Svelte
+// plugin processes it at consume time.
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,0CAA0C;AAC1C,cAAc,gBAAgB,CAAC;AAmB/B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,0CAA0C;AAC1C,cAAc,gBAAgB,CAAC;AAmB/B,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,0EAA0E;AAC1E,4EAA4E;AAC5E,yEAAyE;AACzE,uCAAuC"}

package/dist/loaders/ElementLoader.d.ts

@@ -1,11 +1,12 @@
 /**
- * Element Loader - Core types and utilities for loading PIE elements
+ * Element Loader — element aggregation utilities.
  *
- * This module provides element aggregation and loading abstractions for PIE players.
- * It enables loading multiple PIE elements in a single operation, eliminating duplicate
- * bundle requests when multiple items use the same elements.
+ * The deep `ElementLoader` primitive lives in `./element-loader.ts`. This
+ * module owns the shared `ElementMap` type and the `aggregateElements`
+ * helper that reduces many items' element declarations into a single
+ * deduplicated, version-aware map (used by the section-player to
+ * pre-warm in one shot).
  */
-import type { BundleType } from "../pie/types.js";
 import type { ItemEntity } from "../types/index.js";
 /**
  * Map of element tag names to their package versions
@@ -14,35 +15,6 @@ import type { ItemEntity } from "../types/index.js";
 export type ElementMap = {
     [tagName: string]: string;
 };
-/**
- * Options for loading PIE elements
- */
-export interface LoadOptions {
-    /** Bundle type to load (player or clientPlayer) */
-    bundleType?: BundleType;
-    /** Whether to load controllers (for client-side processing) */
-    needsControllers?: boolean;
-    /** View mode (ESM only) - delivery, author, or print */
-    view?: "delivery" | "author" | "print";
-}
-/**
- * Common interface for element loaders (IIFE and ESM)
- */
-export interface ElementLoaderInterface {
-    /**
-     * 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
-     * @param items - Array of items to extract elements from
-     * @param options - Loading options
-     */
-    loadFromItems(items: ItemEntity[], options?: LoadOptions): Promise<void>;
-}
 /**
  * Aggregate unique elements from multiple items
  *

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

@@ -1 +1 @@
-{"version":3,"file":"ElementLoader.d.ts","sourceRoot":"","sources":["../../src/loaders/ElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,mDAAmD;IACnD,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,wDAAwD;IACxD,IAAI,CAAC,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACtC;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzE;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,CAmDjE"}
+{"version":3,"file":"ElementLoader.d.ts","sourceRoot":"","sources":["../../src/loaders/ElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,CAmEjE"}

package/dist/loaders/ElementLoader.js

@@ -1,9 +1,11 @@
 /**
- * Element Loader - Core types and utilities for loading PIE elements
+ * Element Loader — element aggregation utilities.
  *
- * This module provides element aggregation and loading abstractions for PIE players.
- * It enables loading multiple PIE elements in a single operation, eliminating duplicate
- * bundle requests when multiple items use the same elements.
+ * The deep `ElementLoader` primitive lives in `./element-loader.ts`. This
+ * module owns the shared `ElementMap` type and the `aggregateElements`
+ * helper that reduces many items' element declarations into a single
+ * deduplicated, version-aware map (used by the section-player to
+ * pre-warm in one shot).
  */
 import { parsePackageName } from "../pie/utils.js";
 /**
@@ -35,21 +37,31 @@ export function aggregateElements(items) {
     const elementMap = {};
     const seenOriginalTags = {};
     const VERSION_DELIMITER = "--version-";
+    const TAG_VERSION_PATTERN = "[0-9A-Za-z-]+";
+    const encodeVersionForTag = (version) => version
+        .trim()
+        .replace(/[.+]/g, "-")
+        .replace(/[^0-9A-Za-z-]/g, "-")
+        .replace(/-{2,}/g, "-");
     const parseTagName = (tagName) => {
-        const versionMatch = tagName.match(`${VERSION_DELIMITER}(\\d+-\\d+-\\d+)$`);
+        const versionMatch = tagName.match(new RegExp(`${VERSION_DELIMITER}(${TAG_VERSION_PATTERN})$`));
         return versionMatch
             ? {
                 baseName: tagName.replace(`${VERSION_DELIMITER}${versionMatch[1]}`, ""),
-                existingVersion: versionMatch[1].replace(/-/g, "."),
+                existingEncodedVersion: versionMatch[1],
             }
             : { baseName: tagName };
     };
     const normalizeElementTag = (tagName, packageSpec) => {
-        const { baseName, existingVersion } = parseTagName(tagName);
+        const { baseName, existingEncodedVersion } = parseTagName(tagName);
         const { version } = parsePackageName(packageSpec);
-        if (!version || existingVersion === version)
+        if (!version)
             return tagName;
-        return `${baseName}${VERSION_DELIMITER}${version.replace(/\./g, "-")}`;
+        const targetEncodedVersion = encodeVersionForTag(version);
+        if (!targetEncodedVersion || existingEncodedVersion === targetEncodedVersion) {
+            return tagName;
+        }
+        return `${baseName}${VERSION_DELIMITER}${targetEncodedVersion}`;
     };
     items.forEach((item) => {
         const itemElements = item.config?.elements || {};

package/dist/loaders/ElementLoader.js.map

@@ -1 +1 @@
-{"version":3,"file":"ElementLoader.js","sourceRoot":"","sources":["../../src/loaders/ElementLoader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA2CnD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAmB;IACpD,MAAM,UAAU,GAA2B,EAAE,CAAC;IAC9C,MAAM,gBAAgB,GAA2B,EAAE,CAAC;IAEpD,MAAM,iBAAiB,GAAG,YAAY,CAAC;IACvC,MAAM,YAAY,GAAG,CACpB,OAAe,EACkC,EAAE;QACnD,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,iBAAiB,mBAAmB,CAAC,CAAC;QAC5E,OAAO,YAAY;YAClB,CAAC,CAAC;gBACA,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,iBAAiB,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;gBACvE,eAAe,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;aACnD;YACF,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;IAC1B,CAAC,CAAC;IACF,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAE,WAAmB,EAAU,EAAE;QAC5E,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAC5D,MAAM,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,CAAC,OAAO,IAAI,eAAe,KAAK,OAAO;YAAE,OAAO,OAAO,CAAC;QAC5D,OAAO,GAAG,QAAQ,GAAG,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;IACxE,CAAC,CAAC;IAEF,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QACtB,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAC;QAEjD,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE;YACnD,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC5B,gBAAgB,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;YACrC,CAAC;iBAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,KAAK,WAAW,EAAE,CAAC;gBAClD,kEAAkE;gBAClE,MAAM,IAAI,KAAK,CACd,6BAA6B,GAAG,kBAAkB,gBAAgB,CAAC,GAAG,CAAC,QAAQ,WAAW,IAAI;oBAC7F,mEAAmE,CACpE,CAAC;YACH,CAAC;YAED,MAAM,aAAa,GAAG,mBAAmB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;YAC5D,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;gBAChC,UAAU,CAAC,aAAa,CAAC,GAAG,WAAW,CAAC;YACzC,CAAC;iBAAM,IAAI,UAAU,CAAC,aAAa,CAAC,KAAK,WAAW,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CACd,6BAA6B,aAAa,kBAAkB,UAAU,CAAC,aAAa,CAAC,QAAQ,WAAW,IAAI;oBAC3G,mEAAmE,CACpE,CAAC;YACH,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,UAAU,CAAC;AACnB,CAAC"}
+{"version":3,"file":"ElementLoader.js","sourceRoot":"","sources":["../../src/loaders/ElementLoader.ts"],"names":[],"mappings":"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"}

package/dist/loaders/element-loader-types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types for the ElementLoader primitive and its backend adapters.
+ *
+ * Keeping types in their own module breaks the import cycle that would
+ * otherwise form between the primitive (which dispatches to adapters) and
+ * the adapters (which implement the backend interface).
+ */
+import type { ElementMap } from "./ElementLoader.js";
+export type ElementTag = string;
+export type { ElementMap };
+/**
+ * Structured reason for why a specific tag failed to register.
+ *
+ * The primitive prefers adapter-supplied reasons (rich, diagnostic) over the
+ * generic `timeout` reason it synthesizes from its own verification pass.
+ */
+export type RegistrationFailureReason = {
+    kind: "timeout";
+    tag: ElementTag;
+    timeoutMs: number;
+} | {
+    kind: "not-a-constructor";
+    tag: ElementTag;
+    packageName?: string;
+} | {
+    kind: "package-not-in-bundle";
+    tag: ElementTag;
+    packageName: string;
+    availablePackages: string[];
+} | {
+    kind: "module-load-failed";
+    tag: ElementTag;
+    specifier: string;
+    cause: string;
+} | {
+    kind: "bundle-load-failed";
+    tag: ElementTag;
+    url: string;
+    cause: string;
+} | {
+    kind: "define-failed";
+    tag: ElementTag;
+    cause: string;
+} | {
+    kind: "backend-rejected";
+    tag: ElementTag;
+    cause: string;
+} | {
+    kind: "no-element-class";
+    tag: ElementTag;
+    packageName: string;
+};
+/**
+ * Thrown by an adapter when it has structured, per-tag knowledge of which
+ * registrations failed and why. The primitive unpacks the `reasons` map
+ * and merges it into its own `ElementLoaderError.reasons`.
+ *
+ * Generic `Error` thrown from an adapter is treated as catastrophic: the
+ * primitive assigns a blanket `backend-rejected` reason to every requested
+ * tag that is still missing after verification.
+ */
+export declare class AdapterFailure extends Error {
+    readonly name = "AdapterFailure";
+    readonly reasons: Map<ElementTag, RegistrationFailureReason>;
+    constructor(reasons: Map<ElementTag, RegistrationFailureReason>);
+}
+/**
+ * Context the primitive hands to the adapter for each load.
+ *
+ * The adapter is free to use `whenDefinedTimeoutMs` for its own internal
+ * waits, but the primitive always enforces an independent
+ * `customElements.whenDefined` verification after the adapter returns — so
+ * an adapter cannot silently under-register tags even if it ignores this
+ * context.
+ */
+export type BackendContext = {
+    doc: Document;
+    whenDefinedTimeoutMs: number;
+};
+/**
+ * Backend adapter contract.
+ *
+ * Resolve only if every requested tag was attempted and the adapter
+ * believes every tag is registered. On partial failure, throw
+ * `AdapterFailure` with a `reasons` map. On catastrophic failure, throw a
+ * generic Error.
+ */
+export type ElementLoaderBackend = {
+    load(elements: ElementMap, context: BackendContext): Promise<void>;
+};
+//# sourceMappingURL=element-loader-types.d.ts.map

package/dist/loaders/element-loader-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-loader-types.d.ts","sourceRoot":"","sources":["../../src/loaders/element-loader-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,MAAM,yBAAyB,GAClC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IACA,IAAI,EAAE,uBAAuB,CAAC;IAC9B,GAAG,EAAE,UAAU,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC3B,GACD;IACA,IAAI,EAAE,oBAAoB,CAAC;IAC3B,GAAG,EAAE,UAAU,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACb,GACD;IACA,IAAI,EAAE,oBAAoB,CAAC;IAC3B,GAAG,EAAE,UAAU,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACb,GACD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE;;;;;;;;GAQG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACxC,SAAkB,IAAI,oBAAoB;IAC1C,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,yBAAyB,CAAC,CAAC;gBAEjD,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,yBAAyB,CAAC;CAO/D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,GAAG,EAAE,QAAQ,CAAC;IACd,oBAAoB,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,CAAC,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE,CAAC"}

package/dist/loaders/element-loader-types.js

@@ -0,0 +1,26 @@
+/**
+ * Shared types for the ElementLoader primitive and its backend adapters.
+ *
+ * Keeping types in their own module breaks the import cycle that would
+ * otherwise form between the primitive (which dispatches to adapters) and
+ * the adapters (which implement the backend interface).
+ */
+/**
+ * Thrown by an adapter when it has structured, per-tag knowledge of which
+ * registrations failed and why. The primitive unpacks the `reasons` map
+ * and merges it into its own `ElementLoaderError.reasons`.
+ *
+ * Generic `Error` thrown from an adapter is treated as catastrophic: the
+ * primitive assigns a blanket `backend-rejected` reason to every requested
+ * tag that is still missing after verification.
+ */
+export class AdapterFailure extends Error {
+    name = "AdapterFailure";
+    reasons;
+    constructor(reasons) {
+        const tags = [...reasons.keys()];
+        super(`Backend adapter failure for ${reasons.size} tag(s): ${tags.join(", ")}`);
+        this.reasons = reasons;
+    }
+}
+//# sourceMappingURL=element-loader-types.js.map

package/dist/loaders/element-loader-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-loader-types.js","sourceRoot":"","sources":["../../src/loaders/element-loader-types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuCH;;;;;;;;GAQG;AACH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACtB,IAAI,GAAG,gBAAgB,CAAC;IACjC,OAAO,CAA6C;IAE7D,YAAY,OAAmD;QAC9D,MAAM,IAAI,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACjC,KAAK,CACJ,+BAA+B,OAAO,CAAC,IAAI,YAAY,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxE,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACxB,CAAC;CACD"}

package/dist/loaders/element-loader.d.ts

@@ -0,0 +1,92 @@
+/**
+ * ElementLoader primitive — the one place where "these tags are registered
+ * with customElements" is decided.
+ *
+ * Owns the truthful promise contract end-to-end:
+ *
+ *     ensureRegistered(elements, options) resolves iff every requested tag
+ *     is in `customElements` at the moment of resolution. On partial
+ *     success it rejects with an `ElementLoaderError` carrying the set of
+ *     unregistered tags and a per-tag `RegistrationFailureReason` map.
+ *
+ * The primitive delegates the actual fetch/register work to a backend
+ * adapter (IIFE or ESM) but always verifies the outcome via
+ * `customElements.whenDefined`. An adapter cannot silently under-register
+ * — the primitive will catch it and surface a timeout reason.
+ *
+ * See packages/players-shared/tests/element-loader-contract.test.ts for
+ * the executable specification of every failure mode this primitive is
+ * required to catch.
+ */
+import type { ElementMap } from "./ElementLoader.js";
+import { type ElementLoaderBackend, type ElementTag, type RegistrationFailureReason } from "./element-loader-types.js";
+import { type EsmBackendConfig } from "./esm-adapter.js";
+import { type IifeBackendConfig } from "./iife-adapter.js";
+export type { BackendContext, ElementLoaderBackend, ElementMap, ElementTag, RegistrationFailureReason, } from "./element-loader-types.js";
+export { AdapterFailure } from "./element-loader-types.js";
+export type { IifeBackendConfig } from "./iife-adapter.js";
+export type { EsmBackendConfig } from "./esm-adapter.js";
+/**
+ * Aggregate error thrown by `ensureRegistered` when one or more requested
+ * tags were not registered by the time verification timed out.
+ */
+export declare class ElementLoaderError extends Error {
+    readonly name = "ElementLoaderError";
+    readonly unregisteredTags: Set<ElementTag>;
+    readonly reasons: Map<ElementTag, RegistrationFailureReason>;
+    constructor(message: string, unregisteredTags: Set<ElementTag>, reasons: Map<ElementTag, RegistrationFailureReason>);
+}
+/**
+ * Thrown by `assertRegistered` when any requested tag is missing from
+ * `customElements`. Carries enough detail for the host to diagnose what
+ * pre-registration step was skipped.
+ */
+export declare class ElementAssertionError extends Error {
+    readonly name = "ElementAssertionError";
+    readonly expectedTags: readonly ElementTag[];
+    readonly missingTags: readonly ElementTag[];
+    readonly currentlyRegisteredTags: readonly ElementTag[];
+    constructor(expected: ElementTag[], missing: ElementTag[], currentlyRegistered: ElementTag[]);
+}
+export type BackendOption = IifeBackendConfig | EsmBackendConfig | ElementLoaderBackend;
+export type EnsureRegisteredOptions = {
+    backend: BackendOption;
+    doc?: Document;
+    whenDefinedTimeoutMs?: number;
+    /**
+     * Outer cumulative deadline for the backend's `load()` call.
+     *
+     * Closes the "promise never settles" seam for adapters whose underlying
+     * fetch can stall indefinitely (e.g. ESM `import()` against a frozen
+     * CDN). When the deadline elapses, the primitive synthesizes an
+     * `AdapterFailure` with `kind: "timeout"` reasons for every requested
+     * tag — surfacing as a normal `ElementLoaderError` to the caller.
+     *
+     * Defaults to `DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs` so
+     * adapter-internal retry windows (IIFE bundle-build polling) fit
+     * inside the same overall budget.
+     */
+    loadTimeoutMs?: number;
+};
+/**
+ * Resolve iff every tag in `elements` is registered with `customElements`.
+ * Reject with `ElementLoaderError` otherwise.
+ *
+ * The primitive is the sole authority on registration state:
+ * - Empty element map resolves immediately (no backend call).
+ * - Already-registered tags resolve immediately (no backend call).
+ * - Concurrent identical requests share one backend call.
+ * - After the adapter's `load` settles, a post-load verification pass
+ *   (bounded `customElements.whenDefined`) checks every tag. Any missing
+ *   tag becomes a rejection.
+ */
+export declare function ensureRegistered(elements: ElementMap, options: EnsureRegisteredOptions): Promise<void>;
+/**
+ * Synchronously assert that every tag is already in `customElements`.
+ * Throws `ElementAssertionError` with diagnostic detail otherwise.
+ *
+ * Used by hosts that opt into the "preloaded" strategy — they pre-register
+ * elements out-of-band and want a loud failure if anything is missing.
+ */
+export declare function assertRegistered(tags: ElementTag[]): void;
+//# sourceMappingURL=element-loader.d.ts.map

package/dist/loaders/element-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-loader.d.ts","sourceRoot":"","sources":["../../src/loaders/element-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAGN,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,yBAAyB,EAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEN,KAAK,gBAAgB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEN,KAAK,iBAAiB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACX,cAAc,EACd,oBAAoB,EACpB,UAAU,EACV,UAAU,EACV,yBAAyB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,wBAAwB;IAC9C,QAAQ,CAAC,gBAAgB,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,yBAAyB,CAAC,CAAC;gBAG5D,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,GAAG,CAAC,UAAU,CAAC,EACjC,OAAO,EAAE,GAAG,CAAC,UAAU,EAAE,yBAAyB,CAAC;CAMpD;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC/C,SAAkB,IAAI,2BAA2B;IACjD,QAAQ,CAAC,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,EAAE,SAAS,UAAU,EAAE,CAAC;IAC5C,QAAQ,CAAC,uBAAuB,EAAE,SAAS,UAAU,EAAE,CAAC;gBAGvD,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,EAAE,UAAU,EAAE,EACrB,mBAAmB,EAAE,UAAU,EAAE;CASlC;AAkBD,MAAM,MAAM,aAAa,GACtB,iBAAiB,GACjB,gBAAgB,GAChB,oBAAoB,CAAC;AAExB,MAAM,MAAM,uBAAuB,GAAG;IACrC,OAAO,EAAE,aAAa,CAAC;IACvB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AASF;;;;;;;;;;;GAWG;AACH,wBAAsB,gBAAgB,CACrC,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,uBAAuB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAoCf;AA2FD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,IAAI,CAKzD"}