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

package/dist/runtime/SectionControllerBinding.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Section controller binding — the toolkit's side of a section runtime.
+ *
+ * `PieAssessmentToolkit` holds one per element. It resolves the section's
+ * controller from the coordinator (`initialize`), keeps the registered item and
+ * passage shells (`RuntimeRegistry`) and which of them have loaded, replays
+ * both into each controller it resolves, and forwards shell events, session
+ * updates and host commands to that controller.
+ *
+ * The registry outlives a section switch: the shells of the section being left
+ * stay registered until they unmount. One membership rule routes every shell
+ * event, in replay or live: an event goes to the controller of the section
+ * whose composition renders the shell, which is the current controller or a
+ * cached controller of a section this binding bound earlier, and is dropped
+ * with a warning when no bound section renders it; see `controllerFor`. A
+ * cached controller re-bound on a revisit first forgets the loads of shells
+ * that are no longer registered, so its `section-loading-complete` waits for
+ * the new shells.
+ *
+ * The section's stage chain is a separate object: the section player's layout
+ * kernel drives a `SectionRuntimeEngine` from the readiness signals it derives.
+ * The two share no state.
+ */
+import type { ToolkitCoordinator } from "../services/ToolkitCoordinator.js";
+import type { SectionControllerEvent, SectionControllerHandle, SectionControllerSessionState } from "../services/section-controller-types.js";
+import type { MediaTimeSource } from "@pie-players/pie-players-shared/timed-media";
+import type { RuntimeRegistrationDetail } from "./registration-events.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 binding has to say. */
+export interface SectionRuntimeMediaTimeSourceAction {
+    renderableId: string;
+    action: "attach" | "detach";
+    source?: MediaTimeSource;
+    origin?: "native-adapter" | "host";
+}
+/** What a formative action reaching the binding has to say. */
+export interface SectionRuntimeFormativeAction {
+    itemId: string;
+    canonicalItemId?: string;
+    action: "check" | "retry";
+    outcomes?: unknown[];
+}
+/**
+ * Initialize args used by the toolkit CE to resolve the coordinator-backed
+ * section controller.
+ */
+export interface SectionControllerBindingInitArgs {
+    coordinator: ToolkitCoordinator;
+    section: unknown;
+    sectionId: string;
+    assessmentId: string;
+    view: string;
+    attemptId?: string;
+    /**
+     * A host-supplied session for this section, applied by the coordinator in
+     * place of `hydrate()` when it creates the controller. Absent, creation
+     * hydrates from the persistence strategy as before.
+     */
+    initialSession?: SectionControllerSessionState | null;
+    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;
+}
+export declare class SectionControllerBinding {
+    private readonly registry;
+    private controller;
+    private coordinator;
+    private sectionId;
+    private attemptId;
+    private unsubscribeController;
+    private activeInitToken;
+    /**
+     * Ids of the renderables in the current controller's composition model, read
+     * when `initialize` resolves it. `null` while no controller is resolved, and
+     * for a controller that publishes no `renderables`: its section cannot be
+     * told apart, so every shell reaches it.
+     */
+    private sectionRenderableIds;
+    /**
+     * The renderable ids of every section this binding has bound, keyed by
+     * section and attempt, least recently bound first. `controllerFor` reads it
+     * to find the section that owns a shell outside the current one.
+     */
+    private readonly boundSections;
+    /**
+     * Tracks which `(canonicalItemId, contentKind)` pairs have already
+     * fired `handleContentLoaded` on this binding, so a section handoff can
+     * replay the persistent shells' loaded state into the new controller; see
+     * `replayRegisteredShellsIntoController`.
+     *
+     * Records loads of every registered shell, in or out of the current
+     * section, so a shell registered ahead of its section's controller is
+     * replayed as loaded. A key is dropped when its last shell unregisters,
+     * and on `dispose`.
+     */
+    private readonly loadedRenderableKeys;
+    initialize(args: SectionControllerBindingInitArgs): Promise<void>;
+    /**
+     * Re-feed the binding's `RuntimeRegistry` and loaded-set into the
+     * resolved controller, limited to the shells of its section (see
+     * `isSectionRenderable`). Runs on every `initialize`.
+     *
+     * Two-pass order — register every shell in document order, then
+     * issue `handleContentLoaded` for each shell whose load already
+     * fired on this binding. The two-pass shape prevents
+     * `evaluateSectionLoadingState` from flapping
+     * `section-loading-complete` `false→true→false→…` while replay is
+     * mid-walk: any subscriber wired before the binding'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: `handleContentRegistered` and
+     * `handleContentLoaded` return early on duplicates, so re-feeding shells
+     * the controller already tracks emits nothing.
+     */
+    private replayRegisteredShellsIntoController;
+    /**
+     * Stable key for the binding'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;
+    /**
+     * Whether a shell renders one of the current section's renderables: its
+     * runtime or canonical id is among the composition model's renderable ids.
+     * An item in two sections belongs to both, so its shell carries over a
+     * switch the way a persistent passage shell does.
+     */
+    private isSectionRenderable;
+    private getSectionKey;
+    /**
+     * The controller a shell event belongs to: the current controller when the
+     * shell renders one of its section's renderables, otherwise the cached
+     * controller of the most recently bound section that renders it — the
+     * section being left, for an outgoing shell's teardown. `null` when no bound
+     * section renders the shell or its controller is gone.
+     */
+    private controllerFor;
+    /** `controllerFor`, warning when the event has nowhere to go. */
+    private requireControllerFor;
+    /**
+     * Forget, on a cached controller about to be re-bound, every load whose
+     * shell is no longer registered. A shell that unmounted while its section
+     * was not current told that section's controller through `controllerFor`;
+     * this covers one whose unregister never arrived.
+     */
+    private forgetUnregisteredLoads;
+    register(detail: RuntimeRegistrationDetail): boolean;
+    unregister(element: HTMLElement): boolean;
+    getCompositionModel(): unknown;
+    getCanonicalItemId(itemId: string): string;
+    handleContentRegistered(detail: RuntimeRegistrationDetail): void;
+    /**
+     * Called after `unregister` removed the shell from the registry. While
+     * another registered shell renders the same renderable — the next
+     * section's shell for an item both sections hold — the renderable stays
+     * registered and loaded.
+     */
+    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. Both ids are kept, since the composition's renderables are
+     * keyed by the runtime one.
+     */
+    handleFormativeAction(action: SectionRuntimeFormativeAction): void;
+    /**
+     * Bind or release the section's Media Time Source.
+     *
+     * A pass-through, like `handleFormativeAction`: the binding 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.
+     */
+    requestMediaPauseForCompetingAudio(): boolean;
+    persist(): Promise<void>;
+    hydrate(): Promise<void>;
+    /**
+     * Releases the binding and disposes the controller of every section it
+     * bound, so a coordinator the host passes or an outer toolkit lends keeps
+     * none of this toolkit's sections, and a later mount of one restores it from
+     * its session. The coordinator itself stays with its owner.
+     */
+    dispose(): Promise<void>;
+}
+export {};