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

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,25 +4,29 @@
  * 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">;
     env?: Partial<Env>;
     models?: PieModel[];
-    /**
-     * Existing callers keep the historical scorePieItem controller call shape.
-     * provideScore() opts into the item-player score result shape explicitly.
-     */
-    outcomeArguments?: "session-env" | "model-session-env";
     /**
      * Preserve one result slot per model, including undefined for missing element/controller.
-     * Existing scorePieItem callers keep the filtered result shape by default.
+     * Missing slots are filtered out 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));
@@ -60,13 +62,9 @@ const findRenderedPieElement = (root, modelId) => {
     return (root.querySelector(`[id="${escapedId}"]`) ||
         root.querySelector(`[pie-id="${escapedId}"]`));
 };
-const invokeOutcome = async (controller, model, session, env, argumentShape) => {
-    if (argumentShape === "model-session-env") {
-        const outcome = controller.outcome;
-        return outcome.call(controller, model, session, env);
-    }
+const invokeOutcome = async (controller, model, session, env) => {
     const outcome = controller.outcome;
-    return outcome.call(controller, session, env);
+    return outcome.call(controller, model, session, env);
 };
 /**
  * Score a PIE item by calling outcome on all PIE elements
@@ -74,7 +72,6 @@ const invokeOutcome = async (controller, model, session, env, argumentShape) =>
 export async function scorePieItem(config, sessionData, options = {}) {
     const root = options.container ?? document;
     const models = options.models ?? config.models ?? [];
-    const outcomeArguments = options.outcomeArguments ?? "session-env";
     const scoringEnv = {
         ...options.env,
         mode: "evaluate",
@@ -85,11 +82,11 @@ 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,
-                    ...(await invokeOutcome(controller, model, session, scoringEnv, outcomeArguments)),
+                    ...(await invokeOutcome(controller, model, session, scoringEnv)),
                 };
             }
             else {

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:
  *
@@ -90,7 +93,7 @@ function assignedElementsOf(element) {
  * elements assigned to each `<slot>`.
  *
  * `querySelectorAll("*")` sees none of the last two, and both are load-bearing
- * here. The section player mounts each item inside `<pie-item-shell>`'s shadow
+ * here. The section player mounts each item inside `<pie-item-scope>`'s shadow
  * root, and projects its item pane through a slot on the assessment toolkit -
  * a walk that stops at `<slot>` finds every delivery element in a section
  * unreachable.
@@ -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.
  *

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

@@ -0,0 +1,80 @@
+/**
+ * Device-local snapshot of a committed session.
+ *
+ * A crash or an OS kill fires no lifecycle event, so the only state that
+ * survives it is state already written. The snapshot writes each committed
+ * session to device storage and offers it back on the next load.
+ *
+ * It is offered, never applied. School devices are shared, and a player cannot
+ * tell a legitimate recovery from a previous student's draft, so the host
+ * decides.
+ *
+ * `sessionStorage` is the default, matching the annotation toolbar's existing
+ * use of it for learner annotations: it is tab-scoped and cleared when the tab
+ * closes, so a response does not outlive the sitting, and browser session
+ * restore brings it back after a crash. A host that wants recovery across a
+ * full browser restart injects a `localStorage`-backed store and owns the
+ * retention consequences.
+ */
+export interface SessionSnapshotStore {
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    clear(key: string): void;
+}
+export type SessionSnapshotConfig = boolean | {
+    enabled?: boolean;
+    /** Defaults to `sessionStorage`. */
+    store?: SessionSnapshotStore;
+    /** Defaults to a key derived from the delivery identity. */
+    key?: string;
+};
+export interface SessionSnapshotRecord {
+    key: string;
+    session: unknown;
+    /** `Date.now()` at the time of the write. */
+    timestamp: number;
+}
+export interface SessionSnapshot {
+    readonly key: string;
+    write(session: unknown): void;
+    read(): SessionSnapshotRecord | null;
+    clear(): void;
+}
+export type SessionSnapshotIdentity = {
+    itemId?: string;
+    sessionId?: string;
+    assignmentId?: string;
+};
+/**
+ * Whether an identity names one sitting.
+ *
+ * `sessionId` is the only field that distinguishes one learner's attempt from
+ * another's. Keyed on the item alone, a shared device offers the previous
+ * student's draft to the next one - and the offer is itself a disclosure, before
+ * the host ever decides whether to apply it. So without a `sessionId` there is
+ * no snapshot, and a host driving the player by props alone opts in by passing
+ * an explicit `key`.
+ */
+export declare function isSnapshotIdentitySpecific(identity: SessionSnapshotIdentity): boolean;
+/**
+ * Key built from the delivery identity, so a snapshot is only offered back to
+ * the sitting that wrote it.
+ */
+export declare function sessionSnapshotKey(identity: SessionSnapshotIdentity): string;
+/**
+ * `sessionStorage`-backed store. Every access is guarded: private mode and
+ * blocked site data make the accessor throw, and a player must keep working
+ * without a snapshot rather than fail.
+ */
+export declare function sessionStorageSnapshotStore(): SessionSnapshotStore;
+export declare function isSessionSnapshotEnabled(config: SessionSnapshotConfig | null | undefined): boolean;
+/**
+ * Returns `null` when the host has not enabled a snapshot, and when the
+ * identity does not name one sitting. PIE writes learner responses to the
+ * device only on an explicit opt-in, and only under a key no other learner
+ * shares.
+ */
+export declare function createSessionSnapshot(args: {
+    config: SessionSnapshotConfig | null | undefined;
+    identity: SessionSnapshotIdentity;
+}): SessionSnapshot | null;