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

package/dist/runtime/content-registration.d.ts

@@ -0,0 +1,13 @@
+import type { ToolkitCoordinatorApi } from "../services/interfaces.js";
+import type { RuntimeRegistrationDetail } from "./registration-events.js";
+/**
+ * What a content registration files with the coordinator: the content's
+ * accessibility catalogs, and an item's policy settings under its canonical
+ * id, the id its item-level toolbar scopes decisions by. Returns the cleanups
+ * that withdraw them, for the toolkit to run when the content unregisters or
+ * the coordinator changes.
+ */
+export declare function registerContentWithCoordinator(coordinator: Pick<ToolkitCoordinatorApi, "catalogResolver" | "registerItemSettings">, detail: RuntimeRegistrationDetail, owner: {
+    assessmentId: string;
+    sectionId: string;
+}): Array<() => void>;

package/dist/runtime/content-registration.js

@@ -0,0 +1,25 @@
+/**
+ * What a content registration files with the coordinator: the content's
+ * accessibility catalogs, and an item's policy settings under its canonical
+ * id, the id its item-level toolbar scopes decisions by. Returns the cleanups
+ * that withdraw them, for the toolkit to run when the content unregisters or
+ * the coordinator changes.
+ */
+export function registerContentWithCoordinator(coordinator, detail, owner) {
+    const cleanups = [
+        coordinator.catalogResolver.registerOwner({
+            owner: {
+                kind: detail.kind,
+                itemId: detail.itemId,
+                canonicalItemId: detail.canonicalItemId,
+                assessmentId: owner.assessmentId,
+                sectionId: owner.sectionId,
+            },
+            entity: detail.item,
+        }),
+    ];
+    if (detail.kind === "item" && detail.settings) {
+        cleanups.push(coordinator.registerItemSettings(detail.canonicalItemId || detail.itemId, detail.settings));
+    }
+    return cleanups;
+}

package/dist/runtime/core/SectionEngineCore.d.ts

@@ -1,12 +1,12 @@
 /**
- * Section runtime engine — pure core (M7 — Variant C, layered).
+ * Section runtime engine — pure core.
  *
  * `SectionEngineCore` is a thin object oriented wrapper over the pure
  * `transition()` function. It owns the current `SectionEngineState`,
  * applies inputs serially, and fans out the resulting
  * `SectionEngineOutput[]` to subscribers. There is no DOM, Svelte,
  * coordinator, or timing dependency in this module — all I/O lives in
- * the adapter layer (PR 2).
+ * the adapter layer.
  *
  * Lifetime model:
  *   - One instance per cohort logical lifetime. Cohort changes happen
@@ -45,7 +45,5 @@ export declare class SectionEngineCore {
      * construction time if you need every output from `idle` onward.
      */
     subscribe(listener: SectionEngineCoreListener): () => void;
-    /** Test-only: detach every listener. */
-    disposeListeners(): void;
     private fanOut;
 }

package/dist/runtime/core/SectionEngineCore.js

@@ -1,12 +1,12 @@
 /**
- * Section runtime engine — pure core (M7 — Variant C, layered).
+ * Section runtime engine — pure core.
  *
  * `SectionEngineCore` is a thin object oriented wrapper over the pure
  * `transition()` function. It owns the current `SectionEngineState`,
  * applies inputs serially, and fans out the resulting
  * `SectionEngineOutput[]` to subscribers. There is no DOM, Svelte,
  * coordinator, or timing dependency in this module — all I/O lives in
- * the adapter layer (PR 2).
+ * the adapter layer.
  *
  * Lifetime model:
  *   - One instance per cohort logical lifetime. Cohort changes happen
@@ -61,10 +61,6 @@ export class SectionEngineCore {
             this.listeners.delete(listener);
         };
     }
-    /** Test-only: detach every listener. */
-    disposeListeners() {
-        this.listeners.clear();
-    }
     fanOut(outputs) {
         const snapshot = Array.from(this.listeners);
         const frozen = Object.freeze(outputs.slice());

package/dist/runtime/core/cohort.d.ts

@@ -1,5 +1,5 @@
 /**
- * Cohort identity for the section runtime engine (M7).
+ * Cohort identity for the section runtime engine.
  *
  * One cohort is the tuple `(sectionId, attemptId)` for the section the
  * host is currently rendering. Stage progression, readiness latches, and
@@ -17,11 +17,6 @@ export interface CohortKey {
     /** Attempt identifier; empty string if the host did not provide one. */
     attemptId: string;
 }
-/**
- * Stable string form of the cohort tuple used as a key for the
- * `loadingCompleteEmittedForCohort` latch and equality checks.
- */
-export declare function cohortKey(cohort: CohortKey | null): string;
 /**
  * `true` iff the two cohorts have the same `(sectionId, attemptId)` pair.
  * Treats both inputs as identifying the cohort by value, never by

package/dist/runtime/core/cohort.js

@@ -1,5 +1,5 @@
 /**
- * Cohort identity for the section runtime engine (M7).
+ * Cohort identity for the section runtime engine.
  *
  * One cohort is the tuple `(sectionId, attemptId)` for the section the
  * host is currently rendering. Stage progression, readiness latches, and
@@ -11,15 +11,6 @@
  * layout-CE prop shape) but the engine carries it as the empty string
  * when absent so the cohort key is total.
  */
-/**
- * Stable string form of the cohort tuple used as a key for the
- * `loadingCompleteEmittedForCohort` latch and equality checks.
- */
-export function cohortKey(cohort) {
-    if (!cohort)
-        return "";
-    return `${cohort.sectionId}|${cohort.attemptId}`;
-}
 /**
  * `true` iff the two cohorts have the same `(sectionId, attemptId)` pair.
  * Treats both inputs as identifying the cohort by value, never by

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

@@ -1,24 +1,22 @@
 /**
- * Section runtime engine inputs (M7 — Variant C, layered core).
+ * Section runtime engine inputs.
  *
- * Inputs are the discriminated union of events the adapter (PR 2) feeds
- * into the pure transition function (`engine-transition.ts`). The shape
- * is closed: every field is plain data so the transition can be tested
- * without any DOM, Svelte, or coordinator wiring.
+ * Inputs are the closed union of events the adapter feeds into the pure
+ * transition function (`engine-transition.ts`). Every field is plain data, so
+ * the transition is testable without DOM, Svelte, or coordinator wiring.
  *
  * Adapter→core boundary contract:
- *   - The adapter never mutates engine state directly. It always
- *     constructs an input and calls `core.dispatch(input)`.
- *   - Inputs are total: an unhandled `kind` is a programming error
- *     (the transition uses `assertNever` exhaustiveness).
- *   - Inputs carry only data, never live host references that would
- *     pin lifetime. Coordinator and controller handles live in the
- *     adapter; the core only sees readiness signals derived from them.
+ *   - The adapter never mutates engine state directly. It constructs an input
+ *     and calls `core.dispatch(input)`.
+ *   - The transition switch is exhaustive over `kind`: a new input kind that
+ *     it does not handle fails to type-check.
+ *   - Inputs carry no live host references. Coordinator and controller handles
+ *     live in the adapter; the core sees only readiness signals derived from
+ *     them.
  */
 import type { CohortKey } from "./cohort.js";
 import type { EffectiveRuntime, RuntimeInputs } from "./engine-resolver.js";
 import type { EngineReadinessSignals } from "./engine-readiness.js";
-import type { FrameworkErrorModel } from "../../services/framework-error.js";
 /**
  * `initialize` is the first transition out of `idle`. It carries the
  * cohort key and the resolved runtime/tools snapshot for the cohort.
@@ -60,7 +58,8 @@ export type EngineInputCohortChange = {
  * the controller for the current cohort. Advances the phase from
  * `booting-section` → `engine-ready` (assuming `composed` is already
  * implied by `phase >= booting-section`, which the FSM treats as
- * monotonic).
+ * monotonic), and on to `interactive` when the last readiness snapshot
+ * already satisfies it.
  */
 export type EngineInputSectionControllerResolved = {
     kind: "section-controller-resolved";
@@ -68,7 +67,8 @@ export type EngineInputSectionControllerResolved = {
 /**
  * `update-readiness-signals` carries the latest readiness snapshot
  * from the host. The transition uses it to gate the move into
- * `interactive` and to decide whether to emit `loading-complete`.
+ * `interactive`, to end the chain as `failed` when `runtimeError` is set
+ * before `interactive`, and to decide whether to emit `loading-complete`.
  *
  * The full signal set is sent every time so the transition does not
  * have to reason about partial overlays.
@@ -76,7 +76,6 @@ export type EngineInputSectionControllerResolved = {
 export type EngineInputUpdateReadinessSignals = {
     kind: "update-readiness-signals";
     signals: EngineReadinessSignals;
-    loadedCount: number;
     itemCount: number;
     /**
      * Strict-mode gate. When `"strict"`, `interactive` only fires
@@ -86,26 +85,15 @@ export type EngineInputUpdateReadinessSignals = {
      */
     mode: "progressive" | "strict";
 };
-/**
- * `framework-error` is sent for every framework-error report (M3
- * canonical channel). The transition records the latest error in
- * state and emits a `framework-error` output so the adapter can fan
- * out to subscribers and the DOM event.
- */
-export type EngineInputFrameworkError = {
-    kind: "framework-error";
-    error: FrameworkErrorModel;
-};
 /**
  * `dispose` tears the engine down. Emits `disposed` for the current
- * cohort (if any) and moves to the terminal `disposed` phase. After
- * dispose the engine accepts no further inputs (the transition logs
- * a warning and is a no-op).
+ * cohort (if any) and moves to the terminal `disposed` phase. Every input
+ * after dispose is a no-op.
  */
 export type EngineInputDispose = {
     kind: "dispose";
 };
-export type SectionEngineInput = EngineInputInitialize | EngineInputUpdateRuntime | EngineInputCohortChange | EngineInputSectionControllerResolved | EngineInputUpdateReadinessSignals | EngineInputFrameworkError | EngineInputDispose;
+export type SectionEngineInput = EngineInputInitialize | EngineInputUpdateRuntime | EngineInputCohortChange | EngineInputSectionControllerResolved | EngineInputUpdateReadinessSignals | EngineInputDispose;
 /**
  * Convenience re-export so the adapter can import `RuntimeInputs`
  * from a single place when it constructs `initialize` inputs.

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

@@ -1,18 +1,17 @@
 /**
- * Section runtime engine inputs (M7 — Variant C, layered core).
+ * Section runtime engine inputs.
  *
- * Inputs are the discriminated union of events the adapter (PR 2) feeds
- * into the pure transition function (`engine-transition.ts`). The shape
- * is closed: every field is plain data so the transition can be tested
- * without any DOM, Svelte, or coordinator wiring.
+ * Inputs are the closed union of events the adapter feeds into the pure
+ * transition function (`engine-transition.ts`). Every field is plain data, so
+ * the transition is testable without DOM, Svelte, or coordinator wiring.
  *
  * Adapter→core boundary contract:
- *   - The adapter never mutates engine state directly. It always
- *     constructs an input and calls `core.dispatch(input)`.
- *   - Inputs are total: an unhandled `kind` is a programming error
- *     (the transition uses `assertNever` exhaustiveness).
- *   - Inputs carry only data, never live host references that would
- *     pin lifetime. Coordinator and controller handles live in the
- *     adapter; the core only sees readiness signals derived from them.
+ *   - The adapter never mutates engine state directly. It constructs an input
+ *     and calls `core.dispatch(input)`.
+ *   - The transition switch is exhaustive over `kind`: a new input kind that
+ *     it does not handle fails to type-check.
+ *   - Inputs carry no live host references. Coordinator and controller handles
+ *     live in the adapter; the core sees only readiness signals derived from
+ *     them.
  */
 export {};

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

@@ -1,36 +1,22 @@
 /**
- * Section runtime engine outputs (M7 — Variant C, layered core).
+ * Section runtime engine outputs.
  *
- * Outputs are the closed discriminated union of effects the transition
- * function returns. The adapter (PR 2) takes the output array, walks
- * it in order, and dispatches each one to the right bridge (DOM
- * events, framework-error bus, subscriber fan-out).
+ * Outputs are the closed union of effects the transition function returns. The
+ * adapter walks each batch in order and hands it to the DOM-event bridge and the
+ * subscriber fan-out. Outputs carry only plain data, so the transition table is
+ * testable without DOM or coordinator wiring.
  *
- * Outputs carry only plain data so the transition table can be tested
- * exhaustively without any DOM or coordinator wiring.
- *
- * Adjustment A2 from the M7 implementation plan: `loading-complete`
- * is an output, **not** an FSM phase. The transition emits it from
- * the `interactive` phase when the readiness signals indicate every
- * item has finished loading. This mirrors today's
- * `pie-loading-complete` DOM event semantics.
- *
- * Readiness alias output kinds (`readiness-change`,
- * `interaction-ready`, `ready`) were removed in the broad
- * architecture review compat sweep along with their DOM-event bridge
- * event bridge. Stage and readiness changes now flow
- * through `stage-change` (with `EngineReadinessDetail` available via
- * `SectionEngineCore.getState()` / kernel `selectReadiness()`); the
- * "all items loaded" signal flows through `loading-complete` only.
+ * Framework errors are not an output. The toolkit that owns the coordinator
+ * publishes each one once, as its `framework-error` event and `onFrameworkError`
+ * hook; the engine sees an error only through the readiness signals, and a
+ * fatal one before `interactive` ends the cohort's stage chain as `failed`.
  */
 import type { Stage, StageStatus } from "@pie-players/pie-players-shared/pie";
 import type { CohortKey } from "./cohort.js";
-import type { FrameworkErrorModel } from "../../services/framework-error.js";
 /**
- * Stage transition. The adapter dispatches a `pie-stage-change` DOM
- * event with the canonical detail and forwards to subscribers /
- * coordinator. The status indicates whether the stage was entered,
- * skipped, or recorded as failed.
+ * Stage transition. The adapter dispatches it as `pie-stage-change` with the
+ * canonical detail. The status says whether the stage was entered, skipped, or
+ * recorded as failed.
  */
 export type EngineOutputStageChange = {
     kind: "stage-change";
@@ -39,23 +25,14 @@ export type EngineOutputStageChange = {
     cohort: CohortKey | null;
 };
 /**
- * Canonical `pie-loading-complete` emit (M6 D1). One-shot per cohort.
- * Fires from the `interactive` phase when loaded == items count and
- * the readiness signals satisfy `allLoadingComplete`.
+ * Canonical `pie-loading-complete`. One-shot per cohort, emitted when the
+ * readiness signals satisfy `allLoadingComplete`: section ready plus the host's
+ * loading signal, which the section player kernel raises once the element
+ * pre-warm resolves. `itemCount` is the composition's item count.
  */
 export type EngineOutputLoadingComplete = {
     kind: "loading-complete";
     cohort: CohortKey;
     itemCount: number;
-    loadedCount: number;
-};
-/**
- * Framework error fan-out. Mirrors the M3 `framework-error` DOM event
- * and the `subscribeFrameworkErrors` listener channel. Emitted on
- * every `framework-error` input.
- */
-export type EngineOutputFrameworkError = {
-    kind: "framework-error";
-    error: FrameworkErrorModel;
 };
-export type SectionEngineOutput = EngineOutputStageChange | EngineOutputLoadingComplete | EngineOutputFrameworkError;
+export type SectionEngineOutput = EngineOutputStageChange | EngineOutputLoadingComplete;

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

@@ -1,26 +1,14 @@
 /**
- * Section runtime engine outputs (M7 — Variant C, layered core).
+ * Section runtime engine outputs.
  *
- * Outputs are the closed discriminated union of effects the transition
- * function returns. The adapter (PR 2) takes the output array, walks
- * it in order, and dispatches each one to the right bridge (DOM
- * events, framework-error bus, subscriber fan-out).
+ * Outputs are the closed union of effects the transition function returns. The
+ * adapter walks each batch in order and hands it to the DOM-event bridge and the
+ * subscriber fan-out. Outputs carry only plain data, so the transition table is
+ * testable without DOM or coordinator wiring.
  *
- * Outputs carry only plain data so the transition table can be tested
- * exhaustively without any DOM or coordinator wiring.
- *
- * Adjustment A2 from the M7 implementation plan: `loading-complete`
- * is an output, **not** an FSM phase. The transition emits it from
- * the `interactive` phase when the readiness signals indicate every
- * item has finished loading. This mirrors today's
- * `pie-loading-complete` DOM event semantics.
- *
- * Readiness alias output kinds (`readiness-change`,
- * `interaction-ready`, `ready`) were removed in the broad
- * architecture review compat sweep along with their DOM-event bridge
- * event bridge. Stage and readiness changes now flow
- * through `stage-change` (with `EngineReadinessDetail` available via
- * `SectionEngineCore.getState()` / kernel `selectReadiness()`); the
- * "all items loaded" signal flows through `loading-complete` only.
+ * Framework errors are not an output. The toolkit that owns the coordinator
+ * publishes each one once, as its `framework-error` event and `onFrameworkError`
+ * hook; the engine sees an error only through the readiness signals, and a
+ * fatal one before `interactive` ends the cohort's stage chain as `failed`.
  */
 export {};

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

@@ -1,48 +1,16 @@
 /**
- * Readiness derivation for the section runtime engine (M7).
- *
- * Canonical home of `createReadinessDetail` and `resolveReadinessPhase`.
- * As of M7 PR 7 the previous duplicates in
- * `packages/section-player/src/components/shared/section-player-readiness.ts`
- * have been deleted; section-player now consumes these helpers via
- * `@pie-players/pie-assessment-toolkit/runtime/internal`.
- *
- * Type duplication note: the public DOM-event detail aliases
- * (`SectionPlayerReadinessChangeDetail` /
- * `SectionPlayerReadinessPhase`) still live in section-player's
- * `contracts/public-events.ts` because that file is part of section-
- * player's published custom-element contract. The toolkit core defines
- * `EngineReadinessPhase` independently so it has zero section-player
- * imports. The two definitions must stay structurally identical;
- * that invariant is covered by the readiness assertions in this
- * package's tests, which mirror the section-player suite.
+ * Readiness gating for the section runtime engine: which of the host's
+ * readiness signals open `interactive` and `loading-complete` under the
+ * section's readiness mode.
  */
-/**
- * Coarse readiness phase label, derived from the four readiness
- * signals. Surfaced via the kernel's `selectReadiness()` /
- * `getSnapshot().readiness` selectors; M6 stages own the stage-level
- * transitions on `pie-stage-change` and use this phase as a
- * convenience label only. The `readiness-change` DOM
- * event that used to surface this directly was removed in the broad
- * architecture review compat sweep alongside its
- * event bridge.
- */
-export type EngineReadinessPhase = "bootstrapping" | "interaction-ready" | "loading" | "ready" | "error";
 export type EngineReadinessSignals = {
     sectionReady: boolean;
     interactionReady: boolean;
     allLoadingComplete: boolean;
     runtimeError: boolean;
 };
-export type EngineReadinessDetail = {
-    phase: EngineReadinessPhase;
+export type EngineReadinessGates = {
     interactionReady: boolean;
     allLoadingComplete: boolean;
-    reason?: string;
 };
-export declare function resolveReadinessPhase(signals: EngineReadinessSignals): EngineReadinessPhase;
-export declare function createReadinessDetail(args: {
-    mode: "progressive" | "strict";
-    signals: EngineReadinessSignals;
-    reason?: string;
-}): EngineReadinessDetail;
+export declare function resolveReadinessGates(mode: "progressive" | "strict", signals: EngineReadinessSignals): EngineReadinessGates;

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

@@ -1,46 +1,13 @@
 /**
- * Readiness derivation for the section runtime engine (M7).
- *
- * Canonical home of `createReadinessDetail` and `resolveReadinessPhase`.
- * As of M7 PR 7 the previous duplicates in
- * `packages/section-player/src/components/shared/section-player-readiness.ts`
- * have been deleted; section-player now consumes these helpers via
- * `@pie-players/pie-assessment-toolkit/runtime/internal`.
- *
- * Type duplication note: the public DOM-event detail aliases
- * (`SectionPlayerReadinessChangeDetail` /
- * `SectionPlayerReadinessPhase`) still live in section-player's
- * `contracts/public-events.ts` because that file is part of section-
- * player's published custom-element contract. The toolkit core defines
- * `EngineReadinessPhase` independently so it has zero section-player
- * imports. The two definitions must stay structurally identical;
- * that invariant is covered by the readiness assertions in this
- * package's tests, which mirror the section-player suite.
+ * Readiness gating for the section runtime engine: which of the host's
+ * readiness signals open `interactive` and `loading-complete` under the
+ * section's readiness mode.
  */
-export function resolveReadinessPhase(signals) {
-    if (signals.runtimeError)
-        return "error";
-    if (signals.allLoadingComplete)
-        return "ready";
-    if (signals.interactionReady)
-        return "interaction-ready";
-    if (signals.sectionReady)
-        return "loading";
-    return "bootstrapping";
-}
-export function createReadinessDetail(args) {
-    // Final ready must always be gated by section lifecycle and complete loading.
-    const finalReady = args.signals.sectionReady && args.signals.allLoadingComplete;
-    const interactionReady = args.mode === "strict" ? finalReady : args.signals.interactionReady;
-    const phase = resolveReadinessPhase({
-        ...args.signals,
-        allLoadingComplete: finalReady,
-        interactionReady,
-    });
+export function resolveReadinessGates(mode, signals) {
+    // Final ready is always gated by the section lifecycle and complete loading.
+    const allLoadingComplete = signals.sectionReady && signals.allLoadingComplete;
     return {
-        phase,
-        interactionReady,
-        allLoadingComplete: finalReady,
-        reason: args.reason,
+        interactionReady: mode === "strict" ? allLoadingComplete : signals.interactionReady,
+        allLoadingComplete,
     };
 }