@pie-players/pie-players-shared 0.3.47 → 0.3.49

package/dist/loaders/esm-adapter.js

@@ -1,11 +1,11 @@
 /**
  * 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.
+ * Loads PIE elements via dynamic `import()` from static browser ESM files on a
+ * CDN, optionally resolving bare specifiers through an import map 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
@@ -13,6 +13,7 @@
  * call `customElements.define`.
  */
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
+import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
 import { pieRegistry } from "../pie/registry.js";
 import { validateCustomElementTag } from "../pie/tag-names.js";
 import { isCustomElementConstructor, Status } from "../pie/types.js";
@@ -24,14 +25,16 @@ export const BUILT_IN_VIEWS = {
 };
 export function createEsmBackend(config) {
     const cdnBaseUrl = config.cdnBaseUrl.replace(/\/+$/, "");
+    const cdnProvider = resolveCdnProvider(config.cdnProvider, cdnBaseUrl);
     const moduleResolution = config.moduleResolution ?? "url";
     const view = config.view ?? "delivery";
     const loadControllers = config.loadControllers ?? true;
-    const viewConfig = config.viewConfig ??
-        BUILT_IN_VIEWS[view] ??
-        BUILT_IN_VIEWS.delivery;
-    const injectedPackages = new Set();
+    const viewConfig = config.viewConfig ?? BUILT_IN_VIEWS[view] ?? BUILT_IN_VIEWS.delivery;
+    const injectedPackageVersions = new Set();
+    const importMappedPackageVersions = new Map();
+    let sharedDependencyVersions = {};
     let importer = defaultImporter;
+    let packageMetadataLoader = defaultPackageMetadataLoader;
     let importMapObserver;
     const __seams = {
         replaceImporter(fn) {
@@ -40,10 +43,16 @@ export function createEsmBackend(config) {
         observeImportMapInjection(cb) {
             importMapObserver = cb;
         },
+        replacePackageMetadataLoader(fn) {
+            packageMetadataLoader = fn;
+        },
         restore() {
             importer = defaultImporter;
+            packageMetadataLoader = defaultPackageMetadataLoader;
             importMapObserver = undefined;
-            injectedPackages.clear();
+            injectedPackageVersions.clear();
+            importMappedPackageVersions.clear();
+            sharedDependencyVersions = {};
         },
     };
     async function load(elements, context) {
@@ -51,19 +60,42 @@ export function createEsmBackend(config) {
             return;
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
-            const newEntries = {};
-            for (const [tag, pkg] of Object.entries(elements)) {
-                const packageName = extractPackageName(pkg);
-                if (!injectedPackages.has(packageName)) {
-                    newEntries[tag] = pkg;
-                    injectedPackages.add(packageName);
+        }
+        const newEntries = {};
+        for (const [tag, pkg] of Object.entries(elements)) {
+            const packageName = extractPackageName(pkg);
+            if (moduleResolution === "import-map") {
+                const existingVersion = importMappedPackageVersions.get(packageName);
+                if (existingVersion && existingVersion !== pkg) {
+                    throw new Error(`Conflicting browser ESM package version for ${packageName}: ${existingVersion} is already mapped, but ${pkg} was requested`);
                 }
             }
-            if (Object.keys(newEntries).length > 0) {
-                const json = buildImportMapJson(newEntries, viewConfig, cdnBaseUrl, loadControllers);
+            if (!injectedPackageVersions.has(pkg)) {
+                newEntries[tag] = pkg;
+            }
+        }
+        if (Object.keys(newEntries).length > 0) {
+            let importMapResult;
+            try {
+                importMapResult = await buildImportMapJson(newEntries, viewConfig, cdnProvider, loadControllers, moduleResolution === "import-map", packageMetadataLoader, sharedDependencyVersions, reportSharedDependencyConflict);
+            }
+            catch (err) {
+                reportSharedDependencyError(err);
+                throw err;
+            }
+            const json = importMapResult.json;
+            if (json) {
+                assertImportMapSupported();
                 injectImportMap(json, context.doc);
                 importMapObserver?.(json, context.doc);
             }
+            sharedDependencyVersions = importMapResult.sharedDependencyVersions;
+            for (const pkg of Object.values(newEntries)) {
+                injectedPackageVersions.add(pkg);
+                if (moduleResolution === "import-map") {
+                    importMappedPackageVersions.set(extractPackageName(pkg), pkg);
+                }
+            }
         }
         const reasons = new Map();
         const registry = pieRegistry();
@@ -81,7 +113,7 @@ export function createEsmBackend(config) {
                 });
                 return;
             }
-            const specifier = resolveElementSpecifier(packageName, packageVersion, viewConfig, moduleResolution, cdnBaseUrl);
+            const specifier = resolveElementSpecifier(packageName, packageVersion, viewConfig, moduleResolution, cdnProvider, view);
             let module;
             try {
                 module = await importer(specifier);
@@ -89,7 +121,7 @@ export function createEsmBackend(config) {
             catch (err) {
                 if (viewConfig.fallback) {
                     const fallbackConfig = BUILT_IN_VIEWS[viewConfig.fallback] ?? BUILT_IN_VIEWS.delivery;
-                    const fallbackSpecifier = resolveElementSpecifier(packageName, packageVersion, fallbackConfig, moduleResolution, cdnBaseUrl);
+                    const fallbackSpecifier = resolveElementSpecifier(packageName, packageVersion, fallbackConfig, moduleResolution, cdnProvider, viewConfig.fallback);
                     try {
                         module = await importer(fallbackSpecifier);
                     }
@@ -146,7 +178,7 @@ export function createEsmBackend(config) {
             }
             let controller = null;
             if (loadControllers) {
-                const controllerSpecifier = resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnBaseUrl);
+                const controllerSpecifier = resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnProvider);
                 try {
                     const controllerModule = await importer(controllerSpecifier);
                     controller = controllerModule?.default ?? controllerModule;
@@ -170,6 +202,48 @@ export function createEsmBackend(config) {
             throw new AdapterFailure(reasons);
         }
     }
+    function getInstrumentationProvider() {
+        if (!config.trackPageActions)
+            return undefined;
+        const provider = config.instrumentationProvider;
+        if (!isInstrumentationProvider(provider))
+            return undefined;
+        if (!provider.isReady())
+            return undefined;
+        return provider;
+    }
+    function reportSharedDependencyConflict(attributes) {
+        if (typeof console !== "undefined" && console.warn) {
+            console.warn(`[pie-esm] Shared dependency version conflict resolved for ${String(attributes.dependencyName)}`, attributes);
+        }
+        const provider = getInstrumentationProvider();
+        if (!provider)
+            return;
+        try {
+            provider.trackEvent("pie-esm-shared-dependency-conflict", attributes);
+        }
+        catch {
+            // Swallow: instrumentation must never break loading.
+        }
+    }
+    function reportSharedDependencyError(error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (typeof console !== "undefined" && console.error) {
+            console.error("[pie-esm] Shared dependency resolution failed", err);
+        }
+        const provider = getInstrumentationProvider();
+        if (!provider)
+            return;
+        try {
+            provider.trackError(err, {
+                component: "esm-adapter",
+                errorType: "EsmSharedDependencyError",
+            });
+        }
+        catch {
+            // Swallow: instrumentation must never break loading.
+        }
+    }
     return {
         load,
         get __seams() {
@@ -182,47 +256,133 @@ function defaultImporter(specifier) {
     // @vite-ignore — dynamic import resolved at runtime.
     return import(/* @vite-ignore */ specifier);
 }
+async function defaultPackageMetadataLoader(packageVersion, packageJsonUrl) {
+    const browserFetch = typeof window !== "undefined" &&
+        typeof window.fetch === "function"
+        ? window.fetch.bind(window)
+        : undefined;
+    if (!browserFetch) {
+        return null;
+    }
+    const response = await browserFetch(packageJsonUrl);
+    if (!response.ok) {
+        return null;
+    }
+    return (await response.json());
+}
+function resolveCdnProvider(provider, cdnBaseUrl) {
+    if (isEsmCdnProvider(provider))
+        return provider;
+    const resolvedProviderName = provider ?? (cdnBaseUrl.includes("esm.sh") ? "esm.sh" : "jsdelivr");
+    if (resolvedProviderName === "esm.sh") {
+        return createEsmShProvider(cdnBaseUrl);
+    }
+    return createJsDelivrProvider(cdnBaseUrl, resolvedProviderName);
+}
+function isEsmCdnProvider(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return (typeof candidate.name === "string" &&
+        typeof candidate.packageJsonUrl === "function" &&
+        typeof candidate.browserViewUrl === "function" &&
+        typeof candidate.browserControllerUrl === "function" &&
+        typeof candidate.sharedDependencyUrl === "function");
+}
+function createJsDelivrProvider(cdnBaseUrl, name = "jsdelivr") {
+    return {
+        name,
+        packageJsonUrl: (packageVersion) => `${cdnBaseUrl}/${packageVersion}/package.json`,
+        browserViewUrl: (packageVersion, view) => `${cdnBaseUrl}/${packageVersion}/dist/browser/${view}/index.js`,
+        browserControllerUrl: (packageVersion) => `${cdnBaseUrl}/${packageVersion}/dist/browser/controller/index.js`,
+        sharedDependencyUrl: (dependencyName, version, subpath) => {
+            const suffix = subpath ? `/${subpath}/+esm` : "/+esm";
+            return `${cdnBaseUrl}/${dependencyName}@${version}${suffix}`;
+        },
+    };
+}
+function createEsmShProvider(cdnBaseUrl) {
+    const esmBaseUrl = cdnBaseUrl.replace(/\/+$/, "");
+    const rawBaseUrl = toRawEsmShBaseUrl(esmBaseUrl);
+    return {
+        name: "esm.sh",
+        packageJsonUrl: (packageVersion) => `${rawBaseUrl}/${packageVersion}/package.json`,
+        browserViewUrl: (packageVersion, view) => `${rawBaseUrl}/${packageVersion}/dist/browser/${view}/index.js`,
+        browserControllerUrl: (packageVersion) => `${rawBaseUrl}/${packageVersion}/dist/browser/controller/index.js`,
+        sharedDependencyUrl: (dependencyName, version, subpath) => {
+            const suffix = subpath ? `/${subpath}` : "";
+            return `${esmBaseUrl}/${dependencyName}@${version}${suffix}`;
+        },
+    };
+}
+function toRawEsmShBaseUrl(cdnBaseUrl) {
+    try {
+        const url = new URL(cdnBaseUrl);
+        if (url.hostname === "raw.esm.sh")
+            return url.toString().replace(/\/+$/, "");
+        if (url.hostname === "esm.sh") {
+            url.hostname = "raw.esm.sh";
+            return url.toString().replace(/\/+$/, "");
+        }
+    }
+    catch {
+        // Fall through to the public raw endpoint for non-URL test fixtures.
+    }
+    return "https://raw.esm.sh";
+}
+function assertBrowserEsmExports(metadata, packageVersion, viewConfig, loadControllers, viewName) {
+    if (!metadata?.exports)
+        return;
+    const requiredExports = new Set([
+        `./browser/${browserViewName(viewConfig, viewName)}`,
+    ]);
+    if (viewConfig.fallback) {
+        const fallbackConfig = BUILT_IN_VIEWS[viewConfig.fallback];
+        if (fallbackConfig) {
+            requiredExports.add(`./browser/${browserViewName(fallbackConfig, viewConfig.fallback)}`);
+        }
+    }
+    if (loadControllers) {
+        requiredExports.add("./browser/controller");
+    }
+    for (const exportKey of requiredExports) {
+        if (!(exportKey in metadata.exports)) {
+            throw new Error(`${packageVersion} does not publish browser ESM export ${exportKey}; use IIFE/preloaded mode or publish browser ESM artifacts first`);
+        }
+    }
+}
 function extractPackageName(packageVersion) {
     const parts = packageVersion.split("@");
     return parts.length >= 3 ? `@${parts[1]}` : parts[0];
 }
-function isJsDelivrNpm(cdnBaseUrl) {
-    return cdnBaseUrl.includes("cdn.jsdelivr.net/npm");
+function cleanViewSubpath(subpath) {
+    const cleanSubpath = subpath.replace(/^\/+|\/+$/g, "");
+    return cleanSubpath.length > 0 ? cleanSubpath : null;
 }
-function resolvePackageUrl(packageVersion, cdnBaseUrl) {
-    if (isJsDelivrNpm(cdnBaseUrl)) {
-        return `${cdnBaseUrl}/${packageVersion}/+esm`;
-    }
-    return `${cdnBaseUrl}/${packageVersion}`;
+function browserViewName(viewConfig, viewName = "delivery") {
+    const subpathView = cleanViewSubpath(viewConfig.subpath);
+    return subpathView ?? viewName;
 }
-function resolveSubpathUrl(packageVersion, subpath, cdnBaseUrl) {
-    const cleanSubpath = subpath.startsWith("/") ? subpath.slice(1) : subpath;
-    if (isJsDelivrNpm(cdnBaseUrl)) {
-        return `${cdnBaseUrl}/${packageVersion}/${cleanSubpath}/+esm`;
-    }
-    return `${cdnBaseUrl}/${packageVersion}/${cleanSubpath}`;
+function resolveBrowserViewUrl(packageVersion, viewConfig, cdnProvider, viewName = "delivery") {
+    const view = browserViewName(viewConfig, viewName);
+    return cdnProvider.browserViewUrl(packageVersion, view);
 }
-function resolveControllerUrl(packageVersion, cdnBaseUrl) {
-    if (isJsDelivrNpm(cdnBaseUrl)) {
-        return `${cdnBaseUrl}/${packageVersion}/controller/+esm`;
-    }
-    return `${cdnBaseUrl}/${packageVersion}/controller`;
+function resolveBrowserControllerUrl(packageVersion, cdnProvider) {
+    return cdnProvider.browserControllerUrl(packageVersion);
 }
-function resolveElementSpecifier(packageName, packageVersion, viewConfig, moduleResolution, cdnBaseUrl) {
+function resolveElementSpecifier(packageName, packageVersion, viewConfig, moduleResolution, cdnProvider, viewName) {
     if (moduleResolution === "import-map") {
         return viewConfig.subpath
             ? `${packageName}${viewConfig.subpath}`
             : packageName;
     }
-    return viewConfig.subpath
-        ? resolveSubpathUrl(packageVersion, viewConfig.subpath, cdnBaseUrl)
-        : resolvePackageUrl(packageVersion, cdnBaseUrl);
+    return resolveBrowserViewUrl(packageVersion, viewConfig, cdnProvider, viewName);
 }
-function resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnBaseUrl) {
+function resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnProvider) {
     if (moduleResolution === "import-map") {
         return `${packageName}/controller`;
     }
-    return resolveControllerUrl(packageVersion, cdnBaseUrl);
+    return resolveBrowserControllerUrl(packageVersion, cdnProvider);
 }
 function pickElementClass(module, view) {
     if (!module || typeof module !== "object")
@@ -235,25 +395,127 @@ function pickElementClass(module, view) {
     }
     return module.default ?? module.Element;
 }
-function buildImportMapJson(elements, viewConfig, cdnBaseUrl, loadControllers) {
+const SHARED_BROWSER_DEPENDENCIES = ["react", "react-dom"];
+function declaredSharedDependencyVersion(metadata, dependencyName, packageVersion) {
+    const version = metadata?.pie?.browserSharedDependencies?.[dependencyName];
+    if (!version) {
+        throw new Error(`${packageVersion} is missing required pie.browserSharedDependencies.${dependencyName}`);
+    }
+    if (!isExactVersion(version)) {
+        throw new Error(`${packageVersion} pie.browserSharedDependencies.${dependencyName} must be an exact version; received "${version}"`);
+    }
+    return version;
+}
+function packageUsesSharedDependency(metadata, dependencyName) {
+    return Boolean(metadata?.pie?.browserSharedDependencies?.[dependencyName] ||
+        metadata?.peerDependencies?.[dependencyName] ||
+        metadata?.dependencies?.[dependencyName] ||
+        metadata?.optionalDependencies?.[dependencyName]);
+}
+function addSharedDependencyImports(imports, selectedVersions, lockedVersions, dependencyName, version, cdnProvider, packageVersion, onConflict) {
+    if (!version) {
+        return;
+    }
+    const currentVersion = selectedVersions[dependencyName];
+    let resolvedVersion = version;
+    if (currentVersion && currentVersion !== version) {
+        resolvedVersion = resolveSharedDependencyVersion(dependencyName, currentVersion, version, packageVersion, lockedVersions.has(dependencyName));
+        onConflict({
+            dependencyName,
+            existingVersion: currentVersion,
+            requestedVersion: version,
+            resolvedVersion,
+            packageVersion,
+        });
+    }
+    selectedVersions[dependencyName] = resolvedVersion;
+    imports[dependencyName] = cdnProvider.sharedDependencyUrl(dependencyName, resolvedVersion);
+    if (dependencyName === "react") {
+        imports["react/jsx-runtime"] = cdnProvider.sharedDependencyUrl("react", resolvedVersion, "jsx-runtime");
+        imports["react/jsx-dev-runtime"] = cdnProvider.sharedDependencyUrl("react", resolvedVersion, "jsx-dev-runtime");
+    }
+    if (dependencyName === "react-dom") {
+        imports["react-dom/client"] = cdnProvider.sharedDependencyUrl("react-dom", resolvedVersion, "client");
+    }
+}
+function isExactVersion(version) {
+    return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version);
+}
+function parseVersion(version) {
+    const match = version.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (!match) {
+        throw new Error(`Invalid shared browser dependency version "${version}"`);
+    }
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+function compareVersions(a, b) {
+    const parsedA = parseVersion(a);
+    const parsedB = parseVersion(b);
+    if (parsedA.major !== parsedB.major)
+        return parsedA.major - parsedB.major;
+    if (parsedA.minor !== parsedB.minor)
+        return parsedA.minor - parsedB.minor;
+    return parsedA.patch - parsedB.patch;
+}
+function resolveSharedDependencyVersion(dependencyName, currentVersion, requestedVersion, packageVersion, isLocked) {
+    const current = parseVersion(currentVersion);
+    const requested = parseVersion(requestedVersion);
+    if (current.major !== requested.major) {
+        throw new Error(`Conflicting shared browser dependency ${dependencyName}: ${currentVersion} vs ${requestedVersion} from ${packageVersion}; different major versions cannot share one browser singleton`);
+    }
+    if (isLocked && compareVersions(requestedVersion, currentVersion) > 0) {
+        throw new Error(`Conflicting shared browser dependency ${dependencyName}: ${currentVersion} is already selected, but ${packageVersion} requires higher version ${requestedVersion}; the browser singleton cannot be upgraded after import-map injection`);
+    }
+    return compareVersions(currentVersion, requestedVersion) >= 0
+        ? currentVersion
+        : requestedVersion;
+}
+async function buildImportMapJson(elements, viewConfig, cdnProvider, loadControllers, includeElementImports, packageMetadataLoader, currentSharedDependencyVersions, onConflict) {
     const imports = {};
+    const selectedVersions = {
+        ...currentSharedDependencyVersions,
+    };
+    const lockedVersions = new Set(Object.keys(currentSharedDependencyVersions));
     for (const [, pkg] of Object.entries(elements)) {
         const packageName = extractPackageName(pkg);
-        imports[packageName] = resolvePackageUrl(pkg, cdnBaseUrl);
-        if (viewConfig.subpath) {
-            imports[`${packageName}${viewConfig.subpath}`] = resolveSubpathUrl(pkg, viewConfig.subpath, cdnBaseUrl);
-        }
-        if (loadControllers) {
-            imports[`${packageName}/controller`] = resolveControllerUrl(pkg, cdnBaseUrl);
+        if (includeElementImports) {
+            imports[packageName] = resolveBrowserViewUrl(pkg, BUILT_IN_VIEWS.delivery, cdnProvider, "delivery");
+            if (viewConfig.subpath) {
+                imports[`${packageName}${viewConfig.subpath}`] = resolveBrowserViewUrl(pkg, viewConfig, cdnProvider, cleanViewSubpath(viewConfig.subpath) ?? "delivery");
+            }
+            if (loadControllers) {
+                imports[`${packageName}/controller`] = resolveBrowserControllerUrl(pkg, cdnProvider);
+            }
+            if (viewConfig.fallback) {
+                const fallbackConfig = BUILT_IN_VIEWS[viewConfig.fallback];
+                if (fallbackConfig) {
+                    const fallbackSpecifier = fallbackConfig.subpath
+                        ? `${packageName}${fallbackConfig.subpath}`
+                        : packageName;
+                    imports[fallbackSpecifier] = resolveBrowserViewUrl(pkg, fallbackConfig, cdnProvider, viewConfig.fallback);
+                }
+            }
         }
-        if (viewConfig.fallback) {
-            const fallbackConfig = BUILT_IN_VIEWS[viewConfig.fallback];
-            if (fallbackConfig?.subpath) {
-                imports[`${packageName}${fallbackConfig.subpath}`] = resolveSubpathUrl(pkg, fallbackConfig.subpath, cdnBaseUrl);
+        const metadata = await packageMetadataLoader(pkg, cdnProvider.packageJsonUrl(pkg));
+        assertBrowserEsmExports(metadata, pkg, viewConfig, loadControllers, cleanViewSubpath(viewConfig.subpath) ?? "delivery");
+        for (const dependencyName of SHARED_BROWSER_DEPENDENCIES) {
+            if (!packageUsesSharedDependency(metadata, dependencyName)) {
+                continue;
             }
+            addSharedDependencyImports(imports, selectedVersions, lockedVersions, dependencyName, declaredSharedDependencyVersion(metadata, dependencyName, pkg), cdnProvider, pkg, onConflict);
         }
     }
-    return JSON.stringify({ imports }, null, 2);
+    if (Object.keys(imports).length === 0) {
+        return { json: null, sharedDependencyVersions: selectedVersions };
+    }
+    return {
+        json: JSON.stringify({ imports }, null, 2),
+        sharedDependencyVersions: selectedVersions,
+    };
 }
 function injectImportMap(json, doc) {
     const script = doc.createElement("script");
@@ -262,9 +524,7 @@ function injectImportMap(json, doc) {
     doc.head.appendChild(script);
 }
 function assertImportMapSupported() {
-    const htmlScriptElement = (typeof HTMLScriptElement !== "undefined"
-        ? HTMLScriptElement
-        : undefined);
+    const htmlScriptElement = (typeof HTMLScriptElement !== "undefined" ? HTMLScriptElement : undefined);
     const supports = typeof htmlScriptElement?.supports === "function" &&
         htmlScriptElement.supports("importmap");
     if (!supports) {