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

package/dist/runtime/SectionRuntimeEngine.d.ts

@@ -1,197 +1,48 @@
 /**
- * Section runtime engine — public facade (M7 — Variant C, layered).
+ * Section runtime engine — the section player's stage chain.
  *
- * The facade is the narrow, stable entry point hosts use to mount,
- * drive, and dispose a section runtime. It composes three layers
- * introduced in earlier M7 PRs:
+ * The section player's layout kernel owns one per layout element and drives it
+ * with `dispatchInput`: the cohort it shows (`initialize`, `cohort-change`,
+ * `update-runtime`), the controller resolving (`section-controller-resolved`),
+ * and the readiness signals it derives (`update-readiness-signals`). The pure
+ * FSM core turns those into `pie-stage-change` and `pie-loading-complete`,
+ * which the adapter dispatches on the layout element, bubbling and composed;
+ * `subscribe` receives the same outputs in batches.
  *
- *   - the **registry** (`RuntimeRegistry`) — registered item/passage
- *     shells in document order, used for canonical-id lookup;
- *   - the **adapter** (`SectionEngineAdapter`) — single I/O seam over
- *     the pure FSM core, fanning outputs to the DOM, framework-error
- *     bus, instrumentation hook, and host subscribers;
- *   - the **resolver** (`resolveSectionEngineRuntimeState`) — the
- *     toolkit-side resolution helper that produces the effective
- *     runtime + tools snapshot a host feeds to the FSM core.
+ * The engine is the only stage emitter. It holds no controller and no
+ * registry: the toolkit's `SectionControllerBinding` owns those. The kernel
+ * learns that the controller resolved from the toolkit's `section-ready`, whose
+ * detail carries the controller and its cohort.
  *
- * The facade exposes an engine-side surface for stage/lifecycle inputs and a
- * controller-facing surface for item registration, session updates, and host
- * controller commands:
- *
- *   1. The **engine-side** surface (`attachHost`, `dispatchInput`,
- *      `subscribe`, `getState`, `getEffectiveRuntime`,
- *      `setInstrumentationHook`). This is what the kernel and the
- *      `pie-assessment-toolkit` CE will switch onto in M7 PR 5 and
- *      PR 6. Construction is lazy: `attachHost(...)` builds the
- *      adapter on first call, with the supplied host element,
- *      framework-error bus, and (optional) coordinator. After
- *      construction, host re-attachments (e.g. cohort change with a
- *      new layout shell) update the adapter's host element via
- *      `setHost(...)`.
- *
- *   2. The **controller-side** surface (`initialize`,
- *      `register`, `unregister`, `handleContent*`, `updateItemSession`,
- *      `navigateToItem`, `persist`, `hydrate`, `dispose`). The
- *      `PieAssessmentToolkit.svelte` CE drives section-controller and
- *      item-shell events through this surface.
- *
- * The two surfaces share `RuntimeRegistry` and the resolved
- * `SectionControllerHandle`.
+ * `attachHost(...)` builds the adapter on first call; a later call moves it to
+ * a new host element.
  */
-import type { ToolkitCoordinator } from "../services/ToolkitCoordinator.js";
-import type { FrameworkErrorReporter } from "../services/framework-error-bus.js";
-import type { SectionControllerEvent, SectionControllerHandle } from "../services/section-controller-types.js";
-import { type SectionEngineAdapterOptions } from "./adapter/SectionEngineAdapter.js";
-import type { InstrumentationHook } from "./adapter/instrumentation-bridge.js";
 import type { EngineOutputListener } from "./adapter/subscriber-fanout.js";
 import type { SectionEngineInput } from "./core/engine-input.js";
 import type { SectionEngineOutput } from "./core/engine-output.js";
-import { type EffectiveRuntime, type RuntimeInputs } from "./core/engine-resolver.js";
 import { type SectionEngineState } from "./core/engine-state.js";
-import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
-import type { RuntimeRegistrationDetail } from "./registration-events.js";
-import { RuntimeRegistry } from "./RuntimeRegistry.js";
-/**
- * Structural view of the resolved section controller, widened with the
- * extra methods the toolkit's runtime CE calls directly. Optional so
- * stub controllers used in tests do not need every entry point.
- */
-interface RuntimeController extends SectionControllerHandle {
-    getCompositionModel?: () => unknown;
-    getCanonicalItemId?: (itemId: string) => string;
-    handleContentLoaded?: (args: {
-        itemId: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-        detail?: unknown;
-        timestamp?: number;
-    }) => void;
-    handleContentRegistered?: (args: {
-        itemId: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-    }) => void;
-    handleContentUnregistered?: (args: {
-        itemId: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-    }) => void;
-    handleItemPlayerError?: (args: {
-        itemId: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-        error: unknown;
-        timestamp?: number;
-    }) => void;
-    reportSectionError?: (args: {
-        source: "item-player" | "section-runtime" | "toolkit" | "controller";
-        error: unknown;
-        itemId?: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-        timestamp?: number;
-    }) => void;
-    updateItemSession?: (itemId: string, sessionDetail: unknown) => {
-        eventDetail?: unknown;
-    } | null;
-    subscribe?: (listener: (event: SectionControllerEvent) => void) => () => void;
-    navigateToItem?: (index: number) => unknown;
-    attachMediaTimeSource?: (source: MediaTimeSource, options?: {
-        origin?: "native-adapter" | "host";
-        renderableId?: string;
-    }) => void;
-    detachMediaTimeSource?: (options?: {
-        origin?: "native-adapter" | "host";
-    }) => void;
-    pauseMediaForCompetingAudio?: () => boolean;
-}
-/** What a media-time-source registration reaching the engine has to say. */
-export interface SectionRuntimeMediaTimeSourceAction {
-    renderableId: string;
-    action: "attach" | "detach";
-    source?: MediaTimeSource;
-    origin?: "native-adapter" | "host";
-}
-/** What a formative action reaching the engine has to say. */
-export interface SectionRuntimeFormativeAction {
-    itemId: string;
-    action: "check" | "retry";
-    outcomes?: unknown[];
-}
-/**
- * Initialize args used by the toolkit CE to resolve the coordinator-backed
- * section controller.
- */
-interface EngineInitArgs {
-    coordinator: ToolkitCoordinator;
-    section: unknown;
-    sectionId: string;
-    assessmentId: string;
-    view: string;
-    attemptId?: string;
-    createDefaultController: () => Promise<RuntimeController> | RuntimeController;
-    onCompositionChanged?: (composition: unknown) => void;
-    /**
-     * The controller event that caused a republish, for the few events the toolkit
-     * has to act on rather than merely propagate — a timed-media policy that cannot
-     * be enforced becomes a framework warning, and malformed cue data becomes a
-     * framework error. Every other event reaches hosts through the composition
-     * republish and the coordinator's own subscriptions.
-     */
-    onControllerEvent?: (event: SectionControllerEvent) => void;
-}
-/**
- * Engine-side `attachHost` args. The host element, framework-error bus,
- * and `sourceCe` together let the adapter dispatch DOM events and bus
- * fan-outs consistently with the kernel emit chain.
- */
+/** `attachHost` args: the element events are dispatched on, and its tag. */
 export interface SectionRuntimeEngineHostArgs {
     host: EventTarget;
     sourceCe: string;
-    frameworkErrorBus: FrameworkErrorReporter;
-    coordinator?: SectionEngineAdapterOptions["coordinator"];
-    instrumentationHook?: InstrumentationHook;
     now?: () => string;
 }
 export declare class SectionRuntimeEngine {
-    private readonly registry;
     private readonly runtimeId;
     private adapter;
-    private controller;
-    private coordinator;
-    private sectionId;
-    private attemptId;
-    private unsubscribeController;
-    private activeInitToken;
-    /**
-     * Tracks which `(canonicalItemId, contentKind)` pairs have already
-     * fired `handleContentLoaded` on this engine. Mirrored alongside
-     * `RuntimeRegistry`'s registered set so a cohort handoff can
-     * replay the persistent shells' loaded state into the new
-     * controller — see `replayRegisteredShellsIntoController` and the
-     * PIE-512 Phase B regression test.
-     *
-     * Cleared in lockstep with `handleContentUnregistered` and on
-     * `dispose`. Not exposed publicly: the registry alone is the
-     * external surface; the loaded set exists only to seed cohort B's
-     * controller with the live state cohort A's shells produced.
-     */
-    private readonly loadedRenderableKeys;
     /**
-     * Attach the host element + framework-error bus + sourceCe so the
-     * adapter can dispatch DOM events and bus errors. Required before
-     * `dispatchInput` / `subscribe` produce observable effects.
+     * Attach the host element and `sourceCe` the adapter dispatches DOM events
+     * with. Required before `dispatchInput` / `subscribe` produce observable
+     * effects.
      *
-     * Constructs the adapter on the first call. Subsequent calls keep
-     * the adapter and update its host element / instrumentation hook
-     * (used by layout-shell rollovers and instrumentation reconfig).
+     * Constructs the adapter on the first call. Subsequent calls keep the
+     * adapter and update its host element.
      */
     attachHost(args: SectionRuntimeEngineHostArgs): void;
     /**
      * Forward a host-constructed input to the FSM core via the adapter.
      * Returns the outputs the transition produced (subscribers and the
-     * DOM/framework-error/instrumentation bridges have already
-     * received them).
+     * DOM bridge have already received them).
      *
      * No-op (returns `[]`) before `attachHost(...)` so callers that
      * dispatch optimistically during teardown do not throw.
@@ -211,127 +62,13 @@ export declare class SectionRuntimeEngine {
      */
     getState(): Readonly<SectionEngineState>;
     /**
-     * Resolve the effective runtime + tools snapshot for the given
-     * two-tier inputs. This is a pure function over the resolver — it
-     * does not depend on adapter state — so callers can use it both
-     * pre- and post-`attachHost`. The kernel uses it to seed
-     * `dispatchInput({ kind: "initialize", effectiveRuntime, ... })`.
-     */
-    getEffectiveRuntime<P>(args: RuntimeInputs, deps: {
-        resolvePlayerRuntime: (resolverArgs: {
-            effectiveRuntime: Record<string, unknown>;
-            playerType: string;
-            env: Record<string, unknown> | null;
-        }) => P;
-    }): EffectiveRuntime;
-    /**
-     * Update the adapter's instrumentation hook. No-op pre-attach.
-     * Hosts that always want a hook should pass it via `attachHost`.
-     */
-    setInstrumentationHook(hook: InstrumentationHook | undefined): void;
-    /**
-     * Stable per-engine runtime id used to scope DOM-event details and
-     * registry telemetry. Exposed so tests and instrumentation can pin
-     * the value the bridges emit.
+     * Stable per-engine runtime id, the `runtimeId` of every event detail the
+     * engine dispatches.
      */
     getRuntimeId(): string;
-    initialize(args: EngineInitArgs): Promise<void>;
     /**
-     * Re-feed the engine's `RuntimeRegistry` and loaded-set into the
-     * resolved controller. Call site: `initialize(...)` — runs on
-     * EVERY initialize, both cohort-flip-resolves-fresh-controller
-     * and same-cohort-resolves-existing-controller cases. Phase C
-     * dropped the `resolved !== previousController` gate; see the
-     * comment at the call site for why.
-     *
-     * Two-pass order — register every shell in document order, then
-     * issue `handleContentLoaded` for each shell whose load already
-     * fired on this engine. The two-pass shape prevents
-     * `evaluateSectionLoadingState` from flapping
-     * `section-loading-complete` `false→true→false→…` while replay is
-     * mid-walk: any subscriber wired before the engine's own
-     * `controller.subscribe` (no such caller today, but cheap defense
-     * for future wiring) sees one clean `false→true` transition.
-     *
-     * Idempotent on the controller side — Phase C makes
-     * `SectionController.handleContentRegistered` and
-     * `handleContentLoaded` early-return on duplicates so re-feeding
-     * the same shells into a controller that already tracks them is
-     * a true no-op (no spurious re-emits, no re-evaluation of
-     * `section-loading-complete`). At the call site no listener is
-     * attached during the replay window, so `emitChange` side effects
-     * fire into a void on this pass anyway, but the controller-side
-     * idempotence is what makes the replay safe to run on every
-     * initialize regardless of whether the controller is fresh.
-     */
-    private replayRegisteredShellsIntoController;
-    /**
-     * Stable key for the engine's `loadedRenderableKeys` set. Mirrors
-     * the `(canonicalItemId, contentKind)` shape `SectionController`
-     * uses internally (see `getRenderableKey`); we only need
-     * consistent add/check semantics on this side, not byte-identical
-     * normalization with the controller.
-     */
-    private getLoadedKey;
-    register(detail: RuntimeRegistrationDetail): boolean;
-    unregister(element: HTMLElement): boolean;
-    getCompositionModel(): unknown;
-    getCanonicalItemId(itemId: string): string;
-    handleContentRegistered(detail: RuntimeRegistrationDetail): void;
-    handleContentUnregistered(detail: RuntimeRegistrationDetail): void;
-    handleContentLoaded(args: {
-        itemId: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-        detail?: unknown;
-        timestamp?: number;
-    }): void;
-    handleItemPlayerError(args: {
-        itemId: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-        error: unknown;
-        timestamp?: number;
-    }): void;
-    reportSectionError(args: {
-        source: "item-player" | "section-runtime" | "toolkit" | "controller";
-        error: unknown;
-        itemId?: string;
-        canonicalItemId?: string;
-        contentKind?: string;
-        timestamp?: number;
-    }): void;
-    updateItemSession(itemId: string, session: unknown): unknown;
-    navigateToItem(index: number): unknown;
-    /**
-     * Route a learner's formative action to the controller.
-     *
-     * Canonicalized here for the same reason `updateItemSession` is: the runtime
-     * id a card dispatches with is not necessarily the identifier the controller
-     * keys state by.
-     */
-    handleFormativeAction(action: SectionRuntimeFormativeAction): void;
-    /**
-     * Bind or release the section's Media Time Source.
-     *
-     * A pass-through, like `handleFormativeAction`: the engine routes, the
-     * controller decides. `renderableId` travels with the attach because whether the
-     * registering renderable is the one `stimulusRef` names is the controller's call
-     * — it validated `stimulusRef` in the first place.
-     */
-    handleMediaTimeSource(action: SectionRuntimeMediaTimeSourceAction): void;
-    /**
-     * Silence media audio because something else is about to speak.
-     *
-     * A pass-through like `handleMediaTimeSource`, and for the same reason: which
-     * source is authoritative and whether it reports `canPause` are the controller's
-     * to know. Returns whether media audio is now silent, or `true` where there is
-     * no timed-media controller to ask — nothing is playing.
+     * Emit `disposed` for the active cohort and detach. Idempotent; inputs
+     * after it are ignored.
      */
-    requestMediaPauseForCompetingAudio(): boolean;
-    persist(): Promise<void>;
-    hydrate(): Promise<void>;
-    getRegistry(): RuntimeRegistry;
-    dispose(): Promise<void>;
+    dispose(): void;
 }
-export {};