@pie-players/pie-players-shared 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/loaders/esm-adapter.js

@@ -19,8 +19,10 @@ import { writeRegistryEntry } from "../pie/registry.js";
 import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status, } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
+import { DEFAULT_ESM_CDN_URL } from "./defaults.js";
 import { AdapterFailure, } from "./element-loader-types.js";
 import { isExactSemver } from "./element-package-policy.js";
+import { invalidPackageSpecMessage, isScopedPackageSpec, } from "./element-package-spec.js";
 import { forwardMathjaxEvents } from "./mathjax-events.js";
 import { isPlainRecord } from "../object/index.js";
 export const BUILT_IN_VIEWS = {
@@ -80,12 +82,30 @@ export function createEsmBackend(config) {
     async function load(elements, context) {
         if (!elements || Object.keys(elements).length === 0)
             return;
+        // Refused before any URL is built from the spec; the other elements load.
+        const reasons = new Map();
+        const loadable = {};
+        for (const [tag, pkg] of Object.entries(elements)) {
+            if (isScopedPackageSpec(pkg)) {
+                loadable[tag] = pkg;
+            }
+            else {
+                reasons.set(tag, {
+                    kind: "backend-rejected",
+                    tag,
+                    cause: invalidPackageSpecMessage(pkg),
+                });
+            }
+        }
+        if (Object.keys(loadable).length === 0) {
+            throw new AdapterFailure(reasons);
+        }
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
         }
         forwardMathjaxEventsOf(context.doc);
         const newEntries = {};
-        for (const [tag, pkg] of Object.entries(elements)) {
+        for (const [tag, pkg] of Object.entries(loadable)) {
             const packageName = parsePackageName(pkg).name;
             if (moduleResolution === "import-map") {
                 const existingVersion = importMappedPackageVersions.get(packageName);
@@ -122,8 +142,11 @@ export function createEsmBackend(config) {
                 : undefined;
             const imports = withoutMappedSpecifiers({ ...importMapResult.imports, ...runtimePlan?.imports }, context.doc);
             let injectedMap;
+            let map;
             if (Object.keys(imports).length > 0) {
-                const json = JSON.stringify({ imports }, null, 2);
+                const scopes = withoutMappedScopes(jsDelivrRootPathScopes(cdnProvider, cdnBaseUrl, context.doc), context.doc);
+                map = scopes ? { imports, scopes } : { imports };
+                const json = JSON.stringify(map, null, 2);
                 // URL resolution maps the shared dependencies and the editor
                 // runtime, so it needs import maps too.
                 assertImportMapSupported();
@@ -143,12 +166,11 @@ export function createEsmBackend(config) {
                     importMappedPackageVersions.set(parsePackageName(pkg).name, pkg);
                 }
             }
-            if (injectedMap) {
-                await applyImportMap(imports, injectedMap, context.doc);
+            if (injectedMap && map) {
+                await applyImportMap(map, injectedMap, context.doc);
             }
         }
-        const reasons = new Map();
-        await Promise.all(Object.entries(elements).map(async ([tag, packageVersion]) => {
+        await Promise.all(Object.entries(loadable).map(async ([tag, packageVersion]) => {
             const packageName = parsePackageName(packageVersion).name;
             let actualTag;
             try {
@@ -321,13 +343,13 @@ export function createEsmBackend(config) {
      * document that already uses it, and otherwise the browser has either
      * applied it or rejected it.
      */
-    async function applyImportMap(imports, script, doc) {
+    async function applyImportMap(map, script, doc) {
         let state = "applied";
         try {
             if (script.type === SHIM_IMPORT_MAP_TYPE) {
-                (await importShim(doc)).addImportMap({ imports });
+                (await importShim(doc)).addImportMap(map);
             }
-            else if (await importMapRejected(imports)) {
+            else if (await importMapRejected(map.imports)) {
                 state = "rejected";
                 await importShim(doc);
             }
@@ -366,7 +388,7 @@ export function createEsmBackend(config) {
      */
     function importShim(doc) {
         importShimRequest ??= importShimLoader().then((shim) => {
-            shim.addImportMap({ imports: documentImports(doc) });
+            shim.addImportMap(documentImportMap(doc));
             return shim;
         }, (err) => {
             importShimRequest = undefined;
@@ -609,9 +631,12 @@ async function fetchPackageMetadata(packageJsonUrl) {
 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.
+ * elements from, or `undefined` when a custom provider names no package root or
+ * `packageVersion` is not a scoped package spec.
  */
 export function resolveEsmRuntimeSupportUrl(packageVersion, options) {
+    if (!isScopedPackageSpec(packageVersion))
+        return undefined;
     const cdnBaseUrl = options.cdnBaseUrl.replace(/\/+$/, "");
     const provider = resolveCdnProvider(options.cdnProvider, cdnBaseUrl);
     if (typeof provider.runtimeSupportUrl === "function") {
@@ -640,6 +665,24 @@ export function resolveEsmAssetRoot(options) {
         ? packageJsonUrl.slice(0, -suffix.length) || undefined
         : undefined;
 }
+/**
+ * URL of a raw npm package file, `file` being `<package>@<version>/<path>`, on
+ * the ESM CDN a player's `loaderOptions` name, so a page asset the players add,
+ * such as a stylesheet, comes from where the elements do. Reads untyped options
+ * as a toolkit runtime context carries them; jsDelivr when they set no base.
+ */
+export function resolveEsmPackageFileUrl(loaderOptions, file) {
+    const configured = loaderOptions?.esmCdnUrl;
+    const cdnBaseUrl = (typeof configured === "string" && configured.trim()
+        ? configured.trim()
+        : DEFAULT_ESM_CDN_URL).replace(/\/+$/, "");
+    const provider = loaderOptions?.esmCdnProvider;
+    const cdnProvider = typeof provider === "string" || isEsmCdnProvider(provider)
+        ? provider
+        : undefined;
+    const root = resolveEsmAssetRoot({ cdnBaseUrl, cdnProvider }) ?? cdnBaseUrl;
+    return `${root}/${file.replace(/^\/+/, "")}`;
+}
 function resolveCdnProvider(provider, cdnBaseUrl) {
     if (isEsmCdnProvider(provider))
         return provider;
@@ -660,7 +703,7 @@ function isEsmCdnProvider(value) {
         typeof candidate.sharedDependencyUrl === "function");
 }
 function createJsDelivrProvider(cdnBaseUrl, name = "jsdelivr") {
-    return {
+    const provider = {
         name,
         packageJsonUrl: (packageVersion) => `${cdnBaseUrl}/${packageVersion}/package.json`,
         browserViewUrl: (packageVersion, view) => `${cdnBaseUrl}/${packageVersion}/dist/browser/${view}/index.js`,
@@ -671,7 +714,31 @@ function createJsDelivrProvider(cdnBaseUrl, name = "jsdelivr") {
             return `${cdnBaseUrl}/${dependencyName}@${version}${suffix}`;
         },
     };
+    jsDelivrShapedProviders.add(provider);
+    return provider;
 }
+/**
+ * jsDelivr's `+esm` builds import their dependencies by root path
+ * (`/npm/react@18.3.1/+esm`), which resolves against the origin that served
+ * them. A base mounted anywhere but `/npm` gets a scope mapping those paths
+ * back under it, so they load from the configured CDN and resolve to the URLs
+ * the shared-dependency entries map, keeping one React on the page.
+ */
+function jsDelivrRootPathScopes(cdnProvider, cdnBaseUrl, doc) {
+    if (!jsDelivrShapedProviders.has(cdnProvider))
+        return undefined;
+    let base;
+    try {
+        base = new URL(`${cdnBaseUrl}/`, doc.baseURI || undefined);
+    }
+    catch {
+        return undefined;
+    }
+    const root = new URL("/npm/", base).href;
+    return root === base.href ? undefined : { [base.href]: { [root]: base.href } };
+}
+/** Providers built by {@link createJsDelivrProvider}, whatever their name. */
+const jsDelivrShapedProviders = new WeakSet();
 function createEsmShProvider(cdnBaseUrl) {
     const esmBaseUrl = cdnBaseUrl.replace(/\/+$/, "");
     const rawBaseUrl = toRawEsmShBaseUrl(esmBaseUrl);
@@ -1029,23 +1096,50 @@ async function importMapsSettled(doc) {
  * for a specifier as it does in the browser.
  */
 function documentImports(doc) {
+    return documentImportMap(doc).imports;
+}
+/** {@link documentImports}, with the scopes the maps define. */
+function documentImportMap(doc) {
     const imports = Object.create(null);
+    const scopes = Object.create(null);
     for (const script of importMapScripts(doc)) {
         try {
-            const mapped = JSON.parse(script.textContent || "{}")?.imports;
-            if (!mapped || typeof mapped !== "object")
+            const map = JSON.parse(script.textContent || "{}");
+            addFirstRules(imports, map?.imports);
+            if (!map?.scopes || typeof map.scopes !== "object")
                 continue;
-            for (const [specifier, url] of Object.entries(mapped)) {
-                if (typeof url === "string" && !(specifier in imports)) {
-                    imports[specifier] = url;
-                }
+            for (const [scope, rules] of Object.entries(map.scopes)) {
+                scopes[scope] ??= Object.create(null);
+                addFirstRules(scopes[scope], rules);
             }
         }
         catch {
             // The browser rejects a map it cannot parse, so it maps nothing.
         }
     }
-    return imports;
+    return { imports, scopes };
+}
+function addFirstRules(target, rules) {
+    if (!rules || typeof rules !== "object")
+        return;
+    for (const [specifier, url] of Object.entries(rules)) {
+        if (typeof url === "string" && !(specifier in target)) {
+            target[specifier] = url;
+        }
+    }
+}
+/** {@link withoutMappedSpecifiers} for scope rules; `undefined` when none remain. */
+function withoutMappedScopes(scopes, doc) {
+    if (!scopes)
+        return undefined;
+    const mapped = documentImportMap(doc).scopes;
+    const remaining = {};
+    for (const [scope, rules] of Object.entries(scopes)) {
+        const kept = Object.entries(rules).filter(([specifier]) => !(specifier in (mapped[scope] ?? {})));
+        if (kept.length > 0)
+            remaining[scope] = Object.fromEntries(kept);
+    }
+    return Object.keys(remaining).length > 0 ? remaining : undefined;
 }
 /**
  * es-module-shims in shim mode: it resolves through the import maps this

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

@@ -21,6 +21,7 @@
 import type { InstrumentationProvider } from "../instrumentation/types.js";
 import { type IifeBundleRetryConfig } from "../loader-config.js";
 import { BundleType } from "../pie/types.js";
+import type { ElementMap } from "./ElementLoader.js";
 import { type ElementLoaderBackend } from "./element-loader-types.js";
 /**
  * Bundle-build retry status emitted while a bundle is being built or after
@@ -77,4 +78,10 @@ export type IifeBackendConfig = {
     instrumentationProvider?: InstrumentationProvider;
 };
 export type IifeBackend = ElementLoaderBackend & {};
+/**
+ * The legacy IIFE bundle global is keyed by unversioned package name. Two
+ * distinct specs for one package therefore cannot coexist in a single bundle:
+ * one constructor would silently be reused for both requested versioned tags.
+ */
+export declare function findIifeElementMapConflict(elements: ElementMap): string | undefined;
 export declare function createIifeBackend(config: IifeBackendConfig): IifeBackend;

package/dist/loaders/iife-adapter.js

@@ -31,7 +31,7 @@ import { AdapterFailure, } from "./element-loader-types.js";
  * distinct specs for one package therefore cannot coexist in a single bundle:
  * one constructor would silently be reused for both requested versioned tags.
  */
-function findIifeElementMapConflict(elements) {
+export function findIifeElementMapConflict(elements) {
     const specsByPackageName = new Map();
     for (const packageSpecValue of Object.values(elements)) {
         const packageSpec = String(packageSpecValue);

package/dist/loaders/index.d.ts

@@ -34,10 +34,11 @@ export type { ElementMap } from "./ElementLoader.js";
 export { aggregateElements } from "./ElementLoader.js";
 export type { ElementPackagePolicy } from "./element-package-policy.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
+export { isScopedPackageSpec } from "./element-package-spec.js";
 export type { BackendContext, BackendOption, ElementLoaderBackend, ElementTag, EnsureRegisteredOptions, EsmBackendConfig, IifeBackendConfig, RegistrationFailureReason, } from "./element-loader.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
 export type { BuiltInEsmCdnProviderName, EsmBackend, EsmCdnProvider, EsmCdnProviderName, EsmCdnProviderOption, ViewConfig, } from "./esm-adapter.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmPackageFileUrl, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
 export type { IifeBackend, IifeBundleRetryStatus, } from "./iife-adapter.js";
 export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";
 export { DEFAULT_BUNDLE_HOST, DEFAULT_ESM_CDN_URL } from "./defaults.js";

package/dist/loaders/index.js

@@ -32,8 +32,9 @@
  */
 export { aggregateElements } from "./ElementLoader.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
+export { isScopedPackageSpec } from "./element-package-spec.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, resolveEsmPackageFileUrl, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
 export { forwardMathjaxEvents, MATHJAX_NO_ASSET_ROOT_EVENT, MATHJAX_VERSION_CONFLICT_EVENT, } from "./mathjax-events.js";
 export { DEFAULT_BUNDLE_HOST, DEFAULT_ESM_CDN_URL } from "./defaults.js";
 export { createIifeBackend } from "./iife-adapter.js";

package/dist/loaders/preloaded-registration.d.ts

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -29,13 +34,20 @@ export interface PreloadedElement {
     /**
      * Base tag to register, e.g. `pie-element-multiple-choice`. Content can
      * author another base tag for the package, which the players define from
-     * this registration.
+     * this registration. Defaults to the package name without its `@`, with
+     * `-` for `/`.
+     */
+    tag?: string;
+    /**
+     * npm package name, e.g. `@pie-element/multiple-choice`. Defaults to the
+     * name in the modules' `piePackage`.
+     */
+    package?: string;
+    /**
+     * The installed version, exact, e.g. `13.4.4`. Defaults to the version in
+     * the modules' `piePackage`.
      */
-    tag: string;
-    /** npm package name, e.g. `@pie-element/multiple-choice`. */
-    package: string;
-    /** The installed version, exact, e.g. `13.4.4`. */
-    version: string;
+    version?: string;
     /** The package's `./browser/delivery` module, or its default export. */
     element: CustomElementConstructor | {
         readonly default: CustomElementConstructor;

package/dist/loaders/preloaded-registration.js

@@ -11,6 +11,11 @@
  * define the ones content names under another base tag
  * (`defineAuthoredPreloadedTags`) and assert them (`assertRegistered`).
  *
+ * pie-elements-ng's `./browser/*` modules export `piePackage`, the
+ * `{ name, version }` of the package they were built from, so an entry can
+ * give its modules alone. A `package` or `version` it also gives must match,
+ * which catches a registration an upgrade left behind.
+ *
  * A hosted player takes models from the server and resolves no controller. A
  * player that is not hosted runs the controller's `model()` in the browser, so
  * it needs the `controller` an entry registers; the item player warns about
@@ -23,6 +28,7 @@
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
 import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
 import { writeRegistryEntry } from "../pie/registry.js";
+import { validateCustomElementTag } from "../pie/tag-names.js";
 import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
 import { toPackageVersionedTag } from "../pie/versioned-tag.js";
@@ -69,15 +75,24 @@ export function registerPreloadedElements(elements, options = {}) {
 function resolveElement(element, index) {
     const at = `[registerPreloadedElements] entry ${index}`;
     if (!element || typeof element !== "object") {
-        throw new Error(`${at}: expected { tag, package, version, element }`);
+        throw new Error(`${at}: expected { element, controller?, tag?, package?, version? }`);
+    }
+    const identity = moduleIdentity(element, at);
+    if (!identity && element.package === undefined && element.version === undefined) {
+        throw new Error(`${at}: package and version are required for modules that export no piePackage`);
     }
-    const { package: packageName, version, tag } = element;
+    const packageName = element.package ?? identity?.name;
+    const version = element.version ?? identity?.version;
     if (!isBarePackageName(packageName)) {
         throw new Error(`${at}: package must be a bare package name, got ${JSON.stringify(packageName)}`);
     }
     if (typeof version !== "string" || !isExactSemver(version)) {
         throw new Error(`${at} (${packageName}): version must be the installed version, exact, such as 1.2.3; got ${JSON.stringify(version)}`);
     }
+    if (identity && (identity.name !== packageName || identity.version !== version)) {
+        throw new Error(`${at}: the modules were built from ${identity.name}@${identity.version}, not ${packageName}@${version}`);
+    }
+    const tag = element.tag ?? packageName.replace(/^@/, "").replace("/", "-");
     if (typeof tag !== "string" || !tag) {
         throw new Error(`${at} (${packageName}): tag must be the base tag to register, got ${JSON.stringify(tag)}`);
     }
@@ -95,13 +110,33 @@ function resolveElement(element, index) {
         }
     }
     const spec = `${packageName}@${version}`;
-    return {
-        packageName,
-        spec,
-        tagName: toPackageVersionedTag(tag, spec),
-        elementClass: candidate,
-        controller,
-    };
+    const tagName = validateCustomElementTag(toPackageVersionedTag(tag, spec), element.tag === undefined
+        ? `${at} (${packageName}) tag derived from the package name; give tag`
+        : `${at} (${packageName}) tag`);
+    return { packageName, spec, tagName, elementClass: candidate, controller };
+}
+/** The `piePackage` of the entry's modules, which agree when both export one. */
+function moduleIdentity(element, at) {
+    const fromElement = readPackageIdentity(element.element, `${at}: element`);
+    const fromController = readPackageIdentity(element.controller, `${at}: controller`);
+    if (fromElement &&
+        fromController &&
+        (fromElement.name !== fromController.name ||
+            fromElement.version !== fromController.version)) {
+        throw new Error(`${at}: the element module is ${fromElement.name}@${fromElement.version}, ` +
+            `but the controller module is ${fromController.name}@${fromController.version}`);
+    }
+    return fromElement ?? fromController;
+}
+function readPackageIdentity(module, at) {
+    if (!module || typeof module !== "object" || !("piePackage" in module)) {
+        return undefined;
+    }
+    const identity = module.piePackage;
+    if (typeof identity?.name !== "string" || typeof identity.version !== "string") {
+        throw new Error(`${at} module's piePackage must be { name, version }`);
+    }
+    return { name: identity.name, version: identity.version };
 }
 function resolveController(value) {
     if (!value || typeof value !== "object")

package/dist/object/index.d.ts

@@ -6,7 +6,10 @@
  */
 export declare const mergeObjectsIgnoringNullUndefined: <T extends object>(...objects: T[]) => T;
 /**
- * Deep clone an object.
+ * Deep clone of arrays and plain objects. Any other object — a `Date`, a bson
+ * `ObjectId`, a class instance — is carried over by reference: copying its own
+ * keys onto a plain object would drop its prototype, and with it the methods
+ * that identify and serialise it.
  */
 export declare const cloneDeep: <T>(value: T) => T;
 /**

package/dist/object/index.js

@@ -17,7 +17,10 @@ export const mergeObjectsIgnoringNullUndefined = (...objects) => {
     }, {});
 };
 /**
- * Deep clone an object.
+ * Deep clone of arrays and plain objects. Any other object — a `Date`, a bson
+ * `ObjectId`, a class instance — is carried over by reference: copying its own
+ * keys onto a plain object would drop its prototype, and with it the methods
+ * that identify and serialise it.
  */
 export const cloneDeep = (value) => {
     if (value === null || typeof value !== "object") {
@@ -26,6 +29,10 @@ export const cloneDeep = (value) => {
     if (Array.isArray(value)) {
         return value.map(cloneDeep);
     }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return value;
+    }
     const copy = {};
     for (const key in value) {
         if (Object.hasOwn(value, key)) {

package/dist/pie/config.d.ts

@@ -8,6 +8,14 @@ export type PieConfigContractValidationResult = {
     valid: boolean;
     errors: string[];
     warnings: string[];
+    /**
+     * Id problems that can bind a model, markup element or session entry to the
+     * wrong partner. They do not invalidate the config, since content that
+     * carries them has always rendered, but the players report them as errors
+     * so they reach instrumentation. Kept apart from `warnings`, which are
+     * advisory.
+     */
+    bindingWarnings: string[];
 };
 export declare const validatePieConfigContract: (config: unknown) => PieConfigContractValidationResult;
 export declare const assertPieConfigContract: (config: unknown) => void;

package/dist/pie/config.js

@@ -6,6 +6,16 @@
 import { cloneDeep } from "../object/index.js";
 import { parsePackageName } from "./utils.js";
 import { parseVersionedTagName, toPackageVersionedTag, } from "./versioned-tag.js";
+const MARKUP_ELEMENT_ID_REGEX = /<([a-zA-Z][a-zA-Z0-9._]*-[a-zA-Z0-9._-]*)\b[^>]*?\sid\s*=\s*(["'])(.*?)\2/g;
+/** How many PIE elements in the markup carry each `id`. */
+function countMarkupElementIds(markup) {
+    const counts = new Map();
+    for (const match of markup.matchAll(MARKUP_ELEMENT_ID_REGEX)) {
+        const id = match[3] ?? "";
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+    }
+    return counts;
+}
 function collectMarkupElementTags(markup) {
     const tags = new Set();
     const tagRegex = /<\/?([a-zA-Z][a-zA-Z0-9._-]*)(?=[\t\n\f\r />])/g;
@@ -24,11 +34,13 @@ function collectMarkupElementTags(markup) {
 export const validatePieConfigContract = (config) => {
     const errors = [];
     const warnings = [];
+    const bindingWarnings = [];
     if (!config || typeof config !== "object" || Array.isArray(config)) {
         return {
             valid: false,
             errors: ["Config must be an object."],
             warnings,
+            bindingWarnings,
         };
     }
     const cfg = config;
@@ -45,7 +57,7 @@ export const validatePieConfigContract = (config) => {
         errors.push("`models` must be an array.");
     }
     if (errors.length > 0) {
-        return { valid: false, errors, warnings };
+        return { valid: false, errors, warnings, bindingWarnings };
     }
     const elementMap = elements;
     const modelList = models;
@@ -66,8 +78,21 @@ export const validatePieConfigContract = (config) => {
             errors.push(`Element "${tagName}" has invalid package spec "${packageSpec}".`);
         }
     }
+    // Ids bind models, markup elements and session entries one-to-one, and each
+    // binding takes the first match.
     const modelElementTags = new Set();
+    const modelIds = new Set();
     for (const [index, model] of modelList.entries()) {
+        const modelId = model?.id;
+        if (typeof modelId !== "string" || modelId.trim().length === 0) {
+            bindingWarnings.push(`Model at index ${index} has no valid "id", so no markup element binds to it.`);
+        }
+        else if (modelIds.has(modelId)) {
+            bindingWarnings.push(`Duplicate model id "${modelId}"; the markup element binds to the first model with it.`);
+        }
+        else {
+            modelIds.add(modelId);
+        }
         const modelElement = model?.element;
         if (typeof modelElement !== "string" || modelElement.trim().length === 0) {
             errors.push(`Model at index ${index} is missing a valid "element" reference.`);
@@ -78,6 +103,11 @@ export const validatePieConfigContract = (config) => {
             errors.push(`Model element "${modelElement}" is not declared in \`elements\`.`);
         }
     }
+    for (const [id, count] of countMarkupElementIds(markup)) {
+        if (count > 1) {
+            bindingWarnings.push(`${count} markup elements share id "${id}"; they bind to one model and one session entry.`);
+        }
+    }
     const markupElementTags = collectMarkupElementTags(markup);
     for (const tagName of markupElementTags) {
         if (!(tagName in elementMap)) {
@@ -97,6 +127,7 @@ export const validatePieConfigContract = (config) => {
         valid: errors.length === 0,
         errors,
         warnings,
+        bindingWarnings,
     };
 };
 export const assertPieConfigContract = (config) => {

package/dist/pie/index.d.ts

@@ -15,6 +15,7 @@ export type { PieElementContext, PieElementContextSource, } from "./element-obse
 export { createAuthoringAssetEventManager, initializeAuthoringConfigures, resolveConfigureConfiguration, validateAuthoringModels, } from "./authoring.js";
 export type { AuthoringMediaHandlers, AuthoringValidationResult, InitializedConfigureModel, } from "./authoring.js";
 export { initializeMathRendering, setMathRenderer, } from "./math-rendering.js";
+export type { MathRenderingOptions } from "./math-rendering.js";
 export { attachInstrumentationEventBridge } from "./instrumentation-event-bridge.js";
 export type { AttachInstrumentationEventBridgeArgs } from "./instrumentation-event-bridge.js";
 export { resolveInstrumentationProvider } from "./instrumentation-provider-resolution.js";
@@ -41,6 +42,7 @@ export { BundleType, defaultPieElementOptions, isCustomElementConstructor, isPie
 export { attemptCustomElementDefine, defineCustomElementSafely, type AttemptCustomElementDefineOptions, type SafeDefineAttempt, type SafeDefineOutcome, type SafeDefineResult, type SafeDefineStatus, } from "./custom-element-define.js";
 export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX, } from "./tag-names.js";
 export type { PieViewMode } from "./tag-names.js";
+export { runtimeElementTags } from "./versioned-tag.js";
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";
 export type { ElementOverrides } from "./overrides.js";
 export { addOrUpdateOverrideInUrl, applyElementOverrides, applyElementVersionOverridesPreserveTags, extractPackageInfo, formatElementOverrideParam, parseElementOverridesFromCurrentUrl, parseElementOverridesFromUrl, } from "./overrides.js";

package/dist/pie/index.js

@@ -44,6 +44,7 @@ isPieAvailable, isPieRegistryAvailable, Status, } from "./types.js";
 // Tag naming helpers
 export { attemptCustomElementDefine, defineCustomElementSafely, } from "./custom-element-define.js";
 export { toPrintHashedTag, toViewTag, validateCustomElementTag, VIEW_TAG_SUFFIX, } from "./tag-names.js";
+export { runtimeElementTags } from "./versioned-tag.js";
 // Updates
 export { updatePieElement, updatePieElements, updatePieElementWithRef, } from "./updates.js";
 export { addOrUpdateOverrideInUrl, applyElementOverrides, applyElementVersionOverridesPreserveTags, extractPackageInfo, formatElementOverrideParam, parseElementOverridesFromCurrentUrl, parseElementOverridesFromUrl, } from "./overrides.js";

package/dist/pie/math-rendering.d.ts

@@ -13,6 +13,16 @@ export interface MathRenderingAPI {
     unWrapMath?: (wrapped: string) => string;
     mmlToLatex?: (mathml: string) => string;
 }
+/** How the default renderer `initializeMathRendering` installs loads its assets. */
+export interface MathRenderingOptions {
+    /**
+     * The npm root the renderer's speech rules load from when the page's math
+     * options set no `assetRoot`. With neither, jsDelivr. A page that names the
+     * rules' directory itself, in `SREfeature.json` or a `text/x-sre-config`
+     * block, keeps it.
+     */
+    assetRoot?: string;
+}
 /**
  * The page's renderer: the one `initializeMathRendering` installed, or a
  * host's. IIFE elements render with it, and so do ESM elements when the page
@@ -27,6 +37,8 @@ export declare const getMathRenderer: () => MathRenderingAPI | null;
  * - window["@pie-lib/math-rendering"] (standard key)
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
  *
+ * The first call installs the renderer for the page, so its `options` apply.
+ *
  * @example
  * ```typescript
  * // Default MathJax
@@ -37,7 +49,7 @@ export declare const getMathRenderer: () => MathRenderingAPI | null;
  * await initializeMathRendering();
  * ```
  */
-export declare function initializeMathRendering(): Promise<void>;
+export declare function initializeMathRendering(options?: MathRenderingOptions): Promise<void>;
 /**
  * Set custom math renderer programmatically
  *