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

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

@@ -1,41 +1,51 @@
 /**
- * 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 { cohortsEqual } from "./cohort.js";
-import { createReadinessDetail, } from "./engine-readiness.js";
-import { phaseToStage } from "./engine-stage-derivation.js";
+import { resolveReadinessGates, } from "./engine-readiness.js";
 import { createInitialEngineState, } from "./engine-state.js";
+/** `idle` and `failed` have no stage of their own. */
+function phaseToStage(phase) {
+    switch (phase) {
+        case "idle":
+        case "failed":
+            return null;
+        case "booting-section":
+            return "composed";
+        case "engine-ready":
+            return "engine-ready";
+        case "interactive":
+            return "interactive";
+        case "disposed":
+            return "disposed";
+    }
+}
 function emitStageChange(outputs, phase, cohort, status = "entered") {
     const stage = phaseToStage(phase);
     if (!stage)
@@ -52,6 +62,7 @@ function startCohort(args) {
         ...createInitialEngineState(),
         phase: "booting-section",
         cohort: args.cohort,
+        readinessMode: args.state.readinessMode,
         effectiveRuntime: args.effectiveRuntime,
         effectiveToolsConfig: args.effectiveToolsConfig,
         itemCount: args.itemCount,
@@ -60,46 +71,62 @@ function startCohort(args) {
     emitStageChange(outputs, "booting-section", args.cohort);
     return { state: next, outputs };
 }
+/**
+ * End the chain of a cohort that has not reached `interactive`. Returns the
+ * `failed` phase after recording the stages it will not reach.
+ */
+function failChain(outputs, phase, cohort) {
+    if (phase === "booting-section") {
+        emitStageChange(outputs, "engine-ready", cohort, "failed");
+        emitStageChange(outputs, "interactive", cohort, "skipped");
+    }
+    else {
+        emitStageChange(outputs, "interactive", cohort, "failed");
+    }
+    return "failed";
+}
 /**
  * Apply a readiness update: store new signals, derive the detail in
- * the requested mode, advance the phase to `interactive` when gated,
- * and emit `loading-complete` once per cohort.
+ * the requested mode, end the chain on a runtime error before
+ * `interactive`, advance the phase to `interactive` when gated, and emit
+ * `loading-complete` once per cohort.
  */
 function applyReadinessUpdate(state, args) {
     if (state.phase === "idle" || state.phase === "disposed") {
         // No cohort to update; ignore.
         return { state, outputs: [] };
     }
-    const detail = createReadinessDetail({
-        mode: args.mode,
-        signals: args.signals,
-    });
+    const detail = resolveReadinessGates(args.mode, args.signals);
     const outputs = [];
     let phase = state.phase;
     let loadingCompleteEmitted = state.loadingCompleteEmitted;
-    // Stage advancement: engine-ready → interactive when readiness
-    // satisfies `interactionReady` (mode-aware via `createReadinessDetail`).
-    if (phase === "engine-ready" && detail.interactionReady) {
+    if (args.signals.runtimeError &&
+        (phase === "booting-section" || phase === "engine-ready")) {
+        phase = failChain(outputs, phase, state.cohort);
+    }
+    else if (phase === "engine-ready" && detail.interactionReady) {
+        // engine-ready → interactive when readiness satisfies
+        // `interactionReady` (mode-aware via `resolveReadinessGates`).
         phase = "interactive";
         emitStageChange(outputs, phase, state.cohort);
     }
     // Canonical `loading-complete` emission. One-shot per cohort, gated
-    // on the readiness signals indicating every item has finished
-    // loading.
+    // on `allLoadingComplete`: section ready plus the host's loading signal,
+    // which the section player kernel raises once the element pre-warm
+    // resolves.
     if (detail.allLoadingComplete && state.cohort && !loadingCompleteEmitted) {
         loadingCompleteEmitted = true;
         outputs.push({
             kind: "loading-complete",
             cohort: state.cohort,
             itemCount: args.itemCount,
-            loadedCount: args.loadedCount,
         });
     }
     const nextState = {
         ...state,
         phase,
         readinessSignals: args.signals,
-        loadedCount: args.loadedCount,
+        readinessMode: args.mode,
         itemCount: args.itemCount,
         loadingCompleteEmitted,
     };
@@ -194,8 +221,8 @@ export function transition(state, input) {
         }
         case "section-controller-resolved": {
             if (state.phase !== "booting-section") {
-                // Either too early (idle), too late (interactive / disposed),
-                // or a duplicate notification; the FSM is monotonic.
+                // Either too early (idle), too late (interactive / failed /
+                // disposed), or a duplicate notification; the FSM is monotonic.
                 return {
                     state: { ...state, controllerResolved: true },
                     outputs: [],
@@ -203,10 +230,20 @@ export function transition(state, input) {
             }
             const outputs = [];
             emitStageChange(outputs, "engine-ready", state.cohort);
+            // Readiness can be satisfied before the controller resolves: with
+            // preloaded elements the items load in the same flush as the
+            // composition. No later signal change would move the cohort on, so
+            // the stored snapshot gates `interactive` here.
+            let phase = "engine-ready";
+            if (resolveReadinessGates(state.readinessMode, state.readinessSignals)
+                .interactionReady) {
+                phase = "interactive";
+                emitStageChange(outputs, phase, state.cohort);
+            }
             return {
                 state: {
                     ...state,
-                    phase: "engine-ready",
+                    phase,
                     controllerResolved: true,
                 },
                 outputs,
@@ -216,25 +253,9 @@ export function transition(state, input) {
             return applyReadinessUpdate(state, {
                 signals: input.signals,
                 mode: input.mode,
-                loadedCount: input.loadedCount,
                 itemCount: input.itemCount,
             });
         }
-        case "framework-error": {
-            return {
-                state: {
-                    ...state,
-                    lastFrameworkError: input.error,
-                    readinessSignals: {
-                        ...state.readinessSignals,
-                        runtimeError: input.error.recoverable === true
-                            ? state.readinessSignals.runtimeError
-                            : true,
-                    },
-                },
-                outputs: [{ kind: "framework-error", error: input.error }],
-            };
-        }
         case "dispose": {
             if (state.phase === "disposed") {
                 return { state, outputs: [] };

package/dist/runtime/engine.d.ts

@@ -1,23 +1,20 @@
 /**
- * Section runtime engine — facade entry point (M7 — Variant C).
+ * Section runtime engine — the stable entry for a host that drives a section's
+ * stage chain.
  *
- * Narrow, stable public surface for hosts that want to mount, drive,
- * or dispose a section runtime via the layered engine. Re-exports the
- * `SectionRuntimeEngine` facade and its `attachHost` arg shape.
- *
- * **Pairing.** This module is the stable counterpart to
- * `./runtime/internal`, which exposes the wider, evolving surface
- * (core types, adapter bridges, cohort helpers) for advanced hosts and
- * for the engine's own tests / benchmarks. Consumers that only need to
- * mount + drive a section runtime should import from here. Consumers
- * that need to reach past the facade (e.g. construct an adapter
- * manually, inspect FSM state types, build alternate fan-out paths)
- * should import from `./runtime/internal` and accept the documented
- * stability disclaimer there.
- *
- * The package's `exports` map adds `./runtime/engine` in M7 PR 3
- * alongside the facade refactor.
+ * Besides the `SectionRuntimeEngine` facade it carries the vocabulary of the
+ * facade's own surface: the inputs `dispatchInput` takes and the outputs
+ * `subscribe` delivers, the state `getState` returns, the runtime config and its
+ * resolution, the id a section runs under, the cohort an `initialize` or
+ * `cohort-change` input names, and the
+ * readiness signals. The section player's layout kernel is the host
+ * this was cut for. The engine's core, adapter and bridges stay behind the
+ * facade, with no entry of their own.
  */
 export { SectionRuntimeEngine, type SectionRuntimeEngineHostArgs, } from "./SectionRuntimeEngine.js";
-export { SECTION_RUNTIME_ENGINE_KEY, type SectionRuntimeEngineContext, } from "./engine-context.js";
-export { sectionRuntimeEngineHostContext, connectSectionRuntimeEngineHostContext, type SectionRuntimeLifecycleHandle, type SectionRuntimeEngineHostContextValue, type SectionRuntimeEngineHostContextListener, } from "./section-runtime-engine-host-context.js";
+export type { SectionEngineInput } from "./core/engine-input.js";
+export type { SectionEngineOutput } from "./core/engine-output.js";
+export type { SectionEnginePhase, SectionEngineState, } from "./core/engine-state.js";
+export { DEFAULT_ENV, DEFAULT_ISOLATION, DEFAULT_PLAYER_TYPE, resolveSectionEngineRuntimeState, resolveSectionId, type FrameworkErrorHandler, type LoadingCompleteHandler, type PlayerOverrides, type RuntimeConfig, type RuntimeInputs, type StageChangeHandler, } from "./core/engine-resolver.js";
+export { cohortsEqual, makeCohort, type CohortKey } from "./core/cohort.js";
+export type { EngineReadinessSignals } from "./core/engine-readiness.js";

package/dist/runtime/engine.js

@@ -1,23 +1,16 @@
 /**
- * Section runtime engine — facade entry point (M7 — Variant C).
+ * Section runtime engine — the stable entry for a host that drives a section's
+ * stage chain.
  *
- * Narrow, stable public surface for hosts that want to mount, drive,
- * or dispose a section runtime via the layered engine. Re-exports the
- * `SectionRuntimeEngine` facade and its `attachHost` arg shape.
- *
- * **Pairing.** This module is the stable counterpart to
- * `./runtime/internal`, which exposes the wider, evolving surface
- * (core types, adapter bridges, cohort helpers) for advanced hosts and
- * for the engine's own tests / benchmarks. Consumers that only need to
- * mount + drive a section runtime should import from here. Consumers
- * that need to reach past the facade (e.g. construct an adapter
- * manually, inspect FSM state types, build alternate fan-out paths)
- * should import from `./runtime/internal` and accept the documented
- * stability disclaimer there.
- *
- * The package's `exports` map adds `./runtime/engine` in M7 PR 3
- * alongside the facade refactor.
+ * Besides the `SectionRuntimeEngine` facade it carries the vocabulary of the
+ * facade's own surface: the inputs `dispatchInput` takes and the outputs
+ * `subscribe` delivers, the state `getState` returns, the runtime config and its
+ * resolution, the id a section runs under, the cohort an `initialize` or
+ * `cohort-change` input names, and the
+ * readiness signals. The section player's layout kernel is the host
+ * this was cut for. The engine's core, adapter and bridges stay behind the
+ * facade, with no entry of their own.
  */
 export { SectionRuntimeEngine, } from "./SectionRuntimeEngine.js";
-export { SECTION_RUNTIME_ENGINE_KEY, } from "./engine-context.js";
-export { sectionRuntimeEngineHostContext, connectSectionRuntimeEngineHostContext, } from "./section-runtime-engine-host-context.js";
+export { DEFAULT_ENV, DEFAULT_ISOLATION, DEFAULT_PLAYER_TYPE, resolveSectionEngineRuntimeState, resolveSectionId, } from "./core/engine-resolver.js";
+export { cohortsEqual, makeCohort } from "./core/cohort.js";

package/dist/runtime/page-warnings.d.ts

@@ -0,0 +1,13 @@
+/**
+ * How long a warning about a missing input waits when a host may still be
+ * supplying it, such as a toolkit or a registry loaded after mount.
+ */
+export declare const PENDING_INPUT_WARNING_DELAY_MS = 10000;
+/**
+ * Warns about a setup mistake once per document, across every copy of the
+ * toolkit loaded into it: the latch is a `Symbol.for` slot on the document, so
+ * the custom-element bundle and the modules a host imports share it. Not
+ * development-only, because the custom-element build compiles those branches
+ * out, and a host misconfigures in production as readily as anywhere.
+ */
+export declare function warnOncePerDocument(doc: Document | null | undefined, key: string, message: string): void;

package/dist/runtime/page-warnings.js

@@ -0,0 +1,22 @@
+/**
+ * How long a warning about a missing input waits when a host may still be
+ * supplying it, such as a toolkit or a registry loaded after mount.
+ */
+export const PENDING_INPUT_WARNING_DELAY_MS = 10_000;
+/**
+ * Warns about a setup mistake once per document, across every copy of the
+ * toolkit loaded into it: the latch is a `Symbol.for` slot on the document, so
+ * the custom-element bundle and the modules a host imports share it. Not
+ * development-only, because the custom-element build compiles those branches
+ * out, and a host misconfigures in production as readily as anywhere.
+ */
+export function warnOncePerDocument(doc, key, message) {
+    if (!doc)
+        return;
+    const slot = Symbol.for(`pie.assessmentToolkit.warned.${key}`);
+    const latches = doc;
+    if (latches[slot])
+        return;
+    latches[slot] = true;
+    console.warn(message);
+}

package/dist/runtime/policy-input-forwarding.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Which policy inputs `<pie-assessment-toolkit>` forwards to the coordinator it
+ * owns.
+ *
+ * The toolkit forwards an input when its own value for it changes. A host
+ * driving the owned coordinator directly — an embedded toolkit's host binds its
+ * assessment from `runtime-ready` or `toolkit-ready` — keeps that binding until
+ * the toolkit's own value changes, so an unrelated re-run of the forwarding
+ * effect (a `tools` change, a coordinator rebuild trigger) cannot reset it. A
+ * coordinator not forwarded to yet is newly built and holds no inputs, so it
+ * receives only the inputs that are set.
+ */
+import type { AssessmentEntity } from "@pie-players/pie-players-shared/types";
+import type { PnpEnforcementMode } from "../policy/core/ToolPolicyEngine.js";
+export interface ForwardedPolicyInputs {
+    pnpEnforcement: PnpEnforcementMode | null;
+    assessment: AssessmentEntity | null;
+}
+/**
+ * The inputs to forward, in apply order: the enforcement override first, so
+ * binding the assessment never resolves auto-mode against a stale override.
+ * `previous` is what was last forwarded to the same coordinator, or `null` for
+ * a coordinator not forwarded to yet.
+ */
+export declare function policyInputsToForward(previous: ForwardedPolicyInputs | null, next: ForwardedPolicyInputs): Array<keyof ForwardedPolicyInputs>;

package/dist/runtime/policy-input-forwarding.js

@@ -0,0 +1,25 @@
+/**
+ * Which policy inputs `<pie-assessment-toolkit>` forwards to the coordinator it
+ * owns.
+ *
+ * The toolkit forwards an input when its own value for it changes. A host
+ * driving the owned coordinator directly — an embedded toolkit's host binds its
+ * assessment from `runtime-ready` or `toolkit-ready` — keeps that binding until
+ * the toolkit's own value changes, so an unrelated re-run of the forwarding
+ * effect (a `tools` change, a coordinator rebuild trigger) cannot reset it. A
+ * coordinator not forwarded to yet is newly built and holds no inputs, so it
+ * receives only the inputs that are set.
+ */
+/**
+ * The inputs to forward, in apply order: the enforcement override first, so
+ * binding the assessment never resolves auto-mode against a stale override.
+ * `previous` is what was last forwarded to the same coordinator, or `null` for
+ * a coordinator not forwarded to yet.
+ */
+export function policyInputsToForward(previous, next) {
+    const order = [
+        "pnpEnforcement",
+        "assessment",
+    ];
+    return order.filter((key) => previous ? !Object.is(previous[key], next[key]) : next[key] !== null);
+}

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

@@ -1,4 +1,5 @@
 import type { SessionCommitReason } from "@pie-players/pie-players-shared/pie";
+import type { ItemSettings } from "@pie-players/pie-players-shared/types";
 import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
 export declare const PIE_REGISTER_EVENT = "pie-register";
 export declare const PIE_UNREGISTER_EVENT = "pie-unregister";
@@ -15,7 +16,17 @@ export interface RuntimeRegistrationDetail {
     canonicalItemId?: string;
     contentKind?: string;
     item?: unknown;
+    /**
+     * An item's policy settings, which govern decisions scoped to the item; see
+     * `ToolkitCoordinatorApi.registerItemSettings`.
+     */
+    settings?: ItemSettings;
     element: HTMLElement;
+    /**
+     * The runtime the shell found through `assessmentToolkitHostRuntimeContext`.
+     * A toolkit claims an event carrying it only when the id is its own.
+     */
+    runtimeId?: string;
 }
 export interface ItemSessionChangedDetail {
     itemId: string;
@@ -60,16 +71,14 @@ export interface InternalFormativeActionDetail {
 /**
  * A Media Time Source becoming available or going away.
  *
- * The one seam through which a timed-media section reaches media, and
- * deliberately the *only* one: the stimulus card dispatches this with a native
- * `<video>` adapter, and a host wrapping a third-party player dispatches the same
- * event with its own port. One code path, two producers — which is what keeps
- * "a host can supply its own media element without shipping a PIE element" true
- * rather than aspirational.
+ * The only seam through which a timed-media section reaches media: the stimulus
+ * card dispatches it with a native `<video>` adapter, and a host wrapping a
+ * third-party player dispatches it with its own port. One code path with two
+ * producers is what lets a host supply its own media element without shipping a
+ * PIE element.
  *
- * `source` carries a live object, not serializable data. That is fine and
- * intended: this event never crosses a realm, exactly like the element reference
- * on `pie-register`.
+ * `source` is a live object. The event never crosses a realm, like the element
+ * reference on `pie-register`.
  */
 export interface InternalMediaTimeSourceDetail {
     /** The renderable that owns the media, for matching against `stimulusRef`. */
@@ -82,11 +91,10 @@ export interface InternalMediaTimeSourceDetail {
      * wiring its own player, and omitting the field reads as `"host"` because a
      * caller constructing this event by hand is one.
      *
-     * Load-bearing for precedence: the card re-runs its discovery whenever its
-     * content changes, so without this a host that supplied a third-party port would
-     * have it silently replaced by the native element mid-session — and the
-     * capabilities would flip back with it, which is exactly the "appears to enforce"
-     * failure this contract exists to prevent.
+     * Precedence depends on it: the card re-runs its discovery whenever its content
+     * changes, and without the field the native element would replace a host's
+     * third-party port mid-session, flipping the capabilities back with it, so a
+     * policy would read as enforced while it is not.
      */
     origin?: "native-adapter" | "host";
 }

package/dist/runtime/runtime-event-claim.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether the toolkit running as `runtimeId` claims a shell's event. A shell
+ * scope puts the id of the runtime that answered it in `detail.runtimeId`, and
+ * only that runtime claims the event. An event without one, from a shell that
+ * dispatches on its own, is claimed when `isLocalTarget` resolves its target
+ * to this runtime.
+ */
+export declare function isRuntimeEventClaimed(event: Event, runtimeId: string, isLocalTarget: (target: EventTarget | null) => boolean): boolean;

package/dist/runtime/runtime-event-claim.js

@@ -0,0 +1,15 @@
+/**
+ * Whether the toolkit running as `runtimeId` claims a shell's event. A shell
+ * scope puts the id of the runtime that answered it in `detail.runtimeId`, and
+ * only that runtime claims the event. An event without one, from a shell that
+ * dispatches on its own, is claimed when `isLocalTarget` resolves its target
+ * to this runtime.
+ */
+export function isRuntimeEventClaimed(event, runtimeId, isLocalTarget) {
+    const addressedTo = event
+        .detail?.runtimeId;
+    if (typeof addressedTo === "string" && addressedTo !== "") {
+        return addressedTo === runtimeId;
+    }
+    return isLocalTarget(event.target);
+}

package/dist/runtime/runtime-id.d.ts

@@ -2,6 +2,6 @@
  * Stable runtime-instance id generator.
  *
  * Produces a per-runtime id used to scope DOM attribute names and
- * telemetry tags. Single export by design — not a "guards" module.
+ * telemetry tags.
  */
 export declare function createRuntimeId(prefix?: string): string;

package/dist/runtime/runtime-id.js

@@ -2,7 +2,7 @@
  * Stable runtime-instance id generator.
  *
  * Produces a per-runtime id used to scope DOM attribute names and
- * telemetry tags. Single export by design — not a "guards" module.
+ * telemetry tags.
  */
 export function createRuntimeId(prefix = "runtime") {
     return `${prefix}-${Math.random().toString(16).slice(2)}-${Date.now()}`;

package/dist/runtime/shell-event-bridge.d.ts

@@ -0,0 +1,45 @@
+import type { ShellContextKind } from "../context/assessment-toolkit-context.js";
+/**
+ * `section`: the shell is its content's only channel to the section. The
+ * player's `session-changed`, `load-complete` and `player-error` stop at the
+ * shell and travel on as the runtime's internal events, with an item's
+ * response changes also announced as `item-session-changed`.
+ *
+ * `plain`: the host owns the player and listens to it, so the player's events
+ * pass through untouched. The runtime still hears that the content loaded or
+ * failed, which a section bound later replays; sessions stay with the host.
+ */
+export type ShellEventBridgeMode = "section" | "plain";
+export interface ShellEventBridgeIdentity {
+    itemId: string;
+    canonicalItemId?: string;
+    contentKind?: string;
+}
+export interface ShellEventBridgeOptions {
+    /** The shell element, where the player's events arrive and leave from. */
+    host: HTMLElement;
+    kind: ShellContextKind;
+    /** Read as each event arrives, so a prop change needs no rebinding. */
+    identity: () => ShellEventBridgeIdentity;
+    /** Read as each event arrives. */
+    mode: () => ShellEventBridgeMode;
+    /** Sends an event addressed to the shell's runtime. */
+    send: (type: string, detail: object) => void;
+}
+export interface ShellEventBridge {
+    /**
+     * Gives an item's pending session one last chance to reach the section, then
+     * stops listening. The commit runs while the player is still inside the
+     * shell, so its `session-changed` arrives at the bridge before it is unbound.
+     * The shell has usually left the document by then; `send` delivers the
+     * forwarded session on the runtime's element.
+     */
+    disconnect: () => void;
+}
+/**
+ * A shell's translation of its player's events into the runtime's, shared by
+ * `<pie-item-scope>` and `<pie-passage-shell>`. The dedupe
+ * state lives as long as the bridge, so a prop change does not forget what was
+ * forwarded.
+ */
+export declare function createShellEventBridge(options: ShellEventBridgeOptions): ShellEventBridge;