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

package/dist/loaders/element-loader.js

@@ -0,0 +1,391 @@
+/**
+ * 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 { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG } from "../loader-config.js";
+import { AdapterFailure, } from "./element-loader-types.js";
+import { createEsmBackend, } from "./esm-adapter.js";
+import { createIifeBackend, } from "./iife-adapter.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.
+ */
+export class ElementLoaderError extends Error {
+    name = "ElementLoaderError";
+    unregisteredTags;
+    reasons;
+    constructor(message, unregisteredTags, reasons) {
+        super(message);
+        this.unregisteredTags = unregisteredTags;
+        this.reasons = reasons;
+    }
+}
+/**
+ * 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 class ElementAssertionError extends Error {
+    name = "ElementAssertionError";
+    expectedTags;
+    missingTags;
+    currentlyRegisteredTags;
+    constructor(expected, missing, currentlyRegistered) {
+        super(buildAssertionMessage(expected, missing, currentlyRegistered));
+        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}].`);
+}
+const DEFAULT_WHEN_DEFINED_TIMEOUT_MS = 5000;
+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();
+/**
+ * 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 async function ensureRegistered(elements, options) {
+    if (!elements || Object.keys(elements).length === 0)
+        return;
+    const tags = Object.keys(elements);
+    const timeoutMs = options.whenDefinedTimeoutMs ?? DEFAULT_WHEN_DEFINED_TIMEOUT_MS;
+    const loadTimeoutMs = options.loadTimeoutMs ?? DEFAULT_LOAD_TIMEOUT_MS;
+    // Fast path: everything already registered. Skip backend and dedup
+    // bookkeeping entirely.
+    if (allAlreadyRegistered(tags))
+        return;
+    const dedupKey = buildDedupKey(options.backend, elements);
+    const existing = inFlightRequests.get(dedupKey);
+    if (existing)
+        return existing;
+    const backend = resolveBackend(options.backend);
+    const doc = resolveDoc(options.doc);
+    const promise = runEnsureRegistered(elements, tags, backend, { doc, whenDefinedTimeoutMs: timeoutMs }, timeoutMs, loadTimeoutMs);
+    inFlightRequests.set(dedupKey, promise);
+    try {
+        await promise;
+    }
+    finally {
+        if (inFlightRequests.get(dedupKey) === promise) {
+            inFlightRequests.delete(dedupKey);
+        }
+    }
+}
+async function runEnsureRegistered(elements, tags, backend, context, timeoutMs, loadTimeoutMs) {
+    let adapterError;
+    try {
+        await raceWithLoadTimeout(backend.load(elements, context), tags, loadTimeoutMs);
+    }
+    catch (err) {
+        adapterError = err instanceof Error ? err : new Error(String(err));
+    }
+    const verification = await Promise.all(tags.map(async (tag) => {
+        if (isRegistered(tag))
+            return { tag, ok: true };
+        try {
+            await whenDefinedWithTimeout(tag, timeoutMs);
+            return { tag, ok: true };
+        }
+        catch {
+            return { tag, ok: false };
+        }
+    }));
+    const unregistered = new Set();
+    const reasons = new Map();
+    for (const v of verification) {
+        if (v.ok)
+            continue;
+        unregistered.add(v.tag);
+        const adapterReason = extractAdapterReason(adapterError, v.tag);
+        reasons.set(v.tag, adapterReason ?? { kind: "timeout", tag: v.tag, timeoutMs });
+    }
+    if (unregistered.size > 0) {
+        throw new ElementLoaderError(`Element registration failed; missing tags: ${[...unregistered].join(", ")}`, unregistered, reasons);
+    }
+}
+/**
+ * Race the backend's `load()` against a cumulative deadline.
+ *
+ * On timeout, synthesize an `AdapterFailure` whose `reasons` map carries
+ * a `kind: "timeout"` entry per requested tag. The verification pass in
+ * `runEnsureRegistered` will then produce a normal `ElementLoaderError`
+ * with structured per-tag reasons — same surface shape as any other
+ * adapter rejection.
+ */
+async function raceWithLoadTimeout(loadPromise, tags, loadTimeoutMs) {
+    let timer;
+    try {
+        await Promise.race([
+            loadPromise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    const reasons = new Map();
+                    for (const tag of tags) {
+                        reasons.set(tag, {
+                            kind: "timeout",
+                            tag,
+                            timeoutMs: loadTimeoutMs,
+                        });
+                    }
+                    reject(new AdapterFailure(reasons));
+                }, loadTimeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * 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 function assertRegistered(tags) {
+    if (!tags || tags.length === 0)
+        return;
+    const missing = tags.filter((tag) => !isRegistered(tag));
+    if (missing.length === 0)
+        return;
+    throw new ElementAssertionError(tags, missing, snapshotRegisteredTags());
+}
+// ─── Internals ───────────────────────────────────────────────────────────────
+function resolveBackend(backend) {
+    if (isDirectBackend(backend))
+        return backend;
+    if ("kind" in backend) {
+        if (backend.kind === "iife")
+            return createIifeBackend(backend);
+        if (backend.kind === "esm")
+            return createEsmBackend(backend);
+    }
+    throw new Error("ElementLoader: invalid backend option");
+}
+function isDirectBackend(backend) {
+    return (typeof backend.load === "function" &&
+        !("kind" in backend));
+}
+function resolveDoc(doc) {
+    if (doc)
+        return doc;
+    if (typeof document !== "undefined")
+        return document;
+    throw new Error("ElementLoader: no Document available; pass options.doc explicitly");
+}
+function buildDedupKey(backend, elements) {
+    const backendKey = backendKeyOf(backend);
+    const entries = Object.entries(elements).sort(([a], [b]) => a.localeCompare(b));
+    return `${backendKey}|${JSON.stringify(entries)}`;
+}
+const backendIds = new WeakMap();
+let nextBackendId = 0;
+const functionIds = new WeakMap();
+let nextFunctionId = 0;
+const opaqueObjectIds = new WeakMap();
+let nextOpaqueObjectId = 0;
+function backendKeyOf(backend) {
+    if (isDirectBackend(backend)) {
+        let id = backendIds.get(backend);
+        if (!id) {
+            id = `b${++nextBackendId}`;
+            backendIds.set(backend, id);
+        }
+        return `backend#${id}`;
+    }
+    if ("kind" in backend) {
+        if (backend.kind === "iife") {
+            return `iife#${fingerprintValue({
+                kind: "iife",
+                bundleHost: backend.bundleHost,
+                bundleType: backend.bundleType ?? "",
+                needsControllers: backend.needsControllers ?? true,
+                bundleInfo: backend.bundleInfo ?? null,
+                debugEnabled: backend.debugEnabled ?? null,
+                bundleRetry: backend.bundleRetry ?? null,
+                onBundleRetryStatus: backend.onBundleRetryStatus ?? null,
+                trackPageActions: backend.trackPageActions ?? false,
+                instrumentationProvider: backend.instrumentationProvider ?? null,
+            })}`;
+        }
+        if (backend.kind === "esm") {
+            return `esm#${fingerprintValue({
+                kind: "esm",
+                cdnBaseUrl: backend.cdnBaseUrl,
+                moduleResolution: backend.moduleResolution ?? "url",
+                view: backend.view ?? "delivery",
+                viewConfig: backend.viewConfig ?? null,
+                loadControllers: backend.loadControllers ?? true,
+                debugEnabled: backend.debugEnabled ?? null,
+            })}`;
+        }
+    }
+    return "unknown";
+}
+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") {
+        return value;
+    }
+    if (primitiveType === "function") {
+        return { __functionRef: getFunctionRefId(value) };
+    }
+    if (primitiveType !== "object") {
+        return String(value);
+    }
+    const objectValue = value;
+    const existing = seen.get(objectValue);
+    if (existing)
+        return { __cycleRef: existing };
+    const cycleRefId = `cycle#${seen.size + 1}`;
+    seen.set(objectValue, cycleRefId);
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeForFingerprint(entry, seen));
+    }
+    if (!isPlainObject(value)) {
+        return { __objectRef: getOpaqueObjectRefId(objectValue) };
+    }
+    const normalized = {};
+    for (const key of Object.keys(value).sort()) {
+        normalized[key] = normalizeForFingerprint(value[key], seen);
+    }
+    return normalized;
+}
+function isPlainObject(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function getFunctionRefId(fn) {
+    let id = functionIds.get(fn);
+    if (!id) {
+        id = `fn#${++nextFunctionId}`;
+        functionIds.set(fn, id);
+    }
+    return id;
+}
+function getOpaqueObjectRefId(value) {
+    let id = opaqueObjectIds.get(value);
+    if (!id) {
+        id = `obj#${++nextOpaqueObjectId}`;
+        opaqueObjectIds.set(value, id);
+    }
+    return id;
+}
+function allAlreadyRegistered(tags) {
+    return tags.every((tag) => isRegistered(tag));
+}
+function isRegistered(tag) {
+    if (typeof customElements === "undefined")
+        return false;
+    return customElements.get(tag) !== undefined;
+}
+async function whenDefinedWithTimeout(tag, timeoutMs) {
+    if (typeof customElements === "undefined") {
+        throw new Error(`no customElements to await ${tag}`);
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            customElements.whenDefined(tag).then(() => undefined),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Timeout waiting for ${tag}`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function snapshotRegisteredTags() {
+    if (typeof customElements === "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 [];
+}
+function extractAdapterReason(err, tag) {
+    if (!err)
+        return undefined;
+    if (err instanceof AdapterFailure)
+        return err.reasons.get(tag);
+    return { kind: "backend-rejected", tag, cause: err.message };
+}
+// ─── Test-only helpers ───────────────────────────────────────────────────────
+/**
+ * Internal helpers for test harnesses. Not part of the public runtime API;
+ * production code should never reach for these.
+ *
+ * @internal
+ */
+export const __testing = {
+    resetDedupState() {
+        inFlightRequests.clear();
+    },
+    inFlightCount() {
+        return inFlightRequests.size;
+    },
+    dedupKeyFor(elements, backend) {
+        return buildDedupKey(backend, elements);
+    },
+};
+//# sourceMappingURL=element-loader.js.map

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

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

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

@@ -0,0 +1,40 @@
+/**
+ * ESM backend adapter for the ElementLoader primitive.
+ *
+ * Loads PIE elements via dynamic `import()` from an ESM CDN (esm.sh,
+ * jsDelivr, etc.), optionally resolving bare specifiers through an
+ * `<script type="importmap">` injected into the host document. On any
+ * per-tag failure (module load, non-constructor element class, define
+ * failure), throws `AdapterFailure` with a structured `reasons` map.
+ *
+ * Like the IIFE adapter, this module does not gate its own promise on
+ * `customElements.whenDefined`; the primitive performs that verification
+ * uniformly. Here the adapter's job is narrowly to fetch, extract, and
+ * call `customElements.define`.
+ */
+import { type ElementLoaderBackend } from "./element-loader-types.js";
+/** View configuration: how a PIE package's subpath maps to a tag suffix. */
+export type ViewConfig = {
+    subpath: string;
+    tagSuffix: string;
+    fallback?: string;
+};
+export declare const BUILT_IN_VIEWS: Record<string, ViewConfig>;
+export type EsmBackendConfig = {
+    kind: "esm";
+    /** Base URL for the ESM CDN (e.g., "https://esm.sh"). */
+    cdnBaseUrl: string;
+    /** `"url"` loads via fully-qualified URLs; `"import-map"` uses bare specifiers. */
+    moduleResolution?: "url" | "import-map";
+    /** View to load (`delivery`, `author`, `print`, or a custom name). */
+    view?: string;
+    /** Custom view configuration (overrides built-ins). */
+    viewConfig?: ViewConfig;
+    /** Whether to also load controller modules. */
+    loadControllers?: boolean;
+    /** Debug flag hook. */
+    debugEnabled?: () => boolean;
+};
+export type EsmBackend = ElementLoaderBackend & {};
+export declare function createEsmBackend(config: EsmBackendConfig): EsmBackend;
+//# sourceMappingURL=esm-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"esm-adapter.d.ts","sourceRoot":"","sources":["../../src/loaders/esm-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,OAAO,EAGN,KAAK,oBAAoB,EAGzB,MAAM,2BAA2B,CAAC;AAEnC,4EAA4E;AAC5E,MAAM,MAAM,UAAU,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAIrD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B,IAAI,EAAE,KAAK,CAAC;IACZ,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,KAAK,GAAG,YAAY,CAAC;IACxC,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,+CAA+C;IAC/C,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uBAAuB;IACvB,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC;CAC7B,CAAC;AAqBF,MAAM,MAAM,UAAU,GAAG,oBAAoB,GAAG,EAG/C,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAsMrE"}