@pie-players/pie-players-shared 0.3.73 → 0.3.74

package/dist/loader-config.d.ts

@@ -24,13 +24,16 @@ export type LoaderConfig = {
     /**
      * Instrumentation provider for tracking events and errors.
      *
-     * Optional. If not provided, defaults to NewRelicInstrumentationProvider.
-     * The provider handles instrumentation gracefully - if New Relic (or the configured
-     * backend) is not available, it will simply not track events (no errors thrown).
+     * - Unset or `undefined`: nothing is reported unless `trackPageActions` is
+     *   `true`, in which case players fall back to a
+     *   `NewRelicInstrumentationProvider`, which reports while the New Relic
+     *   browser agent is on the page.
+     * - A provider: players report to it. A value that fails the
+     *   `InstrumentationProvider` contract is treated as `null`.
+     * - `null`: disables instrumentation, whatever `trackPageActions` says.
      *
-     * @example Using New Relic (default - no configuration needed)
+     * @example Using New Relic (the fallback, no provider needed)
      * ```typescript
-     * // Just enable tracking - will use New Relic if window.newrelic is available
      * const loaderConfig = {
      *   trackPageActions: true
      * };
@@ -47,8 +50,15 @@ export type LoaderConfig = {
      *   instrumentationProvider: provider
      * };
      * ```
+     * @example Disabling instrumentation
+     * ```typescript
+     * const loaderConfig = {
+     *   trackPageActions: true,
+     *   instrumentationProvider: null
+     * };
+     * ```
      */
-    instrumentationProvider?: InstrumentationProvider;
+    instrumentationProvider?: InstrumentationProvider | null;
     /**
      * Maximum number of retry attempts for failed resources (images/audio/video).
      */

package/dist/loaders/controller-loading.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Whether a player's ESM backend fetches controller modules
+ * (`EsmBackendConfig.loadControllers`).
+ *
+ * The host's `loaderOptions.loadControllers` decides when set. Otherwise an
+ * author view loads them, and a delivery loads them unless it is hosted: a
+ * hosted player takes models and scores from the server and resolves no
+ * controller (`findPieController`), so fetching one is wasted.
+ */
+export declare function resolveLoadControllers(args: {
+    loadControllers?: boolean;
+    author: boolean;
+    hosted: boolean;
+}): boolean;

package/dist/loaders/controller-loading.js

@@ -0,0 +1,12 @@
+/**
+ * Whether a player's ESM backend fetches controller modules
+ * (`EsmBackendConfig.loadControllers`).
+ *
+ * The host's `loaderOptions.loadControllers` decides when set. Otherwise an
+ * author view loads them, and a delivery loads them unless it is hosted: a
+ * hosted player takes models and scores from the server and resolves no
+ * controller (`findPieController`), so fetching one is wasted.
+ */
+export function resolveLoadControllers(args) {
+    return args.loadControllers ?? (args.author || !args.hosted);
+}

package/dist/loaders/defaults.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Default PIE bundle service base URL. Exported so widgets can use it as
+ * the fallback when the host does not supply `loaderOptions.bundleHost`.
+ */
+export declare const DEFAULT_BUNDLE_HOST = "https://proxy.pie-api.com/bundles/";
+/**
+ * Default ESM CDN base URL, the fallback when the host does not supply
+ * `loaderOptions.esmCdnUrl`.
+ */
+export declare const DEFAULT_ESM_CDN_URL = "https://cdn.jsdelivr.net/npm";

package/dist/loaders/defaults.js

@@ -0,0 +1,10 @@
+/**
+ * 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/";
+/**
+ * Default ESM CDN base URL, the fallback when the host does not supply
+ * `loaderOptions.esmCdnUrl`.
+ */
+export const DEFAULT_ESM_CDN_URL = "https://cdn.jsdelivr.net/npm";

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

@@ -10,9 +10,10 @@
  *     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
+ * adapter (IIFE or ESM) and verifies the outcome via
  * `customElements.whenDefined`. An adapter cannot silently under-register
- * — the primitive will catch it and surface a timeout reason.
+ * — the primitive will catch it and surface a timeout reason. A tag the
+ * adapter reports a failed load for is not waited on.
  *
  * See packages/players-shared/tests/element-loader-contract.test.ts for
  * the executable specification of every failure mode this primitive is
@@ -29,7 +30,7 @@ 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.
+ * tags were not registered: their loads failed, or verification timed out.
  */
 export declare class ElementLoaderError extends Error {
     readonly name = "ElementLoaderError";
@@ -37,17 +38,24 @@ export declare class ElementLoaderError extends Error {
     readonly reasons: Map<ElementTag, RegistrationFailureReason>;
     constructor(message: string, unregisteredTags: Set<ElementTag>, reasons: Map<ElementTag, RegistrationFailureReason>);
 }
+/**
+ * Why each tag of an `ElementLoaderError` failed to register, one clause per
+ * tag; `undefined` for any other error. Players report it as the `cause` of a
+ * load error.
+ */
+export declare function describeRegistrationFailures(error: unknown): string | undefined;
 /**
  * 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.
+ * `customElements`. The message names, for each missing tag, the tags its
+ * package (or, without one, its base tag) is registered under.
  */
 export declare class ElementAssertionError extends Error {
     readonly name = "ElementAssertionError";
     readonly expectedTags: readonly ElementTag[];
     readonly missingTags: readonly ElementTag[];
+    /** The `window.PIE_REGISTRY` tags `customElements` holds. */
     readonly currentlyRegisteredTags: readonly ElementTag[];
-    constructor(expected: ElementTag[], missing: ElementTag[], currentlyRegistered: ElementTag[]);
+    constructor(expected: ElementTag[], missing: ElementTag[], currentlyRegistered: ElementTag[], packages?: ElementMap);
 }
 export type BackendOption = IifeBackendConfig | EsmBackendConfig | ElementLoaderBackend;
 export type EnsureRegisteredOptions = {
@@ -85,6 +93,8 @@ export type EnsureRegisteredOptions = {
  * - After the adapter's `load` settles, a post-load verification pass
  *   (bounded `customElements.whenDefined`) checks every tag. Any missing
  *   tag becomes a rejection.
+ * - Verification does not wait on a tag the adapter reports a failed load
+ *   for, so when that covers every missing tag the rejection is immediate.
  */
 export declare function ensureRegistered(elements: ElementMap, options: EnsureRegisteredOptions): Promise<void>;
 /**
@@ -92,6 +102,8 @@ export declare function ensureRegistered(elements: ElementMap, options: EnsureRe
  * 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.
+ * elements out-of-band and want a loud failure if anything is missing. An
+ * element map, tag to package spec, lets the error name what each missing
+ * tag's package is registered as.
  */
-export declare function assertRegistered(tags: ElementTag[]): void;
+export declare function assertRegistered(tags: ElementTag[] | ElementMap): void;

package/dist/loaders/element-loader.js

@@ -10,23 +10,28 @@
  *     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
+ * adapter (IIFE or ESM) and verifies the outcome via
  * `customElements.whenDefined`. An adapter cannot silently under-register
- * — the primitive will catch it and surface a timeout reason.
+ * — the primitive will catch it and surface a timeout reason. A tag the
+ * adapter reports a failed load for is not waited on.
  *
  * 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 { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG } from "../loader-config.js";
+import { pieRegistry } from "../pie/registry.js";
+import { Status } from "../pie/types.js";
+import { parsePackageName } from "../pie/utils.js";
+import { parseVersionedTagName } from "../pie/versioned-tag.js";
 import { AdapterFailure, } from "./element-loader-types.js";
-import { createEsmBackend } from "./esm-adapter.js";
+import { clearPackageMetadataRequests, createEsmBackend, } from "./esm-adapter.js";
 import { createIifeBackend } from "./iife-adapter.js";
 import { assertElementPackagesAllowed, } from "./element-package-policy.js";
 export { AdapterFailure } from "./element-loader-types.js";
 /**
  * Aggregate error thrown by `ensureRegistered` when one or more requested
- * tags were not registered by the time verification timed out.
+ * tags were not registered: their loads failed, or verification timed out.
  */
 export class ElementLoaderError extends Error {
     name = "ElementLoaderError";
@@ -38,31 +43,85 @@ export class ElementLoaderError extends Error {
         this.reasons = reasons;
     }
 }
+const describeRegistrationFailure = (reason) => {
+    switch (reason.kind) {
+        case "timeout":
+            return `not defined within ${reason.timeoutMs} ms`;
+        case "module-load-failed":
+            return `${reason.specifier} failed to load: ${reason.cause}`;
+        case "bundle-load-failed":
+            return `${reason.url} failed to load: ${reason.cause}`;
+        case "define-failed":
+        case "backend-rejected":
+            return reason.cause;
+        case "not-a-constructor":
+            return `${reason.packageName ?? "its package"} exports no element constructor`;
+        case "no-element-class":
+            return `${reason.packageName} exports no element class`;
+        case "package-not-in-bundle":
+            return `${reason.packageName} is not in the bundle, which holds ${reason.availablePackages.join(", ") || "no packages"}`;
+    }
+};
+/**
+ * Why each tag of an `ElementLoaderError` failed to register, one clause per
+ * tag; `undefined` for any other error. Players report it as the `cause` of a
+ * load error.
+ */
+export function describeRegistrationFailures(error) {
+    if (!(error instanceof ElementLoaderError))
+        return undefined;
+    return [...error.reasons]
+        .map(([tag, reason]) => `${tag} (${reason.kind}): ${describeRegistrationFailure(reason)}`)
+        .join("; ");
+}
 /**
  * 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.
+ * `customElements`. The message names, for each missing tag, the tags its
+ * package (or, without one, its base tag) is registered under.
  */
 export class ElementAssertionError extends Error {
     name = "ElementAssertionError";
     expectedTags;
     missingTags;
+    /** The `window.PIE_REGISTRY` tags `customElements` holds. */
     currentlyRegisteredTags;
-    constructor(expected, missing, currentlyRegistered) {
-        super(buildAssertionMessage(expected, missing, currentlyRegistered));
+    constructor(expected, missing, currentlyRegistered, packages = {}) {
+        super(buildAssertionMessage(expected, missing, currentlyRegistered, packages));
         this.expectedTags = expected;
         this.missingTags = missing;
         this.currentlyRegisteredTags = currentlyRegistered;
     }
 }
-function buildAssertionMessage(expected, missing, registered) {
-    const expectedStr = expected.join(", ");
-    const missingStr = missing.join(", ");
-    const registeredStr = registered.length
-        ? registered.join(", ")
-        : "(none enumerable)";
-    return (`ElementLoader.assertRegistered: expected [${expectedStr}], ` +
-        `missing [${missingStr}]. customElements contains: [${registeredStr}].`);
+function buildAssertionMessage(expected, missing, registered, packages) {
+    const details = missing.map((tag) => {
+        const packageName = packageNameOf(packages[tag]);
+        const baseName = parseVersionedTagName(tag).baseName;
+        const related = packageName
+            ? registered.filter((other) => registeredPackageName(other) === packageName)
+            : registered.filter((other) => parseVersionedTagName(other).baseName === baseName);
+        if (!related.includes(baseName) && isRegistered(baseName)) {
+            related.push(baseName);
+        }
+        const subject = packageName ?? baseName;
+        return related.length > 0
+            ? `${subject} is registered as [${related.join(", ")}]`
+            : `nothing is registered for ${subject}`;
+    });
+    return (`ElementLoader.assertRegistered: missing [${missing.join(", ")}] ` +
+        `of [${expected.join(", ")}]; ${details.join("; ")}.`);
+}
+function packageNameOf(spec) {
+    if (!spec)
+        return undefined;
+    try {
+        return parsePackageName(spec).name || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function registeredPackageName(tag) {
+    return packageNameOf(pieRegistry()[tag]?.package);
 }
 const DEFAULT_WHEN_DEFINED_TIMEOUT_MS = 5000;
 const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
@@ -82,6 +141,8 @@ const resolvedBackendOverrides = new Map();
  * - After the adapter's `load` settles, a post-load verification pass
  *   (bounded `customElements.whenDefined`) checks every tag. Any missing
  *   tag becomes a rejection.
+ * - Verification does not wait on a tag the adapter reports a failed load
+ *   for, so when that covers every missing tag the rejection is immediate.
  */
 export async function ensureRegistered(elements, options) {
     if (!elements || Object.keys(elements).length === 0)
@@ -121,9 +182,15 @@ async function runEnsureRegistered(elements, tags, backend, context, timeoutMs,
     catch (err) {
         adapterError = err instanceof Error ? err : new Error(String(err));
     }
+    // A tag whose load failed cannot register any more, so verification waits
+    // only on the others. A timed-out load can still register, so its tag waits.
     const verification = await Promise.all(tags.map(async (tag) => {
         if (isRegistered(tag))
             return { tag, ok: true };
+        const adapterReason = extractAdapterReason(adapterError, tag);
+        if (adapterReason && adapterReason.kind !== "timeout") {
+            return { tag, ok: false };
+        }
         try {
             await whenDefinedWithTimeout(tag, timeoutMs);
             return { tag, ok: true };
@@ -184,15 +251,19 @@ async function raceWithLoadTimeout(loadPromise, tags, loadTimeoutMs) {
  * 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.
+ * elements out-of-band and want a loud failure if anything is missing. An
+ * element map, tag to package spec, lets the error name what each missing
+ * tag's package is registered as.
  */
 export function assertRegistered(tags) {
-    if (!tags || tags.length === 0)
+    const packages = Array.isArray(tags) ? {} : (tags ?? {});
+    const expected = Array.isArray(tags) ? tags : Object.keys(packages);
+    if (expected.length === 0)
         return;
-    const missing = tags.filter((tag) => !isRegistered(tag));
+    const missing = expected.filter((tag) => !isRegistered(tag));
     if (missing.length === 0)
         return;
-    throw new ElementAssertionError(tags, missing, snapshotRegisteredTags());
+    throw new ElementAssertionError(expected, missing, snapshotRegisteredTags(), packages);
 }
 // ─── Internals ───────────────────────────────────────────────────────────────
 function resolveBackend(backend) {
@@ -363,24 +434,18 @@ async function whenDefinedWithTimeout(tag, timeoutMs) {
             clearTimeout(timer);
     }
 }
+/**
+ * `customElements` cannot be enumerated, so the registered tags are the
+ * `window.PIE_REGISTRY` entries it holds.
+ */
 function snapshotRegisteredTags() {
-    if (typeof customElements === "undefined")
+    if (typeof window === "undefined")
         return [];
-    // Standard `CustomElementRegistry` does not expose iteration. Tests install
-    // a scripted registry with a `__pieSnapshot` extension to make diagnostic
-    // messages assertable. Production falls through to an empty list —
-    // still strictly better than today's "missing tags: X" error which leaks
-    // no registry state at all.
-    const reg = customElements;
-    if (typeof reg.__pieSnapshot === "function") {
-        try {
-            return reg.__pieSnapshot();
-        }
-        catch {
-            return [];
-        }
-    }
-    return [];
+    return Object.values(pieRegistry())
+        .filter((entry) => entry?.status === Status.loaded)
+        .map((entry) => entry.tagName)
+        .filter((tag) => typeof tag === "string" && isRegistered(tag))
+        .sort();
 }
 function extractAdapterReason(err, tag) {
     if (!err)
@@ -401,6 +466,7 @@ export const __testing = {
         inFlightRequests.clear();
         resolvedEsmBackends.clear();
         resolvedBackendOverrides.clear();
+        clearPackageMetadataRequests();
     },
     inFlightCount() {
         return inFlightRequests.size;

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

@@ -12,6 +12,8 @@ export declare class ElementPackagePolicyError extends Error {
     readonly name = "ElementPackagePolicyError";
     constructor(tagName: string, packageSpec: string, message: string);
 }
+/** Exact semver: no range, tag, `v` prefix or build metadata. */
+export declare function isExactSemver(version: string): boolean;
 /**
  * Validate an element map only when a host explicitly supplies a policy.
  * Omitting the policy preserves the existing trusted-application behavior.

package/dist/loaders/element-package-policy.js

@@ -10,7 +10,8 @@ export class ElementPackagePolicyError extends Error {
         this.packageSpec = packageSpec;
     }
 }
-function isExactSemver(version) {
+/** Exact semver: no range, tag, `v` prefix or build metadata. */
+export function isExactSemver(version) {
     return validSemver(version) === version;
 }
 function parsePolicyPackageSpec(spec) {

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

@@ -27,9 +27,18 @@ export type EsmCdnProviderName = BuiltInEsmCdnProviderName | (string & {});
 export type EsmCdnProvider = {
     name: EsmCdnProviderName;
     packageJsonUrl(packageVersion: string): string;
+    /**
+     * URL of `dist/browser/<view>/index.js`. `view` can be a nested path: an
+     * element's editor-runtime variant is `editor-runtime/<view>`.
+     */
     browserViewUrl(packageVersion: string, view: string): string;
     browserControllerUrl(packageVersion: string): string;
     sharedDependencyUrl(dependencyName: string, version: string, subpath?: string): string;
+    /**
+     * URL of the package's `./runtime-support` module. Without it, the file
+     * `dist/runtime-support.js` beside `packageJsonUrl`.
+     */
+    runtimeSupportUrl?(packageVersion: string): string;
 };
 export type EsmCdnProviderOption = EsmCdnProviderName | EsmCdnProvider;
 export type EsmBackendConfig = {
@@ -56,3 +65,12 @@ export type EsmBackendConfig = {
 export type EsmBackend = ElementLoaderBackend & {};
 export declare function createEsmBackend(config: EsmBackendConfig): EsmBackend;
 export declare function mapEsmViewElements(elements: ElementMap, view?: string, viewConfig?: ViewConfig): ElementMap;
+/**
+ * URL of a package's `./runtime-support` module on the ESM CDN the players load
+ * elements from, or `undefined` when a custom provider names no package root.
+ */
+export declare function resolveEsmRuntimeSupportUrl(packageVersion: string, options: {
+    cdnBaseUrl: string;
+    cdnProvider?: EsmCdnProviderOption;
+}): string | undefined;
+export declare function pickElementClass(module: any, view: string): unknown;