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

package/dist/runtime/core/engine-resolver.d.ts

@@ -1,11 +1,9 @@
 /**
- * Section runtime engine resolver (M7).
+ * Section runtime engine resolver.
  *
  * Canonical home of `resolveRuntime`, `resolveToolsConfig`, and their
- * supporting helpers/types. As of M7 PR 7 the previous duplicates in
- * `packages/section-player/src/components/shared/section-player-runtime.ts`
- * have been deleted; section-player now consumes these helpers via
- * `@pie-players/pie-assessment-toolkit/runtime/internal`.
+ * supporting helpers/types; section-player consumes them through
+ * `@pie-players/pie-assessment-toolkit/runtime/engine`.
  *
  * What is NOT absorbed in this module:
  * - `resolvePlayerRuntime` stays in section-player because it depends on
@@ -18,22 +16,26 @@
  *   `packages/section-player/src/components/shared/section-player-host-runtime.ts`)
  *   hands its local implementation in.
  *
- * Runtime-owned configuration flows through `runtime.<key>`. Layout-only
- * inputs stay on the section-player host elements.
+ * Each input has one tier. `assessmentId`, the tools and player config and the
+ * `on*` callbacks arrive on `runtime`. The primitive inputs (`nds-icons`,
+ * `locale`, `tool-config-strictness`) are element attributes; the resolver takes
+ * `toolConfigStrictness` beside `runtime`.
  */
 import type { LoaderConfig } from "@pie-players/pie-players-shared/loader-config";
 import type { LoadingCompleteDetail, StageChangeDetail } from "@pie-players/pie-players-shared/pie";
 import type { FrameworkErrorModel } from "../../services/framework-error.js";
 import type { ToolConfigStrictness } from "../../services/tool-config-validation.js";
-export declare const DEFAULT_ASSESSMENT_ID = "section-demo-direct";
 export declare const DEFAULT_PLAYER_TYPE = "iife";
-export declare const DEFAULT_LAZY_INIT = true;
+export declare const DEFAULT_LAZY_INIT = false;
 export declare const DEFAULT_ISOLATION = "inherit";
 export declare const DEFAULT_ENV: Record<string, unknown>;
 export type PlayerOverrides = {
+    /** The host has already loaded the item bundles; the player loads none. */
+    hosted?: boolean;
     loaderConfig?: LoaderConfig;
     loaderOptions?: Record<string, unknown>;
-    [key: string]: unknown;
+    /** The item player's `backend` config, passed through unread. */
+    backend?: Record<string, unknown> | null;
 };
 export type FrameworkErrorHandler = (model: FrameworkErrorModel) => void;
 export type StageChangeHandler = (detail: StageChangeDetail) => void;
@@ -61,48 +63,34 @@ export type RuntimeConfig = {
     isolation?: string;
     env?: Record<string, unknown>;
     /**
-     * Presentation flag: opt-in to the vendored `<nds-icon-button>` for the
-     * toolbar tool buttons, the calculator shell controls, inline-TTS
-     * play/pause, and the section scroll-hint. NDS icons render only when
-     * this is explicitly `true`; unset/`false` keeps the plain `<button>`
-     * markup (the default). Purely visual — no engine effect.
-     */
-    ndsIcons?: boolean;
-    /**
-     * Interface locale: a BCP-47 tag naming the language the player renders its own
-     * UI in. Purely presentational — no engine effect.
-     *
-     * Distinct from content language, which describes the authored item and
-     * travels on `env`. QTI 3's implementation guide states the independence
-     * directly: a candidate may choose an interface language which may or may not
-     * also be the language of the content.
+     * Content language: a BCP-47 tag naming the language the authored content is
+     * written in, which read-aloud speaks it in and catalog lookups select
+     * alternates by. A `lang` in the content's markup wins over it. Purely
+     * presentational — no engine effect.
      *
-     * Unset renders `en-US`. POSIX (`nl_NL`) and bare (`nl`) forms both resolve.
+     * Unset reads as `en-US` wherever the markup names no language.
      */
-    locale?: string;
-    toolConfigStrictness?: ToolConfigStrictness;
+    contentLanguage?: string;
     onFrameworkError?: FrameworkErrorHandler;
+    /** Called with each `pie-stage-change` detail. */
     onStageChange?: StageChangeHandler;
+    /** Called with each `pie-loading-complete` detail. */
     onLoadingComplete?: LoadingCompleteHandler;
 };
 export type RuntimeInputs = {
-    assessmentId?: string;
-    toolConfigStrictness?: ToolConfigStrictness;
-    onFrameworkError?: FrameworkErrorHandler;
-    onStageChange?: StageChangeHandler;
-    onLoadingComplete?: LoadingCompleteHandler;
     runtime: RuntimeConfig | null;
+    toolConfigStrictness?: ToolConfigStrictness;
 };
 /**
- * Resolve the canonical `onFrameworkError` handler from the two-tier
- * surface. Precedence (highest first): `runtime.onFrameworkError`,
- * then top-level `onFrameworkError`. Layout CEs and the kernel call
- * this so every entry point converges on the same handler.
+ * The id a section runs under: the host's `section-id`, else the section's own
+ * `identifier`, else one named after the assessment. The toolkit keys the
+ * section's controller by it, and the layout kernel its stage cohort.
  */
-export declare function resolveOnFrameworkError(args: {
-    runtime: RuntimeConfig | null;
-    onFrameworkError?: FrameworkErrorHandler;
-}): FrameworkErrorHandler | undefined;
+export declare function resolveSectionId(args: {
+    sectionId?: string | null;
+    section?: unknown;
+    assessmentId?: string | null;
+}): string;
 export declare function resolveToolsConfig(args: {
     runtime: RuntimeConfig | null;
 }): {
@@ -111,20 +99,18 @@ export declare function resolveToolsConfig(args: {
     };
 };
 export declare function resolveRuntime(args: {
-    assessmentId: string;
     runtime: RuntimeConfig | null;
     effectiveToolsConfig: unknown;
     toolConfigStrictness?: ToolConfigStrictness;
-    onFrameworkError?: FrameworkErrorHandler;
-    onStageChange?: StageChangeHandler;
-    onLoadingComplete?: LoadingCompleteHandler;
 }): {
-    assessmentId: string | undefined;
     playerType: string;
     player: {
-        [key: string]: unknown;
+        /** The host has already loaded the item bundles; the player loads none. */
+        hosted?: boolean;
         loaderConfig?: LoaderConfig;
         loaderOptions?: Record<string, unknown>;
+        /** The item player's `backend` config, passed through unread. */
+        backend?: Record<string, unknown> | null;
     } | null;
     lazyInit: boolean;
     accessibility: Record<string, unknown> | null;
@@ -132,39 +118,25 @@ export declare function resolveRuntime(args: {
     createSectionController: unknown;
     isolation: string;
     env: Record<string, unknown>;
-    toolConfigStrictness: "off" | "error" | "warn";
-    onFrameworkError: FrameworkErrorHandler | undefined;
-    onStageChange: StageChangeHandler | undefined;
-    onLoadingComplete: LoadingCompleteHandler | undefined;
+    toolConfigStrictness: ToolConfigStrictness;
     tools: unknown;
+    assessmentId?: string;
     toolContextResolvers?: Record<string, unknown> | null;
     /**
-     * Presentation flag: opt-in to the vendored `<nds-icon-button>` for the
-     * toolbar tool buttons, the calculator shell controls, inline-TTS
-     * play/pause, and the section scroll-hint. NDS icons render only when
-     * this is explicitly `true`; unset/`false` keeps the plain `<button>`
-     * markup (the default). Purely visual — no engine effect.
-     */
-    ndsIcons?: boolean;
-    /**
-     * Interface locale: a BCP-47 tag naming the language the player renders its own
-     * UI in. Purely presentational — no engine effect.
+     * Content language: a BCP-47 tag naming the language the authored content is
+     * written in, which read-aloud speaks it in and catalog lookups select
+     * alternates by. A `lang` in the content's markup wins over it. Purely
+     * presentational — no engine effect.
      *
-     * Distinct from content language, which describes the authored item and
-     * travels on `env`. QTI 3's implementation guide states the independence
-     * directly: a candidate may choose an interface language which may or may not
-     * also be the language of the content.
-     *
-     * Unset renders `en-US`. POSIX (`nl_NL`) and bare (`nl`) forms both resolve.
+     * Unset reads as `en-US` wherever the markup names no language.
      */
-    locale?: string;
+    contentLanguage?: string;
+    onFrameworkError?: FrameworkErrorHandler;
+    /** Called with each `pie-stage-change` detail. */
+    onStageChange?: StageChangeHandler;
+    /** Called with each `pie-loading-complete` detail. */
+    onLoadingComplete?: LoadingCompleteHandler;
 };
-/**
- * Effective runtime returned by `resolveRuntime`. The shape is exposed
- * as `unknown` at the public boundary because consumers spread it into
- * arbitrary host props; downstream call sites narrow with the specific
- * keys they need.
- */
 export type EffectiveRuntime = ReturnType<typeof resolveRuntime>;
 /**
  * Engine-side orchestrator that powers `resolveSectionPlayerRuntimeState`

package/dist/runtime/core/engine-resolver.js

@@ -1,11 +1,9 @@
 /**
- * Section runtime engine resolver (M7).
+ * Section runtime engine resolver.
  *
  * Canonical home of `resolveRuntime`, `resolveToolsConfig`, and their
- * supporting helpers/types. As of M7 PR 7 the previous duplicates in
- * `packages/section-player/src/components/shared/section-player-runtime.ts`
- * have been deleted; section-player now consumes these helpers via
- * `@pie-players/pie-assessment-toolkit/runtime/internal`.
+ * supporting helpers/types; section-player consumes them through
+ * `@pie-players/pie-assessment-toolkit/runtime/engine`.
  *
  * What is NOT absorbed in this module:
  * - `resolvePlayerRuntime` stays in section-player because it depends on
@@ -18,33 +16,26 @@
  *   `packages/section-player/src/components/shared/section-player-host-runtime.ts`)
  *   hands its local implementation in.
  *
- * Runtime-owned configuration flows through `runtime.<key>`. Layout-only
- * inputs stay on the section-player host elements.
+ * Each input has one tier. `assessmentId`, the tools and player config and the
+ * `on*` callbacks arrive on `runtime`. The primitive inputs (`nds-icons`,
+ * `locale`, `tool-config-strictness`) are element attributes; the resolver takes
+ * `toolConfigStrictness` beside `runtime`.
  */
-export const DEFAULT_ASSESSMENT_ID = "section-demo-direct";
 export const DEFAULT_PLAYER_TYPE = "iife";
-export const DEFAULT_LAZY_INIT = true;
+export const DEFAULT_LAZY_INIT = false;
 export const DEFAULT_ISOLATION = "inherit";
 export const DEFAULT_ENV = { mode: "gather", role: "student" };
 /**
- * Pick the runtime-tier value when defined, otherwise the prop/attribute
- * value. The strict mirror rule means every tier-1 surface is resolved
- * with this single helper; per-feature special-casing is forbidden.
+ * The id a section runs under: the host's `section-id`, else the section's own
+ * `identifier`, else one named after the assessment. The toolkit keys the
+ * section's controller by it, and the layout kernel its stage cohort.
  */
-function pick(runtimeVal, attrVal) {
-    return runtimeVal !== undefined ? runtimeVal : attrVal;
-}
-/**
- * Resolve the canonical `onFrameworkError` handler from the two-tier
- * surface. Precedence (highest first): `runtime.onFrameworkError`,
- * then top-level `onFrameworkError`. Layout CEs and the kernel call
- * this so every entry point converges on the same handler.
- */
-export function resolveOnFrameworkError(args) {
-    const r = args.runtime ?? {};
-    if (r.onFrameworkError !== undefined)
-        return r.onFrameworkError;
-    return args.onFrameworkError;
+export function resolveSectionId(args) {
+    const identifier = args.section
+        ?.identifier;
+    return (args.sectionId ||
+        (typeof identifier === "string" ? identifier : "") ||
+        `section-${args.assessmentId || "default"}`);
 }
 export function resolveToolsConfig(args) {
     const runtimeTools = (args.runtime?.tools || {});
@@ -58,7 +49,6 @@ export function resolveRuntime(args) {
     const runtimePlayer = r.player ? { ...r.player } : null;
     return {
         ...r,
-        assessmentId: pick(r.assessmentId, args.assessmentId),
         playerType: r.playerType ?? DEFAULT_PLAYER_TYPE,
         player: runtimePlayer,
         lazyInit: r.lazyInit ?? DEFAULT_LAZY_INIT,
@@ -67,17 +57,7 @@ export function resolveRuntime(args) {
         createSectionController: r.createSectionController,
         isolation: r.isolation ?? DEFAULT_ISOLATION,
         env: r.env ?? DEFAULT_ENV,
-        toolConfigStrictness: pick(r.toolConfigStrictness, args.toolConfigStrictness) ?? "error",
-        // Runtime callback wins; top-level callback remains a layout CE event
-        // convenience for hosts that do not use DOM listeners.
-        onFrameworkError: resolveOnFrameworkError({
-            runtime: args.runtime,
-            onFrameworkError: args.onFrameworkError,
-        }),
-        // Runtime callback wins over the top-level callback prop.
-        onStageChange: pick(r.onStageChange, args.onStageChange),
-        // Runtime callback wins over the top-level callback prop.
-        onLoadingComplete: pick(r.onLoadingComplete, args.onLoadingComplete),
+        toolConfigStrictness: args.toolConfigStrictness ?? "error",
         tools: args.effectiveToolsConfig,
     };
 }
@@ -88,18 +68,13 @@ export function resolveRuntime(args) {
  * stays free of host-coupled defaults (`DEFAULT_PLAYER_DEFINITIONS`).
  */
 export function resolveSectionEngineRuntimeState(args, deps) {
-    const assessmentId = args.assessmentId ?? DEFAULT_ASSESSMENT_ID;
     const effectiveToolsConfig = resolveToolsConfig({
         runtime: args.runtime,
     });
     const effectiveRuntime = resolveRuntime({
-        assessmentId,
         runtime: args.runtime,
         effectiveToolsConfig,
         toolConfigStrictness: args.toolConfigStrictness,
-        onFrameworkError: args.onFrameworkError,
-        onStageChange: args.onStageChange,
-        onLoadingComplete: args.onLoadingComplete,
     });
     const playerRuntime = deps.resolvePlayerRuntime({
         effectiveRuntime: effectiveRuntime,

package/dist/runtime/core/engine-state.d.ts

@@ -1,33 +1,30 @@
 /**
- * Section runtime engine state (M7 — Variant C, layered core).
+ * Section runtime engine state.
  *
- * The state object is the single source of truth for stage, cohort,
- * readiness signals, and the resolved coordinator/controller handles
- * across one engine instance. The transition function in
- * `engine-transition.ts` is the only legal mutator; the adapter (M7
- * PR 2) reads the state via `SectionEngineCore.getState()` and emits
- * the bundled `SectionEngineOutput[]` to its bridges.
+ * The state object is the single source of truth for stage, cohort and
+ * readiness signals across one engine instance. The transition function in
+ * `engine-transition.ts` is its only mutator; the adapter reads it through
+ * `SectionEngineCore.getState()`.
  *
- * Phases (the FSM). Adjustment A2 of the M7 implementation plan locks
- * this list to four phases that map 1:1 onto the M6 canonical stages:
+ * Phases map onto the canonical stages:
  *
- *   `idle`             → no cohort yet (before `initialize`).
- *   `booting-section`  → cohort known, controller resolution pending. Maps to stage `composed`.
- *   `engine-ready`     → controller resolved. Maps to stage `engine-ready`.
- *   `interactive`      → readiness gate satisfied. Maps to stage `interactive`.
- *   `disposed`         → engine torn down. Maps to stage `disposed`.
+ *   `idle`             → no cohort yet. No stage.
+ *   `booting-section`  → cohort known, controller pending. Stage `composed`.
+ *   `engine-ready`     → controller resolved. Stage `engine-ready`.
+ *   `interactive`      → readiness gate satisfied. Stage `interactive`.
+ *   `failed`           → a runtime error ended the cohort's chain before
+ *                        `interactive`. No stage of its own: the transition
+ *                        records the stages it did not reach as `failed` and
+ *                        `skipped`.
+ *   `disposed`         → engine torn down. Stage `disposed`.
  *
- * `loading-complete` is intentionally **not** an FSM phase — it is a
- * `SectionEngineOutput` emitted from the `interactive` phase when the
- * readiness signals satisfy `allLoadingComplete`. See
- * `engine-output.ts` for the output shape and the implementation
- * plan's Adjustment A2 fence.
+ * `loading-complete` is an output, emitted once per cohort when the readiness
+ * signals report every item loaded.
  */
 import type { CohortKey } from "./cohort.js";
 import type { EffectiveRuntime } from "./engine-resolver.js";
 import type { EngineReadinessSignals } from "./engine-readiness.js";
-import type { FrameworkErrorModel } from "../../services/framework-error.js";
-export type SectionEnginePhase = "idle" | "booting-section" | "engine-ready" | "interactive" | "disposed";
+export type SectionEnginePhase = "idle" | "booting-section" | "engine-ready" | "interactive" | "failed" | "disposed";
 export type SectionEngineState = {
     /** Current FSM phase. The single source of truth for stage derivation. */
     phase: SectionEnginePhase;
@@ -45,13 +42,17 @@ export type SectionEngineState = {
      */
     controllerResolved: boolean;
     /**
-     * Readiness signal snapshot. Updated by `update-readiness-signals`
-     * inputs from the host (kernel) — the engine itself does not
-     * compute these from scratch in PR 1. Strict-mode gating is
-     * applied at derivation time via `createReadinessDetail`, not by
-     * mutating the signals.
+     * Readiness signal snapshot, replaced by each `update-readiness-signals`
+     * input from the host. Strict-mode gating is applied at derivation time
+     * through `resolveReadinessGates`.
      */
     readinessSignals: EngineReadinessSignals;
+    /**
+     * Readiness mode of the last `update-readiness-signals` input. Kept with
+     * the signals so `section-controller-resolved` can apply a snapshot that
+     * arrived while the controller was pending.
+     */
+    readinessMode: "progressive" | "strict";
     /** Last resolved effective runtime (output of `resolveRuntime`). */
     effectiveRuntime: EffectiveRuntime | null;
     /** Last resolved tools config. */
@@ -63,17 +64,8 @@ export type SectionEngineState = {
      * preserved by gating emission on this flag in the transition.
      */
     loadingCompleteEmitted: boolean;
-    /**
-     * Most recent framework error, if any. The engine routes errors
-     * through outputs, not through state — this field is kept so
-     * subscribers asking for the latest snapshot (e.g. error banners)
-     * can read it without replaying the output stream.
-     */
-    lastFrameworkError: FrameworkErrorModel | null;
-    /** Number of items the host has registered for the current cohort. */
+    /** Number of items in the current cohort's composition. */
     itemCount: number;
-    /** Number of items reported as loaded. */
-    loadedCount: number;
 };
 /**
  * Initial state. Kept as a function so callers cannot mutate a shared

package/dist/runtime/core/engine-state.js

@@ -1,27 +1,25 @@
 /**
- * Section runtime engine state (M7 — Variant C, layered core).
+ * Section runtime engine state.
  *
- * The state object is the single source of truth for stage, cohort,
- * readiness signals, and the resolved coordinator/controller handles
- * across one engine instance. The transition function in
- * `engine-transition.ts` is the only legal mutator; the adapter (M7
- * PR 2) reads the state via `SectionEngineCore.getState()` and emits
- * the bundled `SectionEngineOutput[]` to its bridges.
+ * The state object is the single source of truth for stage, cohort and
+ * readiness signals across one engine instance. The transition function in
+ * `engine-transition.ts` is its only mutator; the adapter reads it through
+ * `SectionEngineCore.getState()`.
  *
- * Phases (the FSM). Adjustment A2 of the M7 implementation plan locks
- * this list to four phases that map 1:1 onto the M6 canonical stages:
+ * Phases map onto the canonical stages:
  *
- *   `idle`             → no cohort yet (before `initialize`).
- *   `booting-section`  → cohort known, controller resolution pending. Maps to stage `composed`.
- *   `engine-ready`     → controller resolved. Maps to stage `engine-ready`.
- *   `interactive`      → readiness gate satisfied. Maps to stage `interactive`.
- *   `disposed`         → engine torn down. Maps to stage `disposed`.
+ *   `idle`             → no cohort yet. No stage.
+ *   `booting-section`  → cohort known, controller pending. Stage `composed`.
+ *   `engine-ready`     → controller resolved. Stage `engine-ready`.
+ *   `interactive`      → readiness gate satisfied. Stage `interactive`.
+ *   `failed`           → a runtime error ended the cohort's chain before
+ *                        `interactive`. No stage of its own: the transition
+ *                        records the stages it did not reach as `failed` and
+ *                        `skipped`.
+ *   `disposed`         → engine torn down. Stage `disposed`.
  *
- * `loading-complete` is intentionally **not** an FSM phase — it is a
- * `SectionEngineOutput` emitted from the `interactive` phase when the
- * readiness signals satisfy `allLoadingComplete`. See
- * `engine-output.ts` for the output shape and the implementation
- * plan's Adjustment A2 fence.
+ * `loading-complete` is an output, emitted once per cohort when the readiness
+ * signals report every item loaded.
  */
 /**
  * Initial state. Kept as a function so callers cannot mutate a shared
@@ -38,11 +36,10 @@ export function createInitialEngineState() {
             allLoadingComplete: false,
             runtimeError: false,
         },
+        readinessMode: "progressive",
         effectiveRuntime: null,
         effectiveToolsConfig: null,
         loadingCompleteEmitted: false,
-        lastFrameworkError: null,
         itemCount: 0,
-        loadedCount: 0,
     };
 }

package/dist/runtime/core/engine-transition.d.ts

@@ -1,36 +1,31 @@
 /**
- * Pure transition function for the section runtime engine (M7 — Variant
- * C, layered core).
+ * Pure transition function for the section runtime engine.
  *
  * `transition(state, input)` is total over `(state, input)` pairs and
  * returns:
- *   - the next `SectionEngineState` (immutable; the input state object
- *     is never mutated);
- *   - the ordered list of `SectionEngineOutput`s the adapter must
- *     dispatch (DOM events, framework-error fan-out, etc.).
+ *   - the next `SectionEngineState` (the input state object is never
+ *     mutated);
+ *   - the ordered list of `SectionEngineOutput`s the adapter dispatches.
  *
- * The function imports nothing from Svelte, the DOM, or the
- * coordinator. The `core/` constraint is enforced by the per-PR audit
- * step in the M7 implementation plan.
+ * The function imports nothing from Svelte, the DOM, or the coordinator;
+ * `scripts/check-engine-core-purity.mjs` enforces that.
  *
  * Phase machine (per `engine-state.ts`):
  *   idle → booting-section → engine-ready → interactive → disposed
- *   (cohort-change rolls back to booting-section for the new cohort
- *    after emitting `disposed` for the outgoing cohort)
+ *   booting-section | engine-ready → failed → disposed
+ *   (cohort-change emits `disposed` for the outgoing cohort and restarts at
+ *    booting-section for the new one)
+ *
+ * A readiness update that reports `runtimeError` before `interactive` ends the
+ * chain: the first stage the cohort did not reach is recorded as `failed` and
+ * any after it as `skipped`, so a host waiting on `engine-ready` or
+ * `interactive` always hears an answer.
  *
  * Output ordering invariants:
  *   1. `stage-change` for stage advancement fires before any
  *      `loading-complete` triggered by the same input.
  *   2. `loading-complete` fires once per cohort, gated on
  *      `state.loadingCompleteEmitted`.
- *   3. `framework-error` outputs are independent of the stage chain
- *      and do not move the phase.
- *
- * Readiness alias output kinds (`readiness-change`,
- * `interaction-ready`, `ready`) and their DOM-event bridge were
- * removed in the broad architecture review compat sweep. Hosts that
- * need the readiness detail read it via the kernel's `selectReadiness`
- * / `getSnapshot` selectors or via `SectionEngineCore.getState()`.
  */
 import type { SectionEngineInput } from "./engine-input.js";
 import type { SectionEngineOutput } from "./engine-output.js";