@pie-players/pie-assessment-player 0.3.73 → 0.3.75

package/README.md

@@ -8,6 +8,9 @@ Primary entrypoint:
 
 - `@pie-players/pie-assessment-player`
 
+The entry is bundler-only: it imports the toolkit, players-shared and the
+section player by bare specifier.
+
 ## AssessmentController
 
 `AssessmentController` is the domain authority for an assessment attempt. It
@@ -40,10 +43,10 @@ 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;
+Connect the element and assign `assessmentId`, `attemptId`, `assessment`,
+`hooks` and `session` in the same turn, or assign them before connecting. These
+assignments are batched; changing assessment, attempt, hooks or session 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.
 
@@ -68,7 +71,8 @@ controller.navigateTo("section-2");
 controller.navigateNext();
 controller.navigatePrevious();
 
-// persist on whatever cadence the host wants; submit() always persists.
+// persist on whatever cadence the host wants; saves run in call order.
+// submit() saves first and rejects, unsubmitted, if that save fails.
 await controller.persist();
 await controller.submit();
 unsubscribe();
@@ -79,10 +83,20 @@ shape the persistence strategy load/save methods exchange and the same
 shape per-section bridges roll up into via `updateSectionSession(sectionId,
 snapshot)`.
 
+The element's `session` property takes that shape too. The controller's first
+hydrate applies an assigned session in place of the strategy's `loadSession`;
+the strategy still receives every `persist()`. The value is consumed once: a
+rebuild for another reason, such as an `assessment` change, hydrates from the
+strategy. Assigning a session equal to the controller's, as writing
+`assessment-session-changed` back into the property does, is a no-op, and so is
+`null` once the controller is ready. Reading `session` returns the assigned value
+until the controller is ready and a copy of the controller's session after.
+
 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
+including navigation through the controller. A returning section receives its
+saved section snapshot as the section player's `session` property, which its
+controller applies before the canonical `engine-ready` stage; the section accepts
+input and session updates from `engine-ready` on. 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
@@ -98,9 +112,11 @@ change only — section-level events flow through the embedded
 
 - `assessment-route-changed` — section-level navigation moved (index / id,
   `previousSectionId`, `canNext` / `canPrevious`).
-- `assessment-session-applied` — `hydrate()` loaded a persisted session.
+- `assessment-session-applied` — `hydrate()` applied a session, persisted or
+  assigned as `session`.
 - `assessment-session-changed` — assessment session mutated (navigation,
-  per-section snapshot upsert).
+  per-section snapshot upsert). The active section's snapshot is upserted once
+  for each `session-changed` it emits.
 - `assessment-progress-changed` — visited-section count flipped.
 - `assessment-submission-state-changed` — `submit()` recorded the final
   state.
@@ -189,16 +205,75 @@ Toolkit tool/backend operational stream (when toolkit is mounted):
 - `pie-tool-backend-call-start|success|error`
 - `pie-tool-library-load-start|success|error`
 
+## Preloaded elements
+
+With `player-type="preloaded"` (or `playerType = "preloaded"`) the section
+players load no element code, and their pre-warm asserts that every tag the
+content names is registered. The host registers the elements with
+`registerPreloadedElements` from `@pie-players/pie-item-player/preloaded`
+before the assessment player mounts:
+
+```ts
+import { registerPreloadedElements } from "@pie-players/pie-item-player/preloaded";
+import * as delivery from "@pie-element/multiple-choice/browser/delivery";
+import * as controller from "@pie-element/multiple-choice/browser/controller";
+import manifest from "../package.json"; // pins "@pie-element/multiple-choice" exactly
+
+registerPreloadedElements(
+  [
+    {
+      tag: "pie-element-multiple-choice",
+      package: "@pie-element/multiple-choice",
+      version: manifest.dependencies["@pie-element/multiple-choice"],
+      element: delivery,
+      controller,
+    },
+  ],
+  { math: { assetRoot: "https://assets.example.com/npm" } },
+);
+```
+
+- A tag missing at pre-warm leaves the section's items unmounted and raises a
+  non-recoverable `element-preload` framework error.
+- Install element packages with `npm install --save-exact`. npm otherwise saves
+  a caret range, which registration rejects as a `version`, and which a fresh
+  install can resolve to another release line: `^13.4.0-next.15` resolves to
+  the legacy `13.4.4`, which has no `./browser/*` modules.
+- Install every pie-elements-ng package from one release, in one install from
+  the same dist-tag, and upgrade them together. Elements whose `./browser/*`
+  builds typeset on `window.MathJax` share the MathJax the first of them loads,
+  in the build and configuration of that element's release, so in a mixed set
+  an element can typeset with a MathJax it was not built for. Elements that
+  bundle their own MathJax share none
+  ([One MathJax version per page](../../docs/item-player/loading-strategies.md#one-mathjax-version-per-page)).
+- Pass `math.assetRoot`, an npm root serving the fonts and speech the elements'
+  bundled MathJax loads, or `math.assetUrls`, each file's URL; without either,
+  elements on adapter 0.1.3 or later render without web fonts and speech
+  ([MathJax assets](../../docs/item-player/loading-strategies.md#mathjax-assets)).
+- Register one version per package; registering a second version throws.
+- Register each package's `controller` unless the item players are hosted
+  (`sectionPlayerRuntime.player.hosted`, or an enabled
+  `sectionPlayerRuntime.player.backend.delivery`). A player that is not hosted
+  runs `model()` in the browser and warns for each tag registered without one.
+- Only `@pie-element/*` builds from pie-elements-ng publish
+  `./browser/delivery` and `./browser/controller`.
+- Under TypeScript, the `package.json` import needs `resolveJsonModule`, and a
+  package version that ships no declarations for `./browser/*` needs a
+  `declare module` shim for those subpaths.
+
+See [`strategy="preloaded"`](../../docs/item-player/loading-strategies.md#strategypreloaded)
+for the registration contract.
+
 ## Content trust boundary
 
 Assessment markup reaches the DOM via the underlying
 `<pie-item-player>` element, which now sanitizes item / passage markup by
-default through DOMPurify. See
-[pie-item-player README](./README.md#content-trust-boundary)
+default through DOMPurify. See the
+[pie-item-player README](../item-player/README.md#content-trust-boundary)
 for the allow-list, opt-out mechanics (`trust-markup`), and the
 `sanitizeMarkup` property override. Assessment-player hosts forward these
-settings by setting `runtime.player.trustMarkup` /
-`runtime.player.sanitizeMarkup` on the shared runtime they pass into the
-section-player instances; the section-player runtime flattens `runtime.player.*`
+settings by setting `sectionPlayerRuntime.player.trustMarkup` /
+`sectionPlayerRuntime.player.sanitizeMarkup` on the assessment player; it passes
+that runtime to each section player, whose runtime flattens `runtime.player.*`
 fields onto the embedded `<pie-item-player>` (see the section-player README
 for the exact forwarding shape).

package/dist/components/AssessmentPlayerDefaultElement.d.ts

@@ -1,7 +1,7 @@
 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';
 export declare class AssessmentPlayerDefaultElement extends HTMLElement implements AssessmentPlayerRuntimeHostContract {
     static get observedAttributes(): string[];
     private _assessmentId;
@@ -16,6 +16,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 +70,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 +146,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/assessment-section-player-runtime.d.ts

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

package/dist/contracts/public-events.d.ts

@@ -1,7 +1,6 @@
 export declare const ASSESSMENT_PLAYER_PUBLIC_EVENTS: {
     readonly controllerReady: "assessment-controller-ready";
     readonly navigationRequested: "assessment-navigation-requested";
-    readonly submitRequested: "assessment-submit-requested";
     readonly routeChanged: "assessment-route-changed";
     readonly sessionApplied: "assessment-session-applied";
     readonly sessionChanged: "assessment-session-changed";

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,16 +174,25 @@ 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;
@@ -196,6 +205,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;

package/dist/{nl-NL-FLtEAIq9.js → nl-NL-CfezB59b.js}

@@ -43,6 +43,7 @@ var e = {
     items: "Vragen",
     section: "Onderdeel",
     loadingSection: "Onderdeel wordt geladen…",
+    sectionLoadError: "Het onderdeel kon niet worden geladen.",
     loadingPassage: "Tekst wordt geladen…",
     configurationError: "Configuratiefout",
     playerError: "Fout in de speler",
@@ -108,6 +109,11 @@ var e = {
       centerA11y: "Venster centreren",
       closeA11y: "Hulpmiddel sluiten"
     },
+    placement: {
+      controlsA11y: "Verplaatsen en draaien",
+      rotateClockwiseA11y: "{degrees}° rechtsom draaien",
+      rotateCounterclockwiseA11y: "{degrees}° linksom draaien"
+    },
     announce: {
       movedUp: "Omhoog verplaatst naar {position}",
       movedDown: "Omlaag verplaatst naar {position}",
@@ -135,8 +141,8 @@ var e = {
     },
     graph: {
       name: "Grafiek",
-      description: "Grafische rekenmachine en assenstelsel",
-      buttonA11y: "Grafiek, grafische rekenmachine",
+      description: "Assenstelsel",
+      buttonA11y: "Grafiek, assenstelsel",
       tooltip: "Grafiek",
       toolA11y: "Grafiekhulpmiddel — punten en lijnen tekenen in een assenstelsel",
       canvasA11y: "Tekenvlak — gebruik de hulpmiddelen om punten toe te voegen en lijnen te tekenen",
@@ -300,30 +306,6 @@ var e = {
     textToSpeech: {
       name: "Voorlezen",
       description: "Inhoud laten voorlezen",
-      toolA11y: "Voorleeshulp",
-      title: "Voorlezen",
-      initializing: "Wordt gestart…",
-      initFailed: "Voorlezen kon niet worden gestart.",
-      selectText: "Selecteer tekst op de pagina om die te laten voorlezen.",
-      speed: "Snelheid:",
-      play: "Voorlezen",
-      pause: "Pauzeren",
-      resume: "Hervatten",
-      stop: "Stoppen",
-      speaking: "Aan het voorlezen…",
-      paused: "Gepauzeerd",
-      charactersSelected: {
-        one: "{count} teken geselecteerd",
-        other: "{count} tekens geselecteerd"
-      },
-      rate: {
-        slow: "Langzaam",
-        slower: "Langzamer",
-        normal: "Normaal",
-        faster: "Sneller",
-        fast: "Snel",
-        veryFast: "Zeer snel"
-      },
       inline: {
         controlsA11y: "Voorleesknoppen",
         playbackSpeedA11y: "Voorleessnelheid",
@@ -429,6 +411,7 @@ var e = {
       resolvedTools: "Toegekende hulpmiddelen (toolkit)",
       provenanceSummary: "Overzicht van herkomst van het hulpmiddelenbeleid",
       perToolDecisions: "Beslissingen per hulpmiddel",
+      policyDiagnostics: "Diagnose van het hulpmiddelenbeleid",
       profileReadOnly: "PNP-profiel (alleen lezen)"
     },
     tts: {