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

package/dist/loaders/esm-adapter.js

@@ -12,12 +12,16 @@
  * uniformly. Here the adapter's job is narrowly to fetch, extract, and
  * call `customElements.define`.
  */
+import { compare as compareSemver, major as semverMajor, minor as semverMinor, } from "semver";
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
 import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
-import { pieRegistry } from "../pie/registry.js";
+import { writeRegistryEntry } from "../pie/registry.js";
 import { validateCustomElementTag } from "../pie/tag-names.js";
-import { isCustomElementConstructor, Status } from "../pie/types.js";
+import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js";
+import { parsePackageName } from "../pie/utils.js";
 import { AdapterFailure, } from "./element-loader-types.js";
+import { isExactSemver } from "./element-package-policy.js";
+import { forwardMathjaxVersionConflicts } from "./mathjax-version-conflict.js";
 export const BUILT_IN_VIEWS = {
     delivery: { subpath: "", tagSuffix: "" },
     author: { subpath: "/author", tagSuffix: "-config", fallback: "delivery" },
@@ -30,12 +34,21 @@ export function createEsmBackend(config) {
     const view = config.view ?? "delivery";
     const loadControllers = config.loadControllers ?? true;
     const viewConfig = resolveEsmViewConfig(view, config.viewConfig);
+    const browserView = browserViewName(viewConfig, view);
     const injectedPackageVersions = new Set();
     const importMappedPackageVersions = new Map();
+    /** Packages whose editor-runtime variant this backend loads. */
+    const editorRuntimeVariants = new Map();
+    /** Packages that do not publish the browser ESM exports this backend loads. */
+    const unpublishedPackages = new Map();
+    /** Windows whose MathJax version conflicts this backend forwards. */
+    const mathjaxConflictViews = new WeakSet();
     let sharedDependencyVersions = {};
     let importer = defaultImporter;
     let packageMetadataLoader = defaultPackageMetadataLoader;
     let importMapObserver;
+    let importShimLoader = defaultImportShimLoader;
+    let importShimRequest;
     const __seams = {
         replaceImporter(fn) {
             importer = fn;
@@ -46,12 +59,20 @@ export function createEsmBackend(config) {
         replacePackageMetadataLoader(fn) {
             packageMetadataLoader = fn;
         },
+        replaceImportShimLoader(fn) {
+            importShimLoader = fn;
+            importShimRequest = undefined;
+        },
         restore() {
             importer = defaultImporter;
             packageMetadataLoader = defaultPackageMetadataLoader;
+            importShimLoader = defaultImportShimLoader;
+            importShimRequest = undefined;
             importMapObserver = undefined;
             injectedPackageVersions.clear();
             importMappedPackageVersions.clear();
+            editorRuntimeVariants.clear();
+            unpublishedPackages.clear();
             sharedDependencyVersions = {};
         },
     };
@@ -61,9 +82,10 @@ export function createEsmBackend(config) {
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
         }
+        forwardMathjaxVersionConflictsOf(context.doc);
         const newEntries = {};
         for (const [tag, pkg] of Object.entries(elements)) {
-            const packageName = extractPackageName(pkg);
+            const packageName = parsePackageName(pkg).name;
             if (moduleResolution === "import-map") {
                 const existingVersion = importMappedPackageVersions.get(packageName);
                 if (existingVersion && existingVersion !== pkg) {
@@ -77,30 +99,51 @@ export function createEsmBackend(config) {
         if (Object.keys(newEntries).length > 0) {
             let importMapResult;
             try {
-                importMapResult = await buildImportMapJson(newEntries, viewConfig, cdnProvider, loadControllers, moduleResolution === "import-map", packageMetadataLoader, sharedDependencyVersions, reportSharedDependencyConflict);
+                importMapResult = await buildImportMap(newEntries, viewConfig, cdnProvider, loadControllers, moduleResolution === "import-map", packageMetadataLoader, sharedDependencyVersions, reportSharedDependencyConflict);
             }
             catch (err) {
                 reportSharedDependencyError(err);
                 throw err;
             }
-            const json = importMapResult.json;
-            if (json) {
+            for (const [pkg, cause] of importMapResult.unpublished) {
+                unpublishedPackages.set(pkg, cause);
+                if (typeof console !== "undefined" && console.error) {
+                    console.error(`[pie-esm] ${cause}`);
+                }
+            }
+            const editorRuntime = moduleResolution === "url"
+                ? await prepareEditorRuntime(importMapResult.metadata, context.doc)
+                : undefined;
+            // Synchronous from here through the injection, so a loader that runs
+            // next on this page reads the runtime this one maps.
+            const runtimePlan = editorRuntime
+                ? planEditorRuntime(editorRuntime, context.doc)
+                : undefined;
+            const imports = withoutMappedSpecifiers({ ...importMapResult.imports, ...runtimePlan?.imports }, context.doc);
+            let injectedMap;
+            if (Object.keys(imports).length > 0) {
+                const json = JSON.stringify({ imports }, null, 2);
                 assertImportMapSupported();
-                injectImportMap(json, context.doc);
+                injectedMap = injectImportMap(json, context.doc, runtimePlan?.mappedRuntime);
                 importMapObserver?.(json, context.doc);
             }
+            for (const [pkg, variant] of runtimePlan?.served ?? []) {
+                editorRuntimeVariants.set(pkg, variant);
+            }
             sharedDependencyVersions = importMapResult.sharedDependencyVersions;
             for (const pkg of Object.values(newEntries)) {
                 injectedPackageVersions.add(pkg);
                 if (moduleResolution === "import-map") {
-                    importMappedPackageVersions.set(extractPackageName(pkg), pkg);
+                    importMappedPackageVersions.set(parsePackageName(pkg).name, pkg);
                 }
             }
+            if (injectedMap) {
+                await applyImportMap(imports, injectedMap, context.doc);
+            }
         }
         const reasons = new Map();
-        const registry = pieRegistry();
         await Promise.all(Object.entries(elements).map(async ([tag, packageVersion]) => {
-            const packageName = extractPackageName(packageVersion);
+            const packageName = parsePackageName(packageVersion).name;
             let actualTag;
             try {
                 actualTag = validateCustomElementTag(tag, `element tag for ${packageName}`);
@@ -114,48 +157,65 @@ export function createEsmBackend(config) {
                 return;
             }
             const specifier = resolveElementSpecifier(packageName, packageVersion, viewConfig, moduleResolution, cdnProvider, view);
-            let module;
-            try {
-                module = await importer(specifier);
+            const unpublished = unpublishedPackages.get(packageVersion);
+            if (unpublished) {
+                reasons.set(tag, {
+                    kind: "module-load-failed",
+                    tag,
+                    specifier,
+                    cause: unpublished,
+                });
+                return;
             }
-            catch (err) {
-                if (viewConfig.fallback) {
-                    const fallbackConfig = BUILT_IN_VIEWS[viewConfig.fallback] ?? BUILT_IN_VIEWS.delivery;
-                    const fallbackSpecifier = resolveElementSpecifier(packageName, packageVersion, fallbackConfig, moduleResolution, cdnProvider, viewConfig.fallback);
-                    try {
-                        module = await importer(fallbackSpecifier);
+            const variant = editorRuntimeVariants.get(packageVersion);
+            let ElementClass;
+            if (variant) {
+                ElementClass = await importVariantElementClass(packageVersion, variant, context.doc);
+            }
+            if (!ElementClass) {
+                let module;
+                try {
+                    module = await importModule(specifier, context.doc);
+                }
+                catch (err) {
+                    if (viewConfig.fallback) {
+                        const fallbackConfig = BUILT_IN_VIEWS[viewConfig.fallback] ?? BUILT_IN_VIEWS.delivery;
+                        const fallbackSpecifier = resolveElementSpecifier(packageName, packageVersion, fallbackConfig, moduleResolution, cdnProvider, viewConfig.fallback);
+                        try {
+                            module = await importModule(fallbackSpecifier, context.doc);
+                        }
+                        catch (fallbackErr) {
+                            reasons.set(tag, {
+                                kind: "module-load-failed",
+                                tag,
+                                specifier: fallbackSpecifier,
+                                cause: fallbackErr instanceof Error
+                                    ? fallbackErr.message
+                                    : String(fallbackErr),
+                            });
+                            return;
+                        }
                     }
-                    catch (fallbackErr) {
+                    else {
                         reasons.set(tag, {
                             kind: "module-load-failed",
                             tag,
-                            specifier: fallbackSpecifier,
-                            cause: fallbackErr instanceof Error
-                                ? fallbackErr.message
-                                : String(fallbackErr),
+                            specifier,
+                            cause: err instanceof Error ? err.message : String(err),
                         });
                         return;
                     }
                 }
-                else {
+                ElementClass = pickElementClass(module, view);
+                if (!ElementClass) {
                     reasons.set(tag, {
-                        kind: "module-load-failed",
+                        kind: "no-element-class",
                         tag,
-                        specifier,
-                        cause: err instanceof Error ? err.message : String(err),
+                        packageName,
                     });
                     return;
                 }
             }
-            const ElementClass = pickElementClass(module, view);
-            if (!ElementClass) {
-                reasons.set(tag, {
-                    kind: "no-element-class",
-                    tag,
-                    packageName,
-                });
-                return;
-            }
             if (!isCustomElementConstructor(ElementClass)) {
                 reasons.set(tag, {
                     kind: "not-a-constructor",
@@ -178,30 +238,239 @@ export function createEsmBackend(config) {
             }
             let controller = null;
             if (loadControllers) {
-                const controllerSpecifier = resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnProvider);
-                try {
-                    const controllerModule = await importer(controllerSpecifier);
-                    controller = controllerModule?.default ?? controllerModule;
+                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)}`);
+                    }
                 }
-                catch {
-                    // Controllers are best-effort; element registration is what the
-                    // primitive verifies.
+                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.
+                    }
                 }
             }
-            registry[actualTag] = {
+            writeRegistryEntry({
                 package: packageVersion,
                 status: Status.loaded,
                 tagName: actualTag,
                 element: ElementClass,
                 controller,
                 config: null,
-                bundleType: "esm",
-            };
+                bundleType: BundleType.esm,
+            });
         }));
         if (reasons.size > 0) {
             throw new AdapterFailure(reasons);
         }
     }
+    /**
+     * The element class of a package's editor-runtime variant, or `undefined`
+     * after reporting why it cannot load, so the caller loads `./browser/*`.
+     */
+    async function importVariantElementClass(packageVersion, variant, doc) {
+        const specifier = cdnProvider.browserViewUrl(packageVersion, variant.views[browserView]);
+        try {
+            const ElementClass = pickElementClass(await importModule(specifier, doc), view);
+            if (isCustomElementConstructor(ElementClass))
+                return ElementClass;
+            throw new Error(`${specifier} exports no custom element class`);
+        }
+        catch (err) {
+            editorRuntimeVariants.delete(packageVersion);
+            reportEditorRuntimeFallback(packageVersion, variant.declaration, variant.runtime, `its editor-runtime ${browserView} view failed to load: ${errorMessage(err)}`);
+            return undefined;
+        }
+    }
+    /**
+     * 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.
+     */
+    async function importModule(specifier, doc) {
+        await importMapsSettled(doc);
+        if (!documentUsesImportShim(doc))
+            return importer(specifier);
+        return (await importShim(doc))(specifier);
+    }
+    /**
+     * Settles the map this backend just added: es-module-shims takes it in a
+     * document that already uses it, and otherwise the browser has either
+     * applied it or rejected it.
+     */
+    async function applyImportMap(imports, script, doc) {
+        let state = "applied";
+        try {
+            if (script.type === SHIM_IMPORT_MAP_TYPE) {
+                (await importShim(doc)).addImportMap({ imports });
+            }
+            else if (await importMapRejected(imports)) {
+                state = "rejected";
+                await importShim(doc);
+            }
+        }
+        finally {
+            settleImportMap(script, state);
+        }
+    }
+    /**
+     * Whether the browser rejected a map this backend added. Firefox rejects
+     * every import map added after the page's first module load, so a specifier
+     * the map defines fails to resolve while the module it maps to loads. When
+     * that module fails too, the map is not the cause, and the element imports
+     * report the failure.
+     */
+    async function importMapRejected(imports) {
+        const specifier = "react" in imports ? "react" : Object.keys(imports)[0];
+        try {
+            await importer(specifier);
+            return false;
+        }
+        catch {
+            // Resolved below: the map, or the module it maps to.
+        }
+        try {
+            await importer(imports[specifier]);
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * es-module-shims, holding every map in `doc`: the rejected ones, and any
+     * the browser applied before, so both resolve the same way.
+     */
+    function importShim(doc) {
+        importShimRequest ??= importShimLoader().then((shim) => {
+            shim.addImportMap({ imports: documentImports(doc) });
+            return shim;
+        }, (err) => {
+            importShimRequest = undefined;
+            throw err;
+        });
+        return importShimRequest;
+    }
+    /**
+     * Collect the packages whose variant covers this backend's view and, when
+     * the page maps no editor runtime yet, fetch the metadata of the one to map.
+     */
+    async function prepareEditorRuntime(metadataByPackage, doc) {
+        const candidates = [];
+        for (const [packageVersion, metadata] of metadataByPackage) {
+            const declaration = readEditorRuntimeDeclaration(metadata);
+            if (declaration === undefined)
+                continue;
+            if (declaration === null) {
+                reportEditorRuntimeFallback(packageVersion, undefined, undefined, "its pie.browserEditorRuntime declaration is invalid");
+                continue;
+            }
+            if (declaration.views[browserView]) {
+                candidates.push({ packageVersion, declaration });
+            }
+        }
+        if (candidates.length === 0)
+            return { candidates };
+        if (!importMapsSupported()) {
+            for (const { packageVersion, declaration } of candidates) {
+                reportEditorRuntimeFallback(packageVersion, declaration, undefined, "this browser does not support import maps");
+            }
+            return { candidates: [] };
+        }
+        if (readMappedEditorRuntime(doc))
+            return { candidates };
+        const runtime = highestDeclaredEditorRuntime(candidates);
+        return {
+            candidates,
+            target: { runtime, ...(await loadEditorRuntimeModules(runtime)) },
+        };
+    }
+    async function loadEditorRuntimeModules(runtime) {
+        const runtimeVersion = `${runtime.name}@${runtime.version}`;
+        let metadata;
+        try {
+            metadata = await packageMetadataLoader(runtimeVersion, cdnProvider.packageJsonUrl(runtimeVersion));
+        }
+        catch (err) {
+            return {
+                failure: `the package.json of ${runtimeVersion} could not be loaded: ${errorMessage(err)}`,
+            };
+        }
+        if (!metadata) {
+            return {
+                failure: `the package.json of ${runtimeVersion} could not be loaded`,
+            };
+        }
+        const modules = readBrowserModules(metadata);
+        return modules
+            ? { modules }
+            : { failure: `${runtimeVersion} declares no valid pie.browserModules` };
+    }
+    /**
+     * Decide which packages the page's editor runtime serves, and the entries
+     * that map it when the page maps none yet. Runs synchronously up to the
+     * import-map injection, so it reads the runtime any other loader mapped
+     * while this one awaited metadata.
+     */
+    function planEditorRuntime(prepared, doc) {
+        const plan = { imports: {}, served: new Map() };
+        if (prepared.candidates.length === 0)
+            return plan;
+        let runtime = readMappedEditorRuntime(doc);
+        if (!runtime) {
+            const { target } = prepared;
+            let failure = target?.failure;
+            if (target?.modules) {
+                const taken = documentImports(doc);
+                const mapped = Object.keys(target.modules).find((specifier) => specifier in taken);
+                if (mapped)
+                    failure = `the page already maps ${mapped}`;
+            }
+            if (failure || !target?.modules) {
+                for (const { packageVersion, declaration } of prepared.candidates) {
+                    reportEditorRuntimeFallback(packageVersion, declaration, undefined, failure ?? "the page no longer maps its editor runtime");
+                }
+                return plan;
+            }
+            runtime = target.runtime;
+            const runtimeVersion = `${runtime.name}@${runtime.version}`;
+            for (const [specifier, runtimeView] of Object.entries(target.modules)) {
+                plan.imports[specifier] = cdnProvider.browserViewUrl(runtimeVersion, runtimeView);
+            }
+            plan.mappedRuntime = runtimeVersion;
+        }
+        for (const { packageVersion, declaration } of prepared.candidates) {
+            if (!canServeEditorRuntime(runtime, declaration)) {
+                reportEditorRuntimeFallback(packageVersion, declaration, runtime, `the page maps ${runtime.name}@${runtime.version}, which cannot serve ${declaration.name}@${declaration.version}`);
+                continue;
+            }
+            plan.served.set(packageVersion, {
+                views: declaration.views,
+                declaration,
+                runtime,
+            });
+            if (declaration.version !== runtime.version) {
+                reportSharedDependencyConflict({
+                    dependencyName: runtime.name,
+                    existingVersion: runtime.version,
+                    requestedVersion: declaration.version,
+                    resolvedVersion: runtime.version,
+                    packageVersion,
+                });
+            }
+        }
+        return plan;
+    }
     function getInstrumentationProvider() {
         if (!config.trackPageActions)
             return undefined;
@@ -212,9 +481,16 @@ export function createEsmBackend(config) {
             return undefined;
         return provider;
     }
-    function reportSharedDependencyConflict(attributes) {
+    function forwardMathjaxVersionConflictsOf(doc) {
+        const view = doc.defaultView;
+        if (!view || mathjaxConflictViews.has(view))
+            return;
+        mathjaxConflictViews.add(view);
+        forwardMathjaxVersionConflicts(view, getInstrumentationProvider);
+    }
+    function reportSharedDependencyConflict(attributes, message = `[pie-esm] Shared dependency version conflict resolved for ${String(attributes.dependencyName)}`) {
         if (typeof console !== "undefined" && console.warn) {
-            console.warn(`[pie-esm] Shared dependency version conflict resolved for ${String(attributes.dependencyName)}`, attributes);
+            console.warn(message, attributes);
         }
         const provider = getInstrumentationProvider();
         if (!provider)
@@ -226,6 +502,17 @@ export function createEsmBackend(config) {
             // Swallow: instrumentation must never break loading.
         }
     }
+    /** Report a package that loads `./browser/*` although it declares a variant. */
+    function reportEditorRuntimeFallback(packageVersion, declaration, runtime, reason) {
+        reportSharedDependencyConflict({
+            dependencyName: declaration?.name,
+            existingVersion: runtime?.version,
+            requestedVersion: declaration?.version,
+            packageVersion,
+            fallback: "./browser/*",
+            reason,
+        }, `[pie-esm] ${packageVersion} loads ./browser/* in place of its editor-runtime variant: ${reason}`);
+    }
     function reportSharedDependencyError(error) {
         const err = error instanceof Error ? error : new Error(String(error));
         if (typeof console !== "undefined" && console.error) {
@@ -261,9 +548,37 @@ export function mapEsmViewElements(elements, view = "delivery", viewConfig) {
 }
 function defaultImporter(specifier) {
     // @vite-ignore — dynamic import resolved at runtime.
-    return import(/* @vite-ignore */ specifier);
+    return import(/* webpackIgnore: true */ /* @vite-ignore */ specifier);
+}
+/**
+ * One request per package.json URL, shared by every backend on the page: the
+ * players on a page read the metadata of the same element versions and of the
+ * same editor runtime. A request that fails or finds no metadata is dropped
+ * once it settles, so a later load asks again.
+ */
+const packageMetadataRequests = new Map();
+/** @internal Test-only: drops every shared package.json request. */
+export function clearPackageMetadataRequests() {
+    packageMetadataRequests.clear();
 }
-async function defaultPackageMetadataLoader(packageVersion, packageJsonUrl) {
+function defaultPackageMetadataLoader(packageVersion, packageJsonUrl) {
+    const pending = packageMetadataRequests.get(packageJsonUrl);
+    if (pending)
+        return pending;
+    const request = fetchPackageMetadata(packageJsonUrl);
+    packageMetadataRequests.set(packageJsonUrl, request);
+    const forget = () => {
+        if (packageMetadataRequests.get(packageJsonUrl) === request) {
+            packageMetadataRequests.delete(packageJsonUrl);
+        }
+    };
+    request.then((metadata) => {
+        if (metadata === null)
+            forget();
+    }, forget);
+    return request;
+}
+async function fetchPackageMetadata(packageJsonUrl) {
     const browserFetch = typeof window !== "undefined" &&
         typeof window.fetch === "function"
         ? window.fetch.bind(window)
@@ -277,6 +592,22 @@ async function defaultPackageMetadataLoader(packageVersion, packageJsonUrl) {
     }
     return (await response.json());
 }
+const RUNTIME_SUPPORT_PATH = "dist/runtime-support.js";
+/**
+ * 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 function resolveEsmRuntimeSupportUrl(packageVersion, options) {
+    const cdnBaseUrl = options.cdnBaseUrl.replace(/\/+$/, "");
+    const provider = resolveCdnProvider(options.cdnProvider, cdnBaseUrl);
+    if (typeof provider.runtimeSupportUrl === "function") {
+        return provider.runtimeSupportUrl(packageVersion);
+    }
+    const packageJsonUrl = provider.packageJsonUrl(packageVersion);
+    return packageJsonUrl.endsWith("/package.json")
+        ? `${packageJsonUrl.slice(0, -"package.json".length)}${RUNTIME_SUPPORT_PATH}`
+        : undefined;
+}
 function resolveCdnProvider(provider, cdnBaseUrl) {
     if (isEsmCdnProvider(provider))
         return provider;
@@ -302,6 +633,7 @@ function createJsDelivrProvider(cdnBaseUrl, name = "jsdelivr") {
         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`,
+        runtimeSupportUrl: (packageVersion) => `${cdnBaseUrl}/${packageVersion}/${RUNTIME_SUPPORT_PATH}`,
         sharedDependencyUrl: (dependencyName, version, subpath) => {
             const suffix = subpath ? `/${subpath}/+esm` : "/+esm";
             return `${cdnBaseUrl}/${dependencyName}@${version}${suffix}`;
@@ -316,6 +648,7 @@ function createEsmShProvider(cdnBaseUrl) {
         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`,
+        runtimeSupportUrl: (packageVersion) => `${rawBaseUrl}/${packageVersion}/${RUNTIME_SUPPORT_PATH}`,
         sharedDependencyUrl: (dependencyName, version, subpath) => {
             const suffix = subpath ? `/${subpath}` : "";
             return `${esmBaseUrl}/${dependencyName}@${version}${suffix}`;
@@ -340,9 +673,13 @@ function toRawEsmShBaseUrl(cdnBaseUrl) {
 function resolveEsmViewConfig(view, viewConfig) {
     return viewConfig ?? BUILT_IN_VIEWS[view] ?? BUILT_IN_VIEWS.delivery;
 }
-function assertBrowserEsmExports(metadata, packageVersion, viewConfig, loadControllers, viewName) {
+/**
+ * Why a package cannot load this view as browser ESM, or `undefined` when its
+ * metadata publishes every export the view needs or names no exports.
+ */
+function missingBrowserEsmExport(metadata, packageVersion, viewConfig, loadControllers, viewName) {
     if (!metadata?.exports)
-        return;
+        return undefined;
     const requiredExports = new Set([
         `./browser/${browserViewName(viewConfig, viewName)}`,
     ]);
@@ -357,13 +694,10 @@ function assertBrowserEsmExports(metadata, packageVersion, viewConfig, loadContr
     }
     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`);
+            return `${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];
+    return undefined;
 }
 function cleanViewSubpath(subpath) {
     const cleanSubpath = subpath.replace(/^\/+|\/+$/g, "");
@@ -394,7 +728,7 @@ function resolveControllerSpecifier(packageName, packageVersion, moduleResolutio
     }
     return resolveBrowserControllerUrl(packageVersion, cdnProvider);
 }
-function pickElementClass(module, view) {
+export function pickElementClass(module, view) {
     if (!module || typeof module !== "object")
         return undefined;
     if (view === "author") {
@@ -411,7 +745,7 @@ function declaredSharedDependencyVersion(metadata, dependencyName, packageVersio
     if (!version) {
         throw new Error(`${packageVersion} is missing required pie.browserSharedDependencies.${dependencyName}`);
     }
-    if (!isExactVersion(version)) {
+    if (!isExactSemver(version)) {
         throw new Error(`${packageVersion} pie.browserSharedDependencies.${dependencyName} must be an exact version; received "${version}"`);
     }
     return version;
@@ -448,50 +782,35 @@ function addSharedDependencyImports(imports, selectedVersions, lockedVersions, d
         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;
-}
+/** Versions are exact semver, validated before they are compared. */
 function resolveSharedDependencyVersion(dependencyName, currentVersion, requestedVersion, packageVersion, isLocked) {
-    const current = parseVersion(currentVersion);
-    const requested = parseVersion(requestedVersion);
-    if (current.major !== requested.major) {
+    if (semverMajor(currentVersion) !== semverMajor(requestedVersion)) {
         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) {
+    if (isLocked && compareSemver(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
+    return compareSemver(currentVersion, requestedVersion) >= 0
         ? currentVersion
         : requestedVersion;
 }
-async function buildImportMapJson(elements, viewConfig, cdnProvider, loadControllers, includeElementImports, packageMetadataLoader, currentSharedDependencyVersions, onConflict) {
+async function buildImportMap(elements, viewConfig, cdnProvider, loadControllers, includeElementImports, packageMetadataLoader, currentSharedDependencyVersions, onConflict) {
     const imports = {};
     const selectedVersions = {
         ...currentSharedDependencyVersions,
     };
     const lockedVersions = new Set(Object.keys(currentSharedDependencyVersions));
+    const metadataByPackage = new Map();
+    const unpublished = new Map();
     for (const [, pkg] of Object.entries(elements)) {
-        const packageName = extractPackageName(pkg);
+        const metadata = await packageMetadataLoader(pkg, cdnProvider.packageJsonUrl(pkg));
+        const missingExport = missingBrowserEsmExport(metadata, pkg, viewConfig, loadControllers, cleanViewSubpath(viewConfig.subpath) ?? "delivery");
+        if (missingExport) {
+            unpublished.set(pkg, missingExport);
+            continue;
+        }
+        metadataByPackage.set(pkg, metadata);
+        const packageName = parsePackageName(pkg).name;
         if (includeElementImports) {
             imports[packageName] = resolveBrowserViewUrl(pkg, BUILT_IN_VIEWS.delivery, cdnProvider, "delivery");
             if (viewConfig.subpath) {
@@ -510,8 +829,6 @@ async function buildImportMapJson(elements, viewConfig, cdnProvider, loadControl
                 }
             }
         }
-        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;
@@ -519,25 +836,223 @@ async function buildImportMapJson(elements, viewConfig, cdnProvider, loadControl
             addSharedDependencyImports(imports, selectedVersions, lockedVersions, dependencyName, declaredSharedDependencyVersion(metadata, dependencyName, pkg), cdnProvider, pkg, onConflict);
         }
     }
-    if (Object.keys(imports).length === 0) {
-        return { json: null, sharedDependencyVersions: selectedVersions };
-    }
     return {
-        json: JSON.stringify({ imports }, null, 2),
+        imports,
         sharedDependencyVersions: selectedVersions,
+        metadata: metadataByPackage,
+        unpublished,
     };
 }
-function injectImportMap(json, doc) {
+// ─── Shared editor runtime ───────────────────────────────────────────────────
+/**
+ * Names the editor runtime an injected import map maps, as `<name>@<version>`.
+ * The document holds it because every loader on the page, whichever backend
+ * or players-shared copy runs it, shares the one import map.
+ */
+const EDITOR_RUNTIME_ATTRIBUTE = "data-pie-editor-runtime";
+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.
+ */
+function readEditorRuntimeDeclaration(metadata) {
+    const declared = metadata?.pie?.browserEditorRuntime;
+    if (declared === undefined)
+        return undefined;
+    if (!isRecord(declared) || !isRecord(declared.views))
+        return null;
+    const { name, version } = declared;
+    if (typeof name !== "string" || !PACKAGE_NAME.test(name))
+        return null;
+    if (typeof version !== "string" || !isExactSemver(version))
+        return null;
+    const views = Object.entries(declared.views);
+    if (views.length === 0 ||
+        !views.every(([, path]) => typeof path === "string" && BROWSER_VIEW_PATH.test(path))) {
+        return null;
+    }
+    return {
+        name,
+        version,
+        views: Object.fromEntries(views),
+    };
+}
+/**
+ * The editor runtime's `pie.browserModules`, or `null` when it is missing or
+ * malformed. A runtime has no React import, so it maps no React specifier.
+ */
+function readBrowserModules(metadata) {
+    const declared = metadata.pie?.browserModules;
+    if (!isRecord(declared))
+        return null;
+    const modules = Object.entries(declared);
+    const valid = modules.length > 0 &&
+        modules.every(([specifier, view]) => BARE_SPECIFIER.test(specifier) &&
+            !SHARED_BROWSER_DEPENDENCIES.some((dependency) => specifier === dependency || specifier.startsWith(`${dependency}/`)) &&
+            typeof view === "string" &&
+            BROWSER_VIEW_PATH.test(view));
+    return valid ? Object.fromEntries(modules) : null;
+}
+/** The highest runtime version the candidates declare, by semver precedence. */
+function highestDeclaredEditorRuntime(candidates) {
+    const { name } = candidates[0].declaration;
+    let { version } = candidates[0].declaration;
+    for (const { declaration } of candidates) {
+        if (declaration.name === name &&
+            compareSemver(declaration.version, version) > 0) {
+            version = declaration.version;
+        }
+    }
+    return { name, version };
+}
+/**
+ * A runtime serves a variant built against a version in its caret range (the
+ * same major, and below 1.0.0 the same minor) at or below its own.
+ */
+function canServeEditorRuntime(runtime, declaration) {
+    if (runtime.name !== declaration.name)
+        return false;
+    if (semverMajor(runtime.version) !== semverMajor(declaration.version)) {
+        return false;
+    }
+    if (semverMajor(runtime.version) === 0 &&
+        semverMinor(runtime.version) !== semverMinor(declaration.version)) {
+        return false;
+    }
+    return compareSemver(runtime.version, declaration.version) >= 0;
+}
+function importMapScripts(doc) {
+    return typeof doc.querySelectorAll === "function"
+        ? Array.from(doc.querySelectorAll(`script[type="importmap"], script[type="${SHIM_IMPORT_MAP_TYPE}"]`))
+        : [];
+}
+/** The editor runtime an import map in the document maps, first map first. */
+function readMappedEditorRuntime(doc) {
+    for (const script of importMapScripts(doc)) {
+        const mapped = script.getAttribute(EDITOR_RUNTIME_ATTRIBUTE);
+        const at = mapped?.lastIndexOf("@") ?? -1;
+        if (!mapped || at <= 0)
+            continue;
+        const name = mapped.slice(0, at);
+        const version = mapped.slice(at + 1);
+        if (PACKAGE_NAME.test(name) && isExactSemver(version)) {
+            return { name, version };
+        }
+    }
+    return null;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Drop the specifiers an import map already in the document maps. The browser
+ * keeps the first rule for a specifier and discards a later one with a console
+ * warning, so injecting them changes no resolution.
+ */
+function withoutMappedSpecifiers(imports, doc) {
+    const mapped = documentImports(doc);
+    return Object.fromEntries(Object.entries(imports).filter(([specifier]) => !(specifier in mapped)));
+}
+/**
+ * Whether the browser applied an import map this backend added, recorded on
+ * the map so every player and every copy of this module on the page reads the
+ * same answer: `pending` until the backend knows, then `applied` or
+ * `rejected`. A document with a rejected map loads elements through
+ * es-module-shims.
+ */
+const IMPORT_MAP_STATE_ATTRIBUTE = "data-pie-import-map";
+const IMPORT_MAP_SETTLED_EVENT = "pie-import-map-settled";
+const SHIM_IMPORT_MAP_TYPE = "importmap-shim";
+function injectImportMap(json, doc, editorRuntime) {
     const script = doc.createElement("script");
-    script.type = "importmap";
+    script.type = documentUsesImportShim(doc)
+        ? SHIM_IMPORT_MAP_TYPE
+        : "importmap";
+    script.setAttribute(IMPORT_MAP_STATE_ATTRIBUTE, "pending");
+    if (editorRuntime)
+        script.setAttribute(EDITOR_RUNTIME_ATTRIBUTE, editorRuntime);
     script.textContent = json;
     doc.head.appendChild(script);
+    return script;
 }
-function assertImportMapSupported() {
+function settleImportMap(script, state) {
+    script.setAttribute(IMPORT_MAP_STATE_ATTRIBUTE, state);
+    script.dispatchEvent(new Event(IMPORT_MAP_SETTLED_EVENT));
+}
+function documentUsesImportShim(doc) {
+    return importMapScripts(doc).some((script) => script.getAttribute(IMPORT_MAP_STATE_ATTRIBUTE) === "rejected");
+}
+/** Resolves once no import map a PIE backend added to `doc` is pending. */
+async function importMapsSettled(doc) {
+    const pending = importMapScripts(doc).filter((script) => script.getAttribute(IMPORT_MAP_STATE_ATTRIBUTE) === "pending");
+    await Promise.all(pending.map((script) => new Promise((resolve) => script.addEventListener(IMPORT_MAP_SETTLED_EVENT, () => resolve(), {
+        once: true,
+    }))));
+}
+/**
+ * Every mapping the import maps in `doc` define, the first map's rule winning
+ * for a specifier as it does in the browser.
+ */
+function documentImports(doc) {
+    const imports = Object.create(null);
+    for (const script of importMapScripts(doc)) {
+        try {
+            const mapped = JSON.parse(script.textContent || "{}")?.imports;
+            if (!mapped || typeof mapped !== "object")
+                continue;
+            for (const [specifier, url] of Object.entries(mapped)) {
+                if (typeof url === "string" && !(specifier in imports)) {
+                    imports[specifier] = url;
+                }
+            }
+        }
+        catch {
+            // The browser rejects a map it cannot parse, so it maps nothing.
+        }
+    }
+    return imports;
+}
+/**
+ * es-module-shims in shim mode: it resolves through the import maps this
+ * backend hands it and leaves the page's own scripts and load events alone.
+ * A page that already runs es-module-shims keeps its instance, which has to be
+ * in shim mode to take maps from this backend.
+ */
+async function defaultImportShimLoader() {
+    const scope = globalThis;
+    if (!scope.importShim) {
+        scope.esmsInitOptions = {
+            ...scope.esmsInitOptions,
+            shimMode: true,
+            noLoadEventRetriggers: true,
+        };
+        await import("./module-shim.js");
+    }
+    const shim = scope.importShim;
+    if (typeof shim !== "function" || typeof shim.addImportMap !== "function") {
+        throw new Error("es-module-shims did not initialize, so this browser cannot load browser ESM elements after the page's first module load. Use the iife or preloaded strategy.");
+    }
+    try {
+        shim.addImportMap({ imports: {} });
+    }
+    catch {
+        throw new Error("This page runs es-module-shims in polyfill mode, and this browser rejects import maps added after the page's first module load. Load es-module-shims in shim mode, or use the iife or preloaded strategy.");
+    }
+    return shim;
+}
+function importMapsSupported() {
     const htmlScriptElement = (typeof HTMLScriptElement !== "undefined" ? HTMLScriptElement : undefined);
-    const supports = typeof htmlScriptElement?.supports === "function" &&
-        htmlScriptElement.supports("importmap");
-    if (!supports) {
+    return (typeof htmlScriptElement?.supports === "function" &&
+        htmlScriptElement.supports("importmap"));
+}
+function assertImportMapSupported() {
+    if (!importMapsSupported()) {
         throw new Error('This browser does not support import maps. Use moduleResolution="url" or switch to iife/preloaded strategy.');
     }
 }