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

package/dist/loaders/esm-adapter.js

@@ -21,7 +21,8 @@ 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";
+import { forwardMathjaxEvents } from "./mathjax-events.js";
+import { isPlainRecord } from "../object/index.js";
 export const BUILT_IN_VIEWS = {
     delivery: { subpath: "", tagSuffix: "" },
     author: { subpath: "/author", tagSuffix: "-config", fallback: "delivery" },
@@ -41,8 +42,8 @@ export function createEsmBackend(config) {
     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();
+    /** Windows whose MathJax events this backend forwards. */
+    const mathjaxEventViews = new WeakSet();
     let sharedDependencyVersions = {};
     let importer = defaultImporter;
     let packageMetadataLoader = defaultPackageMetadataLoader;
@@ -82,7 +83,7 @@ export function createEsmBackend(config) {
         if (moduleResolution === "import-map") {
             assertImportMapSupported();
         }
-        forwardMathjaxVersionConflictsOf(context.doc);
+        forwardMathjaxEventsOf(context.doc);
         const newEntries = {};
         for (const [tag, pkg] of Object.entries(elements)) {
             const packageName = parsePackageName(pkg).name;
@@ -123,10 +124,15 @@ export function createEsmBackend(config) {
             let injectedMap;
             if (Object.keys(imports).length > 0) {
                 const json = JSON.stringify({ imports }, null, 2);
+                // URL resolution maps the shared dependencies and the editor
+                // runtime, so it needs import maps too.
                 assertImportMapSupported();
                 injectedMap = injectImportMap(json, context.doc, runtimePlan?.mappedRuntime);
                 importMapObserver?.(json, context.doc);
             }
+            // Recorded before the map settles: a load that starts meanwhile skips
+            // these packages, builds on the shared dependency versions this map
+            // fixed, and its imports wait for the map in `importModule`.
             for (const [pkg, variant] of runtimePlan?.served ?? []) {
                 editorRuntimeVariants.set(pkg, variant);
             }
@@ -152,7 +158,7 @@ export function createEsmBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 return;
             }
@@ -189,9 +195,7 @@ export function createEsmBackend(config) {
                                 kind: "module-load-failed",
                                 tag,
                                 specifier: fallbackSpecifier,
-                                cause: fallbackErr instanceof Error
-                                    ? fallbackErr.message
-                                    : String(fallbackErr),
+                                cause: errorMessage(fallbackErr),
                             });
                             return;
                         }
@@ -201,7 +205,7 @@ export function createEsmBackend(config) {
                             kind: "module-load-failed",
                             tag,
                             specifier,
-                            cause: err instanceof Error ? err.message : String(err),
+                            cause: errorMessage(err),
                         });
                         return;
                     }
@@ -225,6 +229,8 @@ export function createEsmBackend(config) {
                 return;
             }
             try {
+                // `customElements` rejects a constructor already defined under
+                // another tag, so each versioned tag gets its own subclass.
                 defineCustomElementSafely(actualTag, class extends ElementClass {
                 }, `element tag for ${packageName}`);
             }
@@ -232,35 +238,13 @@ export function createEsmBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 return;
             }
-            let controller = null;
-            if (loadControllers) {
-                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)}`);
-                    }
-                }
-                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.
-                    }
-                }
-            }
+            const controller = loadControllers
+                ? await importController(packageName, packageVersion, context.doc)
+                : null;
             writeRegistryEntry({
                 package: packageVersion,
                 status: Status.loaded,
@@ -293,6 +277,35 @@ export function createEsmBackend(config) {
             return undefined;
         }
     }
+    /**
+     * The package's controller: its editor-runtime variant's when one is served
+     * and loads, else the package's own. Controllers are best-effort; element
+     * registration is what the primitive verifies.
+     */
+    async function importController(packageName, packageVersion, doc) {
+        let controller = null;
+        const servedVariant = editorRuntimeVariants.get(packageVersion);
+        const variantController = servedVariant?.views.controller;
+        if (servedVariant && variantController) {
+            try {
+                const controllerModule = await importModule(cdnProvider.browserViewUrl(packageVersion, variantController), doc);
+                controller = controllerModule?.default ?? controllerModule;
+                if (controller)
+                    return controller;
+            }
+            catch (err) {
+                reportEditorRuntimeFallback(packageVersion, servedVariant.declaration, servedVariant.runtime, `its editor-runtime controller failed to load: ${errorMessage(err)}`);
+            }
+        }
+        const controllerSpecifier = resolveControllerSpecifier(packageName, packageVersion, moduleResolution, cdnProvider);
+        try {
+            const controllerModule = await importModule(controllerSpecifier, doc);
+            return controllerModule?.default ?? controllerModule;
+        }
+        catch {
+            return controller;
+        }
+    }
     /**
      * 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.
@@ -481,12 +494,12 @@ export function createEsmBackend(config) {
             return undefined;
         return provider;
     }
-    function forwardMathjaxVersionConflictsOf(doc) {
+    function forwardMathjaxEventsOf(doc) {
         const view = doc.defaultView;
-        if (!view || mathjaxConflictViews.has(view))
+        if (!view || mathjaxEventViews.has(view))
             return;
-        mathjaxConflictViews.add(view);
-        forwardMathjaxVersionConflicts(view, getInstrumentationProvider);
+        mathjaxEventViews.add(view);
+        forwardMathjaxEvents(view, getInstrumentationProvider);
     }
     function reportSharedDependencyConflict(attributes, message = `[pie-esm] Shared dependency version conflict resolved for ${String(attributes.dependencyName)}`) {
         if (typeof console !== "undefined" && console.warn) {
@@ -547,7 +560,8 @@ export function mapEsmViewElements(elements, view = "delivery", viewConfig) {
     ]));
 }
 function defaultImporter(specifier) {
-    // @vite-ignore — dynamic import resolved at runtime.
+    // Host bundlers must leave this import alone: the specifier is a CDN URL or
+    // import-map specifier known only at runtime.
     return import(/* webpackIgnore: true */ /* @vite-ignore */ specifier);
 }
 /**
@@ -608,6 +622,24 @@ export function resolveEsmRuntimeSupportUrl(packageVersion, options) {
         ? `${packageJsonUrl.slice(0, -"package.json".length)}${RUNTIME_SUPPORT_PATH}`
         : undefined;
 }
+/** A package the probe below names, so a provider URL ends in its `<package>@<version>` path. */
+const ROOT_PROBE_PACKAGE = "@pie-element/shared-math-rendering-mathjax@0.0.0";
+/**
+ * The npm root the ESM CDN the players load elements from serves raw package
+ * files under, `<root>/<package>@<version>/<path>`: the base URL for jsDelivr,
+ * raw.esm.sh for esm.sh, and for a custom provider whatever its
+ * `packageJsonUrl` puts before the package. `undefined` when that URL names
+ * no such root.
+ */
+export function resolveEsmAssetRoot(options) {
+    const cdnBaseUrl = options.cdnBaseUrl.replace(/\/+$/, "");
+    const provider = resolveCdnProvider(options.cdnProvider, cdnBaseUrl);
+    const suffix = `/${ROOT_PROBE_PACKAGE}/package.json`;
+    const packageJsonUrl = provider.packageJsonUrl(ROOT_PROBE_PACKAGE);
+    return packageJsonUrl.endsWith(suffix)
+        ? packageJsonUrl.slice(0, -suffix.length) || undefined
+        : undefined;
+}
 function resolveCdnProvider(provider, cdnBaseUrl) {
     if (isEsmCdnProvider(provider))
         return provider;
@@ -854,9 +886,6 @@ 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.
@@ -865,7 +894,7 @@ function readEditorRuntimeDeclaration(metadata) {
     const declared = metadata?.pie?.browserEditorRuntime;
     if (declared === undefined)
         return undefined;
-    if (!isRecord(declared) || !isRecord(declared.views))
+    if (!isPlainRecord(declared) || !isPlainRecord(declared.views))
         return null;
     const { name, version } = declared;
     if (typeof name !== "string" || !PACKAGE_NAME.test(name))
@@ -889,7 +918,7 @@ function readEditorRuntimeDeclaration(metadata) {
  */
 function readBrowserModules(metadata) {
     const declared = metadata.pie?.browserModules;
-    if (!isRecord(declared))
+    if (!isPlainRecord(declared))
         return null;
     const modules = Object.entries(declared);
     const valid = modules.length > 0 &&

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

@@ -1,7 +1,7 @@
 /**
  * IIFE backend adapter for the ElementLoader primitive.
  *
- * Loads PIE elements from IIFE bundles served by the PIE build service,
+ * Loads PIE elements from IIFE bundles served by the bundle host,
  * then registers them with `customElements`. On any per-tag failure
  * (missing package, non-constructor element class, define failure),
  * throws `AdapterFailure` with a structured `reasons` map that the
@@ -38,7 +38,7 @@ export type IifeBundleRetryStatus = {
 };
 export type IifeBackendConfig = {
     kind: "iife";
-    /** Base URL for the PIE bundle service. */
+    /** Base URL of the bundle host. */
     bundleHost: string;
     /** Bundle variant to request (player / client-player / editor). */
     bundleType?: BundleType;
@@ -54,7 +54,7 @@ export type IifeBackendConfig = {
     /**
      * Retry policy for transient bundle load failures.
      *
-     * When the bundle service is building a bundle on demand, the first
+     * When the bundle host is building a bundle on demand, the first
      * few `<script src>` requests can fail. This policy polls until the
      * bundle is available or `timeoutMs` elapses. Default matches
      * `DEFAULT_IIFE_BUNDLE_RETRY_CONFIG`.

package/dist/loaders/iife-adapter.js

@@ -1,7 +1,7 @@
 /**
  * IIFE backend adapter for the ElementLoader primitive.
  *
- * Loads PIE elements from IIFE bundles served by the PIE build service,
+ * Loads PIE elements from IIFE bundles served by the bundle host,
  * then registers them with `customElements`. On any per-tag failure
  * (missing package, non-constructor element class, define failure),
  * throws `AdapterFailure` with a structured `reasons` map that the
@@ -76,7 +76,7 @@ export function createIifeBackend(config) {
     /**
      * Wrap the single-shot script loader with poll-until-ready retry.
      *
-     * The PIE bundle service may return a transient failure while it
+     * The bundle host may return a transient failure while it
      * builds a bundle on demand. Retry with fixed-interval polling until
      * the bundle is ready or the cumulative deadline elapses. Emits
      * retry lifecycle events to the host via `onBundleRetryStatus` and to
@@ -111,7 +111,7 @@ export function createIifeBackend(config) {
             catch (error) {
                 const elapsedMs = Date.now() - startedAt;
                 const remainingMs = timeoutMs - elapsedMs;
-                const reason = error instanceof Error ? error.message : String(error);
+                const reason = errorMessage(error);
                 if (remainingMs <= 0) {
                     const timeoutError = new Error(`IIFE bundle load timed out after ${timeoutMs}ms: ${url}`);
                     config.onBundleRetryStatus?.({
@@ -201,45 +201,33 @@ export function createIifeBackend(config) {
             return;
         const conflict = findIifeElementMapConflict(elements);
         if (conflict) {
-            const reasons = new Map();
-            for (const tag of Object.keys(elements)) {
-                reasons.set(tag, {
-                    kind: "backend-rejected",
-                    tag,
-                    cause: conflict,
-                });
-            }
-            throw new AdapterFailure(reasons);
+            throw failureForEveryTag(elements, (tag) => ({
+                kind: "backend-rejected",
+                tag,
+                cause: conflict,
+            }));
         }
         const bundleUrl = buildBundleUrl(elements, bundleType, config);
         try {
             await ensureBundleLoaded(bundleUrl, context.doc);
         }
         catch (err) {
-            const cause = err instanceof Error ? err.message : String(err);
-            const reasons = new Map();
-            for (const tag of Object.keys(elements)) {
-                reasons.set(tag, {
-                    kind: "bundle-load-failed",
-                    tag,
-                    url: bundleUrl,
-                    cause,
-                });
-            }
-            throw new AdapterFailure(reasons);
+            const cause = errorMessage(err);
+            throw failureForEveryTag(elements, (tag) => ({
+                kind: "bundle-load-failed",
+                tag,
+                url: bundleUrl,
+                cause,
+            }));
         }
         const pieModule = readPieModule();
         if (!pieModule) {
-            const reasons = new Map();
-            for (const tag of Object.keys(elements)) {
-                reasons.set(tag, {
-                    kind: "bundle-load-failed",
-                    tag,
-                    url: bundleUrl,
-                    cause: "window.pie.default missing after bundle load",
-                });
-            }
-            throw new AdapterFailure(reasons);
+            throw failureForEveryTag(elements, (tag) => ({
+                kind: "bundle-load-failed",
+                tag,
+                url: bundleUrl,
+                cause: "window.pie.default missing after bundle load",
+            }));
         }
         const reasons = new Map();
         const isEditorBundle = bundleType === BundleType.editor;
@@ -282,11 +270,13 @@ export function createIifeBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 continue;
             }
             try {
+                // `customElements` rejects a constructor already defined under
+                // another tag, so each versioned tag gets its own subclass.
                 defineCustomElementSafely(actualTag, class extends ElementClass {
                 }, `element tag for ${packageName}`);
             }
@@ -294,7 +284,7 @@ export function createIifeBackend(config) {
                 reasons.set(tag, {
                     kind: "define-failed",
                     tag,
-                    cause: err instanceof Error ? err.message : String(err),
+                    cause: errorMessage(err),
                 });
                 continue;
             }
@@ -320,6 +310,17 @@ export function createIifeBackend(config) {
     };
 }
 // ─── Helpers ─────────────────────────────────────────────────────────────────
+/** A failure of the whole request, reported once per tag. */
+function failureForEveryTag(elements, reasonFor) {
+    const reasons = new Map();
+    for (const tag of Object.keys(elements)) {
+        reasons.set(tag, reasonFor(tag));
+    }
+    return new AdapterFailure(reasons);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 function defaultLoadBundleScript(url, doc) {
     return new Promise((resolve, reject) => {
         const script = doc.createElement("script");

package/dist/loaders/index.d.ts

@@ -37,12 +37,14 @@ export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./elem
 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, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, 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";
 export { createIifeBackend } from "./iife-adapter.js";
 export { resolveLoadControllers } from "./controller-loading.js";
-export type { PreloadedController, PreloadedElement, } from "./preloaded-registration.js";
+export type { PreloadedController, PreloadedElement, PreloadedRegistrationOptions, } from "./preloaded-registration.js";
+export type { MathAssetOptions } from "../pie/math-assets.js";
 export { registerPreloadedElements } from "./preloaded-registration.js";
 export type { PreloadedElementSpecs } from "./preloaded-alignment.js";
 export { alignPreloadedElementVersions } from "./preloaded-alignment.js";

package/dist/loaders/index.js

@@ -33,7 +33,8 @@
 export { aggregateElements } from "./ElementLoader.js";
 export { assertElementPackagesAllowed, ElementPackagePolicyError, } from "./element-package-policy.js";
 export { AdapterFailure, ElementAssertionError, ElementLoaderError, assertRegistered, describeRegistrationFailures, ensureRegistered, } from "./element-loader.js";
-export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmRuntimeSupportUrl, } from "./esm-adapter.js";
+export { BUILT_IN_VIEWS, createEsmBackend, mapEsmViewElements, resolveEsmAssetRoot, 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";
 export { resolveLoadControllers } from "./controller-loading.js";

package/dist/loaders/mathjax-events.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Forwards the MathJax adapter's page events to instrumentation.
+ *
+ * Every copy of the MathJax 4 adapter that browser ESM elements render with
+ * dispatches these on `window`, once per condition per page:
+ * `pie-mathjax-version-conflict` when MathJax 3 runs on the same page — an
+ * unsupported page, see
+ * docs/item-player/loading-strategies.md#one-mathjax-version-per-page — and
+ * `pie-mathjax-no-asset-root` when a copy has nowhere to load MathJax's files
+ * from, see docs/item-player/loading-strategies.md#mathjax-assets. The event
+ * names are repeated here because players do not depend on the element
+ * packages.
+ */
+import type { InstrumentationProvider } from "../instrumentation/types.js";
+export declare const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
+export declare const MATHJAX_NO_ASSET_ROOT_EVENT = "pie-mathjax-no-asset-root";
+/**
+ * Tracks each MathJax event on `target` with the provider `getProvider`
+ * returns when it fires, once per provider. Returns the function that stops
+ * forwarding.
+ */
+export declare function forwardMathjaxEvents(target: EventTarget, getProvider: () => InstrumentationProvider | undefined): () => void;

package/dist/loaders/mathjax-events.js

@@ -0,0 +1,65 @@
+/**
+ * Forwards the MathJax adapter's page events to instrumentation.
+ *
+ * Every copy of the MathJax 4 adapter that browser ESM elements render with
+ * dispatches these on `window`, once per condition per page:
+ * `pie-mathjax-version-conflict` when MathJax 3 runs on the same page — an
+ * unsupported page, see
+ * docs/item-player/loading-strategies.md#one-mathjax-version-per-page — and
+ * `pie-mathjax-no-asset-root` when a copy has nowhere to load MathJax's files
+ * from, see docs/item-player/loading-strategies.md#mathjax-assets. The event
+ * names are repeated here because players do not depend on the element
+ * packages.
+ */
+export const MATHJAX_VERSION_CONFLICT_EVENT = "pie-mathjax-version-conflict";
+export const MATHJAX_NO_ASSET_ROOT_EVENT = "pie-mathjax-no-asset-root";
+/** The detail fields each event is tracked with. */
+const TRACKED_FIELDS = {
+    [MATHJAX_VERSION_CONFLICT_EVENT]: ["condition", "docsUrl"],
+    [MATHJAX_NO_ASSET_ROOT_EVENT]: ["effect", "docsUrl"],
+};
+// Every player on a page listens, and each player bundle carries its own copy
+// of this module, so the providers that tracked an event are kept on the page.
+const TRACKED = Symbol.for("@pie-players/pie-players-shared/mathjax-version-conflict-tracked");
+function providersThatTracked(event) {
+    const registry = globalThis;
+    registry[TRACKED] ??= new WeakMap();
+    let providers = registry[TRACKED].get(event);
+    if (!providers) {
+        providers = new WeakSet();
+        registry[TRACKED].set(event, providers);
+    }
+    return providers;
+}
+/**
+ * Tracks each MathJax event on `target` with the provider `getProvider`
+ * returns when it fires, once per provider. Returns the function that stops
+ * forwarding.
+ */
+export function forwardMathjaxEvents(target, getProvider) {
+    const forward = (event) => {
+        const provider = getProvider();
+        if (!provider)
+            return;
+        const tracked = providersThatTracked(event);
+        if (tracked.has(provider))
+            return;
+        tracked.add(provider);
+        const detail = event.detail;
+        const fields = (detail && typeof detail === "object" ? detail : {});
+        try {
+            provider.trackEvent(event.type, Object.fromEntries(TRACKED_FIELDS[event.type].map((field) => [field, fields[field]])));
+        }
+        catch {
+            // Swallow: instrumentation must never break rendering.
+        }
+    };
+    for (const type of Object.keys(TRACKED_FIELDS)) {
+        target.addEventListener(type, forward);
+    }
+    return () => {
+        for (const type of Object.keys(TRACKED_FIELDS)) {
+            target.removeEventListener(type, forward);
+        }
+    };
+}

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

@@ -15,7 +15,12 @@
  * 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
  * each tag it renders without one.
+ *
+ * Bundled by the host, the elements' copies of the MathJax adapter find no npm
+ * root in their module URLs, so the registration also takes where they load
+ * MathJax's fonts and speech from (`options.math`): a root, or each file's URL.
  */
+import { type MathAssetOptions } from "../pie/math-assets.js";
 /** A controller module: the `model()` a player that is not hosted runs. */
 export type PreloadedController = {
     readonly model: (...args: any[]) => unknown;
@@ -43,6 +48,16 @@ export interface PreloadedElement {
         readonly default: PreloadedController;
     };
 }
+export interface PreloadedRegistrationOptions {
+    /**
+     * Where the elements' MathJax loads its fonts, its speech worker and, on the
+     * adapter's npm build, MathJax itself from, and whether math is in the tab
+     * order, written to `window['@pie-lib/math-rendering@2'].opts`. With neither
+     * an `assetRoot` nor the fonts in `assetUrls`, math renders without web fonts
+     * and speech.
+     */
+    math?: MathAssetOptions;
+}
 /**
  * Register host-bundled elements for the `preloaded` strategy.
  *
@@ -51,6 +66,7 @@ export interface PreloadedElement {
  * registry entry, which only gains a controller it lacked. Every entry is
  * validated before any is registered. A package registers at one version per
  * page, because the players align every authored version of a package to the
- * registered one.
+ * registered one. `options.math` replaces the page's math asset options it
+ * sets, and keeps the others.
  */
-export declare function registerPreloadedElements(elements: readonly PreloadedElement[]): void;
+export declare function registerPreloadedElements(elements: readonly PreloadedElement[], options?: PreloadedRegistrationOptions): void;

package/dist/loaders/preloaded-registration.js

@@ -15,8 +15,13 @@
  * 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
  * each tag it renders without one.
+ *
+ * Bundled by the host, the elements' copies of the MathJax adapter find no npm
+ * root in their module URLs, so the registration also takes where they load
+ * MathJax's fonts and speech from (`options.math`): a root, or each file's URL.
  */
 import { defineCustomElementSafely } from "../pie/custom-element-define.js";
+import { mathAssetOptionsError, setMathAssetOptions, } from "../pie/math-assets.js";
 import { writeRegistryEntry } from "../pie/registry.js";
 import { BundleType, isCustomElementConstructor, Status } from "../pie/types.js";
 import { parsePackageName } from "../pie/utils.js";
@@ -31,15 +36,22 @@ import { pickElementClass } from "./esm-adapter.js";
  * registry entry, which only gains a controller it lacked. Every entry is
  * validated before any is registered. A package registers at one version per
  * page, because the players align every authored version of a package to the
- * registered one.
+ * registered one. `options.math` replaces the page's math asset options it
+ * sets, and keeps the others.
  */
-export function registerPreloadedElements(elements) {
+export function registerPreloadedElements(elements, options = {}) {
     if (typeof window === "undefined" || typeof customElements === "undefined") {
         throw new Error("[registerPreloadedElements] requires a browser with customElements");
     }
     const preloaded = preloadedPackageSpecs();
     const resolved = elements.map(resolveElement);
     assertOneVersionPerPackage(resolved, preloaded);
+    const mathError = options.math === undefined ? undefined : mathAssetOptionsError(options.math);
+    if (mathError) {
+        throw new Error(`[registerPreloadedElements] options.math: ${mathError}`);
+    }
+    if (options.math)
+        setMathAssetOptions(options.math);
     for (const { packageName, spec, tagName, elementClass, controller } of resolved) {
         defineCustomElementSafely(tagName, class extends elementClass {
         }, `preloaded element tag for ${packageName}`);

package/dist/media/index.d.ts

@@ -2,12 +2,10 @@
  * Validation primitives shared by every catalog card whose payload references
  * media.
  *
- * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
- * audio form: both card types take authored, wire-facing URLs and hand them to a
- * media element in the learner's browser, so both need the same scheme
- * allow-list and the same "treat as absent, never as partially valid" posture.
- * Two copies of a URL allow-list is one copy that gets a fix and one that does
- * not.
+ * `sign-language` and recorded `spoken` cards both hand authored, wire-facing
+ * URLs to a media element in the learner's browser, so both take the same
+ * scheme allow-list and the same "treat as absent, never as partially valid"
+ * posture from here.
  *
  * Lives here, behind its own subpath, so a PIE element can validate authored
  * media without importing the assessment toolkit, whose root entry declares

package/dist/media/index.js

@@ -2,12 +2,10 @@
  * Validation primitives shared by every catalog card whose payload references
  * media.
  *
- * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
- * audio form: both card types take authored, wire-facing URLs and hand them to a
- * media element in the learner's browser, so both need the same scheme
- * allow-list and the same "treat as absent, never as partially valid" posture.
- * Two copies of a URL allow-list is one copy that gets a fix and one that does
- * not.
+ * `sign-language` and recorded `spoken` cards both hand authored, wire-facing
+ * URLs to a media element in the learner's browser, so both take the same
+ * scheme allow-list and the same "treat as absent, never as partially valid"
+ * posture from here.
  *
  * Lives here, behind its own subpath, so a PIE element can validate authored
  * media without importing the assessment toolkit, whose root entry declares
@@ -21,7 +19,7 @@
  * Relative and protocol-relative URLs are allowed — host content is commonly
  * served from the same origin as the player.
  */
-const DISALLOWED_SRC_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const URL_SCHEME_PREFIX = /^[a-z][a-z0-9+.-]*:/i;
 const ALLOWED_SRC_SCHEMES = new Set(["http:", "https:", "data:", "blob:"]);
 /**
  * The only `MediaAssetRef.version` this build renders.
@@ -53,7 +51,7 @@ export function isSafeMediaSrc(raw) {
         return false;
     // Relative ("/video.mp4", "video.mp4") and protocol-relative ("//cdn/x.mp4")
     // forms carry no scheme to check and inherit the document's.
-    if (src.startsWith("//") || !DISALLOWED_SRC_SCHEME.test(src))
+    if (src.startsWith("//") || !URL_SCHEME_PREFIX.test(src))
         return true;
     const scheme = src.slice(0, src.indexOf(":") + 1).toLowerCase();
     return ALLOWED_SRC_SCHEMES.has(scheme);