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

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-assets.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Where the MathJax adapter's copies load MathJax's fonts, speech worker and,
+ * on its npm build, MathJax itself from, and whether math is in the tab order.
+ * Every copy of `@pie-element/shared-math-rendering-mathjax` reads these from
+ * the legacy renderer's page options as it starts MathJax, on its first render,
+ * so they are set before any element renders. See
+ * https://github.com/pie-framework/pie-elements-ng/blob/develop/docs/MATH-RENDERING.md#assets
+ */
+export interface MathAssetOptions {
+    /**
+     * An npm root: a URL under which `<package>@<version>/<path>` serves that
+     * file of the package, such as `https://cdn.jsdelivr.net/npm`. A relative URL
+     * resolves against the page.
+     */
+    assetRoot?: string | URL;
+    /**
+     * The directory of `speech-worker.js` and its `mathmaps/`, by default
+     * `mathjax@<version>/sre` under the asset root.
+     */
+    speechPath?: string | URL;
+    /**
+     * The URL of individual files by npm path, `<package>@<version>/<path>`: a
+     * listed file loads from its URL, the rest from the asset root. A bundle lists
+     * each file it ships as `new URL("./…", import.meta.url)`, which its host's
+     * bundler emits, and needs no root. Read by the adapter's browser build, for
+     * its fonts, speech worker and speech rules.
+     */
+    assetUrls?: Readonly<Record<string, string | URL>>;
+    /**
+     * The speech locales the MathJax menu lists, by id (`["en", "es"]`), or by id
+     * with the label it shows. Unset, it lists every locale SRE ships.
+     */
+    speechLocales?: readonly string[] | Readonly<Record<string, string>>;
+    /**
+     * Puts typeset math in the keyboard tab order, for the MathJax menu and its
+     * explorer. Off by default.
+     */
+    inTabOrder?: boolean;
+}
+/** Why `options` is not a `MathAssetOptions`, or `undefined` when it is. */
+export declare function mathAssetOptionsError(options: unknown): string | undefined;
+/**
+ * Writes `options` to the page options, keeping the ones it leaves unset and
+ * the files of `assetUrls` it does not list.
+ */
+export declare function setMathAssetOptions(options: MathAssetOptions): void;
+/** The asset root the page options set, if any. */
+export declare function pageMathAssetRoot(): string | undefined;

package/dist/pie/math-assets.js

@@ -0,0 +1,81 @@
+/**
+ * Where the MathJax adapter's copies load MathJax's fonts, speech worker and,
+ * on its npm build, MathJax itself from, and whether math is in the tab order.
+ * Every copy of `@pie-element/shared-math-rendering-mathjax` reads these from
+ * the legacy renderer's page options as it starts MathJax, on its first render,
+ * so they are set before any element renders. See
+ * https://github.com/pie-framework/pie-elements-ng/blob/develop/docs/MATH-RENDERING.md#assets
+ */
+/** The legacy renderer's page options, which the adapter reads as well. */
+const PAGE_OPTIONS_KEY = "@pie-lib/math-rendering@2";
+const isUrl = (value) => (typeof value === "string" && value !== "") || value instanceof URL;
+/** Why `options` is not a `MathAssetOptions`, or `undefined` when it is. */
+export function mathAssetOptionsError(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        return "must be an object";
+    }
+    const { assetRoot, speechPath, assetUrls, speechLocales, inTabOrder } = options;
+    if (assetRoot !== undefined && !isUrl(assetRoot)) {
+        return `assetRoot must be a URL, got ${JSON.stringify(assetRoot)}`;
+    }
+    if (speechPath !== undefined && !isUrl(speechPath)) {
+        return `speechPath must be a URL, got ${JSON.stringify(speechPath)}`;
+    }
+    if (assetUrls !== undefined &&
+        (!assetUrls ||
+            typeof assetUrls !== "object" ||
+            Array.isArray(assetUrls) ||
+            !Object.values(assetUrls).every(isUrl))) {
+        return "assetUrls must map npm paths to URLs";
+    }
+    if (speechLocales !== undefined) {
+        const listed = Array.isArray(speechLocales)
+            ? speechLocales
+            : speechLocales && typeof speechLocales === "object"
+                ? Object.values(speechLocales)
+                : null;
+        if (!listed || listed.some((entry) => typeof entry !== "string" || !entry)) {
+            return "speechLocales must be locale ids, or locale ids mapped to their labels";
+        }
+    }
+    if (inTabOrder !== undefined && typeof inTabOrder !== "boolean") {
+        return `inTabOrder must be a boolean, got ${JSON.stringify(inTabOrder)}`;
+    }
+    return undefined;
+}
+/**
+ * Writes `options` to the page options, keeping the ones it leaves unset and
+ * the files of `assetUrls` it does not list.
+ */
+export function setMathAssetOptions(options) {
+    if (typeof window === "undefined")
+        return;
+    const host = window;
+    const page = (host[PAGE_OPTIONS_KEY] ??= {});
+    const opts = (page.opts ??= {});
+    if (options.assetRoot !== undefined)
+        opts.assetRoot = String(options.assetRoot);
+    if (options.speechPath !== undefined)
+        opts.speechPath = String(options.speechPath);
+    if (options.assetUrls !== undefined) {
+        const listed = opts.assetUrls && typeof opts.assetUrls === "object" ? opts.assetUrls : {};
+        opts.assetUrls = {
+            ...listed,
+            ...Object.fromEntries(Object.entries(options.assetUrls).map(([path, url]) => [path, String(url)])),
+        };
+    }
+    if (options.speechLocales !== undefined) {
+        opts.speechLocales = Array.isArray(options.speechLocales)
+            ? [...options.speechLocales]
+            : { ...options.speechLocales };
+    }
+    if (options.inTabOrder !== undefined)
+        opts.inTabOrder = options.inTabOrder;
+}
+/** The asset root the page options set, if any. */
+export function pageMathAssetRoot() {
+    if (typeof window === "undefined")
+        return undefined;
+    const root = window[PAGE_OPTIONS_KEY]?.opts?.assetRoot;
+    return typeof root === "string" && root ? root : undefined;
+}

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);
-    }
-}

package/dist/pie/registry.d.ts

@@ -3,8 +3,20 @@
  *
  * Manages the global PIE registry that tracks loaded elements.
  */
-import type { PieRegistry } from "./types.js";
+import type { Entry, PieRegistry } from "./types.js";
 /**
  * Get or create the global PIE registry
  */
 export declare const pieRegistry: () => PieRegistry;
+/**
+ * Record a tag in `window.PIE_REGISTRY`. Every registration path writes through
+ * here: the IIFE and ESM loaders, bundle initialization, and
+ * `registerPreloadedElements`.
+ *
+ * The first loaded entry for a tag `customElements` holds describes that
+ * definition, which no later load replaces, so it keeps its package and
+ * element. A later write fills only what it left empty: a controller, with the
+ * bundle type that supplied it, and a config. Any other entry is replaced.
+ * Returns the entry the registry holds afterwards.
+ */
+export declare function writeRegistryEntry(entry: Entry): Entry;

package/dist/pie/registry.js

@@ -3,7 +3,7 @@
  *
  * Manages the global PIE registry that tracks loaded elements.
  */
-import { isPieRegistryAvailable } from "./types.js";
+import { isPieRegistryAvailable, Status } from "./types.js";
 /**
  * Get or create the global PIE registry
  */
@@ -18,3 +18,41 @@ export const pieRegistry = () => {
     }
     return registry;
 };
+/**
+ * Record a tag in `window.PIE_REGISTRY`. Every registration path writes through
+ * here: the IIFE and ESM loaders, bundle initialization, and
+ * `registerPreloadedElements`.
+ *
+ * The first loaded entry for a tag `customElements` holds describes that
+ * definition, which no later load replaces, so it keeps its package and
+ * element. A later write fills only what it left empty: a controller, with the
+ * bundle type that supplied it, and a config. Any other entry is replaced.
+ * Returns the entry the registry holds afterwards.
+ */
+export function writeRegistryEntry(entry) {
+    const registry = pieRegistry();
+    const existing = registry[entry.tagName];
+    if (!existing ||
+        existing.status !== Status.loaded ||
+        !isDefinedTag(entry.tagName)) {
+        registry[entry.tagName] = entry;
+        return entry;
+    }
+    const fillsController = !existing.controller && !!entry.controller;
+    const fillsConfig = existing.config == null && entry.config != null;
+    if (!fillsController && !fillsConfig)
+        return existing;
+    const filled = { ...existing };
+    if (fillsController) {
+        filled.controller = entry.controller;
+        filled.bundleType = entry.bundleType;
+    }
+    if (fillsConfig)
+        filled.config = entry.config;
+    registry[entry.tagName] = filled;
+    return filled;
+}
+function isDefinedTag(tagName) {
+    return (typeof customElements !== "undefined" &&
+        customElements.get(tagName) !== undefined);
+}

package/dist/pie/resource-monitor.d.ts

@@ -7,11 +7,11 @@
  * Features:
  * - Tracks resource load timing with PerformanceObserver
  * - Detects and retries failed resource loads
- * - Sends instrumentation to New Relic
+ * - With `trackPageActions`, reports loads, retries and failures to the
+ *   instrumentation provider it is given
  * - Works with all resource types (audio, video, img, link)
  */
 import type { InstrumentationProvider } from "../instrumentation/types.js";
-import type { ComponentContext } from "./component-context.js";
 export type ResourceMonitorConfig = {
     /**
      * Enable tracking page actions/events
@@ -22,29 +22,15 @@ export type ResourceMonitorConfig = {
     /**
      * Instrumentation provider for tracking events and errors
      *
-     * Optional. If not provided, defaults to NewRelicInstrumentationProvider.
-     * The provider handles instrumentation gracefully - if New Relic is not available,
-     * it will simply not track events (no errors thrown).
-     *
-     * To use a different provider, pass it here:
-     *
-     * @example
-     * ```typescript
-     * const provider = new ConsoleInstrumentationProvider();
-     * await provider.initialize({ debug: true });
-     *
-     * const monitor = new ResourceMonitor({
-     *   trackPageActions: true,
-     *   instrumentationProvider: provider
-     * });
-     * ```
+     * The monitor constructs no provider of its own: without one it only
+     * retries. Players pass what `resolveInstrumentationProvider` resolves from
+     * their `loaderConfig`.
      */
     instrumentationProvider?: InstrumentationProvider;
     /**
      * Whether ResourceMonitor should initialize/destroy the instrumentation provider.
      *
-     * Defaults to `true` when ResourceMonitor creates the provider internally, and
-     * `false` when a provider is injected by the host.
+     * Defaults to `false`: the provider belongs to whoever passed it in.
      */
     manageProviderLifecycle?: boolean;
     /**
@@ -97,8 +83,6 @@ export declare class ResourceMonitor {
     private isBrowser;
     private containerResources;
     private provider;
-    private readonly ownsProvider;
-    private readonly manageProviderLifecycle;
     private started;
     private lifecycleVersion;
     private pendingRetryTimers;
@@ -229,14 +213,3 @@ export declare class ResourceMonitor {
         }>;
     };
 }
-/**
- * Create and start a resource monitor for a container
- */
-export declare function createResourceMonitor(container: HTMLElement, config?: ResourceMonitorConfig): ResourceMonitor;
-/**
- * Initialize global resource request tracking (404s for fonts/images/etc.)
- * Call this once when the app loads (client-side only).
- */
-export declare function initializeResourceRequestTracking(): void;
-export declare function getTrackedResourceRequests(): Map<string, ComponentContext[]>;
-export declare function clearTrackedResourceRequests(): void;