@pie-players/pie-assessment-toolkit 0.3.30 → 0.3.32

package/dist/runtime/adapter/SectionEngineAdapter.js

@@ -0,0 +1,183 @@
+/**
+ * Section runtime engine adapter (M7 — Variant C, layered).
+ *
+ * The adapter is the single I/O seam between the pure FSM core
+ * (`SectionEngineCore`) and the rest of the world (DOM, coordinator,
+ * framework-error bus, host subscribers, instrumentation). It does
+ * exactly two jobs:
+ *
+ *   1. Translate **host inputs** (from kernels, the toolkit CE, or
+ *      direct facade callers) into `SectionEngineInput`s and forward
+ *      them to the core via `core.dispatch(input)`.
+ *
+ *   2. Subscribe to the core's output stream and **route each output**
+ *      through the bridges in a deterministic order so the public DOM
+ *      surface, framework-error bus, instrumentation hook, and host
+ *      subscribers all see exactly the same fan-out with
+ *      byte-identical detail shapes.
+ *
+ * Output routing is a single exhaustive `switch` (`assertNever` on
+ * the default branch) so adding a new `SectionEngineOutput` kind in
+ * `engine-output.ts` is a compile error here until the adapter knows
+ * what to do with it.
+ *
+ * **Routing order per output:**
+ *   - canonical DOM event (`pie-stage-change`, `pie-loading-complete`,
+ *     `framework-error`)
+ *   - framework-error bus (single fan-out for in-process subscribers)
+ *   - instrumentation hook
+ *   - public subscriber fan-out (batched, runs once per
+ *     `core.dispatch`)
+ *
+ * The deprecated `readiness-change` / `interaction-ready` / `ready`
+ * DOM events and their `legacy-event-bridge.ts` were removed in the
+ * broad architecture review compat sweep; the corresponding output
+ * kinds are gone from `engine-output.ts`.
+ *
+ * **Layering constraint.** The adapter is plain TS. It must not
+ * import `svelte` — the M7 implementation plan and
+ * `scripts/check-engine-core-purity.mjs` enforce the core's purity;
+ * the adapter follows the same constraint by convention so it stays
+ * usable from non-Svelte hosts (Node tests, Storybook, or future
+ * non-Svelte consumers). `bun run check:custom-elements` already
+ * blocks `.svelte` imports in published `dist`; adding a Svelte
+ * dependency here would also leak through that gate.
+ */
+import { SectionEngineCore } from "../core/SectionEngineCore.js";
+import { createCoordinatorBridge, } from "./coordinator-bridge.js";
+import { createDomEventBridge, } from "./dom-event-bridge.js";
+import { createFrameworkErrorBridge, } from "./framework-error-bridge.js";
+import { createInstrumentationBridge, } from "./instrumentation-bridge.js";
+import { createSubscriberFanout, } from "./subscriber-fanout.js";
+export class SectionEngineAdapter {
+    core;
+    domEventBridge;
+    frameworkErrorBridge;
+    instrumentationBridge;
+    subscriberFanout;
+    coordinatorBridge;
+    unsubscribeCore;
+    disposed = false;
+    constructor(options) {
+        this.core = options.core ?? new SectionEngineCore();
+        this.domEventBridge = createDomEventBridge({
+            host: options.host,
+            runtimeId: options.runtimeId,
+            sourceCe: options.sourceCe,
+            now: options.now,
+        });
+        this.frameworkErrorBridge = createFrameworkErrorBridge({
+            bus: options.frameworkErrorBus,
+        });
+        this.instrumentationBridge = createInstrumentationBridge({
+            hook: options.instrumentationHook,
+        });
+        this.subscriberFanout = createSubscriberFanout();
+        this.coordinatorBridge = options.coordinator
+            ? createCoordinatorBridge({
+                coordinator: options.coordinator,
+                dispatchCoreInput: (input) => this.dispatchInput(input),
+            })
+            : null;
+        this.unsubscribeCore = this.core.subscribe((outputs) => {
+            this.routeOutputs(outputs);
+        });
+    }
+    /**
+     * Read-only snapshot of the FSM state. Mirrors
+     * `SectionEngineCore.getState()`.
+     */
+    getState() {
+        return this.core.getState();
+    }
+    /**
+     * Forward a host-constructed input to the core. Returns the outputs
+     * that resulted (the bridges have already received them).
+     */
+    dispatchInput(input) {
+        if (this.disposed)
+            return [];
+        return this.core.dispatch(input);
+    }
+    /**
+     * Subscribe to batched output streams, one batch per
+     * `dispatchInput`.
+     */
+    subscribe(listener) {
+        return this.subscriberFanout.subscribe(listener);
+    }
+    /**
+     * Update the host element after construction (e.g. when the kernel
+     * receives its host element via Svelte action / context).
+     */
+    setHost(host) {
+        this.domEventBridge.setHost(host);
+    }
+    /**
+     * Update the instrumentation hook at runtime.
+     */
+    setInstrumentationHook(hook) {
+        this.instrumentationBridge.setHook(hook);
+    }
+    /**
+     * Resolve a section controller through the configured coordinator.
+     *
+     * Throws if the adapter was constructed without a coordinator.
+     * Standalone callers should manually feed
+     * `{ kind: "section-controller-resolved" }` after their own
+     * controller resolution path completes.
+     */
+    resolveSectionController(args) {
+        if (!this.coordinatorBridge) {
+            throw new Error("[SectionEngineAdapter] resolveSectionController called without a coordinator.");
+        }
+        return this.coordinatorBridge.resolveSectionController(args);
+    }
+    /**
+     * Tear the adapter down. Safe to call more than once. Disposes the
+     * coordinator bridge (which in turn disposes the section
+     * controller for the current cohort), detaches the core
+     * subscription, and clears subscribers.
+     *
+     * Does **not** dispose the framework-error bus — its lifetime is
+     * owned by the toolkit CE / host.
+     */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Dispatch the FSM `dispose` input first so the disposed-stage
+        // output flows through the bridges before we tear anything down.
+        this.core.dispatch({ kind: "dispose" });
+        this.unsubscribeCore();
+        this.subscriberFanout.dispose();
+        if (this.coordinatorBridge) {
+            await this.coordinatorBridge.dispose();
+        }
+    }
+    routeOutputs(outputs) {
+        for (const output of outputs) {
+            this.routeOne(output);
+        }
+        this.subscriberFanout.emit(outputs);
+    }
+    routeOne(output) {
+        switch (output.kind) {
+            case "stage-change":
+            case "loading-complete":
+                this.domEventBridge.dispatch(output);
+                break;
+            case "framework-error":
+                this.domEventBridge.dispatch(output);
+                this.frameworkErrorBridge.dispatch(output);
+                break;
+            default: {
+                const exhaustive = output;
+                void exhaustive;
+                return;
+            }
+        }
+        this.instrumentationBridge.dispatch(output);
+    }
+}
+//# sourceMappingURL=SectionEngineAdapter.js.map

package/dist/runtime/adapter/SectionEngineAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SectionEngineAdapter.js","sourceRoot":"","sources":["../../../src/runtime/adapter/SectionEngineAdapter.ts"],"names":[],"mappings":"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"}

package/dist/runtime/adapter/coordinator-bridge.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Coordinator bridge for the section runtime engine adapter (M7 —
+ * Variant C, layered).
+ *
+ * Unlike the DOM / legacy / framework-error bridges (which translate
+ * **outputs** into I/O), the coordinator bridge is an **input source**:
+ * it listens to a `ToolkitCoordinator` and feeds the resulting events
+ * into the core via the `dispatchCoreInput` callback supplied by the
+ * adapter.
+ *
+ * Responsibilities:
+ *   1. **Framework-error subscription.** When the coordinator reports
+ *      a framework error through its bus, dispatch a
+ *      `{ kind: "framework-error" }` core input. Listener isolation
+ *      matches `FrameworkErrorBus`: a throwing bridge handler is
+ *      caught and `console.warn`-logged so the original fan-out is
+ *      not interrupted.
+ *
+ *   2. **Section-controller resolution.** When the host calls
+ *      `resolveSectionController({ ... })`, the bridge invokes
+ *      `coordinator.getOrCreateSectionController({ ... })` and, on
+ *      successful resolution, dispatches
+ *      `{ kind: "section-controller-resolved" }` to the core. Init
+ *      tokens guard against late resolutions overwriting a more
+ *      recent cohort (mirrors `SectionRuntimeEngine.initialize`'s
+ *      `activeInitToken` pattern).
+ *
+ *   3. **Disposal.** On `dispose()`, the bridge unsubscribes from the
+ *      framework-error bus and (if the engine owns the section
+ *      controller for the cohort) calls
+ *      `coordinator.disposeSectionController({ ... })`. It does
+ *      **not** dispose the coordinator itself — the coordinator's
+ *      lifetime is owned by the toolkit CE / host, not by the engine.
+ *
+ * Disposal is idempotent: calling `dispose()` twice is a no-op.
+ *
+ * The bridge **must not** import `svelte`.
+ */
+import type { SectionControllerHandle } from "../../services/section-controller-types.js";
+import type { CohortKey } from "../core/cohort.js";
+import type { SectionEngineInput } from "../core/engine-input.js";
+/**
+ * Subset of the `ToolkitCoordinator` surface the bridge consumes. Kept
+ * structural so tests can pass a fake without pulling the full
+ * coordinator.
+ */
+export interface CoordinatorPort {
+    subscribeFrameworkErrors(listener: (model: import("../../services/framework-error.js").FrameworkErrorModel) => void): () => void;
+    getOrCreateSectionController(args: {
+        sectionId: string;
+        attemptId?: string;
+        input?: unknown;
+        updateExisting?: boolean;
+        createDefaultController: () => SectionControllerHandle | Promise<SectionControllerHandle>;
+    }): Promise<SectionControllerHandle>;
+    disposeSectionController(args: {
+        sectionId: string;
+        attemptId?: string;
+    }): Promise<void>;
+}
+export interface ResolveSectionControllerArgs {
+    cohort: CohortKey;
+    assessmentId: string;
+    view: string;
+    section: unknown;
+    createDefaultController: () => SectionControllerHandle | Promise<SectionControllerHandle>;
+    /**
+     * Optional callback invoked when the controller resolves and on
+     * every controller `subscribe` event. The kernel uses this to keep
+     * its composition snapshot in sync with the controller's view.
+     *
+     * The bridge is responsible for unsubscribing on dispose / cohort
+     * change so a stale controller doesn't keep emitting after rollover.
+     */
+    onCompositionChanged?: (composition: unknown) => void;
+    /**
+     * Optional callback invoked once with the resolved controller handle
+     * the moment it is available. Lets the host keep a reference for
+     * direct method calls (e.g. `navigateToItem`, `applySession`)
+     * without re-querying the coordinator.
+     */
+    onControllerResolved?: (controller: SectionControllerHandle) => void;
+}
+export interface CoordinatorBridgeOptions {
+    coordinator: CoordinatorPort;
+    dispatchCoreInput: (input: SectionEngineInput) => void;
+}
+export interface CoordinatorBridgeHandle {
+    resolveSectionController(args: ResolveSectionControllerArgs): Promise<void>;
+    dispose(): Promise<void>;
+}
+export declare function createCoordinatorBridge(options: CoordinatorBridgeOptions): CoordinatorBridgeHandle;
+//# sourceMappingURL=coordinator-bridge.d.ts.map

package/dist/runtime/adapter/coordinator-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-bridge.d.ts","sourceRoot":"","sources":["../../../src/runtime/adapter/coordinator-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAEX,uBAAuB,EACvB,MAAM,4CAA4C,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,wBAAwB,CACvB,QAAQ,EAAE,CACT,KAAK,EAAE,OAAO,mCAAmC,EAAE,mBAAmB,KAClE,IAAI,GACP,MAAM,IAAI,CAAC;IAEd,4BAA4B,CAAC,IAAI,EAAE;QAClC,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,uBAAuB,EAAE,MACtB,uBAAuB,GACvB,OAAO,CAAC,uBAAuB,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAErC,wBAAwB,CAAC,IAAI,EAAE;QAC9B,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,4BAA4B;IAC5C,MAAM,EAAE,SAAS,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,uBAAuB,EAAE,MACtB,uBAAuB,GACvB,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACpC;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;IACtD;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,uBAAuB,KAAK,IAAI,CAAC;CACrE;AAED,MAAM,WAAW,wBAAwB;IACxC,WAAW,EAAE,eAAe,CAAC;IAC7B,iBAAiB,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,uBAAuB;IACvC,wBAAwB,CAAC,IAAI,EAAE,4BAA4B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,wBAAwB,GAC/B,uBAAuB,CA8GzB"}

package/dist/runtime/adapter/coordinator-bridge.js

@@ -0,0 +1,127 @@
+/**
+ * Coordinator bridge for the section runtime engine adapter (M7 —
+ * Variant C, layered).
+ *
+ * Unlike the DOM / legacy / framework-error bridges (which translate
+ * **outputs** into I/O), the coordinator bridge is an **input source**:
+ * it listens to a `ToolkitCoordinator` and feeds the resulting events
+ * into the core via the `dispatchCoreInput` callback supplied by the
+ * adapter.
+ *
+ * Responsibilities:
+ *   1. **Framework-error subscription.** When the coordinator reports
+ *      a framework error through its bus, dispatch a
+ *      `{ kind: "framework-error" }` core input. Listener isolation
+ *      matches `FrameworkErrorBus`: a throwing bridge handler is
+ *      caught and `console.warn`-logged so the original fan-out is
+ *      not interrupted.
+ *
+ *   2. **Section-controller resolution.** When the host calls
+ *      `resolveSectionController({ ... })`, the bridge invokes
+ *      `coordinator.getOrCreateSectionController({ ... })` and, on
+ *      successful resolution, dispatches
+ *      `{ kind: "section-controller-resolved" }` to the core. Init
+ *      tokens guard against late resolutions overwriting a more
+ *      recent cohort (mirrors `SectionRuntimeEngine.initialize`'s
+ *      `activeInitToken` pattern).
+ *
+ *   3. **Disposal.** On `dispose()`, the bridge unsubscribes from the
+ *      framework-error bus and (if the engine owns the section
+ *      controller for the cohort) calls
+ *      `coordinator.disposeSectionController({ ... })`. It does
+ *      **not** dispose the coordinator itself — the coordinator's
+ *      lifetime is owned by the toolkit CE / host, not by the engine.
+ *
+ * Disposal is idempotent: calling `dispose()` twice is a no-op.
+ *
+ * The bridge **must not** import `svelte`.
+ */
+export function createCoordinatorBridge(options) {
+    const { coordinator, dispatchCoreInput } = options;
+    let activeInitToken = 0;
+    let activeCohort = null;
+    let unsubscribeController = null;
+    let disposed = false;
+    const unsubscribeFrameworkErrors = coordinator.subscribeFrameworkErrors((model) => {
+        try {
+            dispatchCoreInput({ kind: "framework-error", error: model });
+        }
+        catch (error) {
+            console.warn("[CoordinatorBridge] framework-error dispatch failed:", error);
+        }
+    });
+    function detachControllerSubscription() {
+        if (!unsubscribeController)
+            return;
+        try {
+            unsubscribeController();
+        }
+        catch (error) {
+            console.warn("[CoordinatorBridge] controller unsubscribe failed:", error);
+        }
+        unsubscribeController = null;
+    }
+    async function resolveSectionController(args) {
+        if (disposed)
+            return;
+        activeInitToken += 1;
+        const token = activeInitToken;
+        activeCohort = args.cohort;
+        const controller = await coordinator.getOrCreateSectionController({
+            sectionId: args.cohort.sectionId,
+            attemptId: args.cohort.attemptId || undefined,
+            input: {
+                section: args.section,
+                sectionId: args.cohort.sectionId,
+                assessmentId: args.assessmentId,
+                view: args.view,
+            },
+            updateExisting: true,
+            createDefaultController: args.createDefaultController,
+        });
+        // Drop late resolutions — a cohort change or dispose may have
+        // rolled the token forward while we awaited the coordinator.
+        if (token !== activeInitToken || disposed)
+            return;
+        detachControllerSubscription();
+        args.onControllerResolved?.(controller);
+        const getCompositionModel = controller.getCompositionModel;
+        args.onCompositionChanged?.(getCompositionModel?.());
+        if (typeof controller.subscribe === "function") {
+            unsubscribeController = controller.subscribe((_event) => {
+                if (token !== activeInitToken || disposed)
+                    return;
+                args.onCompositionChanged?.(getCompositionModel?.());
+            });
+        }
+        dispatchCoreInput({ kind: "section-controller-resolved" });
+    }
+    async function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        activeInitToken += 1;
+        detachControllerSubscription();
+        try {
+            unsubscribeFrameworkErrors();
+        }
+        catch (error) {
+            console.warn("[CoordinatorBridge] framework-error unsubscribe failed:", error);
+        }
+        const cohort = activeCohort;
+        activeCohort = null;
+        if (cohort) {
+            try {
+                await coordinator.disposeSectionController({
+                    sectionId: cohort.sectionId,
+                    attemptId: cohort.attemptId || undefined,
+                });
+            }
+            catch (error) {
+                console.warn("[CoordinatorBridge] section-controller dispose failed:", error);
+            }
+        }
+    }
+    return { resolveSectionController, dispose };
+}
+//# sourceMappingURL=coordinator-bridge.js.map

package/dist/runtime/adapter/coordinator-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator-bridge.js","sourceRoot":"","sources":["../../../src/runtime/adapter/coordinator-bridge.ts"],"names":[],"mappings":"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"}

package/dist/runtime/adapter/dom-event-bridge.d.ts

@@ -0,0 +1,63 @@
+/**
+ * DOM event bridge for the section runtime engine adapter (M7 — Variant
+ * C, layered).
+ *
+ * Translates canonical engine outputs (`stage-change`,
+ * `loading-complete`, `framework-error`) into DOM `CustomEvent`
+ * dispatches on the host element. Mirrors the kernel's existing
+ * `dispatch("pie-stage-change", …)` / `dispatch("pie-loading-complete", …)`
+ * / `dispatch("framework-error", …)` emit chain bit-for-bit so the M6
+ * canonical event surface stays stable while the kernel migrates onto
+ * the engine in PR 5.
+ *
+ * **Detail-shape contract.** The engine core emits structurally minimal
+ * outputs (`{ stage, status, cohort }`, `{ cohort, itemCount,
+ * loadedCount }`). The bridge enriches them with `runtimeId`,
+ * `sourceCe`, and `timestamp` so the dispatched DOM event detail
+ * matches the legacy
+ * `packages/players-shared/src/pie/stages.ts#StageChangeDetail` and
+ * `LoadingCompleteDetail` shapes verbatim. `runtimeId` and `sourceCe`
+ * are supplied at adapter construction time (one per engine instance);
+ * `timestamp` is captured per-emit via the injected `now()` clock so
+ * tests can pin a deterministic value.
+ *
+ * **Why not import the stage tracker.** The tracker's monotonic /
+ * skipped-fill enforcement now lives in the engine core's transition
+ * function. The bridge is purely an output-to-DOM translator — it does
+ * not gate emissions, does not re-order, does not de-duplicate. That
+ * keeps the responsibility clean and matches the "outputs are already
+ * ordered correctly by the core" contract from
+ * `engine-transition.ts`.
+ *
+ * The bridge **must not** import `svelte`; per the M7 layering
+ * constraint the adapter is plain TS.
+ */
+import type { SectionEngineOutput } from "../core/engine-output.js";
+export interface DomEventBridgeOptions {
+    /** Element on which to dispatch the DOM events. */
+    host: EventTarget;
+    /** Stable runtime id for this engine instance. */
+    runtimeId: string;
+    /**
+     * Tag name of the host CE without the `--version-<encoded>` suffix.
+     * Each layout CE that mounts the kernel passes its own canonical tag
+     * name; the toolkit CE passes its own.
+     */
+    sourceCe: string;
+    /**
+     * Clock injection for tests. Defaults to `() => new Date().toISOString()`.
+     */
+    now?: () => string;
+}
+export interface DomEventBridgeHandle {
+    /** Translate a single engine output into a DOM dispatch. */
+    dispatch(output: SectionEngineOutput): void;
+    /**
+     * Update the host element after construction (e.g. when the kernel
+     * receives its host element via Svelte action / context). The
+     * bridge keeps the latest host; future dispatches go to that host.
+     */
+    setHost(host: EventTarget): void;
+}
+export declare function createDomEventBridge(options: DomEventBridgeOptions): DomEventBridgeHandle;
+//# sourceMappingURL=dom-event-bridge.d.ts.map

package/dist/runtime/adapter/dom-event-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-event-bridge.d.ts","sourceRoot":"","sources":["../../../src/runtime/adapter/dom-event-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,WAAW,qBAAqB;IACrC,mDAAmD;IACnD,IAAI,EAAE,WAAW,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC5C;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAED,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,qBAAqB,GAC5B,oBAAoB,CA6EtB"}

package/dist/runtime/adapter/dom-event-bridge.js

@@ -0,0 +1,95 @@
+/**
+ * DOM event bridge for the section runtime engine adapter (M7 — Variant
+ * C, layered).
+ *
+ * Translates canonical engine outputs (`stage-change`,
+ * `loading-complete`, `framework-error`) into DOM `CustomEvent`
+ * dispatches on the host element. Mirrors the kernel's existing
+ * `dispatch("pie-stage-change", …)` / `dispatch("pie-loading-complete", …)`
+ * / `dispatch("framework-error", …)` emit chain bit-for-bit so the M6
+ * canonical event surface stays stable while the kernel migrates onto
+ * the engine in PR 5.
+ *
+ * **Detail-shape contract.** The engine core emits structurally minimal
+ * outputs (`{ stage, status, cohort }`, `{ cohort, itemCount,
+ * loadedCount }`). The bridge enriches them with `runtimeId`,
+ * `sourceCe`, and `timestamp` so the dispatched DOM event detail
+ * matches the legacy
+ * `packages/players-shared/src/pie/stages.ts#StageChangeDetail` and
+ * `LoadingCompleteDetail` shapes verbatim. `runtimeId` and `sourceCe`
+ * are supplied at adapter construction time (one per engine instance);
+ * `timestamp` is captured per-emit via the injected `now()` clock so
+ * tests can pin a deterministic value.
+ *
+ * **Why not import the stage tracker.** The tracker's monotonic /
+ * skipped-fill enforcement now lives in the engine core's transition
+ * function. The bridge is purely an output-to-DOM translator — it does
+ * not gate emissions, does not re-order, does not de-duplicate. That
+ * keeps the responsibility clean and matches the "outputs are already
+ * ordered correctly by the core" contract from
+ * `engine-transition.ts`.
+ *
+ * The bridge **must not** import `svelte`; per the M7 layering
+ * constraint the adapter is plain TS.
+ */
+export function createDomEventBridge(options) {
+    const { runtimeId, sourceCe } = options;
+    let host = options.host;
+    const now = options.now ?? (() => new Date().toISOString());
+    function dispatchStageChange(output) {
+        const detail = {
+            stage: output.stage,
+            status: output.status,
+            runtimeId,
+            sectionId: output.cohort?.sectionId,
+            attemptId: output.cohort?.attemptId ? output.cohort.attemptId : undefined,
+            timestamp: now(),
+            sourceCe,
+        };
+        host.dispatchEvent(new CustomEvent("pie-stage-change", { detail }));
+    }
+    function dispatchLoadingComplete(output) {
+        const detail = {
+            runtimeId,
+            sectionId: output.cohort.sectionId,
+            attemptId: output.cohort.attemptId ? output.cohort.attemptId : undefined,
+            itemCount: output.itemCount,
+            loadedCount: output.loadedCount,
+            timestamp: now(),
+            sourceCe,
+        };
+        host.dispatchEvent(new CustomEvent("pie-loading-complete", {
+            detail,
+        }));
+    }
+    function dispatchFrameworkError(output) {
+        // Mirror the kernel's existing surface — the `framework-error`
+        // DOM event detail is the framework-error model. The
+        // `framework-error-bridge` separately reports the same model
+        // into the bus so subscribers see one fan-out per error.
+        host.dispatchEvent(new CustomEvent("framework-error", { detail: output.error }));
+    }
+    function dispatch(output) {
+        switch (output.kind) {
+            case "stage-change":
+                dispatchStageChange(output);
+                return;
+            case "loading-complete":
+                dispatchLoadingComplete(output);
+                return;
+            case "framework-error":
+                dispatchFrameworkError(output);
+                return;
+            default: {
+                const exhaustive = output;
+                void exhaustive;
+                return;
+            }
+        }
+    }
+    function setHost(next) {
+        host = next;
+    }
+    return { dispatch, setHost };
+}
+//# sourceMappingURL=dom-event-bridge.js.map

package/dist/runtime/adapter/dom-event-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-event-bridge.js","sourceRoot":"","sources":["../../../src/runtime/adapter/dom-event-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAoCH,MAAM,UAAU,oBAAoB,CACnC,OAA8B;IAE9B,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACxC,IAAI,IAAI,GAAgB,OAAO,CAAC,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IAE5D,SAAS,mBAAmB,CAC3B,MAA8D;QAE9D,MAAM,MAAM,GAAsB;YACjC,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS;YACT,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS;YACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YACzE,SAAS,EAAE,GAAG,EAAE;YAChB,QAAQ;SACR,CAAC;QACF,IAAI,CAAC,aAAa,CACjB,IAAI,WAAW,CAAoB,kBAAkB,EAAE,EAAE,MAAM,EAAE,CAAC,CAClE,CAAC;IACH,CAAC;IAED,SAAS,uBAAuB,CAC/B,MAAkE;QAElE,MAAM,MAAM,GAA0B;YACrC,SAAS;YACT,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS;YAClC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;YACxE,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,SAAS,EAAE,GAAG,EAAE;YAChB,QAAQ;SACR,CAAC;QACF,IAAI,CAAC,aAAa,CACjB,IAAI,WAAW,CAAwB,sBAAsB,EAAE;YAC9D,MAAM;SACN,CAAC,CACF,CAAC;IACH,CAAC;IAED,SAAS,sBAAsB,CAC9B,MAAiE;QAEjE,+DAA+D;QAC/D,qDAAqD;QACrD,6DAA6D;QAC7D,yDAAyD;QACzD,IAAI,CAAC,aAAa,CACjB,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAC5D,CAAC;IACH,CAAC;IAED,SAAS,QAAQ,CAAC,MAA2B;QAC5C,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACrB,KAAK,cAAc;gBAClB,mBAAmB,CAAC,MAAM,CAAC,CAAC;gBAC5B,OAAO;YACR,KAAK,kBAAkB;gBACtB,uBAAuB,CAAC,MAAM,CAAC,CAAC;gBAChC,OAAO;YACR,KAAK,iBAAiB;gBACrB,sBAAsB,CAAC,MAAM,CAAC,CAAC;gBAC/B,OAAO;YACR,OAAO,CAAC,CAAC,CAAC;gBACT,MAAM,UAAU,GAAU,MAAM,CAAC;gBACjC,KAAK,UAAU,CAAC;gBAChB,OAAO;YACR,CAAC;QACF,CAAC;IACF,CAAC;IAED,SAAS,OAAO,CAAC,IAAiB;QACjC,IAAI,GAAG,IAAI,CAAC;IACb,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/runtime/adapter/framework-error-bridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Framework-error bridge for the section runtime engine adapter (M7 —
+ * Variant C, layered).
+ *
+ * Routes `framework-error` engine outputs into a `FrameworkErrorBus`
+ * (write side: `FrameworkErrorReporter`). The bus is the single
+ * fan-out point shared with the toolkit CE's banner, the coordinator's
+ * canonical `onFrameworkError` lifecycle hook, and any direct host
+ * subscribers via `subscribeFrameworkErrors`. See
+ * `packages/assessment-toolkit/src/services/framework-error-bus.ts`
+ * for the full bus contract.
+ *
+ * **Why a separate bridge.** The dom-event-bridge dispatches the
+ * `framework-error` DOM event on the host. The framework-error-bridge
+ * routes the same model into the in-process bus so listeners that
+ * subscribe via `coordinator.subscribeFrameworkErrors(...)` see the
+ * same fan-out with byte-identical payloads. Splitting the
+ * responsibilities lets a host opt out of either side (DOM-only or
+ * bus-only) without re-implementing the other.
+ *
+ * **Bus ownership.** The bridge does not construct the bus; the
+ * adapter receives one externally so the toolkit CE can keep sharing
+ * its bus with the coordinator (matching today's
+ * `PieAssessmentToolkit.svelte` lifetime model). This avoids the
+ * "second bus" pitfall — a dual-bus topology would silently fragment
+ * fan-out.
+ */
+import type { FrameworkErrorReporter } from "../../services/framework-error-bus.js";
+import type { SectionEngineOutput } from "../core/engine-output.js";
+export interface FrameworkErrorBridgeOptions {
+    bus: FrameworkErrorReporter;
+}
+export interface FrameworkErrorBridgeHandle {
+    dispatch(output: SectionEngineOutput): void;
+}
+export declare function createFrameworkErrorBridge(options: FrameworkErrorBridgeOptions): FrameworkErrorBridgeHandle;
+//# sourceMappingURL=framework-error-bridge.d.ts.map

package/dist/runtime/adapter/framework-error-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-error-bridge.d.ts","sourceRoot":"","sources":["../../../src/runtime/adapter/framework-error-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AACpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,MAAM,WAAW,2BAA2B;IAC3C,GAAG,EAAE,sBAAsB,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC5C;AAED,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,2BAA2B,GAClC,0BAA0B,CAoB5B"}