@pie-players/pie-assessment-player 0.3.70 → 0.3.72

package/README.md

@@ -33,14 +33,32 @@ const controller =
   host?.getAssessmentController?.();
 ```
 
-`waitForAssessmentController(timeoutMs)` resolves once the controller has
-been wired (the same signal the
-`AssessmentPlayerHooks.onAssessmentControllerReady(controller)` hook fires
-on). Use `getAssessmentController()` if you've already passed the readiness
-anchor synchronously.
+`waitForAssessmentController(timeoutMs)` resolves after initialization and
+hydration succeed. At that point the getter, ready hook, and ready event all
+observe the same controller. The getter returns `null` while initialization is
+pending or failed, and after disconnect. A waiter resolves to `null` when its
+active attempt fails or is retired, or its own timeout expires. A waiter's
+timeout does not cancel a still-active initialization.
+
+Connect the element and assign `assessmentId`, `attemptId`, `assessment`, and
+`hooks` in the same turn, or assign them before connecting. These assignments
+are batched; changing assessment, attempt, or hooks later retires the previous
+controller and starts a new one. Replace object properties to update them;
+mutating a previously assigned object in place is not an update signal. Runtime
+props, locale, and navigation visibility do not reload the assessment.
+
+Failed initialization exposes an error and a keyboard-accessible Retry action.
+The element invokes the ready hook and emits the ready event once per successful
+initialization. Ready hooks are notifications: their rejection reaches `onError`
+and `assessment-error` without undoing successful hydration.
 
 ### Lifecycle
 
+The element owns its assessment controller and calls its idempotent `dispose()`
+when inputs replace the attempt or the element disconnects. Disposal removes
+listeners and makes the old handle unusable. The nested toolkit disposes any
+coordinator it created; a coordinator supplied by the host remains host-owned.
+
 ```ts
 // hydrate runs as part of initialize(); call it again only on a manual reload.
 const unsubscribe = controller.subscribe(handleEvent);
@@ -61,6 +79,15 @@ shape the persistence strategy load/save methods exchange and the same
 shape per-section bridges roll up into via `updateSectionSession(sectionId,
 snapshot)`.
 
+The default element captures the outgoing section before navigation replaces it,
+including navigation through the controller. A returning section waits for its
+canonical `engine-ready` stage and restores its saved section snapshot before
+accepting input or session updates. The section region stays `aria-busy` during
+this handoff. Failed restoration leaves the saved snapshot intact, reports
+`assessment-error` and `onError` with phase `navigation`, and offers Retry.
+Navigating away or disconnecting retires that handoff. This in-memory restoration
+does not acknowledge durable saves; persistence still uses the host's strategy.
+
 ### Event stream
 
 The controller's typed event stream

package/dist/components/AssessmentPlayerDefaultElement.d.ts

@@ -4,25 +4,27 @@ import { AssessmentPlayerProgressSnapshot, AssessmentPlayerRuntimeHostContract,
 import { AssessmentDefinition, AssessmentPlayerHooks, AssessmentPlayerRuntimeConfig } from '../types.js';
 export declare class AssessmentPlayerDefaultElement extends HTMLElement implements AssessmentPlayerRuntimeHostContract {
     static get observedAttributes(): string[];
-    assessmentId: string;
-    attemptId: string;
+    private _assessmentId;
+    private _attemptId;
     /**
      * Interface locale for this player's own navigation chrome, as a BCP-47 tag.
      * Empty means the graceful default, `en-US`. Also forwarded to the section
      * element, which passes it on to the toolkit.
      */
-    locale: string;
-    assessment: AssessmentDefinition | null;
-    env: Env | null;
-    coordinator: unknown;
-    hooks: AssessmentPlayerHooks | null;
-    showNavigation: boolean | string | null | undefined;
-    sectionPlayerLayout: "splitpane" | "vertical";
-    playerType: "iife" | "esm" | "preloaded";
+    private _locale;
+    private _assessment;
+    private _env;
+    private _coordinator;
+    private _hooks;
+    private _showNavigation;
+    private _sectionPlayerLayout;
+    private _playerType;
     private _debug;
     private controller;
-    private controllerReadyPromise;
-    private controllerReadyResolve;
+    private initializingController;
+    private generation;
+    private reconcileQueued;
+    private controllerWaiters;
     /**
      * This player's own provider rather than a context read. Its navigation sits
      * beside the section host, not inside it, so there is no published toolkit
@@ -33,6 +35,8 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     private unsubscribeI18n?;
     private sectionHost;
     private sectionControllerRef;
+    private sectionSessionReady;
+    private detachSectionListeners?;
     /**
      * Rendered content, tracked so a re-render can replace it without clearing the
      * announcer below. A live region only announces changes that happen while it is
@@ -51,8 +55,27 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     private detachInstrumentationBridge?;
     private _sectionPlayerRuntime;
     private readiness;
-    constructor();
-    attributeChangedCallback(name: string, _oldValue: string | null, value: string | null): void;
+    get assessmentId(): string;
+    set assessmentId(value: string);
+    get attemptId(): string;
+    set attemptId(value: string);
+    get assessment(): AssessmentDefinition | null;
+    set assessment(value: AssessmentDefinition | null);
+    get hooks(): AssessmentPlayerHooks | null;
+    set hooks(value: AssessmentPlayerHooks | null);
+    get locale(): string;
+    set locale(value: string);
+    get env(): Env | null;
+    set env(value: Env | null);
+    get coordinator(): unknown;
+    set coordinator(value: unknown);
+    get showNavigation(): boolean | string | null | undefined;
+    set showNavigation(value: boolean | string | null | undefined);
+    get sectionPlayerLayout(): "splitpane" | "vertical";
+    set sectionPlayerLayout(value: "splitpane" | "vertical");
+    get playerType(): "iife" | "esm" | "preloaded";
+    set playerType(value: "iife" | "esm" | "preloaded");
+    attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
     /**
      * Catalog loading is async, so the first paint carries whatever the provider
      * already holds and the subscription repaints once the requested locale
@@ -70,11 +93,15 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     set sectionPlayerRuntime(value: AssessmentPlayerRuntimeConfig["sectionPlayerRuntime"]);
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private settleControllerWaiters;
+    private retireController;
+    private queueReconciliation;
     private dispatch;
     private bootstrapController;
     private resolveInstrumentationProvider;
     private attachInstrumentationBridge;
     private renderEmptyState;
+    private createStatusContent;
     /**
      * Replace the rendered content, leaving the announcer in place.
      */
@@ -108,6 +135,8 @@ export declare class AssessmentPlayerDefaultElement extends HTMLElement implemen
     private syncCurrentSectionSessionIntoAssessment;
     private attachSectionControllerReadyListener;
     private render;
+    /** Locale and chrome changes must not remount a section or reload its attempt. */
+    private updateNavigationChrome;
     /**
      * Announce the new position, once the live region has been in the document long
      * enough for the change to register as a change.

package/dist/controller/AssessmentController.d.ts

@@ -62,13 +62,15 @@ export type AssessmentControllerEvent = {
 export interface AssessmentControllerHandle {
     /**
      * Bootstrap the controller: build the delivery plan, ensure a
-     * session exists, run `hydrate()`, and fire
-     * `onAssessmentControllerReady`.
+     * session exists, and run `hydrate()` once. The owning element
+     * publishes readiness and invokes `onAssessmentControllerReady`.
      *
      * Called by the assessment player when the player CE mounts. Hosts
      * normally do not call this directly.
      */
     initialize(): Promise<void>;
+    /** Retire this attempt, detach listeners, and notify its disposal hook once. */
+    dispose(): Promise<void>;
     /**
      * Load and apply a previously persisted assessment session via the
      * registered `AssessmentSessionPersistenceStrategy`. Falls back to
@@ -173,6 +175,9 @@ export declare class AssessmentController implements AssessmentControllerHandle
     private readiness;
     private submitted;
     private persistenceStrategy?;
+    private initializationPromise?;
+    private disposalPromise?;
+    private disposed;
     private readonly storageContext;
     constructor(args: {
         assessmentId: string;
@@ -181,12 +186,15 @@ export declare class AssessmentController implements AssessmentControllerHandle
         hooks?: AssessmentPlayerHooks;
     });
     private emit;
+    private assertActive;
     private handleError;
     private getPersistenceStrategy;
     private createDeliveryPlan;
     private ensureSession;
     initialize(): Promise<void>;
+    private initializeOnce;
     hydrate(): Promise<void>;
+    dispose(): Promise<void>;
     persist(): Promise<void>;
     getSession(): AssessmentSession | null;
     getRuntimeState(): AssessmentControllerRuntimeState;

package/dist/{nl-NL-BnK-g-oc.js → nl-NL-FLtEAIq9.js}

@@ -60,7 +60,9 @@ var e = {
     resizePassageAndMediaA11y: "Panelen met tekst en media verkleinen of vergroten",
     assessment: {
       sectionPosition: "Onderdeel {position} van {total}",
-      noSections: "Geen onderdelen"
+      noSections: "Geen onderdelen",
+      loadFailed: "De toets kon niet worden geladen. Probeer het opnieuw.",
+      restoreFailed: "Je opgeslagen antwoorden voor dit onderdeel konden niet worden hersteld. Probeer het opnieuw."
     },
     formative: {
       checkAnswer: "Antwoord controleren",