@pie-players/pie-players-shared 0.3.75 → 1.0.0-beta.1

package/dist/i18n/provider.d.ts

@@ -43,12 +43,10 @@ export declare function detectBrowserLocale(): string;
 /**
  * The bundled provider.
  *
- * Retains the `SimpleI18n` name and the `I18nServiceApi` surface it published
- * before adoption. What changed is behaviour that had no caller: catalogs are
- * BCP-47 keyed and resolved through RFC 4647 lookup rather than string equality,
- * `dir`/`lang` are no longer written to `document.documentElement` (an embedded
- * player has no business writing the host page's root), and plural categories
- * come from `Intl.PluralRules` alone.
+ * Catalogs are BCP-47 keyed and resolved through RFC 4647 lookup, and plural
+ * categories come from `Intl.PluralRules`. It never writes `dir` or `lang` to
+ * `document.documentElement`: an embedded player does not own the host page's
+ * root.
  */
 export declare class SimpleI18n implements I18nServiceApi {
     /** Shared across instances and views: `Intl.PluralRules` is not cheap. */
@@ -138,11 +136,20 @@ export declare class SimpleI18n implements I18nServiceApi {
     private selectPluralCategory;
     private notify;
 }
+/**
+ * The graceful default: an English-only provider, shared process-wide.
+ *
+ * `composition-context.md` requires a resolver to work with no publisher
+ * present, and this is that state. A tool mounted bare — in `print-player` or
+ * an authoring harness — resolves this and renders English rather than
+ * leaking raw message keys onto the screen. It carries no locale loader, so it
+ * pulls no catalog beyond the 5 KB English one already in the bundle.
+ */
 export declare function getDefaultI18n(): I18nServiceApi;
 /**
  * Resolve a component's interface-locale provider from a published context.
  *
- * Returns a **fresh** object on every call, and that is the whole point. A
+ * Returns a **fresh** object on every call. A
  * provider is mutable: `setLocale` swaps its catalog in place, so its identity is
  * unchanged before and after a locale load. A reactive `$derived` reading the
  * provider directly therefore never invalidates, and a label rendered while the

package/dist/i18n/provider.js

@@ -9,7 +9,7 @@
  *
  * @module @pie-players/pie-players-shared/i18n/provider
  */
-import { findBestLanguageMatch, normalizeLanguageTag, } from "./language-tags.js";
+import { findBestLanguageMatch, normalizeLanguageTag, toLanguageTag, } from "./language-tags.js";
 import enUS from "./messages/en-US.js";
 /** The locale every fallback chain terminates at. */
 export const DEFAULT_LOCALE = "en-US";
@@ -31,7 +31,6 @@ export function dynamicMessageKey(key) {
  * Consulted only where `Intl.Locale.prototype.textInfo` is unavailable — it is
  * the authoritative CLDR answer but shipped late in Safari, and an assessment
  * laid out left-to-right for an Arabic reader is not a graceful degradation.
- * Replaces a four-entry list that omitted every subtag below.
  */
 const RTL_LANGUAGES = new Set([
     "ar", // Arabic
@@ -101,12 +100,10 @@ export function detectBrowserLocale() {
 /**
  * The bundled provider.
  *
- * Retains the `SimpleI18n` name and the `I18nServiceApi` surface it published
- * before adoption. What changed is behaviour that had no caller: catalogs are
- * BCP-47 keyed and resolved through RFC 4647 lookup rather than string equality,
- * `dir`/`lang` are no longer written to `document.documentElement` (an embedded
- * player has no business writing the host page's root), and plural categories
- * come from `Intl.PluralRules` alone.
+ * Catalogs are BCP-47 keyed and resolved through RFC 4647 lookup, and plural
+ * categories come from `Intl.PluralRules`. It never writes `dir` or `lang` to
+ * `document.documentElement`: an embedded player does not own the host page's
+ * root.
  */
 export class SimpleI18n {
     /** Shared across instances and views: `Intl.PluralRules` is not cheap. */
@@ -121,7 +118,7 @@ export class SimpleI18n {
     config;
     constructor(config = {}) {
         this.config = { ...config };
-        this.fallbackLocale = normalizeTag(config.fallbackLocale) || DEFAULT_LOCALE;
+        this.fallbackLocale = toLanguageTag(config.fallbackLocale) || DEFAULT_LOCALE;
         this.catalogs = new Map([[DEFAULT_LOCALE, enUS]]);
         this.customMessages = { ...(config.customMessages ?? {}) };
         this.loading = new Map();
@@ -160,11 +157,15 @@ export class SimpleI18n {
             // A locale we ship no catalog for is legitimate: the host may have
             // supplied its own messages for it. Honour the tag and let the
             // fallback chain cover whatever those messages omit.
-            this.locale = normalizeTag(locale) || DEFAULT_LOCALE;
+            this.locale = toLanguageTag(locale) || DEFAULT_LOCALE;
             this.notify();
             return;
         }
-        if (!this.catalogs.has(resolved)) {
+        // The loader is asked only for tags it declares. A tag that resolved through
+        // host messages alone has nothing to load, and is honoured like the
+        // unresolved case above.
+        if (!this.catalogs.has(resolved) &&
+            this.config.availableLocales?.includes(resolved)) {
             const inFlight = this.loading.get(resolved);
             if (inFlight) {
                 await inFlight;
@@ -243,7 +244,7 @@ export class SimpleI18n {
      * a catalog.
      */
     addCustomMessages(locale, messages) {
-        const tag = normalizeTag(locale);
+        const tag = toLanguageTag(locale);
         this.customMessages[tag] = deepMerge(this.customMessages[tag] ?? {}, messages);
         this.notify();
     }
@@ -256,7 +257,7 @@ export class SimpleI18n {
      * locales: the locale is per-view, the catalogs are per-provider.
      */
     withLocale(locale) {
-        const resolved = this.resolveLocaleTag(locale) ?? normalizeTag(locale);
+        const resolved = this.resolveLocaleTag(locale) ?? toLanguageTag(locale);
         if (resolved === this.locale)
             return this;
         const view = new SimpleI18n({ ...this.config, locale: resolved });
@@ -320,9 +321,9 @@ export class SimpleI18n {
             this.catalogs.set(locale, await load(locale));
         }
         catch (error) {
-            // A failed load is not fatal: the fallback chain still resolves every
-            // key to English. Rethrowing here would take down a player over a
-            // missing chunk.
+            // Rethrown with the locale named: `setLocale` rejects before switching
+            // (it assigns `this.locale` only after the load), so the previous locale
+            // stays active.
             throw new Error(`Failed to load i18n catalog for locale: ${locale}`, {
                 cause: error,
             });
@@ -350,9 +351,9 @@ export class SimpleI18n {
         const node = this.lookupNode(key);
         if (typeof node === "string")
             return node;
-        // A key landing on a namespace (`t("common")`) or on a plural group is a
-        // miss, not a hit: returning the object would put one where the caller
-        // expects a string, and interpolating it throws.
+        // A plural group resolves to its `other` form. A namespace (`t("common")`)
+        // is a miss: returning the object would put one where the caller expects
+        // a string, and interpolating it throws.
         if (node !== undefined && isPluralGroup(node))
             return node.other;
         return undefined;
@@ -375,9 +376,6 @@ export class SimpleI18n {
             listener();
     }
 }
-function normalizeTag(locale) {
-    return locale ? locale.trim().replace(/_/g, "-") : "";
-}
 function readPath(source, key) {
     if (!source)
         return undefined;
@@ -415,17 +413,16 @@ function deepMerge(target, source) {
     }
     return result;
 }
+let defaultProvider;
 /**
  * The graceful default: an English-only provider, shared process-wide.
  *
  * `composition-context.md` requires a resolver to work with no publisher
- * present, and this is that state. A tool mounted bare — in `print-player`, in
- * Studio preview, in an authoring harness — resolves this and renders English
- * rather than leaking raw message keys onto the screen. It carries no locale
- * loader, so it pulls no catalog beyond the 5 KB English one already in the
- * bundle.
+ * present, and this is that state. A tool mounted bare — in `print-player` or
+ * an authoring harness — resolves this and renders English rather than
+ * leaking raw message keys onto the screen. It carries no locale loader, so it
+ * pulls no catalog beyond the 5 KB English one already in the bundle.
  */
-let defaultProvider;
 export function getDefaultI18n() {
     if (!defaultProvider)
         defaultProvider = new SimpleI18n();
@@ -434,7 +431,7 @@ export function getDefaultI18n() {
 /**
  * Resolve a component's interface-locale provider from a published context.
  *
- * Returns a **fresh** object on every call, and that is the whole point. A
+ * Returns a **fresh** object on every call. A
  * provider is mutable: `setLocale` swaps its catalog in place, so its identity is
  * unchanged before and after a locale load. A reactive `$derived` reading the
  * provider directly therefore never invalidates, and a label rendered while the

package/dist/index.js

@@ -5,7 +5,6 @@ export * from "./player-strategy.js";
 export * from "./security/index.js";
 export * from "./loaders/index.js";
 export * from "./object/index.js";
-// Barrel export for PIE runtime utilities
 export * from "./pie/index.js";
 export { editorPostFix } from "./types/index.js";
 export * from "./ui/attribute-coercion.js";

package/dist/instrumentation/providers/BaseInstrumentationProvider.js

@@ -37,17 +37,13 @@ export class BaseInstrumentationProvider {
      * @param attributes Contextual attributes
      */
     trackError(error, attributes) {
-        // Guard: check if provider is ready
         if (!this.guardedOperation("trackError", error, attributes)) {
             return;
         }
-        // Apply error filter
         if (!this.applyErrorFilter(error, attributes)) {
             return;
         }
-        // Transform attributes
         const finalAttributes = this.transformAttributes(attributes);
-        // Delegate to concrete provider
         try {
             this.doTrackError(error, finalAttributes);
             if (this.config?.debug) {
@@ -73,28 +69,22 @@ export class BaseInstrumentationProvider {
      * @param attributes Event attributes
      */
     trackEvent(eventName, attributes) {
-        // Guard: check if provider is ready
         if (!this.guardedOperation("trackEvent", eventName, attributes)) {
             return;
         }
-        // Apply event filter
         if (!this.applyEventFilter(eventName, attributes)) {
             return;
         }
-        // Apply sampling
         if (!this.applySampling(eventName)) {
             return;
         }
-        // Transform attributes
         let finalAttributes = this.transformAttributes(attributes);
-        // Add timestamp if not present
         if (!finalAttributes.timestamp) {
             finalAttributes = {
                 ...finalAttributes,
                 timestamp: new Date().toISOString(),
             };
         }
-        // Delegate to concrete provider
         try {
             this.doTrackEvent(eventName, finalAttributes);
             if (this.config?.debug) {
@@ -134,11 +124,9 @@ export class BaseInstrumentationProvider {
      * @param attributes Optional user attributes
      */
     setUserContext(userId, attributes) {
-        // Guard: check if provider is ready
         if (!this.guardedOperation("setUserContext", userId, attributes)) {
             return;
         }
-        // Delegate to concrete provider
         try {
             this.doSetUserContext(userId, attributes);
             if (this.config?.debug) {
@@ -158,11 +146,9 @@ export class BaseInstrumentationProvider {
      * @param attributes Attributes to set globally
      */
     setGlobalAttributes(attributes) {
-        // Guard: check if provider is ready
         if (!this.guardedOperation("setGlobalAttributes", attributes)) {
             return;
         }
-        // Delegate to concrete provider
         try {
             this.doSetGlobalAttributes(attributes);
             if (this.config?.debug) {

package/dist/loader-config.d.ts

@@ -1,7 +1,5 @@
 /**
  * Shared loader configuration for PIE custom elements.
- *
- * Mirrors the `LoaderConfig` used by PIEOneer's custom element tags.
  */
 import type { InstrumentationProvider } from "./instrumentation/types.js";
 export type IifeBundleRetryConfig = {

package/dist/loader-config.js

@@ -1,7 +1,5 @@
 /**
  * Shared loader configuration for PIE custom elements.
- *
- * Mirrors the `LoaderConfig` used by PIEOneer's custom element tags.
  */
 export const DEFAULT_IIFE_BUNDLE_RETRY_CONFIG = {
     retryDelayMs: 3000,

package/dist/loaders/element-loader.js

@@ -128,6 +128,9 @@ const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
 // Module-scoped in-flight cache. Key: backend signature + sorted elements.
 // Keeps concurrent identical requests collapsed to one backend call.
 const inFlightRequests = new Map();
+// An ESM backend keeps page state that later loads build on (the import maps it
+// injected, the shared dependency versions they fixed), so every load with the
+// same config reuses one backend. IIFE backends are created per call.
 const resolvedEsmBackends = new Map();
 const resolvedBackendOverrides = new Map();
 /**
@@ -350,22 +353,26 @@ function backendKeyOf(backend) {
     }
     return "unknown";
 }
+/**
+ * Plain data compares by value, functions and other objects by identity, so
+ * two configs get one key only when they behave the same.
+ */
 function fingerprintValue(value) {
     return JSON.stringify(normalizeForFingerprint(value, new Map()));
 }
 function normalizeForFingerprint(value, seen) {
     if (value === null || value === undefined)
         return value;
-    const primitiveType = typeof value;
-    if (primitiveType === "string" ||
-        primitiveType === "number" ||
-        primitiveType === "boolean") {
+    const valueType = typeof value;
+    if (valueType === "string" ||
+        valueType === "number" ||
+        valueType === "boolean") {
         return value;
     }
-    if (primitiveType === "function") {
+    if (valueType === "function") {
         return { __functionRef: getFunctionRefId(value) };
     }
-    if (primitiveType !== "object") {
+    if (valueType !== "object") {
         return String(value);
     }
     const objectValue = value;

package/dist/loaders/esm-adapter.js

@@ -22,6 +22,7 @@ import { parsePackageName } from "../pie/utils.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { isExactSemver } from "./element-package-policy.js";
 import { forwardMathjaxEvents } from "./mathjax-events.js";
+import { isPlainRecord } from "../object/index.js";
 export const BUILT_IN_VIEWS = {
     delivery: { subpath: "", tagSuffix: "" },
     author: { subpath: "/author", tagSuffix: "-config", fallback: "delivery" },
@@ -123,10 +124,15 @@ export function createEsmBackend(config) {
             let injectedMap;
             if (Object.keys(imports).length > 0) {
                 const json = JSON.stringify({ imports }, null, 2);
+                // URL resolution maps the shared dependencies and the editor
+                // runtime, so it needs import maps too.
                 assertImportMapSupported();
                 injectedMap = injectImportMap(json, context.doc, runtimePlan?.mappedRuntime);
                 importMapObserver?.(json, context.doc);
             }
+            // Recorded before the map settles: a load that starts meanwhile skips
+            // these packages, builds on the shared dependency versions this map
+            // fixed, and its imports wait for the map in `importModule`.
             for (const [pkg, variant] of runtimePlan?.served ?? []) {
                 editorRuntimeVariants.set(pkg, variant);
             }
@@ -152,7 +158,7 @@ export function createEsmBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 return;
             }
@@ -189,9 +195,7 @@ export function createEsmBackend(config) {
                                 kind: "module-load-failed",
                                 tag,
                                 specifier: fallbackSpecifier,
-                                cause: fallbackErr instanceof Error
-                                    ? fallbackErr.message
-                                    : String(fallbackErr),
+                                cause: errorMessage(fallbackErr),
                             });
                             return;
                         }
@@ -201,7 +205,7 @@ export function createEsmBackend(config) {
                             kind: "module-load-failed",
                             tag,
                             specifier,
-                            cause: err instanceof Error ? err.message : String(err),
+                            cause: errorMessage(err),
                         });
                         return;
                     }
@@ -225,6 +229,8 @@ export function createEsmBackend(config) {
                 return;
             }
             try {
+                // `customElements` rejects a constructor already defined under
+                // another tag, so each versioned tag gets its own subclass.
                 defineCustomElementSafely(actualTag, class extends ElementClass {
                 }, `element tag for ${packageName}`);
             }
@@ -232,35 +238,13 @@ export function createEsmBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 return;
             }
-            let controller = null;
-            if (loadControllers) {
-                const servedVariant = editorRuntimeVariants.get(packageVersion);
-                const variantController = servedVariant?.views.controller;
-                if (servedVariant && variantController) {
-                    try {
-                        const controllerModule = await importModule(cdnProvider.browserViewUrl(packageVersion, variantController), context.doc);
-                        controller = controllerModule?.default ?? controllerModule;
-                    }
-                    catch (err) {
-                        reportEditorRuntimeFallback(packageVersion, servedVariant.declaration, servedVariant.runtime, `its editor-runtime controller failed to load: ${errorMessage(err)}`);
-                    }
-                }
-                if (!controller) {
-                    const controllerSpecifier = resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnProvider);
-                    try {
-                        const controllerModule = await importModule(controllerSpecifier, context.doc);
-                        controller = controllerModule?.default ?? controllerModule;
-                    }
-                    catch {
-                        // Controllers are best-effort; element registration is what the
-                        // primitive verifies.
-                    }
-                }
-            }
+            const controller = loadControllers
+                ? await importController(packageName, packageVersion, context.doc)
+                : null;
             writeRegistryEntry({
                 package: packageVersion,
                 status: Status.loaded,
@@ -293,6 +277,35 @@ export function createEsmBackend(config) {
             return undefined;
         }
     }
+    /**
+     * The package's controller: its editor-runtime variant's when one is served
+     * and loads, else the package's own. Controllers are best-effort; element
+     * registration is what the primitive verifies.
+     */
+    async function importController(packageName, packageVersion, doc) {
+        let controller = null;
+        const servedVariant = editorRuntimeVariants.get(packageVersion);
+        const variantController = servedVariant?.views.controller;
+        if (servedVariant && variantController) {
+            try {
+                const controllerModule = await importModule(cdnProvider.browserViewUrl(packageVersion, variantController), doc);
+                controller = controllerModule?.default ?? controllerModule;
+                if (controller)
+                    return controller;
+            }
+            catch (err) {
+                reportEditorRuntimeFallback(packageVersion, servedVariant.declaration, servedVariant.runtime, `its editor-runtime controller failed to load: ${errorMessage(err)}`);
+            }
+        }
+        const controllerSpecifier = resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnProvider);
+        try {
+            const controllerModule = await importModule(controllerSpecifier, doc);
+            return controllerModule?.default ?? controllerModule;
+        }
+        catch {
+            return controller;
+        }
+    }
     /**
      * Imports through the browser, or through es-module-shims once the document
      * has rejected an import map, after every map a backend added has settled.
@@ -547,7 +560,8 @@ export function mapEsmViewElements(elements, view = "delivery", viewConfig) {
     ]));
 }
 function defaultImporter(specifier) {
-    // @vite-ignore — dynamic import resolved at runtime.
+    // Host bundlers must leave this import alone: the specifier is a CDN URL or
+    // import-map specifier known only at runtime.
     return import(/* webpackIgnore: true */ /* @vite-ignore */ specifier);
 }
 /**
@@ -872,9 +886,6 @@ const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
 /** Slash-separated segments, none starting with a dot. */
 const BROWSER_VIEW_PATH = /^[A-Za-z0-9_-][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$/;
 const BARE_SPECIFIER = /^(?:@[A-Za-z0-9_-][A-Za-z0-9._-]*\/)?[A-Za-z0-9_-][A-Za-z0-9._-]*(?:\/[A-Za-z0-9_-][A-Za-z0-9._-]*)*$/;
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 /**
  * A package's `pie.browserEditorRuntime`: `undefined` when it declares none,
  * `null` when the declaration is malformed.
@@ -883,7 +894,7 @@ function readEditorRuntimeDeclaration(metadata) {
     const declared = metadata?.pie?.browserEditorRuntime;
     if (declared === undefined)
         return undefined;
-    if (!isRecord(declared) || !isRecord(declared.views))
+    if (!isPlainRecord(declared) || !isPlainRecord(declared.views))
         return null;
     const { name, version } = declared;
     if (typeof name !== "string" || !PACKAGE_NAME.test(name))
@@ -907,7 +918,7 @@ function readEditorRuntimeDeclaration(metadata) {
  */
 function readBrowserModules(metadata) {
     const declared = metadata.pie?.browserModules;
-    if (!isRecord(declared))
+    if (!isPlainRecord(declared))
         return null;
     const modules = Object.entries(declared);
     const valid = modules.length > 0 &&

package/dist/loaders/iife-adapter.d.ts

@@ -1,7 +1,7 @@
 /**
  * IIFE backend adapter for the ElementLoader primitive.
  *
- * Loads PIE elements from IIFE bundles served by the PIE build service,
+ * Loads PIE elements from IIFE bundles served by the bundle host,
  * 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
@@ -38,7 +38,7 @@ export type IifeBundleRetryStatus = {
 };
 export type IifeBackendConfig = {
     kind: "iife";
-    /** Base URL for the PIE bundle service. */
+    /** Base URL of the bundle host. */
     bundleHost: string;
     /** Bundle variant to request (player / client-player / editor). */
     bundleType?: BundleType;
@@ -54,7 +54,7 @@ export type IifeBackendConfig = {
     /**
      * Retry policy for transient bundle load failures.
      *
-     * When the bundle service is building a bundle on demand, the first
+     * When the bundle host is building a bundle on demand, the first
      * few `<script src>` requests can fail. This policy polls until the
      * bundle is available or `timeoutMs` elapses. Default matches
      * `DEFAULT_IIFE_BUNDLE_RETRY_CONFIG`.

package/dist/loaders/iife-adapter.js

@@ -1,7 +1,7 @@
 /**
  * IIFE backend adapter for the ElementLoader primitive.
  *
- * Loads PIE elements from IIFE bundles served by the PIE build service,
+ * Loads PIE elements from IIFE bundles served by the bundle host,
  * 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
@@ -76,7 +76,7 @@ export function createIifeBackend(config) {
     /**
      * Wrap the single-shot script loader with poll-until-ready retry.
      *
-     * The PIE bundle service may return a transient failure while it
+     * The bundle host 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
@@ -111,7 +111,7 @@ export function createIifeBackend(config) {
             catch (error) {
                 const elapsedMs = Date.now() - startedAt;
                 const remainingMs = timeoutMs - elapsedMs;
-                const reason = error instanceof Error ? error.message : String(error);
+                const reason = errorMessage(error);
                 if (remainingMs <= 0) {
                     const timeoutError = new Error(`IIFE bundle load timed out after ${timeoutMs}ms: ${url}`);
                     config.onBundleRetryStatus?.({
@@ -201,45 +201,33 @@ export function createIifeBackend(config) {
             return;
         const conflict = findIifeElementMapConflict(elements);
         if (conflict) {
-            const reasons = new Map();
-            for (const tag of Object.keys(elements)) {
-                reasons.set(tag, {
-                    kind: "backend-rejected",
-                    tag,
-                    cause: conflict,
-                });
-            }
-            throw new AdapterFailure(reasons);
+            throw failureForEveryTag(elements, (tag) => ({
+                kind: "backend-rejected",
+                tag,
+                cause: conflict,
+            }));
         }
         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 cause = errorMessage(err);
+            throw failureForEveryTag(elements, (tag) => ({
+                kind: "bundle-load-failed",
+                tag,
+                url: bundleUrl,
+                cause,
+            }));
         }
         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);
+            throw failureForEveryTag(elements, (tag) => ({
+                kind: "bundle-load-failed",
+                tag,
+                url: bundleUrl,
+                cause: "window.pie.default missing after bundle load",
+            }));
         }
         const reasons = new Map();
         const isEditorBundle = bundleType === BundleType.editor;
@@ -282,11 +270,13 @@ export function createIifeBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 continue;
             }
             try {
+                // `customElements` rejects a constructor already defined under
+                // another tag, so each versioned tag gets its own subclass.
                 defineCustomElementSafely(actualTag, class extends ElementClass {
                 }, `element tag for ${packageName}`);
             }
@@ -294,7 +284,7 @@ export function createIifeBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 continue;
             }
@@ -320,6 +310,17 @@ export function createIifeBackend(config) {
     };
 }
 // ─── Helpers ─────────────────────────────────────────────────────────────────
+/** A failure of the whole request, reported once per tag. */
+function failureForEveryTag(elements, reasonFor) {
+    const reasons = new Map();
+    for (const tag of Object.keys(elements)) {
+        reasons.set(tag, reasonFor(tag));
+    }
+    return new AdapterFailure(reasons);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 function defaultLoadBundleScript(url, doc) {
     return new Promise((resolve, reject) => {
         const script = doc.createElement("script");