@pie-players/pie-assessment-player 0.3.74 → 1.0.0-beta.0

package/custom-elements.json

@@ -0,0 +1,521 @@
+{
+	"schemaVersion": "2.1.0",
+	"modules": [
+		{
+			"kind": "javascript-module",
+			"path": "dist/pie-assessment-player.js",
+			"declarations": [
+				{
+					"kind": "class",
+					"description": "Reference multi-section assessment player. A host gives it an `assessment` definition and `assessment-id`, optionally with `attempt-id`, `session` and `hooks`; it creates an `AssessmentController` for the attempt, mounts the current section in a split-pane or vertical section player, and renders the section position with Back and Next controls.",
+					"name": "AssessmentPlayerDefaultElement",
+					"tagName": "pie-assessment-player-default",
+					"customElement": true,
+					"superclass": {
+						"name": "HTMLElement"
+					},
+					"members": [
+						{
+							"kind": "field",
+							"name": "assessmentId",
+							"type": {
+								"text": "string"
+							},
+							"attribute": "assessment-id"
+						},
+						{
+							"kind": "field",
+							"name": "attemptId",
+							"type": {
+								"text": "string"
+							},
+							"attribute": "attempt-id"
+						},
+						{
+							"kind": "field",
+							"name": "assessment",
+							"type": {
+								"text": "AssessmentDefinition | null"
+							}
+						},
+						{
+							"kind": "field",
+							"name": "hooks",
+							"type": {
+								"text": "AssessmentPlayerHooks | null"
+							}
+						},
+						{
+							"kind": "field",
+							"name": "session",
+							"type": {
+								"text": "AssessmentSession | null"
+							},
+							"description": "Before a controller is ready, the assigned session; after, a copy of the controller's."
+						},
+						{
+							"kind": "field",
+							"name": "locale",
+							"type": {
+								"text": "string"
+							},
+							"attribute": "locale"
+						},
+						{
+							"kind": "field",
+							"name": "env",
+							"type": {
+								"text": "Env | null"
+							}
+						},
+						{
+							"kind": "field",
+							"name": "coordinator",
+							"type": {
+								"text": "unknown"
+							}
+						},
+						{
+							"kind": "field",
+							"name": "showNavigation",
+							"type": {
+								"text": "boolean | string | null | undefined"
+							},
+							"attribute": "show-navigation"
+						},
+						{
+							"kind": "field",
+							"name": "sectionPlayerLayout",
+							"type": {
+								"text": "\"splitpane\" | \"vertical\""
+							},
+							"attribute": "section-player-layout"
+						},
+						{
+							"kind": "field",
+							"name": "playerType",
+							"type": {
+								"text": "\"iife\" | \"esm\" | \"preloaded\""
+							},
+							"attribute": "player-type"
+						},
+						{
+							"kind": "field",
+							"name": "debug",
+							"type": {
+								"text": "boolean | string | null | undefined"
+							},
+							"attribute": "debug"
+						},
+						{
+							"kind": "field",
+							"name": "sectionPlayerRuntime",
+							"type": {
+								"text": "AssessmentPlayerRuntimeConfig[\"sectionPlayerRuntime\"]"
+							}
+						},
+						{
+							"kind": "method",
+							"name": "getSnapshot",
+							"return": {
+								"type": {
+									"text": "AssessmentPlayerSnapshot"
+								}
+							}
+						},
+						{
+							"kind": "method",
+							"name": "selectNavigation"
+						},
+						{
+							"kind": "method",
+							"name": "selectReadiness"
+						},
+						{
+							"kind": "method",
+							"name": "selectProgress",
+							"return": {
+								"type": {
+									"text": "AssessmentPlayerProgressSnapshot"
+								}
+							}
+						},
+						{
+							"kind": "method",
+							"name": "navigateTo",
+							"parameters": [
+								{
+									"name": "indexOrIdentifier",
+									"type": {
+										"text": "number | string"
+									}
+								}
+							],
+							"return": {
+								"type": {
+									"text": "boolean"
+								}
+							}
+						},
+						{
+							"kind": "method",
+							"name": "navigateNext",
+							"return": {
+								"type": {
+									"text": "boolean"
+								}
+							}
+						},
+						{
+							"kind": "method",
+							"name": "navigatePrevious",
+							"return": {
+								"type": {
+									"text": "boolean"
+								}
+							}
+						},
+						{
+							"kind": "method",
+							"name": "getAssessmentController",
+							"return": {
+								"type": {
+									"text": "AssessmentControllerHandle | null"
+								}
+							}
+						},
+						{
+							"kind": "method",
+							"name": "waitForAssessmentController",
+							"parameters": [
+								{
+									"name": "timeoutMs",
+									"type": {
+										"text": "number"
+									},
+									"optional": true,
+									"default": "5000"
+								}
+							]
+						}
+					],
+					"attributes": [
+						{
+							"name": "assessment-id",
+							"type": {
+								"text": "string"
+							},
+							"fieldName": "assessmentId"
+						},
+						{
+							"name": "attempt-id",
+							"type": {
+								"text": "string"
+							},
+							"fieldName": "attemptId"
+						},
+						{
+							"name": "show-navigation",
+							"type": {
+								"text": "boolean | string | null | undefined"
+							},
+							"fieldName": "showNavigation"
+						},
+						{
+							"name": "section-player-layout",
+							"type": {
+								"text": "\"splitpane\" | \"vertical\""
+							},
+							"fieldName": "sectionPlayerLayout"
+						},
+						{
+							"name": "player-type",
+							"type": {
+								"text": "\"iife\" | \"esm\" | \"preloaded\""
+							},
+							"fieldName": "playerType"
+						},
+						{
+							"name": "debug",
+							"type": {
+								"text": "boolean | string | null | undefined"
+							},
+							"fieldName": "debug"
+						},
+						{
+							"name": "locale",
+							"type": {
+								"text": "string"
+							},
+							"fieldName": "locale"
+						}
+					],
+					"events": [
+						{
+							"name": "assessment-controller-ready",
+							"type": {
+								"text": "CustomEvent<{ controller: AssessmentControllerHandle }>"
+							},
+							"description": "When the controller has initialized and hydrated the attempt."
+						},
+						{
+							"name": "assessment-navigation-requested",
+							"type": {
+								"text": "CustomEvent<AssessmentNavigationRequestedDetail>"
+							},
+							"description": "Before Back, Next or a navigate method moves to another section, cancelable to stay."
+						},
+						{
+							"name": "assessment-route-changed",
+							"type": {
+								"text": "CustomEvent<AssessmentRouteChangedDetail>"
+							},
+							"description": "When the current section changes."
+						},
+						{
+							"name": "assessment-session-applied",
+							"type": {
+								"text": "CustomEvent<{ type: \"assessment-session-applied\"; timestamp: number }>"
+							},
+							"description": "When hydration applies a persisted or assigned session."
+						},
+						{
+							"name": "assessment-session-changed",
+							"type": {
+								"text": "CustomEvent<{ type: \"assessment-session-changed\"; timestamp: number }>"
+							},
+							"description": "When navigation or a section snapshot changes the assessment session."
+						},
+						{
+							"name": "assessment-progress-changed",
+							"type": {
+								"text": "CustomEvent<AssessmentProgressChangedDetail>"
+							},
+							"description": "When the visited-section count changes."
+						},
+						{
+							"name": "assessment-submission-state-changed",
+							"type": {
+								"text": "CustomEvent<AssessmentSubmissionStateChangedDetail>"
+							},
+							"description": "When `submit()` records the submission state."
+						},
+						{
+							"name": "assessment-error",
+							"type": {
+								"text": "CustomEvent<{ error: unknown }>"
+							},
+							"description": "When the attempt fails to load, a ready hook rejects, or a section fails to load or restore."
+						}
+					],
+					"x-pie": {
+						"shadow": "none"
+					}
+				},
+				{
+					"kind": "class",
+					"description": "Layout scaffold for a host-composed assessment: host navigation above a body that fills the remaining height. The scaffold renders in an open shadow root and the host's children stay in its light DOM, where document styles reach them, projecting into the slots.",
+					"name": "AssessmentPlayerShellElement",
+					"tagName": "pie-assessment-player-shell",
+					"customElement": true,
+					"superclass": {
+						"name": "HTMLElement"
+					},
+					"members": [
+						{
+							"kind": "field",
+							"name": "showNavigation",
+							"type": {
+								"text": "boolean | string | null | undefined"
+							},
+							"default": "true",
+							"attribute": "show-navigation"
+						}
+					],
+					"attributes": [
+						{
+							"name": "show-navigation",
+							"type": {
+								"text": "boolean | string | null | undefined"
+							},
+							"fieldName": "showNavigation"
+						}
+					],
+					"slots": [
+						{
+							"name": "",
+							"description": "The body: the host's section player and any other assessment UI."
+						},
+						{
+							"name": "navigation",
+							"description": "Assessment navigation above the body; not rendered while `show-navigation` is false."
+						}
+					],
+					"x-pie": {
+						"shadow": "open"
+					}
+				}
+			],
+			"exports": [
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-assessment-player-default",
+					"declaration": {
+						"name": "AssessmentPlayerDefaultElement"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-assessment-player-shell",
+					"declaration": {
+						"name": "AssessmentPlayerShellElement"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-assessment-toolkit",
+					"declaration": {
+						"name": "PieAssessmentToolkit",
+						"module": "dist/components/pie-assessment-toolkit-element.js",
+						"package": "@pie-players/pie-assessment-toolkit"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-item-player",
+					"declaration": {
+						"name": "PieItemPlayer",
+						"module": "dist/pie-item-player.js",
+						"package": "@pie-players/pie-item-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-item-scope",
+					"declaration": {
+						"name": "ItemScope",
+						"module": "dist/components/item-scope-element.js",
+						"package": "@pie-players/pie-assessment-toolkit"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-item-toolbar",
+					"declaration": {
+						"name": "ItemToolBar",
+						"module": "dist/components/item-toolbar-element.js",
+						"package": "@pie-players/pie-assessment-toolkit"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-passage-shell",
+					"declaration": {
+						"name": "PassageShellElement",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-base",
+					"declaration": {
+						"name": "PieSectionPlayerBaseElement",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-item-card",
+					"declaration": {
+						"name": "SectionItemCard",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-items-pane",
+					"declaration": {
+						"name": "SectionItemsPane",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-kernel-host",
+					"declaration": {
+						"name": "PieSectionPlayerKernelHostElement",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-passage-card",
+					"declaration": {
+						"name": "SectionPassageCard",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-passages-pane",
+					"declaration": {
+						"name": "SectionPassagesPane",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-shell",
+					"declaration": {
+						"name": "SectionPlayerShell",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-splitpane",
+					"declaration": {
+						"name": "PieSectionPlayerSplitPaneElement",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-tabbed",
+					"declaration": {
+						"name": "PieSectionPlayerTabbedElement",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-player-vertical",
+					"declaration": {
+						"name": "PieSectionPlayerVerticalElement",
+						"module": "dist/pie-section-player.js",
+						"package": "@pie-players/pie-section-player"
+					}
+				},
+				{
+					"kind": "custom-element-definition",
+					"name": "pie-section-toolbar",
+					"declaration": {
+						"name": "SectionToolBar",
+						"module": "dist/components/section-toolbar-element.js",
+						"package": "@pie-players/pie-assessment-toolkit"
+					}
+				}
+			]
+		}
+	]
+}

package/dist/components/AssessmentPlayerDefaultElement.d.ts

@@ -1,7 +1,32 @@
 import { Env } from '@pie-players/pie-players-shared/types';
 import { AssessmentControllerHandle } from '../controller/AssessmentController.js';
 import { AssessmentPlayerProgressSnapshot, AssessmentPlayerRuntimeHostContract, AssessmentPlayerSnapshot } from '../contracts/runtime-host-contract.js';
-import { AssessmentDefinition, AssessmentPlayerHooks, AssessmentPlayerRuntimeConfig } from '../types.js';
+import { AssessmentDefinition, AssessmentPlayerHooks, AssessmentPlayerRuntimeConfig, AssessmentSession } from '../types.js';
+/**
+ * Reference multi-section assessment player. A host gives it an `assessment`
+ * definition and `assessment-id`, optionally with `attempt-id`, `session` and
+ * `hooks`; it creates an `AssessmentController` for the attempt, mounts the
+ * current section in a split-pane or vertical section player, and renders the
+ * section position with Back and Next controls.
+ *
+ * @fires {CustomEvent<{ controller: AssessmentControllerHandle }>} assessment-controller-ready -
+ *   When the controller has initialized and hydrated the attempt.
+ * @fires {CustomEvent<AssessmentNavigationRequestedDetail>} assessment-navigation-requested -
+ *   Before Back, Next or a navigate method moves to another section, cancelable
+ *   to stay.
+ * @fires {CustomEvent<AssessmentRouteChangedDetail>} assessment-route-changed -
+ *   When the current section changes.
+ * @fires {CustomEvent<{ type: "assessment-session-applied"; timestamp: number }>} assessment-session-applied -
+ *   When hydration applies a persisted or assigned session.
+ * @fires {CustomEvent<{ type: "assessment-session-changed"; timestamp: number }>} assessment-session-changed -
+ *   When navigation or a section snapshot changes the assessment session.
+ * @fires {CustomEvent<AssessmentProgressChangedDetail>} assessment-progress-changed -
+ *   When the visited-section count changes.
+ * @fires {CustomEvent<AssessmentSubmissionStateChangedDetail>} assessment-submission-state-changed -
+ *   When `submit()` records the submission state.
+ * @fires {CustomEvent<{ error: unknown }>} assessment-error - When the attempt
+ *   fails to load, a ready hook rejects, or a section fails to load or restore.
+ */
 export declare class AssessmentPlayerDefaultElement extends HTMLElement implements AssessmentPlayerRuntimeHostContract {
     static get observedAttributes(): string[];
     private _assessmentId;
@@ -16,6 +41,13 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     private _env;
     private _coordinator;
     private _hooks;
+    /**
+     * The assigned session until a controller initializes from it. A later
+     * rebuild, such as one an `assessment` change causes, hydrates from the
+     * persistence strategy rather than reapplying a value the learner has since
+     * moved past.
+     */
+    private pendingSession;
     private _showNavigation;
     private _sectionPlayerLayout;
     private _playerType;
@@ -63,6 +95,12 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     set assessment(value: AssessmentDefinition | null);
     get hooks(): AssessmentPlayerHooks | null;
     set hooks(value: AssessmentPlayerHooks | null);
+    /**
+     * Before a controller is ready, the assigned session; after, a copy of the
+     * controller's.
+     */
+    get session(): AssessmentSession | null;
+    set session(value: AssessmentSession | null);
     get locale(): string;
     set locale(value: string);
     get env(): Env | null;
@@ -133,6 +171,10 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     private updateCurrentSectionRuntime;
     private cleanupTtsForSectionNavigation;
     private syncCurrentSectionSessionIntoAssessment;
+    /**
+     * `restoring` is whether the section was handed a saved session, which it
+     * applies while it creates its controller, before `engine-ready`.
+     */
     private attachSectionControllerReadyListener;
     private render;
     /** Locale and chrome changes must not remount a section or reload its attempt. */

package/dist/components/AssessmentPlayerShellElement.d.ts

@@ -1,6 +1,17 @@
+/**
+ * Layout scaffold for a host-composed assessment: host navigation above a body
+ * that fills the remaining height. The scaffold renders in an open shadow root
+ * and the host's children stay in its light DOM, where document styles reach
+ * them, projecting into the slots.
+ *
+ * @slot navigation - Assessment navigation above the body; not rendered while
+ *   `show-navigation` is false.
+ * @slot - The body: the host's section player and any other assessment UI.
+ */
 export declare class AssessmentPlayerShellElement extends HTMLElement {
     static get observedAttributes(): string[];
     showNavigation: boolean | string | null | undefined;
+    constructor();
     connectedCallback(): void;
     attributeChangedCallback(name: string, _oldValue: string | null, value: string | null): void;
     private render;

package/dist/components/assessment-section-player-runtime.d.ts

@@ -3,7 +3,7 @@ import { AssessmentPlayerRuntimeConfig } from '../types.js';
 export type ResolveAssessmentSectionPlayerRuntimeArgs = {
     sectionPlayerRuntime?: AssessmentPlayerRuntimeConfig["sectionPlayerRuntime"];
     playerType: "iife" | "esm" | "preloaded";
-    attemptId?: string;
+    assessmentId?: string;
     env?: Record<string, unknown> | null;
     coordinator?: unknown;
 };

package/dist/controller/AssessmentController.d.ts

@@ -83,8 +83,8 @@ export interface AssessmentControllerHandle {
      * persistence strategy.
      *
      * Hosts call this on whatever cadence they choose (debounced on
-     * change, on visibility change, on submit). `submit()` always
-     * `persist()`s as its final step.
+     * change, on visibility change, on submit). Saves run in call order.
+     * A failed save goes to `onError` and the returned promise resolves.
      */
     persist(): Promise<void>;
     /**
@@ -123,9 +123,9 @@ export interface AssessmentControllerHandle {
      */
     navigatePrevious(): boolean;
     /**
-     * Mark the assessment as submitted, emit
-     * `assessment-submission-state-changed`, and `persist()` the final
-     * snapshot.
+     * Save the final snapshot, then mark the assessment as submitted and
+     * emit `assessment-submission-state-changed`. A failed save goes to
+     * `onError` and rejects, and the assessment stays unsubmitted.
      */
     submit(): Promise<void>;
     /**
@@ -174,20 +174,34 @@ export declare class AssessmentController implements AssessmentControllerHandle
     private session;
     private readiness;
     private submitted;
+    private saveQueue;
     private persistenceStrategy?;
     private initializationPromise?;
     private disposalPromise?;
     private disposed;
     private readonly storageContext;
+    /** Taken by the first hydrate; a later `hydrate()` loads from the strategy. */
+    private initialSession;
     constructor(args: {
         assessmentId: string;
         attemptId?: string;
         assessment: AssessmentDefinition | null;
         hooks?: AssessmentPlayerHooks;
+        /**
+         * A host-supplied session, applied by the first hydrate in place of the
+         * persistence strategy's `loadSession` result. The controller keeps a
+         * copy, so later updates never write into the host's object.
+         */
+        initialSession?: AssessmentSession | null;
     });
     private emit;
     private assertActive;
     private handleError;
+    /**
+     * Marks a live controller failed and reports through `onError` when a phase is
+     * given. A throwing hook is logged so the caller still rethrows the original.
+     */
+    private reportFailure;
     private getPersistenceStrategy;
     private createDeliveryPlan;
     private ensureSession;
@@ -196,6 +210,11 @@ export declare class AssessmentController implements AssessmentControllerHandle
     hydrate(): Promise<void>;
     dispose(): Promise<void>;
     persist(): Promise<void>;
+    /**
+     * Saves run one at a time, in call order, so a slow older write can never
+     * land after a newer one. A failed save rejects only its own caller.
+     */
+    private save;
     getSession(): AssessmentSession | null;
     getRuntimeState(): AssessmentControllerRuntimeState;
     private buildNavigationSnapshot;