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

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";

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,26 +71,42 @@ 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);
     }
@@ -92,14 +119,13 @@ function applyReadinessUpdate(state, args) {
             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 +220,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 +229,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 +252,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);
+}