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

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;

package/dist/pie/resource-monitor.js

@@ -7,17 +7,15 @@
  * 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 { NewRelicInstrumentationProvider } from "../instrumentation/providers/NewRelicInstrumentationProvider.js";
 import { isInstrumentationProvider } from "../instrumentation/provider-guards.js";
-import { getCurrentComponentContext } from "./component-context.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 const DEFAULT_CONFIG = {
     trackPageActions: false,
-    instrumentationProvider: undefined,
-    manageProviderLifecycle: undefined,
+    manageProviderLifecycle: false,
     maxRetries: 3,
     initialRetryDelay: 500,
     maxRetryDelay: 5000,
@@ -43,49 +41,39 @@ export class ResourceMonitor {
     isBrowser;
     containerResources = new Set(); // Track resources within our container
     provider;
-    ownsProvider;
-    manageProviderLifecycle;
     started = false;
     lifecycleVersion = 0;
     pendingRetryTimers = new Map();
     retryInFlight = new Set();
     pendingMediaChecks = new Map();
     constructor(config = {}) {
-        const validInjectedProvider = isInstrumentationProvider(config.instrumentationProvider)
-            ? config.instrumentationProvider
-            : undefined;
-        const hasInjectedProvider = !!validInjectedProvider;
-        const manageProviderLifecycle = config.manageProviderLifecycle ?? !hasInjectedProvider;
         this.config = {
             trackPageActions: config.trackPageActions ?? DEFAULT_CONFIG.trackPageActions,
-            instrumentationProvider: validInjectedProvider,
-            manageProviderLifecycle,
+            manageProviderLifecycle: config.manageProviderLifecycle ??
+                DEFAULT_CONFIG.manageProviderLifecycle,
             maxRetries: config.maxRetries ?? DEFAULT_CONFIG.maxRetries,
             initialRetryDelay: config.initialRetryDelay ?? DEFAULT_CONFIG.initialRetryDelay,
             maxRetryDelay: config.maxRetryDelay ?? DEFAULT_CONFIG.maxRetryDelay,
             debug: config.debug ?? DEFAULT_CONFIG.debug,
         };
         this.logger = createPieLogger("resource-monitor", () => this.isDebugEnabled());
-        if (config.instrumentationProvider && !validInjectedProvider) {
+        this.provider = isInstrumentationProvider(config.instrumentationProvider)
+            ? config.instrumentationProvider
+            : undefined;
+        if (config.instrumentationProvider && !this.provider) {
             if (this.isDebugEnabled()) {
                 this.logger.warn("Ignoring invalid instrumentation provider; expected InstrumentationProvider shape");
             }
         }
-        // Always use a provider - default to NewRelic if not specified
-        this.ownsProvider = !this.config.instrumentationProvider;
-        this.provider =
-            this.config.instrumentationProvider ??
-                new NewRelicInstrumentationProvider();
-        this.manageProviderLifecycle = this.config.manageProviderLifecycle;
         // Initialize the provider (async, but don't block constructor)
-        if (this.manageProviderLifecycle) {
+        if (this.provider && this.config.manageProviderLifecycle) {
             this.provider.initialize().catch((err) => {
                 if (this.isDebugEnabled()) {
                     this.logger.warn("Failed to initialize instrumentation provider:", err);
                 }
             });
         }
-        else if (this.isDebugEnabled()) {
+        else if (this.provider && this.isDebugEnabled()) {
             this.logger.debug("Skipping provider lifecycle management for injected provider");
         }
         this.isBrowser =
@@ -186,7 +174,7 @@ export class ResourceMonitor {
      * Track event with instrumentation provider if enabled
      */
     trackInstrumentationEvent(eventName, attributes) {
-        if (!this.config.trackPageActions || !this.provider.isReady()) {
+        if (!this.config.trackPageActions || !this.provider?.isReady()) {
             return;
         }
         this.provider.trackEvent(eventName, {
@@ -199,7 +187,7 @@ export class ResourceMonitor {
      * Track error with instrumentation provider if enabled
      */
     trackInstrumentationError(error, attributes) {
-        if (!this.config.trackPageActions || !this.provider.isReady()) {
+        if (!this.config.trackPageActions || !this.provider?.isReady()) {
             return;
         }
         this.provider.trackError(error, {
@@ -264,7 +252,7 @@ export class ResourceMonitor {
         this.containerResources.clear();
         this.container = null;
         this.started = false;
-        if (this.manageProviderLifecycle) {
+        if (this.provider && this.config.manageProviderLifecycle) {
             try {
                 this.provider.destroy();
             }
@@ -1162,190 +1150,3 @@ export class ResourceMonitor {
         };
     }
 }
-/**
- * Create and start a resource monitor for a container
- */
-export function createResourceMonitor(container, config = {}) {
-    const monitor = new ResourceMonitor(config);
-    monitor.start(container);
-    return monitor;
-}
-// =============================================================================
-// Global resource request tracking (consolidated from the old font-request-tracker)
-// =============================================================================
-// Track failed resource requests (by URL)
-const failedRequests = new Map();
-function isResourceFile(url) {
-    const resourceExtensions = [
-        // Fonts
-        ".woff",
-        ".woff2",
-        ".ttf",
-        ".otf",
-        ".eot",
-        // Images
-        ".gif",
-        ".jpg",
-        ".jpeg",
-        ".png",
-        ".svg",
-        ".webp",
-        ".ico",
-        // Audio/Video
-        ".mp3",
-        ".mp4",
-        ".wav",
-        ".ogg",
-        ".webm",
-        // Other assets
-        ".pdf",
-        ".css",
-        ".js",
-    ];
-    return resourceExtensions.some((ext) => url.toLowerCase().includes(ext));
-}
-function getResourceType(url) {
-    if (url.match(/\.(woff|woff2|ttf|otf|eot)/i))
-        return "Font";
-    if (url.match(/\.(gif|jpg|jpeg|png|svg|webp|ico)/i))
-        return "Image";
-    if (url.match(/\.(mp3|mp4|wav|ogg|webm)/i))
-        return "Media";
-    if (url.match(/\.(css)/i))
-        return "Stylesheet";
-    if (url.match(/\.(js)/i))
-        return "Script";
-    return "Resource";
-}
-function logFailedRequest(url, status, context) {
-    // Only log 404s and other failures (status 0 for network errors)
-    if (status !== 404 && status !== 0) {
-        return;
-    }
-    const key = url;
-    if (!failedRequests.has(key)) {
-        failedRequests.set(key, []);
-    }
-    const contexts = failedRequests.get(key);
-    contexts.push({
-        ...(context || { componentName: "Unknown", timestamp: Date.now() }),
-        timestamp: Date.now(),
-    });
-    const resourceType = getResourceType(url);
-    const filename = url.split("/").pop() || url;
-    const itemId = context?.itemId || "Unknown";
-    const componentName = context?.componentName || "Unknown component";
-    const elementType = context?.elementType || "";
-    console.warn(`Failed ${resourceType} request`, `\n  Resource: ${filename}`, `\n  URL: ${url}`, `\n  Item ID: ${itemId}`, `\n  Mini-Player: ${componentName}`, elementType ? `\n  Element Type: ${elementType}` : "", `\n  Status: ${status}`, context
-        ? ""
-        : "\n  Note: Component not tracked - may be from item markup or PIE element");
-}
-/**
- * Initialize global resource request tracking (404s for fonts/images/etc.)
- * Call this once when the app loads (client-side only).
- */
-export function initializeResourceRequestTracking() {
-    if (typeof window === "undefined")
-        return;
-    // Track fetch requests
-    const originalFetch = window.fetch;
-    window.fetch = async function (...args) {
-        // Extract URL from first argument (can be string, URL, or Request)
-        let url = "";
-        if (typeof args[0] === "string") {
-            url = args[0];
-        }
-        else if (args[0] instanceof URL) {
-            url = args[0].toString();
-        }
-        else if (args[0] instanceof Request) {
-            url = args[0].url;
-        }
-        if (isResourceFile(url) || url.startsWith("/")) {
-            const context = getCurrentComponentContext();
-            try {
-                const response = await originalFetch(...args);
-                if (response.status === 404) {
-                    logFailedRequest(url, response.status, context);
-                }
-                return response;
-            }
-            catch (error) {
-                logFailedRequest(url, 0, context);
-                throw error;
-            }
-        }
-        return originalFetch(...args);
-    };
-    // Track XMLHttpRequest
-    const originalXHROpen = XMLHttpRequest.prototype.open;
-    XMLHttpRequest.prototype.open = function (method, url, async, username, password) {
-        const urlString = typeof url === "string" ? url : url.toString();
-        if (isResourceFile(urlString) || urlString.startsWith("/")) {
-            const context = getCurrentComponentContext();
-            this.addEventListener("load", function () {
-                if (this.status === 404) {
-                    logFailedRequest(urlString, this.status, context);
-                }
-            });
-            this.addEventListener("error", function () {
-                logFailedRequest(urlString, 0, context);
-            });
-        }
-        return originalXHROpen.call(this, method, url, async ?? true, username ?? null, password ?? null);
-    };
-    // Intercept img tag error events (most reliable way to catch failed image loads)
-    const errorHandler = (event) => {
-        const target = event.target;
-        if (target instanceof HTMLImageElement && target.src) {
-            const url = target.src;
-            if (isResourceFile(url) ||
-                url.startsWith("/") ||
-                url.startsWith(window.location.origin + "/")) {
-                const context = getCurrentComponentContext();
-                const relativeUrl = url.startsWith(window.location.origin)
-                    ? url.replace(window.location.origin, "")
-                    : url;
-                logFailedRequest(relativeUrl, 404, context);
-            }
-        }
-    };
-    document.addEventListener("error", errorHandler, true);
-    // Track resource requests via PerformanceObserver (fonts, CSS resources, etc.)
-    const observer = new PerformanceObserver((list) => {
-        for (const entry of list.getEntries()) {
-            if (entry.entryType !== "resource")
-                continue;
-            const resourceEntry = entry;
-            const url = resourceEntry.name;
-            if (isResourceFile(url) ||
-                url.startsWith("/") ||
-                url.startsWith(window.location.origin + "/")) {
-                const perf = resourceEntry;
-                const failed = perf.responseEnd === 0 && perf.duration > 0;
-                const mightBe404 = perf.transferSize === 0 &&
-                    perf.responseEnd > 0 &&
-                    perf.responseStart === 0;
-                if (failed || mightBe404) {
-                    const context = getCurrentComponentContext();
-                    const relativeUrl = url.startsWith(window.location.origin)
-                        ? url.replace(window.location.origin, "")
-                        : url;
-                    logFailedRequest(relativeUrl, 404, context);
-                }
-            }
-        }
-    });
-    try {
-        observer.observe({ type: "resource", buffered: true });
-    }
-    catch (e) {
-        console.warn("Failed to set up PerformanceObserver for resource tracking:", e);
-    }
-}
-export function getTrackedResourceRequests() {
-    return new Map(failedRequests);
-}
-export function clearTrackedResourceRequests() {
-    failedRequests.clear();
-}

package/dist/pie/scoring.d.ts

@@ -4,10 +4,17 @@
  * Scoring and outcome calculation for PIE elements.
  */
 import type { ConfigEntity, Env, OutcomeResponse, PieController, PieModel } from "../types/index.js";
+import { BundleType } from "./types.js";
 /**
- * Find the controller for a PIE element
+ * Find the controller for a PIE element.
+ *
+ * `deliveryBundleType` is the bundle type of the player asking. A `player.js`
+ * delivery, which is what a hosted player is, resolves no controller: its
+ * models and scores come from the server, and the registry is shared with
+ * every other loader on the page, so a registered controller is no evidence
+ * that this player may run one.
  */
-export declare const findPieController: (elementName: string) => PieController | undefined;
+export declare const findPieController: (elementName: string, deliveryBundleType?: BundleType) => PieController | undefined;
 export type ScorePieItemOptions = {
     /** Scope element lookup to a specific player/root. Defaults to document for existing callers. */
     container?: Pick<ParentNode, "querySelector">;
@@ -23,6 +30,8 @@ export type ScorePieItemOptions = {
      * Existing scorePieItem callers keep the filtered result shape by default.
      */
     includeMissingResults?: boolean;
+    /** The scoring player's bundle type; `player.js` scores nothing locally. */
+    bundleType?: BundleType;
 };
 export declare function scorePieItem(config: ConfigEntity, sessionData: any[], options: ScorePieItemOptions & {
     includeMissingResults: true;