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

package/dist/pie/session-snapshot.js

@@ -0,0 +1,166 @@
+/**
+ * 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.
+ */
+const KEY_PREFIX = "pie-session-snapshot";
+/**
+ * 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 function isSnapshotIdentitySpecific(identity) {
+    return Boolean(identity.sessionId);
+}
+/**
+ * Key built from the delivery identity, so a snapshot is only offered back to
+ * the sitting that wrote it.
+ */
+export function sessionSnapshotKey(identity) {
+    const parts = [
+        identity.assignmentId || "",
+        identity.sessionId || "",
+        identity.itemId || "",
+    ];
+    return `${KEY_PREFIX}:${parts.join("|")}`;
+}
+/**
+ * `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 function sessionStorageSnapshotStore() {
+    return {
+        read(key) {
+            try {
+                if (typeof sessionStorage === "undefined")
+                    return null;
+                return sessionStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        write(key, value) {
+            try {
+                if (typeof sessionStorage === "undefined")
+                    return;
+                sessionStorage.setItem(key, value);
+            }
+            catch {
+                // Quota, private mode, blocked site data: no snapshot this sitting.
+            }
+        },
+        clear(key) {
+            try {
+                if (typeof sessionStorage === "undefined")
+                    return;
+                sessionStorage.removeItem(key);
+            }
+            catch {
+                // ignore
+            }
+        },
+    };
+}
+export function isSessionSnapshotEnabled(config) {
+    if (typeof config === "boolean")
+        return config;
+    if (!config)
+        return false;
+    return config.enabled !== false;
+}
+/**
+ * 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 function createSessionSnapshot(args) {
+    if (!isSessionSnapshotEnabled(args.config))
+        return null;
+    const settings = typeof args.config === "object" && args.config ? args.config : {};
+    if (!settings.key && !isSnapshotIdentitySpecific(args.identity))
+        return null;
+    const key = settings.key || sessionSnapshotKey(args.identity);
+    const store = settings.store || sessionStorageSnapshotStore();
+    // A host-injected store is guarded the same way the default one is: a player
+    // keeps working without a snapshot rather than failing on storage.
+    const safeRead = () => {
+        try {
+            return store.read(key);
+        }
+        catch {
+            return null;
+        }
+    };
+    const safeWrite = (value) => {
+        try {
+            store.write(key, value);
+        }
+        catch {
+            // no snapshot this sitting
+        }
+    };
+    const safeClear = () => {
+        try {
+            store.clear(key);
+        }
+        catch {
+            // no snapshot this sitting
+        }
+    };
+    return {
+        key,
+        write(session) {
+            let payload;
+            try {
+                payload = JSON.stringify({ session, timestamp: Date.now() });
+            }
+            catch {
+                return;
+            }
+            safeWrite(payload);
+        },
+        read() {
+            const raw = safeRead();
+            if (!raw)
+                return null;
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || !("session" in parsed)) {
+                    return null;
+                }
+                return {
+                    key,
+                    session: parsed.session,
+                    timestamp: typeof parsed.timestamp === "number" ? parsed.timestamp : 0,
+                };
+            }
+            catch {
+                return null;
+            }
+        },
+        clear() {
+            safeClear();
+        },
+    };
+}

package/dist/pie/tag-names.d.ts

@@ -15,3 +15,4 @@ export declare const toViewTag: (baseTag: string, view: PieViewMode | string, cu
  * Build a safe print tag by appending a deterministic, positive hash suffix.
  */
 export declare const toPrintHashedTag: (baseTag: string, hashSource: string, hashFn: (value: string) => number) => string;
+export { parseVersionedTagName } from "./versioned-tag.js";

package/dist/pie/tag-names.js

@@ -59,3 +59,4 @@ export const toPrintHashedTag = (baseTag, hashSource, hashFn) => {
     const hash = Math.abs(hashFn(hashSource));
     return `${baseTag}-print-${hash}`;
 };
+export { parseVersionedTagName } from "./versioned-tag.js";

package/dist/pie/types.d.ts

@@ -5,10 +5,6 @@
  * This module has NO runtime dependencies on other PIE modules.
  */
 import type { ConfigEntity, Env, PieController, PieModel } from "../types/index.js";
-/**
- * Player modes
- */
-export type PlayerMode = "gather" | "view" | "evaluate" | "author";
 /**
  * PIE custom element interface
  */
@@ -52,7 +48,8 @@ export interface AssetHandler {
 export declare enum BundleType {
     player = "player.js",// Elements only (no controllers)
     clientPlayer = "client-player.js",// Elements + controllers
-    editor = "editor.js"
+    editor = "editor.js",// Editor UI
+    esm = "esm"
 }
 /**
  * Internal PIE registry entry status
@@ -93,6 +90,8 @@ export interface UpdatePieElementOptions {
     session: any[];
     env?: Env;
     invokeControllerForModel?: boolean;
+    /** The delivering player's bundle type, see `findPieController`. */
+    bundleType?: BundleType;
     eventListeners?: EventListeners;
     container?: Element | Document;
     /**

package/dist/pie/types.js

@@ -12,6 +12,7 @@ export var BundleType;
     BundleType["player"] = "player.js";
     BundleType["clientPlayer"] = "client-player.js";
     BundleType["editor"] = "editor.js";
+    BundleType["esm"] = "esm";
 })(BundleType || (BundleType = {}));
 /**
  * Internal PIE registry entry status

package/dist/pie/updates.d.ts

@@ -4,7 +4,7 @@
  * Functions for updating PIE elements with new models, sessions, and env.
  */
 import type { ConfigEntity, Env } from "../types/index.js";
-import type { UpdatePieElementOptions } from "./types.js";
+import type { BundleType, UpdatePieElementOptions } from "./types.js";
 /**
  * Update a PIE element by ref (direct Element reference)
  */
@@ -16,4 +16,4 @@ export declare const updatePieElement: (elName: string, opts: UpdatePieElementOp
 /**
  * Update all PIE elements in a config
  */
-export declare const updatePieElements: (config: ConfigEntity, session: any[], env: Env, container?: Element | Document, onElementSessionUpdate?: UpdatePieElementOptions["onElementSessionUpdate"]) => Promise<void>;
+export declare const updatePieElements: (config: ConfigEntity, session: any[], env: Env, container?: Element | Document, onElementSessionUpdate?: UpdatePieElementOptions["onElementSessionUpdate"], bundleType?: BundleType) => Promise<void>;

package/dist/pie/updates.js

@@ -4,7 +4,6 @@
  * Functions for updating PIE elements with new models, sessions, and env.
  */
 import { mergeObjectsIgnoringNullUndefined } from "../object/index.js";
-import { wrapModelRichContent } from "../security/wrap-model-rich-content.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { findPieController } from "./scoring.js";
 import { defaultPieElementOptions } from "./types.js";
@@ -55,11 +54,23 @@ const emitControllerError = (pieElement, detail) => {
         composed: true,
     }));
 };
+/**
+ * Reports whether an element has left the document since its update started.
+ * A legacy element unmounts its React root when it is disconnected, and a
+ * write after that throws React error #409 in releases before PIE-703, or
+ * renders a tree nothing unmounts in later ones. The controller call is when a
+ * host can remove the player. An element that was never inserted still takes
+ * the update, so a caller can set one up before inserting it.
+ */
+const trackRemoval = (element) => {
+    const wasConnected = element.isConnected;
+    return () => wasConnected && !element.isConnected;
+};
 /**
  * Helper function to apply controller to element
  * Extracted to eliminate duplication and ensure consistent controller invocation
  */
-const applyControllerToElement = async (element, model, elementSession, controller, env, logPrefix, onElementSessionUpdate) => {
+const applyControllerToElement = async (element, model, elementSession, controller, env, logPrefix, wasRemoved, onElementSessionUpdate) => {
     logger.debug(`${logPrefix} Using controller, env:`, env);
     logger.debug(`${logPrefix} Model before filter:`, {
         id: model.id,
@@ -93,15 +104,16 @@ const applyControllerToElement = async (element, model, elementSession, controll
             element: model.element,
             ...controllerResultObject,
         };
-        const wrappedModel = wrapModelRichContent(filteredModel);
         logger.debug(`${logPrefix} ✅ Controller filtered model:`, {
-            id: wrappedModel.id,
-            element: wrappedModel.element,
-            hasCorrectResponse: "correctResponse" in wrappedModel,
+            id: filteredModel.id,
+            element: filteredModel.element,
+            hasCorrectResponse: "correctResponse" in filteredModel,
             mode: env.mode,
             role: env.role,
         });
-        element.model = wrappedModel;
+        if (wasRemoved())
+            return;
+        element.model = filteredModel;
         element.session = elementSession;
     }
     catch (err) {
@@ -110,7 +122,7 @@ const applyControllerToElement = async (element, model, elementSession, controll
     }
 };
 const resolveAndValidateUpdateOptions = (opts) => {
-    const { config, session, env, eventListeners, invokeControllerForModel, onElementSessionUpdate, } = mergeObjectsIgnoringNullUndefined(defaultPieElementOptions, opts);
+    const { config, session, env, eventListeners, invokeControllerForModel, bundleType, onElementSessionUpdate, } = mergeObjectsIgnoringNullUndefined(defaultPieElementOptions, opts);
     if (!env) {
         throw new Error("env is required");
     }
@@ -126,11 +138,12 @@ const resolveAndValidateUpdateOptions = (opts) => {
         env,
         eventListeners,
         invokeControllerForModel,
+        bundleType,
         onElementSessionUpdate,
     };
 };
 const updateSinglePieElement = async (pieElement, controllerLookupTag, options, logContext) => {
-    const { config, session, env, eventListeners, invokeControllerForModel, onElementSessionUpdate, } = options;
+    const { config, session, env, eventListeners, invokeControllerForModel, bundleType, onElementSessionUpdate, } = options;
     const model = config.models?.find((m) => m.id === pieElement.id);
     if (!model) {
         logger.error(`${logContext} Model not found for`, controllerLookupTag);
@@ -144,10 +157,10 @@ const updateSinglePieElement = async (pieElement, controllerLookupTag, options,
         });
     }
     if (env && invokeControllerForModel) {
-        const controller = findPieController(controllerLookupTag);
+        const controller = findPieController(controllerLookupTag, bundleType);
         if (!controller) {
             logger.debug(`${logContext} ℹ️ No controller for ${controllerLookupTag}, using server-processed model`);
-            pieElement.model = wrapModelRichContent(model);
+            pieElement.model = model;
             pieElement.session = elementSession;
             return;
         }
@@ -160,8 +173,9 @@ const updateSinglePieElement = async (pieElement, controllerLookupTag, options,
         // caller computes/emits the session signature; otherwise a late, async
         // shuffle write lands after the cycle that read the session and the order
         // never round-trips (PIE-631).
+        const wasRemoved = trackRemoval(pieElement);
         try {
-            await applyControllerToElement(pieElement, model, elementSession, controller, env, `${logContext}(${controllerLookupTag}#${pieElement.id})`, onElementSessionUpdate);
+            await applyControllerToElement(pieElement, model, elementSession, controller, env, `${logContext}(${controllerLookupTag}#${pieElement.id})`, wasRemoved, onElementSessionUpdate);
         }
         catch (err) {
             const errorMessage = err instanceof Error ? err.message : String(err);
@@ -172,19 +186,22 @@ const updateSinglePieElement = async (pieElement, controllerLookupTag, options,
                     ? "PIE_CONTROLLER_CONTRACT_ERROR"
                     : "PIE_CONTROLLER_RUNTIME_ERROR",
                 message: `${controllerLookupTag} controller failed while applying model for ${pieElement.id}. ${errorMessage}`,
+                recoverable: true,
                 elementName: controllerLookupTag,
                 elementId: pieElement.id,
                 controllerShape: describeControllerShape(controller),
                 cause: errorMessage,
             });
             // Fall back to raw model on controller error
-            pieElement.model = wrapModelRichContent(model);
+            if (wasRemoved())
+                return;
+            pieElement.model = model;
             pieElement.session = elementSession;
         }
     }
     else {
         logger.debug(`${logContext} Direct model assignment for ${controllerLookupTag}#${pieElement.id} (no controller invocation requested)`);
-        pieElement.model = wrapModelRichContent(model);
+        pieElement.model = model;
         pieElement.session = elementSession;
     }
 };
@@ -215,7 +232,7 @@ export const updatePieElement = (elName, opts) => {
 /**
  * Update all PIE elements in a config
  */
-export const updatePieElements = (config, session, env, container, onElementSessionUpdate) => {
+export const updatePieElements = (config, session, env, container, onElementSessionUpdate, bundleType) => {
     logger.debug("[updatePieElements] Updating all elements with env:", env);
     return Promise.all(Object.entries(config.elements).map(([elName, _pkg]) => updatePieElement(elName, {
         config,
@@ -223,5 +240,6 @@ export const updatePieElements = (config, session, env, container, onElementSess
         env,
         container,
         onElementSessionUpdate,
+        bundleType,
     }))).then(() => undefined);
 };

package/dist/pie/versioned-tag.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Split a runtime tag into its base name and the encoded version that follows
+ * `--version-`, when it has one.
+ */
 export declare function parseVersionedTagName(tagName: string): {
     baseName: string;
     existingEncodedVersion?: string;

package/dist/pie/versioned-tag.js

@@ -6,6 +6,10 @@ const encodeVersionForTag = (version) => version
     .replace(/[.+]/g, "-")
     .replace(/[^0-9A-Za-z-]/g, "-")
     .replace(/-{2,}/g, "-");
+/**
+ * Split a runtime tag into its base name and the encoded version that follows
+ * `--version-`, when it has one.
+ */
 export function parseVersionedTagName(tagName) {
     const versionMatch = tagName.match(new RegExp(`${VERSION_DELIMITER}(${TAG_VERSION_PATTERN})$`));
     if (!versionMatch || versionMatch.index === undefined) {

package/dist/security/index.d.ts

@@ -1,7 +1,6 @@
-export { buildAuthoringAllowList, createDefaultItemMarkupSanitizer, resetPurifierForTesting, sanitizeItemMarkup, type ItemMarkupSanitizer, type SanitizeItemMarkupOptions, } from "./sanitize-item-markup.js";
+export { buildAuthoringAllowList, createDefaultItemMarkupSanitizer, sanitizeItemMarkup, type ItemMarkupSanitizer, type SanitizeItemMarkupOptions, } from "./sanitize-item-markup.js";
 export { parseAllowedStyleOrigins, validateExternalStyleUrl, type StyleUrlValidationError, type StyleUrlValidationOk, type StyleUrlValidationOptions, type StyleUrlValidationResult, } from "./validate-style-url.js";
-export { resetSvgSanitizerForTesting, sanitizeSvgIcon, } from "./sanitize-svg-icon.js";
+export { sanitizeSvgIcon } from "./sanitize-svg-icon.js";
 export { sanitizeStyleAttribute } from "./sanitize-style-attribute.js";
 export { isOverwideImageWrapMutation, wrapOverwideImages, wrapOverwideImagesInElement, } from "./wrap-overwide-images.js";
-export { wrapModelRichContent } from "./wrap-model-rich-content.js";
 export { isOverwideTableWrapMutation, wrapOverwideTables, wrapOverwideTablesInElement, } from "./wrap-overwide-tables.js";

package/dist/security/index.js

@@ -1,7 +1,6 @@
-export { buildAuthoringAllowList, createDefaultItemMarkupSanitizer, resetPurifierForTesting, sanitizeItemMarkup, } from "./sanitize-item-markup.js";
+export { buildAuthoringAllowList, createDefaultItemMarkupSanitizer, sanitizeItemMarkup, } from "./sanitize-item-markup.js";
 export { parseAllowedStyleOrigins, validateExternalStyleUrl, } from "./validate-style-url.js";
-export { resetSvgSanitizerForTesting, sanitizeSvgIcon, } from "./sanitize-svg-icon.js";
+export { sanitizeSvgIcon } from "./sanitize-svg-icon.js";
 export { sanitizeStyleAttribute } from "./sanitize-style-attribute.js";
 export { isOverwideImageWrapMutation, wrapOverwideImages, wrapOverwideImagesInElement, } from "./wrap-overwide-images.js";
-export { wrapModelRichContent } from "./wrap-model-rich-content.js";
 export { isOverwideTableWrapMutation, wrapOverwideTables, wrapOverwideTablesInElement, } from "./wrap-overwide-tables.js";

package/dist/security/sanitize-item-markup.d.ts

@@ -52,5 +52,3 @@ export declare function createDefaultItemMarkupSanitizer(options?: SanitizeItemM
  * keeps the rewritten `-config` tags instead of stripping them.
  */
 export declare function buildAuthoringAllowList(elementTagNames: Iterable<string>): string[];
-/** Reset the memoised DOMPurify instance. Only intended for tests. */
-export declare function resetPurifierForTesting(): void;

package/dist/security/sanitize-item-markup.js

@@ -144,7 +144,3 @@ export function buildAuthoringAllowList(elementTagNames) {
     }
     return [...out];
 }
-/** Reset the memoised DOMPurify instance. Only intended for tests. */
-export function resetPurifierForTesting() {
-    purifierInstance = null;
-}

package/dist/security/sanitize-svg-icon.d.ts

@@ -10,5 +10,3 @@
  * or the input is not a string.
  */
 export declare function sanitizeSvgIcon(icon: unknown): string;
-/** Reset sanitizer state. Intended for tests. */
-export declare function resetSvgSanitizerForTesting(): void;

package/dist/security/sanitize-svg-icon.js

@@ -61,8 +61,3 @@ export function sanitizeSvgIcon(icon) {
     stringCache.set(icon, str);
     return str;
 }
-/** Reset sanitizer state. Intended for tests. */
-export function resetSvgSanitizerForTesting() {
-    svgPurifierInstance = null;
-    stringCache.clear();
-}

package/dist/security/wrap-overwide.d.ts

@@ -14,6 +14,11 @@
  * the real divergence — an image has `alt`, a table has `<caption>`,
  * `aria-label` and `aria-labelledby` — which is why it is a function rather than
  * a template.
+ *
+ * Content inside an editing host is never wrapped, on either pass. The editor
+ * owns that DOM: ProseMirror reads the wrapper as a foreign mutation and redraws
+ * the node without it, so an observer-driven wrap and the editor undo each other
+ * for as long as the editor holds an image.
  */
 /** What one content kind needs in order to be wrapped. */
 export interface OverwideWrapSpec {

package/dist/security/wrap-overwide.js

@@ -14,8 +14,22 @@
  * the real divergence — an image has `alt`, a table has `<caption>`,
  * `aria-label` and `aria-labelledby` — which is why it is a function rather than
  * a template.
+ *
+ * Content inside an editing host is never wrapped, on either pass. The editor
+ * owns that DOM: ProseMirror reads the wrapper as a foreign mutation and redraws
+ * the node without it, so an observer-driven wrap and the editor undo each other
+ * for as long as the editor holds an image.
  */
 const PIE_CUSTOM_ELEMENT_TAG_REGEX = /^pie-/i;
+/**
+ * An editing host: `contenteditable` in any state but `false`. A
+ * `contenteditable="false"` island inside a host still belongs to the host's
+ * editor — ProseMirror marks every leaf node that way, images included — so the
+ * test looks past such islands to the nearest host. A read-only editor root
+ * (`contenteditable="false"`) is no host; ProseMirror registers no DOM mutations
+ * while its view is not editable.
+ */
+const EDITING_HOST_SELECTOR = '[contenteditable]:not([contenteditable="false" i])';
 function isInsidePieCustomElement(node, root) {
     let ancestor = node.parentElement;
     while (ancestor && ancestor !== root) {
@@ -49,6 +63,8 @@ export function wrapOverwideInElement(root, spec, options = {}) {
         // Authored-markup pass: leave PIE custom-element internals alone.
         if (skipPieDescendants && isInsidePieCustomElement(node, root))
             continue;
+        if (node.closest(EDITING_HOST_SELECTOR))
+            continue;
         const wrapper = ownerDocument.createElement(spec.wrapperTag);
         wrapper.className = spec.wrapperClass;
         wrapper.setAttribute("tabindex", "0");

package/dist/timed-media/policy.js

@@ -6,6 +6,7 @@
  * reports them as a framework error and delivers as an ordinary section, which is
  * loud without costing the learner the content.
  */
+import { normalizeMediaFragment } from "../media/index.js";
 /**
  * Applied when `playbackPolicy` is absent entirely. The restrictive values are
  * the defaults because a timed-media section is authored to sequence: a section
@@ -43,21 +44,6 @@ function isCorrectnessCondition(condition) {
 function trimmed(value) {
     return typeof value === "string" ? value.trim() : "";
 }
-function normalizeRange(value) {
-    if (!value || typeof value !== "object")
-        return null;
-    const raw = value;
-    const start = Number(raw.startSeconds);
-    if (!Number.isFinite(start) || start < 0)
-        return null;
-    const end = Number(raw.endSeconds);
-    // An end at or before the start is a window that can never contain a
-    // position, so it is treated as no end — the same rule
-    // `normalizeMediaFragment` applies in the toolkit, kept identical on purpose.
-    if (!Number.isFinite(end) || end <= start)
-        return { startSeconds: start };
-    return { startSeconds: start, endSeconds: end };
-}
 function normalizePlaybackPolicy(value) {
     if (value === undefined || value === null) {
         return { policy: { ...TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS }, error: null };
@@ -179,7 +165,10 @@ export function normalizeTimedMediaSectionData(args) {
             continue;
         }
         seenIdentifiers.add(identifier);
-        const range = normalizeRange(cue.range);
+        // The same rule as every other authored media range: an end at or before
+        // the start is a window that can never contain a position, so it is
+        // treated as no end.
+        const range = normalizeMediaFragment(cue.range);
         if (!range) {
             errors.push({
                 code: "invalid-cue-range",