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

package/dist/pie/initialization.js

@@ -11,7 +11,7 @@ import { editorPostFix } from "../types/index.js";
 import { initializePieElement } from "./initialize-element.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { initializeMathRendering } from "./math-rendering.js";
-import { pieRegistry } from "./registry.js";
+import { pieRegistry, writeRegistryEntry } from "./registry.js";
 import { defineCustomElementSafely } from "./custom-element-define.js";
 import { validateCustomElementTag } from "./tag-names.js";
 import { BundleType, isCustomElementConstructor, isPieAvailable, Status, } from "./types.js";
@@ -38,6 +38,7 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
         config,
         session,
         ...(omitEnv ? {} : { env: options.env }),
+        bundleType: options.bundleType,
         container: options.container,
         ...(options.eventListeners?.[elementTagName] && {
             eventListeners: options.eventListeners[elementTagName],
@@ -119,30 +120,21 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                 : [],
             bundleType: options.bundleType,
         });
-        // Validate controller presence based on bundle type
-        if (!elementData.controller) {
-            if (options.bundleType === BundleType.clientPlayer) {
-                logger.error(`[registerPieElementsFromBundle] ❌ CRITICAL: No controller found for ${pkgStripped}!`);
-                logger.error(`[registerPieElementsFromBundle] Bundle type: ${options.bundleType} (controllers required)`);
-                throw new Error(`No controller found for ${pkgStripped}. client-player.js bundles MUST include controllers!`);
-            }
-            else {
-                logger.debug(`[registerPieElementsFromBundle] ℹ️ No controller found for ${pkgStripped} - using server-processed models (player.js bundle)`);
-            }
-        }
         {
-            // Register the element in our registry
+            // Register the element in our registry. A package without a
+            // controller, such as a legacy `@pie-element/protractor`, renders
+            // the model it is given under client-player.js too.
             logger.debug(`[registerPieElementsFromBundle] Registering ${elName} in registry${elementData.controller
                 ? " with controller"
-                : " (no controller - server-processed models)"}`);
-            registry[elementTagName] = {
+                : " (no controller; its model is used as given)"}`);
+            writeRegistryEntry({
                 package: pkg,
                 status: Status.loading,
                 tagName: elementTagName,
                 controller: elementData.controller || null,
                 config: elementData.config,
                 bundleType: options.bundleType,
-            };
+            });
             if (isCustomElementConstructor(elementData.Element)) {
                 defineCustomElementSafely(elementTagName, elementData.Element, `element tag in config.elements for ${String(pkg)}`);
                 // Initialize existing elements
@@ -155,13 +147,13 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                         session,
                         env: options.env,
                         eventListeners: options.eventListeners?.[elementTagName],
+                        bundleType: options.bundleType,
                     });
                 });
-                // Update registry status
-                registry[elementTagName] = {
+                writeRegistryEntry({
                     ...registry[elementTagName],
                     status: Status.loaded,
-                };
+                });
                 promises.push(customElements.whenDefined(elementTagName).then(() => {
                     logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
                 }));
@@ -297,9 +289,8 @@ export const loadPieModule = async (config, session, opts = {}) => {
                 }
                 catch (error) {
                     // `registerPieElementsFromBundle` throws synchronously for a
-                    // package missing from the bundle and for a client-player
-                    // bundle with no controller. Inside a DOM event handler that
-                    // throw reaches the window instead of the caller.
+                    // package missing from the bundle. Inside a DOM event handler
+                    // that throw reaches the window instead of the caller.
                     fail(error instanceof Error ? error : new Error(String(error)));
                 }
             });

package/dist/pie/initialize-element.d.ts

@@ -6,6 +6,7 @@
  */
 import type { ConfigEntity, Env } from "../types/index.js";
 import type { EventListeners, PieElement } from "./types.js";
+import { BundleType } from "./types.js";
 /**
  * Bind `element` to the model in `options.config` whose `id` matches it.
  *
@@ -20,4 +21,6 @@ export declare const initializePieElement: (element: PieElement, options: {
     session: any[];
     env?: Env;
     eventListeners?: EventListeners;
+    /** The delivering player's bundle type, see `findPieController`. */
+    bundleType?: BundleType;
 }) => boolean;

package/dist/pie/initialize-element.js

@@ -4,7 +4,6 @@
  * Split out of `initialization.ts` so the late-arrival observer in
  * `element-observer.ts` can reuse it without importing the bundle loaders.
  */
-import { wrapModelRichContent } from "../security/wrap-model-rich-content.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { pieRegistry } from "./registry.js";
 import { findPieController } from "./scoring.js";
@@ -21,7 +20,7 @@ const logger = createPieLogger("pie-initialize-element", () => isGlobalDebugEnab
  * separately — uses that to stop at the config the element belongs to.
  */
 export const initializePieElement = (element, options) => {
-    const { config, session, env, eventListeners } = options;
+    const { config, session, env, eventListeners, bundleType } = options;
     if (element.__pieInitialized) {
         return true;
     }
@@ -45,7 +44,7 @@ export const initializePieElement = (element, options) => {
     element.__pieInitialized = true;
     logger.debug(`[initializePieElement] Session set for ${tagName}#${element.id}:`, elementSession);
     // Set model - use controller if available (client-player.js), or use server-processed model (player.js)
-    const controller = findPieController(tagName);
+    const controller = findPieController(tagName, bundleType);
     if (!env) {
         logger.error(`[initializePieElement] ❌ FATAL: No env provided for ${tagName}`);
         throw new Error(`No env provided for ${tagName}. PIE elements require an env object with mode and role.`);
@@ -61,7 +60,7 @@ export const initializePieElement = (element, options) => {
             role: env.role,
         });
         // Set model directly - server already processed it
-        element.model = wrapModelRichContent(model);
+        element.model = model;
     }
     else {
         // Controller available - run client-side processing (client-player.js bundle)

package/dist/pie/instrumentation-event-map.js

@@ -37,7 +37,8 @@ export const SECTION_INSTRUMENTATION_EVENT_MAP = [
     // instrumentation bridge forwards the same names to telemetry. The
     // readiness alias mappings (`readiness-change`, `interaction-ready`,
     // `ready`) and the `section-controller-ready` mapping were removed
-    // alongside their DOM-event surfaces.
+    // alongside their DOM-event surfaces. `session-changed` stays off the
+    // bridge for the reason the item map gives below.
     {
         sourceEventName: "pie-stage-change",
         instrumentationEventName: "pie-section-stage-change",
@@ -46,14 +47,6 @@ export const SECTION_INSTRUMENTATION_EVENT_MAP = [
         sourceEventName: "pie-loading-complete",
         instrumentationEventName: "pie-section-loading-complete",
     },
-    {
-        sourceEventName: "session-changed",
-        instrumentationEventName: "pie-section-session-changed",
-    },
-    {
-        sourceEventName: "composition-changed",
-        instrumentationEventName: "pie-section-composition-changed",
-    },
     {
         sourceEventName: "framework-error",
         instrumentationEventName: "pie-section-framework-error",

package/dist/pie/instrumentation-provider-resolution.d.ts

@@ -1,6 +1,7 @@
+import type { InstrumentationProvider } from "../instrumentation/types.js";
 export declare function resolveInstrumentationProvider(args: {
     runtimePlayer?: unknown;
     player?: unknown;
     debug?: boolean;
     component?: string;
-}): unknown;
+}): InstrumentationProvider | undefined;

package/dist/pie/instrumentation-provider-resolution.js

@@ -37,7 +37,6 @@ const logger = createPieLogger("instrumentation-provider-resolution", () => isGl
 function getDefaultInstrumentationProvider() {
     if (!defaultProvider) {
         defaultProvider = new NewRelicInstrumentationProvider();
-        // New Relic provider sets readiness based on window.newrelic.
         void defaultProvider.initialize();
     }
     return defaultProvider;

package/dist/pie/item-session-contract.d.ts

@@ -1,3 +1,4 @@
+import type { SessionCommitReason } from "./session-commit.js";
 export type ItemSessionContainer = {
     id: string;
     data: unknown[];
@@ -8,7 +9,14 @@ export type NormalizedItemSessionChange = {
     session: ItemSessionContainer | null;
     intent: ItemSessionUpdateIntent;
     component?: string;
+    /**
+     * The id of the element whose change this is: the detail's `elementId`, or
+     * the `id` of an element session record carried as `session`.
+     */
+    elementId?: string;
     complete?: boolean;
+    /** The detail's `sessionCommitReason`, when the change is a commit. */
+    sessionCommitReason?: SessionCommitReason;
 };
 export declare function normalizeItemSessionContainer(input: unknown, fallbackSessionId?: string): ItemSessionContainer;
 export declare function hasResponseValue(value: unknown): boolean;

package/dist/pie/item-session-contract.js

@@ -2,6 +2,7 @@ const DEFAULT_SESSION_ID = "";
 const METADATA_ONLY_SESSION_KEYS = new Set([
     "complete",
     "component",
+    "elementId",
     "timestamp",
     "sourceRuntimeId",
 ]);
@@ -162,6 +163,18 @@ function getMetadataComplete(sessionDetail, candidate) {
         return candidate.complete;
     return undefined;
 }
+/**
+ * `elementRecord` is an element's own session record, whose `id` is the
+ * element's; an item session container's `id` is the item session's.
+ */
+function withElementId(sessionDetail, elementRecord) {
+    const elementId = typeof sessionDetail.elementId === "string" && sessionDetail.elementId
+        ? sessionDetail.elementId
+        : typeof elementRecord?.id === "string" && elementRecord.id
+            ? elementRecord.id
+            : undefined;
+    return elementId ? { elementId } : {};
+}
 function isElementIdentityOnlyPayload(candidate) {
     const candidateKeys = Object.keys(candidate);
     const hasIdentityKey = "id" in candidate || "element" in candidate;
@@ -211,6 +224,14 @@ export function mergeElementIntoSession(itemId, previousItemSession, entryId, en
     };
 }
 export function normalizeItemSessionChange(args) {
+    const change = classifyItemSessionChange(args);
+    const reason = args.sessionDetail
+        ?.sessionCommitReason;
+    return typeof reason === "string" && reason
+        ? { ...change, sessionCommitReason: reason }
+        : change;
+}
+function classifyItemSessionChange(args) {
     const sessionDetail = (args.sessionDetail || {});
     const actualSession = sessionDetail &&
         typeof sessionDetail === "object" &&
@@ -229,6 +250,7 @@ export function normalizeItemSessionChange(args) {
             session: null,
             intent: "metadata-only",
             component: getMetadataComponent(sessionDetail),
+            ...withElementId(sessionDetail),
             complete: getMetadataComplete(sessionDetail),
         };
     }
@@ -241,11 +263,7 @@ export function normalizeItemSessionChange(args) {
         const previousForMetadataComparison = alignPreviousSessionIdForRendererSnapshot(normalizedCandidate, previousNormalized);
         const sessionDetailKeys = Object.keys(sessionDetail);
         const metadataWithSessionOnly = sessionDetailKeys.length > 0 &&
-            sessionDetailKeys.every((key) => key === "session" ||
-                key === "complete" ||
-                key === "component" ||
-                key === "timestamp" ||
-                key === "sourceRuntimeId");
+            sessionDetailKeys.every((key) => key === "session" || METADATA_ONLY_SESSION_KEYS.has(key));
         const hasMetadataBeyondSession = sessionDetailKeys.some((key) => key !== "session");
         if (metadataWithSessionOnly &&
             hasMetadataBeyondSession &&
@@ -256,6 +274,7 @@ export function normalizeItemSessionChange(args) {
                 session: null,
                 intent: "metadata-only",
                 component: getMetadataComponent(sessionDetail),
+                ...withElementId(sessionDetail),
                 complete: getMetadataComplete(sessionDetail),
             };
         }
@@ -266,6 +285,7 @@ export function normalizeItemSessionChange(args) {
                 session: null,
                 intent: "metadata-only",
                 component: getMetadataComponent(sessionDetail),
+                ...withElementId(sessionDetail),
                 complete: getMetadataComplete(sessionDetail),
             };
         }
@@ -274,21 +294,20 @@ export function normalizeItemSessionChange(args) {
             session: normalizedCandidate,
             intent: "replace-item-session",
             component: getMetadataComponent(sessionDetail),
+            ...withElementId(sessionDetail),
             complete: getMetadataComplete(sessionDetail),
         };
     }
     const candidateKeys = Object.keys(candidate);
     const isMetadataOnlyPayload = candidateKeys.length > 0 &&
-        candidateKeys.every((key) => key === "complete" ||
-            key === "component" ||
-            key === "timestamp" ||
-            key === "sourceRuntimeId");
+        candidateKeys.every((key) => METADATA_ONLY_SESSION_KEYS.has(key));
     if (isMetadataOnlyPayload) {
         return {
             itemId: safeItemId,
             session: null,
             intent: "metadata-only",
             component: getMetadataComponent(sessionDetail, candidate),
+            ...withElementId(sessionDetail),
             complete: getMetadataComplete(sessionDetail, candidate),
         };
     }
@@ -298,6 +317,7 @@ export function normalizeItemSessionChange(args) {
             session: null,
             intent: "metadata-only",
             component: getMetadataComponent(sessionDetail, candidate),
+            ...withElementId(sessionDetail, candidate),
             complete: getMetadataComplete(sessionDetail, candidate),
         };
     }
@@ -309,6 +329,7 @@ export function normalizeItemSessionChange(args) {
         session: merged,
         intent: "merge-element-session",
         component,
+        ...withElementId(sessionDetail, candidate),
         complete: getMetadataComplete(sessionDetail, candidate),
     };
 }

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

@@ -0,0 +1,20 @@
+/**
+ * Math in an item's own markup: what the item and passage markup carry outside
+ * every PIE element.
+ *
+ * Each element typesets its own subtree, so the player hands its renderer only
+ * the markup around them. A renderer finds math below the element it is given,
+ * so no root holds a PIE element: the markup splits into the elements that hold
+ * none, and math sharing a parent with one is wrapped in a span of its own.
+ */
+import type { MathRenderer } from "./math-rendering.js";
+/**
+ * The parts of `container` holding math and no PIE element, each one a root to
+ * typeset. `pieTags` are the tag names of the PIE elements its markup places.
+ */
+export declare function collectMarkupMathRoots(container: HTMLElement, pieTags: ReadonlySet<string>): HTMLElement[];
+/**
+ * Typesets the math in `containers` outside every PIE element with `render`,
+ * one root at a time.
+ */
+export declare function typesetMarkupMath(containers: Iterable<HTMLElement>, pieTags: ReadonlySet<string>, render: MathRenderer): Promise<void>;

package/dist/pie/markup-math.js

@@ -0,0 +1,118 @@
+/**
+ * Math in an item's own markup: what the item and passage markup carry outside
+ * every PIE element.
+ *
+ * Each element typesets its own subtree, so the player hands its renderer only
+ * the markup around them. A renderer finds math below the element it is given,
+ * so no root holds a PIE element: the markup splits into the elements that hold
+ * none, and math sharing a parent with one is wrapped in a span of its own.
+ */
+/** TeX as `@pie-element/shared-math-rendering-mathjax` detects it. */
+const TEX = /\\\(|\\\[|\$\$|\\\$|\\begin\{|\\(?:eq)?ref\{/;
+/** The same, with `$…$` inline math turned on by the legacy opt-in. */
+const TEX_WITH_SINGLE_DOLLAR = /\\\(|\\\[|\$|\\begin\{|\\(?:eq)?ref\{/;
+/** Elements whose content MathJax leaves alone, as both PIE configurations list them. */
+const SKIPPED_ELEMENTS = new Set([
+    "script",
+    "noscript",
+    "style",
+    "textarea",
+    "pre",
+    "code",
+    "annotation",
+    "annotation-xml",
+    "mjx-container",
+    "mjx-assistive-mml",
+]);
+/** The class an author marks content with to keep MathJax out of it. */
+const IGNORED_CLASS = /(?:^|\s)mathjax_ignore(?:\s|$)/;
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+function texPattern() {
+    const legacy = globalThis["@pie-lib/math-rendering@2"];
+    return legacy?.opts?.useSingleDollar ? TEX_WITH_SINGLE_DOLLAR : TEX;
+}
+function isSkipped(element) {
+    return (SKIPPED_ELEMENTS.has(element.localName) ||
+        IGNORED_CLASS.test(element.getAttribute("class") ?? ""));
+}
+/** Math a renderer would only find on `element` itself, never below it. */
+function holdsOwnMath(element) {
+    return (element.localName === "math" ||
+        (element.hasAttribute("data-latex") &&
+            !element.hasAttribute("data-math-handled")));
+}
+function holdsMath(element, tex) {
+    if (holdsOwnMath(element) ||
+        element.querySelector("[data-latex]:not([data-math-handled])")) {
+        return true;
+    }
+    for (const math of element.getElementsByTagName("math")) {
+        if (!math.closest("mjx-assistive-mml"))
+            return true;
+    }
+    return tex.test(element.textContent ?? "");
+}
+function wrapInSpan(node) {
+    const span = (node.ownerDocument ?? document).createElement("span");
+    node.replaceWith(span);
+    span.append(node);
+    return span;
+}
+/**
+ * The parts of `container` holding math and no PIE element, each one a root to
+ * typeset. `pieTags` are the tag names of the PIE elements its markup places.
+ */
+export function collectMarkupMathRoots(container, pieTags) {
+    const tex = texPattern();
+    const holdsPie = new Set();
+    for (const tag of pieTags) {
+        for (const element of container.getElementsByTagName(tag)) {
+            for (let ancestor = element.parentElement; ancestor && !holdsPie.has(ancestor); ancestor = ancestor.parentElement) {
+                holdsPie.add(ancestor);
+                if (ancestor === container)
+                    break;
+            }
+        }
+    }
+    if (!holdsPie.has(container)) {
+        return holdsMath(container, tex) ? [container] : [];
+    }
+    const roots = [];
+    const visit = (parent) => {
+        for (const child of [...parent.childNodes]) {
+            if (child.nodeType === Node.TEXT_NODE) {
+                if (tex.test(child.data))
+                    roots.push(wrapInSpan(child));
+                continue;
+            }
+            if (child.nodeType !== Node.ELEMENT_NODE)
+                continue;
+            const element = child;
+            if (pieTags.has(element.localName) || isSkipped(element))
+                continue;
+            if (holdsPie.has(element)) {
+                visit(element);
+            }
+            else if (holdsMath(element, tex)) {
+                if (holdsOwnMath(element)) {
+                    roots.push(wrapInSpan(element));
+                }
+                else if (element.namespaceURI === HTML_NAMESPACE) {
+                    roots.push(element);
+                }
+            }
+        }
+    };
+    visit(container);
+    return roots;
+}
+/**
+ * Typesets the math in `containers` outside every PIE element with `render`,
+ * one root at a time.
+ */
+export async function typesetMarkupMath(containers, pieTags, render) {
+    const roots = [...containers].flatMap((container) => collectMarkupMathRoots(container, pieTags));
+    for (const root of roots) {
+        await render(root);
+    }
+}

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

@@ -4,7 +4,7 @@
  * PIE elements expect @pie-lib/math-rendering to be available on window.
  * This module ensures required globals are populated from the upstream
  * @pie-lib/math-rendering-module package, and also supports overriding with
- * a custom renderer object when needed.
+ * a custom renderer object through setMathRenderer().
  */
 export type MathRenderer = (element: HTMLElement) => void | Promise<void>;
 export interface MathRenderingAPI {
@@ -14,32 +14,30 @@ export interface MathRenderingAPI {
     mmlToLatex?: (mathml: string) => string;
 }
 /**
- * Initialize math rendering with optional custom renderer
- *
- * If no custom renderer is provided, defaults to MathJax.
+ * 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
+ * has one.
+ */
+export declare const getMathRenderer: () => MathRenderingAPI | null;
+/**
+ * Initialize math rendering, defaulting to MathJax.
  * For custom renderers, use setMathRenderer() before calling this function.
  *
  * Sets TWO window globals that PIE elements expect:
  * - window["@pie-lib/math-rendering"] (standard key)
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
  *
- * @param customRenderer - Optional custom renderer to use instead of default MathJax
- *
  * @example
  * ```typescript
  * // Default MathJax
  * await initializeMathRendering();
  *
- * // Custom renderer instance implementing MathRenderingAPI
- * const customRenderer = await createCustomRenderer();
- * await initializeMathRendering(customRenderer);
- *
- * // Or use setMathRenderer first
+ * // Custom renderer: install it first
  * setMathRenderer(katexRenderer);
  * await initializeMathRendering();
  * ```
  */
-export declare function initializeMathRendering(customRenderer?: MathRenderingAPI): Promise<void>;
+export declare function initializeMathRendering(): Promise<void>;
 /**
  * Set custom math renderer programmatically
  *
@@ -60,12 +58,3 @@ export declare function initializeMathRendering(customRenderer?: MathRenderingAP
  * ```
  */
 export declare function setMathRenderer(renderer: MathRenderingAPI): void;
-/**
- * Render math in the given element
- *
- * Convenience wrapper that calls the active renderer's renderMath() function.
- * Typically called after PIE elements are rendered.
- *
- * @param element - The element to render math within
- */
-export declare function renderMath(element: HTMLElement): void;

package/dist/pie/math-rendering.js

@@ -4,15 +4,23 @@
  * PIE elements expect @pie-lib/math-rendering to be available on window.
  * This module ensures required globals are populated from the upstream
  * @pie-lib/math-rendering-module package, and also supports overriding with
- * a custom renderer object when needed.
+ * a custom renderer object through setMathRenderer().
  */
 /// <reference path="../shims.d.ts" />
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 const GLOBAL_KEY = "@pie-lib/math-rendering";
 const GLOBAL_DLL_KEY = "_dll_pie_lib__math_rendering";
+// Every copy of @pie-lib/math-rendering on a page typesets through the MathJax
+// instance kept here, and the first copy to typeset creates it.
+const SHARED_INSTANCE_KEY = "@pie-lib/math-rendering@2";
 let initPromise = null;
 const logger = createPieLogger("math-rendering", () => isGlobalDebugEnabled());
-const getWindowRenderer = () => {
+/**
+ * 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
+ * has one.
+ */
+export const getMathRenderer = () => {
     if (typeof window === "undefined") {
         return null;
     }
@@ -26,43 +34,55 @@ const setWindowRenderer = (renderer) => {
     window[GLOBAL_DLL_KEY] = renderer;
 };
 /**
- * Initialize math rendering with optional custom renderer
+ * Creates the shared MathJax instance from `renderer`, unless the page already
+ * holds one.
  *
- * If no custom renderer is provided, defaults to MathJax.
+ * Legacy element bundles carry their own copy of math-rendering. A copy that
+ * predates the assistive-MathML guard, such as the one in multiple-choice
+ * 9.9.1, re-typesets the hidden `<math>` inside `mjx-assistive-mml` on every
+ * pass, so if it creates the instance, each re-render nests the expression
+ * again for every element on the page. Typesetting a detached element makes the
+ * guarded module create it first. Failure leaves the instance to the first
+ * element, as before, so it is logged and never fails initialization.
+ */
+const createSharedInstance = (renderer) => {
+    if (window[SHARED_INSTANCE_KEY]?.instance)
+        return;
+    if (typeof document === "undefined" || !document.body)
+        return;
+    const warn = (error) => logger.warn("Could not create the shared MathJax instance:", error);
+    try {
+        Promise.resolve(renderer.renderMath(document.createElement("div"))).catch(warn);
+    }
+    catch (error) {
+        warn(error);
+    }
+};
+/**
+ * Initialize math rendering, defaulting to MathJax.
  * For custom renderers, use setMathRenderer() before calling this function.
  *
  * Sets TWO window globals that PIE elements expect:
  * - window["@pie-lib/math-rendering"] (standard key)
  * - window["_dll_pie_lib__math_rendering"] (SystemJS/DLL key for IIFE bundles)
  *
- * @param customRenderer - Optional custom renderer to use instead of default MathJax
- *
  * @example
  * ```typescript
  * // Default MathJax
  * await initializeMathRendering();
  *
- * // Custom renderer instance implementing MathRenderingAPI
- * const customRenderer = await createCustomRenderer();
- * await initializeMathRendering(customRenderer);
- *
- * // Or use setMathRenderer first
+ * // Custom renderer: install it first
  * setMathRenderer(katexRenderer);
  * await initializeMathRendering();
  * ```
  */
-export async function initializeMathRendering(customRenderer) {
+export async function initializeMathRendering() {
     // Only run in browser
     if (typeof window === "undefined") {
         return;
     }
-    // Explicit override always wins.
-    if (customRenderer) {
-        setWindowRenderer(customRenderer);
-        return;
-    }
     // Already initialized - skip.
-    if (getWindowRenderer()) {
+    if (getMathRenderer()) {
         return;
     }
     if (initPromise) {
@@ -71,11 +91,20 @@ export async function initializeMathRendering(customRenderer) {
     }
     initPromise = (async () => {
         try {
-            const { _dll_pie_lib__math_rendering } = await import("@pie-lib/math-rendering-module/module");
+            // The package has no exports map, so the file is named in full for
+            // resolvers that do not complete a directory, such as webpack's
+            // fully-specified ESM resolution.
+            const mathRenderingModule = await import("@pie-lib/math-rendering-module/module/index.js");
+            // The player builds defer the module's evaluation to this call (see
+            // math-rendering-module-deferral.mjs); unbundled, it evaluated on import.
+            const renderer = mathRenderingModule.evaluateMathRenderingModule
+                ? mathRenderingModule.evaluateMathRenderingModule()
+                : mathRenderingModule._dll_pie_lib__math_rendering;
             // A host may install its renderer while the default module is in flight.
             // The explicit renderer remains authoritative when that happens.
-            if (!getWindowRenderer()) {
-                setWindowRenderer(_dll_pie_lib__math_rendering);
+            if (!getMathRenderer()) {
+                setWindowRenderer(renderer);
+                createSharedInstance(renderer);
                 logger.debug("Math rendering module initialized (both globals set)");
             }
         }
@@ -113,17 +142,3 @@ export async function initializeMathRendering(customRenderer) {
 export function setMathRenderer(renderer) {
     setWindowRenderer(renderer);
 }
-/**
- * Render math in the given element
- *
- * Convenience wrapper that calls the active renderer's renderMath() function.
- * Typically called after PIE elements are rendered.
- *
- * @param element - The element to render math within
- */
-export function renderMath(element) {
-    const renderer = getWindowRenderer();
-    if (renderer && typeof renderer.renderMath === "function") {
-        renderer.renderMath(element);
-    }
-}