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

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;

package/dist/pie/scoring.js

@@ -10,9 +10,19 @@ import { findOrAddSession } from "./utils.js";
 // Create module-level logger (respects global debug flag - pass function for dynamic checking)
 const logger = createPieLogger("pie-scoring", () => isGlobalDebugEnabled());
 /**
- * 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 const findPieController = (elementName) => {
+export const findPieController = (elementName, deliveryBundleType) => {
+    if (deliveryBundleType === BundleType.player) {
+        logger.debug(`[findPieController] ℹ️ ${elementName} delivered as player.js; using server-processed models`);
+        return undefined;
+    }
     const registry = pieRegistry();
     logger.debug(`[findPieController] Looking for controller for: ${elementName}`);
     logger.debug(`[findPieController] Registry has entries for:`, Object.keys(registry));
@@ -30,20 +40,12 @@ export const findPieController = (elementName) => {
         controllerKeys: entry.controller ? Object.keys(entry.controller) : [],
         bundleType: entry.bundleType,
     });
-    const controller = entry.controller;
+    // Registration writes `null` for a package without a controller.
+    const controller = entry.controller ?? undefined;
     if (!controller) {
-        // Check if missing controller is expected based on bundle type
-        if (entry.bundleType === BundleType.clientPlayer) {
-            // client-player.js MUST have controllers
-            logger.error(`[findPieController] ❌ CRITICAL: Registry entry exists for ${elementName} but controller is missing!`);
-            logger.error(`[findPieController] Bundle type: ${entry.bundleType} (controllers required)`);
-            logger.error(`[findPieController] Entry:`, entry);
-            throw new Error(`No controller found for ${elementName}. client-player.js bundles MUST include controllers. Check bundle loading and registration.`);
-        }
-        else {
-            // player.js doesn't have controllers - this is expected
-            logger.debug(`[findPieController] ℹ️ No controller for ${elementName} - using server-processed models (player.js bundle)`);
-        }
+        // A package without one, such as a legacy `@pie-element/protractor`,
+        // renders the model it is given, as `<pie-player>` passed it through.
+        logger.debug(`[findPieController] ℹ️ No controller for ${elementName}; its model is used as given`);
     }
     else {
         logger.debug(`[findPieController] ✅ Controller found for ${elementName} with functions:`, Object.keys(controller));
@@ -85,7 +87,7 @@ export async function scorePieItem(config, sessionData, options = {}) {
         logger.debug("found pieEl %O for model id %s", pieEl, model.id);
         const session = findOrAddSession(sessionData, model.id, model.element);
         if (pieEl) {
-            const controller = findPieController(pieEl.localName);
+            const controller = findPieController(pieEl.localName, options.bundleType);
             if (controller?.outcome) {
                 return {
                     ...session,

package/dist/pie/session-commit.d.ts

@@ -17,6 +17,9 @@
  *   element, and it does not reach `document`. An SPA host that unmounts the
  *   player is served by `commitPendingSessions()` on the player element, called
  *   before the unmount.
+ * - Ahead of all three, `flushPendingSessionNotifications` runs when focus
+ *   leaves a player, so the event lands before the host acts on the click or
+ *   key that moved it, and carries no reason.
  *
  * Two paths, per element:
  *
@@ -72,6 +75,19 @@ export declare function noteSessionObserved(target: EventTarget | null | undefin
  */
 export declare function noteSessionBaseline(root: ParentNode | null | undefined): void;
 export declare function commitPendingSessions(root: ParentNode | null | undefined, options?: CommitPendingSessionsOptions): CommitPendingSessionsResult;
+/**
+ * Deliver every pending `session-changed` now, as an ordinary announcement.
+ *
+ * The flush a player runs when focus leaves it, ahead of whatever the learner
+ * is moving to, so the host hears the response while the item it belongs to is
+ * still current. Same two paths and the same discriminant as the commit, with
+ * no `sessionCommitReason`: an adopted element's event is exactly what its
+ * debounce would have delivered, only earlier, and the next seam finds nothing
+ * pending.
+ */
+export declare function flushPendingSessionNotifications(root: ParentNode | null | undefined, options?: {
+    logger?: PieLogger;
+}): CommitPendingSessionsResult;
 export interface BindPageLifecycleCommitOptions {
     /**
      * The subtree to commit, re-evaluated on every transition: a player's

package/dist/pie/session-commit.js

@@ -17,6 +17,9 @@
  *   element, and it does not reach `document`. An SPA host that unmounts the
  *   player is served by `commitPendingSessions()` on the player element, called
  *   before the unmount.
+ * - Ahead of all three, `flushPendingSessionNotifications` runs when focus
+ *   leaves a player, so the event lands before the host acts on the click or
+ *   key that moved it, and carries no reason.
  *
  * Two paths, per element:
  *
@@ -254,9 +257,14 @@ export function commitPendingSessions(root, options = {}) {
     };
     if (!root)
         return result;
-    return markCommitsDuring(root, options.reason ?? "teardown", () => sweepPendingSessions(root, options, result));
+    const reason = options.reason ?? "teardown";
+    return markCommitsDuring(root, reason, () => sweepPendingSessions(root, reason, options.logger, result));
 }
-function sweepPendingSessions(root, options, result) {
+/**
+ * `reason` is null for a flush, whose events are ordinary announcements.
+ */
+function sweepPendingSessions(root, reason, logger, result) {
+    const caller = reason ? "commitPendingSessions" : "flushPendingSessionNotifications";
     for (const element of candidatesIn(root)) {
         const session = readSession(element);
         if (!isRecord(session)) {
@@ -307,7 +315,7 @@ function sweepPendingSessions(root, options, result) {
             }
             catch (error) {
                 failed = true;
-                options.logger?.warn(`[commitPendingSessions] ${element.tagName.toLowerCase()} failed to commit its pending session`, error);
+                logger?.warn(`[${caller}] ${element.tagName.toLowerCase()} failed to commit its pending session`, error);
             }
             finally {
                 element.removeEventListener("session-changed", witness, true);
@@ -331,19 +339,39 @@ function sweepPendingSessions(root, options, result) {
                 detail: {
                     component: element.tagName.toLowerCase(),
                     session: JSON.parse(signature),
-                    sessionCommitReason: options.reason ?? "teardown",
+                    ...(reason ? { sessionCommitReason: reason } : {}),
                 },
             }));
             writeObservedSignature(element, signature);
             result.synthesized += 1;
         }
         catch (error) {
-            options.logger?.warn(`[commitPendingSessions] ${element.tagName.toLowerCase()} session commit dispatch failed`, error);
+            logger?.warn(`[${caller}] ${element.tagName.toLowerCase()} session commit dispatch failed`, error);
             result.skipped += 1;
         }
     }
     return result;
 }
+/**
+ * Deliver every pending `session-changed` now, as an ordinary announcement.
+ *
+ * The flush a player runs when focus leaves it, ahead of whatever the learner
+ * is moving to, so the host hears the response while the item it belongs to is
+ * still current. Same two paths and the same discriminant as the commit, with
+ * no `sessionCommitReason`: an adopted element's event is exactly what its
+ * debounce would have delivered, only earlier, and the next seam finds nothing
+ * pending.
+ */
+export function flushPendingSessionNotifications(root, options = {}) {
+    const result = {
+        committed: 0,
+        synthesized: 0,
+        skipped: 0,
+    };
+    if (!root)
+        return result;
+    return sweepPendingSessions(root, null, options.logger, result);
+}
 /**
  * Commit on the page going away rather than on the player being removed from it.
  *