@pie-players/pie-players-shared 0.3.75 → 1.0.0-beta.0

package/dist/media/index.d.ts

@@ -2,12 +2,10 @@
  * Validation primitives shared by every catalog card whose payload references
  * media.
  *
- * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
- * audio form: both card types take authored, wire-facing URLs and hand them to a
- * media element in the learner's browser, so both need the same scheme
- * allow-list and the same "treat as absent, never as partially valid" posture.
- * Two copies of a URL allow-list is one copy that gets a fix and one that does
- * not.
+ * `sign-language` and recorded `spoken` cards both hand authored, wire-facing
+ * URLs to a media element in the learner's browser, so both take the same
+ * scheme allow-list and the same "treat as absent, never as partially valid"
+ * posture from here.
  *
  * Lives here, behind its own subpath, so a PIE element can validate authored
  * media without importing the assessment toolkit, whose root entry declares

package/dist/media/index.js

@@ -2,12 +2,10 @@
  * Validation primitives shared by every catalog card whose payload references
  * media.
  *
- * Extracted from `sign-language-cards.ts` when `spoken` cards gained a recorded
- * audio form: both card types take authored, wire-facing URLs and hand them to a
- * media element in the learner's browser, so both need the same scheme
- * allow-list and the same "treat as absent, never as partially valid" posture.
- * Two copies of a URL allow-list is one copy that gets a fix and one that does
- * not.
+ * `sign-language` and recorded `spoken` cards both hand authored, wire-facing
+ * URLs to a media element in the learner's browser, so both take the same
+ * scheme allow-list and the same "treat as absent, never as partially valid"
+ * posture from here.
  *
  * Lives here, behind its own subpath, so a PIE element can validate authored
  * media without importing the assessment toolkit, whose root entry declares
@@ -21,7 +19,7 @@
  * Relative and protocol-relative URLs are allowed — host content is commonly
  * served from the same origin as the player.
  */
-const DISALLOWED_SRC_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+const URL_SCHEME_PREFIX = /^[a-z][a-z0-9+.-]*:/i;
 const ALLOWED_SRC_SCHEMES = new Set(["http:", "https:", "data:", "blob:"]);
 /**
  * The only `MediaAssetRef.version` this build renders.
@@ -53,7 +51,7 @@ export function isSafeMediaSrc(raw) {
         return false;
     // Relative ("/video.mp4", "video.mp4") and protocol-relative ("//cdn/x.mp4")
     // forms carry no scheme to check and inherit the document's.
-    if (src.startsWith("//") || !DISALLOWED_SRC_SCHEME.test(src))
+    if (src.startsWith("//") || !URL_SCHEME_PREFIX.test(src))
         return true;
     const scheme = src.slice(0, src.indexOf(":") + 1).toLowerCase();
     return ALLOWED_SRC_SCHEMES.has(scheme);

package/dist/object/index.d.ts

@@ -1,7 +1,7 @@
 /**
- * A problem using the spread operator merging objects is that undefined properties may override
- * defined properties, which is often NOT what you want (e.g. when providing default values). This
- * function merges objects, but ignores properties that are null or undefined.
+ * Merges objects left to right, skipping properties whose value is `null` or
+ * `undefined`, so a later object's unset field never overrides an earlier
+ * default the way object spread does.
  * @param objects The objects to merge.
  */
 export declare const mergeObjectsIgnoringNullUndefined: <T extends object>(...objects: T[]) => T;
@@ -9,3 +9,8 @@ export declare const mergeObjectsIgnoringNullUndefined: <T extends object>(...ob
  * Deep clone an object.
  */
 export declare const cloneDeep: <T>(value: T) => T;
+/**
+ * A non-null object that is not an array. The prototype is not checked, so
+ * class instances pass.
+ */
+export declare const isPlainRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/object/index.js

@@ -1,7 +1,7 @@
 /**
- * A problem using the spread operator merging objects is that undefined properties may override
- * defined properties, which is often NOT what you want (e.g. when providing default values). This
- * function merges objects, but ignores properties that are null or undefined.
+ * Merges objects left to right, skipping properties whose value is `null` or
+ * `undefined`, so a later object's unset field never overrides an earlier
+ * default the way object spread does.
  * @param objects The objects to merge.
  */
 export const mergeObjectsIgnoringNullUndefined = (...objects) => {
@@ -21,14 +21,11 @@ export const mergeObjectsIgnoringNullUndefined = (...objects) => {
  */
 export const cloneDeep = (value) => {
     if (value === null || typeof value !== "object") {
-        // Primitive value (or null), just return it
         return value;
     }
     if (Array.isArray(value)) {
-        // Array: clone each element recursively
         return value.map(cloneDeep);
     }
-    // Object: create a new object and clone its properties
     const copy = {};
     for (const key in value) {
         if (Object.hasOwn(value, key)) {
@@ -37,3 +34,8 @@ export const cloneDeep = (value) => {
     }
     return copy;
 };
+/**
+ * A non-null object that is not an array. The prototype is not checked, so
+ * class instances pass.
+ */
+export const isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);

package/dist/pie/asset-handler.d.ts

@@ -5,23 +5,6 @@
  * Provides default DataURL-based implementation and event management.
  */
 import { type ImageHandler, type SoundHandler } from "../types/index.js";
-import type { AssetHandler } from "./types.js";
-/**
- * DataURL-based asset handler (default implementation)
- *
- * Converts uploaded files to base64 data URLs.
- * Suitable for demos and local development.
- */
-export declare class DataURLAssetHandler implements AssetHandler {
-    private onComplete;
-    private cancelled;
-    private fileReader;
-    constructor(onComplete: (src: string) => void);
-    cancel(): void;
-    done(err?: Error, src?: string): void;
-    fileChosen(file: File): void;
-    progress(percent: number, bytes: number, total: number): void;
-}
 /**
  * Asset Event Manager
  *

package/dist/pie/asset-handler.js

@@ -13,7 +13,7 @@ const logger = createPieLogger("asset-handler", () => isGlobalDebugEnabled());
  * Converts uploaded files to base64 data URLs.
  * Suitable for demos and local development.
  */
-export class DataURLAssetHandler {
+class DataURLAssetHandler {
     onComplete;
     cancelled = false;
     fileReader = null;

package/dist/pie/authoring.js

@@ -2,10 +2,8 @@ import { AssetEventManager } from "./asset-handler.js";
 import { createPieLogger, isGlobalDebugEnabled } from "./logger.js";
 import { findPieController } from "./scoring.js";
 import { parsePackageName } from "./utils.js";
+import { isPlainRecord } from "../object/index.js";
 const logger = createPieLogger("authoring", () => isGlobalDebugEnabled());
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}
 function packageNameWithoutVersion(packageSpec) {
     try {
         return parsePackageName(packageSpec).name;
@@ -19,7 +17,7 @@ function packageBaseName(packageName) {
     return lastSegment || packageName;
 }
 function lookupOwn(source, keys) {
-    if (!isRecord(source))
+    if (!isPlainRecord(source))
         return undefined;
     for (const key of keys) {
         if (Object.hasOwn(source, key)) {
@@ -32,7 +30,7 @@ function mergeConfiguration(deliveryConfig, authoringConfig) {
     if (authoringConfig === undefined) {
         return deliveryConfig ?? {};
     }
-    if (isRecord(deliveryConfig) && isRecord(authoringConfig)) {
+    if (isPlainRecord(deliveryConfig) && isPlainRecord(authoringConfig)) {
         return {
             ...deliveryConfig,
             ...authoringConfig,
@@ -108,9 +106,9 @@ function resolveValidationController(configureElement) {
 // A controller's `validate` returns a field → message map. ebsr returns one map
 // per part, so an empty ebsr result is `{ partA: {}, partB: {} }`.
 function hasValidationErrors(errors) {
-    if (!isRecord(errors))
+    if (!isPlainRecord(errors))
         return false;
-    if (isRecord(errors.partA) && isRecord(errors.partB)) {
+    if (isPlainRecord(errors.partA) && isPlainRecord(errors.partB)) {
         return (Object.keys(errors.partA).length > 0 ||
             Object.keys(errors.partB).length > 0);
     }

package/dist/pie/elements-rendered.d.ts

@@ -16,8 +16,6 @@
  * mutation before it, is missed rather than waited for.
  */
 import type { ConfigEntity } from "../types/index.js";
-/** Longer than the 50ms render debounce legacy elements use, plus a scheduler task. */
-export declare const ELEMENT_RENDER_QUIET_MS = 200;
 /**
  * Resolves once every element of `configs` in `root` has rendered, or when
  * `signal` aborts. Never rejects.

package/dist/pie/elements-rendered.js

@@ -16,7 +16,7 @@
  * mutation before it, is missed rather than waited for.
  */
 /** Longer than the 50ms render debounce legacy elements use, plus a scheduler task. */
-export const ELEMENT_RENDER_QUIET_MS = 200;
+const ELEMENT_RENDER_QUIET_MS = 200;
 function hasContent(element) {
     if (element.firstElementChild || element.shadowRoot?.firstChild)
         return true;

package/dist/pie/initialization.d.ts

@@ -1,8 +1,9 @@
 /**
  * PIE Initialization Module
  *
- * Bundle loading and element initialization logic.
- * This is the core of the PIE player system.
+ * Loads IIFE bundles into `window.pie`, defines their elements and records
+ * them in the PIE registry, and binds config and session to the elements in
+ * the container.
  */
 import type { ConfigEntity } from "../types/index.js";
 import type { LoadPieElementsOptions } from "./types.js";
@@ -26,13 +27,11 @@ import type { LoadPieElementsOptions } from "./types.js";
  *   the existing `MutationObserver` / `updatePieElements` flow binds
  *   them on the next reactive pass.
  *
- * The original blanket `window.pie not found; was the bundle inlined
- * correctly?` error has been removed: in the section-player + item-player
- * composition it produced a confusing red stack trace for a routine
- * timing condition that the host already handles. Genuine failures
- * (bundle not loaded by *anyone*) still surface — every unregistered tag
- * gets its own warning, and `updatePieElements` later reports any tag
- * that never resolves.
+ * A missing `window.pie` raises no error: in the section-player and
+ * item-player composition it is a routine timing condition the host already
+ * handles. A bundle nobody loaded still surfaces, as a warning per
+ * unregistered tag and as an `updatePieElements` report for any tag that
+ * never resolves.
  *
  * Binds the elements present in `opts.container` now. Elements that arrive
  * later are the container owner's concern: a player with a lifecycle calls
@@ -53,13 +52,13 @@ export declare const loadPieModule: (config: ConfigEntity, session: any[], opts?
     session: any[];
 }>;
 /**
- * Load a PIE bundle from a JavaScript string into window.pie (IIFE bundles only)
- * This only registers elements and controllers - does NOT initialize them.
- * For initialization, use initializePiesFromLoadedBundle after loading.
+ * Executes an IIFE bundle from a JavaScript string, which populates
+ * `window.pie`. Defines no elements: `initializePiesFromLoadedBundle`
+ * registers and binds them afterwards.
  */
 export declare const loadBundleFromString: (bundleJs: string) => Promise<void>;
 /**
- * Load a PIE bundle from a JavaScript string and initialize elements
- * Convenience wrapper around loadBundleFromString + loadPieModule
+ * Loads a PIE bundle from a JavaScript string and initializes its elements:
+ * `loadPieModule` over a blob URL of the source.
  */
 export declare const loadPieModuleFromString: (bundleJs: string, config: ConfigEntity, session: any[], opts?: LoadPieElementsOptions) => Promise<void>;

package/dist/pie/initialization.js

@@ -1,8 +1,9 @@
 /**
  * PIE Initialization Module
  *
- * Bundle loading and element initialization logic.
- * This is the core of the PIE player system.
+ * Loads IIFE bundles into `window.pie`, defines their elements and records
+ * them in the PIE registry, and binds config and session to the elements in
+ * the container.
  */
 import { BUILDER_BUNDLE_URL } from "../config/profile.js";
 import { DEFAULT_IIFE_BUNDLE_RETRY_CONFIG } from "../loader-config.js";
@@ -17,7 +18,6 @@ import { validateCustomElementTag } from "./tag-names.js";
 import { BundleType, isCustomElementConstructor, isPieAvailable, Status, } from "./types.js";
 import { updatePieElement } from "./updates.js";
 import { getPackageWithoutVersion, getPieElementBundlesUrl, } from "./utils.js";
-// Create module-level logger (respects global debug flag - pass function for dynamic checking)
 const logger = createPieLogger("pie-initialization", () => isGlobalDebugEnabled());
 /**
  * Deadline for `loadPieModule`'s bundle `<script>` load when the caller
@@ -26,7 +26,6 @@ const logger = createPieLogger("pie-initialization", () => isGlobalDebugEnabled(
  * path a host loads it through.
  */
 const DEFAULT_LOAD_TIMEOUT_MS = DEFAULT_IIFE_BUNDLE_RETRY_CONFIG.timeoutMs;
-// Default options for loading PIE elements
 const defaultOptions = {
     buildServiceBase: BUILDER_BUNDLE_URL,
     bundleType: BundleType.player, // Default to player.js (no controllers, server-processed models)
@@ -46,12 +45,10 @@ const updateRegisteredElement = (elementTagName, config, session, options, omitE
     });
 };
 /**
- * Shared element registration logic
- * Extracted from initializePiesFromLoadedBundle and loadPieModule to eliminate ~200 lines of duplication
- *
- * Binds the elements already present in `options.container`. Elements that
- * arrive later are bound by the container owner's observer — see
- * `element-observer.ts`.
+ * Defines the bundle's elements for `config.elements`, records them in the
+ * registry, and binds the elements already present in `options.container`.
+ * Elements that arrive later are bound by the container owner's observer —
+ * see `element-observer.ts`. Returns one promise per defined tag.
  *
  * `elementModule` may be `null`. In that case we cannot register *new*
  * tags (no element constructor source), but we can still update tags
@@ -120,59 +117,55 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
                 : [],
             bundleType: options.bundleType,
         });
-        {
-            // Register the element in our registry. A package without a
-            // controller, such as a legacy `@pie-element/protractor`, renders
-            // the model it is given under client-player.js too.
-            logger.debug(`[registerPieElementsFromBundle] Registering ${elName} in registry${elementData.controller
-                ? " with controller"
-                : " (no controller; its model is used as given)"}`);
-            writeRegistryEntry({
-                package: pkg,
-                status: Status.loading,
-                tagName: elementTagName,
-                controller: elementData.controller || null,
-                config: elementData.config,
+        // A package without a controller, such as a legacy
+        // `@pie-element/protractor`, renders the model it is given under
+        // client-player.js too.
+        logger.debug(`[registerPieElementsFromBundle] Registering ${elName} in registry${elementData.controller
+            ? " with controller"
+            : " (no controller; its model is used as given)"}`);
+        writeRegistryEntry({
+            package: pkg,
+            status: Status.loading,
+            tagName: elementTagName,
+            controller: elementData.controller || null,
+            config: elementData.config,
+            bundleType: options.bundleType,
+        });
+        if (!isCustomElementConstructor(elementData.Element)) {
+            logger.error(`[registerPieElementsFromBundle] pie.Element for ${pkgStripped} is not a valid custom element constructor.`);
+            return;
+        }
+        defineCustomElementSafely(elementTagName, elementData.Element, `element tag in config.elements for ${String(pkg)}`);
+        // Initialize existing elements
+        const searchRoot = options.container || document;
+        const elements = searchRoot.querySelectorAll(elementTagName);
+        logger.debug(`[registerPieElementsFromBundle] Found ${elements.length} elements for tag '${elementTagName}'`);
+        elements.forEach((el) => {
+            initializePieElement(el, {
+                config,
+                session,
+                env: options.env,
+                eventListeners: options.eventListeners?.[elementTagName],
                 bundleType: options.bundleType,
             });
-            if (isCustomElementConstructor(elementData.Element)) {
-                defineCustomElementSafely(elementTagName, elementData.Element, `element tag in config.elements for ${String(pkg)}`);
-                // Initialize existing elements
-                const searchRoot = options.container || document;
-                const elements = searchRoot.querySelectorAll(elementTagName);
-                logger.debug(`[registerPieElementsFromBundle] Found ${elements.length} elements for tag '${elementTagName}'`);
-                elements.forEach((el) => {
-                    initializePieElement(el, {
-                        config,
-                        session,
-                        env: options.env,
-                        eventListeners: options.eventListeners?.[elementTagName],
-                        bundleType: options.bundleType,
-                    });
-                });
-                writeRegistryEntry({
-                    ...registry[elementTagName],
-                    status: Status.loaded,
-                });
-                promises.push(customElements.whenDefined(elementTagName).then(() => {
-                    logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
+        });
+        writeRegistryEntry({
+            ...registry[elementTagName],
+            status: Status.loaded,
+        });
+        promises.push(customElements.whenDefined(elementTagName).then(() => {
+            logger.debug("[registerPieElementsFromBundle] defined custom PIE element: %s", elementTagName);
+        }));
+        if (options.bundleType === BundleType.editor) {
+            if (isCustomElementConstructor(elementData.Configure)) {
+                const editorElName = getEditorElementTagName(elementTagName, String(pkg));
+                defineCustomElementSafely(editorElName, elementData.Configure, `editor element tag for ${String(pkg)}`);
+                promises.push(customElements.whenDefined(editorElName).then(() => {
+                    logger.debug(`[registerPieElementsFromBundle] defined custom PIE editor element: ${editorElName}`);
                 }));
-                // Handle editor elements if needed
-                if (options.bundleType === BundleType.editor) {
-                    if (isCustomElementConstructor(elementData.Configure)) {
-                        const editorElName = getEditorElementTagName(elementTagName, String(pkg));
-                        defineCustomElementSafely(editorElName, elementData.Configure, `editor element tag for ${String(pkg)}`);
-                        promises.push(customElements.whenDefined(editorElName).then(() => {
-                            logger.debug(`[registerPieElementsFromBundle] defined custom PIE editor element: ${editorElName}`);
-                        }));
-                    }
-                    else {
-                        logger.error(`[registerPieElementsFromBundle] pie.Configure for ${pkgStripped} is not a valid custom element constructor.`, elementData.configure);
-                    }
-                }
             }
             else {
-                logger.error(`[registerPieElementsFromBundle] pie.Element for ${pkgStripped} is not a valid custom element constructor.`);
+                logger.error(`[registerPieElementsFromBundle] pie.Configure for ${pkgStripped} is not a valid custom element constructor.`, elementData.configure);
             }
         }
     });
@@ -198,13 +191,11 @@ const registerPieElementsFromBundle = (elementModule, config, session, registry,
  *   the existing `MutationObserver` / `updatePieElements` flow binds
  *   them on the next reactive pass.
  *
- * The original blanket `window.pie not found; was the bundle inlined
- * correctly?` error has been removed: in the section-player + item-player
- * composition it produced a confusing red stack trace for a routine
- * timing condition that the host already handles. Genuine failures
- * (bundle not loaded by *anyone*) still surface — every unregistered tag
- * gets its own warning, and `updatePieElements` later reports any tag
- * that never resolves.
+ * A missing `window.pie` raises no error: in the section-player and
+ * item-player composition it is a routine timing condition the host already
+ * handles. A bundle nobody loaded still surfaces, as a warning per
+ * unregistered tag and as an `updatePieElements` report for any tag that
+ * never resolves.
  *
  * Binds the elements present in `opts.container` now. Elements that arrive
  * later are the container owner's concern: a player with a lifecycle calls
@@ -282,9 +273,7 @@ export const loadPieModule = async (config, session, opts = {}) => {
                 logger.debug("[loadPieModule] window.pie available");
                 const elementModule = window.pie.default;
                 try {
-                    // Use shared registration logic (returns array of promises)
                     const registrationPromises = registerPieElementsFromBundle(elementModule, config, session, registry, options);
-                    // Wait for all element definitions to complete
                     Promise.all(registrationPromises).then(succeed, fail);
                 }
                 catch (error) {
@@ -321,18 +310,16 @@ export const loadPieModule = async (config, session, opts = {}) => {
     return { session };
 };
 /**
- * Load a PIE bundle from a JavaScript string into window.pie (IIFE bundles only)
- * This only registers elements and controllers - does NOT initialize them.
- * For initialization, use initializePiesFromLoadedBundle after loading.
+ * Executes an IIFE bundle from a JavaScript string, which populates
+ * `window.pie`. Defines no elements: `initializePiesFromLoadedBundle`
+ * registers and binds them afterwards.
  */
 export const loadBundleFromString = async (bundleJs) => {
     await initializeMathRendering();
     await withBlobBundleUrl(bundleJs, { stripSourceMapComment: true }, async (bundleUrl) => {
-        // Create a script tag to execute the bundle
         const script = document.createElement("script");
         script.src = bundleUrl;
         script.type = "text/javascript"; // IIFE bundles are standard JS
-        // Wait for script to load
         await new Promise((resolve, reject) => {
             script.onload = () => resolve();
             script.onerror = () => reject(new Error("Failed to load bundle"));
@@ -342,12 +329,11 @@ export const loadBundleFromString = async (bundleJs) => {
     });
 };
 /**
- * Load a PIE bundle from a JavaScript string and initialize elements
- * Convenience wrapper around loadBundleFromString + loadPieModule
+ * Loads a PIE bundle from a JavaScript string and initializes its elements:
+ * `loadPieModule` over a blob URL of the source.
  */
 export const loadPieModuleFromString = async (bundleJs, config, session, opts = {}) => {
     await withBlobBundleUrl(bundleJs, {}, async (bundleUrl) => {
-        // Use existing loadPieModule with the blob URL
         await loadPieModule(config, session, { ...opts, bundleUrl });
     });
 };

package/dist/pie/item-session-contract.js

@@ -1,3 +1,4 @@
+import { isPlainRecord } from "../object/index.js";
 const DEFAULT_SESSION_ID = "";
 const METADATA_ONLY_SESSION_KEYS = new Set([
     "complete",
@@ -146,9 +147,6 @@ export function hasResponseField(value) {
     }
     return false;
 }
-function isPlainObject(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 function getMetadataComponent(sessionDetail, candidate) {
     if (typeof sessionDetail.component === "string")
         return sessionDetail.component;
@@ -194,7 +192,7 @@ function mergeSessionEntry(existing, incoming) {
     for (const [key, value] of Object.entries(incoming)) {
         const previous = merged[key];
         merged[key] =
-            isPlainObject(previous) && isPlainObject(value)
+            isPlainRecord(previous) && isPlainRecord(value)
                 ? mergeSessionEntry(previous, value)
                 : value;
     }
@@ -334,7 +332,7 @@ function classifyItemSessionChange(args) {
     };
 }
 function hostContainerEntries(hostContainer) {
-    if (!isPlainObject(hostContainer)) {
+    if (!isPlainRecord(hostContainer)) {
         return null;
     }
     // A frozen container is not a live view of anything, and a shared immutable
@@ -355,7 +353,7 @@ function hostContainerEntries(hostContainer) {
     return null;
 }
 function sessionEntryId(value) {
-    if (!isPlainObject(value)) {
+    if (!isPlainRecord(value)) {
         return null;
     }
     const id = value.id;
@@ -405,7 +403,7 @@ export function ensureHostSessionEntries(hostContainer, entryIds) {
  */
 export function projectSessionIntoHostContainer(hostContainer, liveSession) {
     const entries = hostContainerEntries(hostContainer);
-    if (!entries || !isPlainObject(hostContainer)) {
+    if (!entries || !isPlainRecord(hostContainer)) {
         return false;
     }
     const live = normalizeItemSessionContainer(liveSession);
@@ -417,11 +415,11 @@ export function projectSessionIntoHostContainer(hostContainer, liveSession) {
     }
     for (const nextEntry of live.data) {
         const id = sessionEntryId(nextEntry);
-        if (!id || !isPlainObject(nextEntry)) {
+        if (!id || !isPlainRecord(nextEntry)) {
             continue;
         }
         const target = entries.find((entry) => sessionEntryId(entry) === id);
-        if (!isPlainObject(target)) {
+        if (!isPlainRecord(target)) {
             entries.push({ ...nextEntry });
             wrote = true;
             continue;