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

package/dist/policy/sources/PnpPolicySource.js

@@ -1,6 +1,5 @@
 /**
- * PNP Policy Source for the M8 engine
- * (see
+ * PNP Policy Source: step 5 of `composeDecision` (see
  * `docs/tools-and-accomodations/architecture.md`).
  *
  * This source applies the PNP/profile precedence rules as a `(candidates, pnpPolicyInputs) →
@@ -16,12 +15,15 @@ export class PnpPolicySource {
     }
     apply(args) {
         const { ctx, result } = this.prepare(args);
-        const { pnp, districtPolicy, itemSettings } = ctx;
+        const { pnp, districtPolicy, testAdmin, itemSettings } = ctx;
         const allSupports = new Set();
         pnp?.supports?.forEach((s) => allSupports.add(s));
         pnp?.prohibitedSupports?.forEach((s) => allSupports.add(s));
         districtPolicy?.blockedTools?.forEach((s) => allSupports.add(s));
         districtPolicy?.requiredTools?.forEach((s) => allSupports.add(s));
+        for (const s of Object.keys(testAdmin?.toolOverrides ?? {})) {
+            allSupports.add(s);
+        }
         itemSettings?.requiredTools?.forEach((s) => allSupports.add(s));
         itemSettings?.restrictedTools?.forEach((s) => allSupports.add(s));
         for (const supportId of allSupports) {
@@ -30,20 +32,18 @@ export class PnpPolicySource {
         return result;
     }
     /**
-     * Evaluate exactly one PNP support id through the same six-level
+     * Evaluate exactly one PNP support id through the same eight-level
      * precedence `apply(...)` uses.
      *
      * This exists for **policy-addressable capabilities that are not toolbar
      * tools** — a signed alternate rendered as its own region, for example.
      * `apply(...)` only evaluates support ids that appear somewhere in the
-     * bound policy inputs, and it keys its result maps by *mapped tool id*, so
-     * a caller asking about one feature would have to re-derive that mapping
-     * and could collide with another support id that maps to the same tool.
-     * Evaluating one id in isolation avoids both problems: the returned result
-     * carries exactly one decision, and `decisions[0].action` is the verdict.
+     * bound policy inputs. Evaluating one id in isolation answers for any
+     * feature: the returned result carries exactly one decision, and
+     * `decisions[0].action` is the verdict.
      *
      * Reusing `resolveSupport(...)` rather than re-walking the precedence rules
-     * is the point — a second copy of the six levels would drift.
+     * is the point — a second copy of the eight levels would drift.
      */
     resolveFeature(featureId, args) {
         const { ctx, result } = this.prepare(args);
@@ -55,16 +55,17 @@ export class PnpPolicySource {
      * configuration-source attribution) from the bound policy inputs.
      */
     prepare(args) {
-        const { assessment, currentItemRef } = args;
+        const { assessment, item } = args;
         const pnp = assessment?.personalNeedsProfile;
         const settings = assessment?.settings;
-        const itemSettings = currentItemRef?.settings;
+        const itemSettings = item?.settings;
         const result = {
             blockedToolIds: new Set(),
             mandatedToolIds: new Set(),
             perToolFlags: new Map(),
             decisions: [],
-            unmappedSupportIds: new Set(),
+            unmappedSupportIds: this.unmappedIds(pnp, settings, itemSettings),
+            blockedOverrides: new Map(),
             sources: {},
         };
         if (settings?.districtPolicy || settings?.testAdministration) {
@@ -81,11 +82,11 @@ export class PnpPolicySource {
                 config: pnp,
             };
         }
-        if (currentItemRef && itemSettings) {
+        if (item) {
             result.sources.item = {
-                id: currentItemRef.identifier,
-                name: currentItemRef.identifier,
-                config: itemSettings,
+                id: item.id,
+                name: item.id,
+                config: item.settings,
             };
         }
         const ctx = {
@@ -100,12 +101,11 @@ export class PnpPolicySource {
     resolveSupport(supportId, ctx, out) {
         // 1. District block (absolute veto)
         if (ctx.districtPolicy?.blockedTools?.includes(supportId)) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.blockedToolIds.add(toolId);
+            out.blockedToolIds.add(supportId);
             out.decisions.push({
                 precedence: 1,
                 rule: "district-block",
-                featureId: toolId,
+                featureId: supportId,
                 action: "block",
                 sourceType: "assessment",
                 reason: `District policy blocks "${supportId}" for all assessments`,
@@ -113,29 +113,32 @@ export class PnpPolicySource {
             });
             return;
         }
-        // 2. Test administration override
-        if (ctx.testAdmin?.toolOverrides?.[supportId] === false) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.blockedToolIds.add(toolId);
+        // 2. Test administration override `false`: withdraws the support for the
+        // session, outranking every level below.
+        const override = ctx.testAdmin?.toolOverrides?.[supportId];
+        if (override === false) {
+            out.blockedToolIds.add(supportId);
             out.decisions.push({
                 precedence: 2,
                 rule: "test-admin-override",
-                featureId: toolId,
+                featureId: supportId,
                 action: "block",
                 sourceType: "assessment",
                 reason: `Test administrator disabled "${supportId}" for this session`,
-                value: ctx.testAdmin.toolOverrides,
+                value: ctx.testAdmin?.toolOverrides,
             });
             return;
         }
         // 3. Item restriction (per-item block)
         if (ctx.itemSettings?.restrictedTools?.includes(supportId)) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.blockedToolIds.add(toolId);
+            out.blockedToolIds.add(supportId);
+            if (override === true) {
+                out.blockedOverrides.set(supportId, "item-restriction");
+            }
             out.decisions.push({
                 precedence: 3,
                 rule: "item-restriction",
-                featureId: toolId,
+                featureId: supportId,
                 action: "block",
                 sourceType: "item",
                 reason: `Item restricts "${supportId}" (e.g., mental math question blocks calculator)`,
@@ -143,21 +146,57 @@ export class PnpPolicySource {
             });
             return;
         }
-        // 4. Item requirement (forces enable)
+        // 4. Profile prohibition: the student's profile withdraws the support,
+        // outranking a `true` override and every requirement.
+        if (ctx.pnp?.prohibitedSupports?.includes(supportId)) {
+            out.blockedToolIds.add(supportId);
+            if (override === true) {
+                out.blockedOverrides.set(supportId, "pnp-prohibited");
+            }
+            out.decisions.push({
+                precedence: 4,
+                rule: "pnp-prohibited",
+                featureId: supportId,
+                action: "block",
+                sourceType: "student",
+                reason: `Student PNP profile prohibits "${supportId}"`,
+                value: ctx.pnp.prohibitedSupports,
+            });
+            return;
+        }
+        // 5. Test administration override `true`: grants the support for the
+        // session.
+        if (override === true) {
+            out.perToolFlags.set(supportId, {
+                required: false,
+                alwaysAvailable: true,
+                settings: this.resolveToolSettings(supportId, ctx),
+                rule: "test-admin-override",
+            });
+            out.decisions.push({
+                precedence: 5,
+                rule: "test-admin-override",
+                featureId: supportId,
+                action: "enable",
+                sourceType: "assessment",
+                reason: `Test administrator enabled "${supportId}" for this session`,
+                value: ctx.testAdmin?.toolOverrides,
+            });
+            return;
+        }
+        // 6. Item requirement (forces enable)
         if (ctx.itemSettings?.requiredTools?.includes(supportId)) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.mandatedToolIds.add(toolId);
-            out.perToolFlags.set(toolId, {
+            out.mandatedToolIds.add(supportId);
+            out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
                 settings: this.resolveToolSettings(supportId, ctx),
                 rule: "item-requirement",
-                sourceType: "item",
             });
             out.decisions.push({
-                precedence: 4,
+                precedence: 6,
                 rule: "item-requirement",
-                featureId: toolId,
+                featureId: supportId,
                 action: "enable",
                 sourceType: "item",
                 reason: `Item requires "${supportId}" for this question`,
@@ -165,21 +204,19 @@ export class PnpPolicySource {
             });
             return;
         }
-        // 5. District requirement
+        // 7. District requirement
         if (ctx.districtPolicy?.requiredTools?.includes(supportId)) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.mandatedToolIds.add(toolId);
-            out.perToolFlags.set(toolId, {
+            out.mandatedToolIds.add(supportId);
+            out.perToolFlags.set(supportId, {
                 required: true,
                 alwaysAvailable: false,
                 settings: this.resolveToolSettings(supportId, ctx),
                 rule: "district-requirement",
-                sourceType: "assessment",
             });
             out.decisions.push({
-                precedence: 5,
+                precedence: 7,
                 rule: "district-requirement",
-                featureId: toolId,
+                featureId: supportId,
                 action: "enable",
                 sourceType: "assessment",
                 reason: `District policy requires "${supportId}" for all assessments`,
@@ -187,34 +224,18 @@ export class PnpPolicySource {
             });
             return;
         }
-        // 6. PNP prohibitions and supports (student needs)
-        if (ctx.pnp?.prohibitedSupports?.includes(supportId)) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.blockedToolIds.add(toolId);
-            out.decisions.push({
-                precedence: 6,
-                rule: "pnp-prohibited",
-                featureId: toolId,
-                action: "block",
-                sourceType: "student",
-                reason: `Student PNP profile prohibits "${supportId}"`,
-                value: ctx.pnp.prohibitedSupports,
-            });
-            return;
-        }
+        // 8. Profile supports (student needs)
         if (ctx.pnp?.supports?.includes(supportId)) {
-            const toolId = this.mapSupportToToolId(supportId, out);
-            out.perToolFlags.set(toolId, {
+            out.perToolFlags.set(supportId, {
                 required: false,
                 alwaysAvailable: true,
                 settings: this.resolveToolSettings(supportId, ctx),
                 rule: "pnp-support",
-                sourceType: "student",
             });
             out.decisions.push({
-                precedence: 6,
+                precedence: 8,
                 rule: "pnp-support",
-                featureId: toolId,
+                featureId: supportId,
                 action: "enable",
                 sourceType: "student",
                 reason: `Student PNP profile requests "${supportId}"`,
@@ -222,16 +243,12 @@ export class PnpPolicySource {
             });
             return;
         }
-        // 6 (skip): support-id mentioned somewhere but no rule fired.
-        // Use the mapped tool id as `featureId` so the trail is keyed
-        // the same way as every other branch — PR 5's debugger surfaces
-        // index provenance trails by tool id and would otherwise show
-        // orphaned support-id entries here (M8 PR 1 R3 S1).
-        const toolId = this.mapSupportToToolId(supportId, out);
+        // 8 (skip): no rule fired. The trail is keyed by tool id, as in every
+        // other branch.
         out.decisions.push({
-            precedence: 6,
+            precedence: 8,
             rule: "pnp-support",
-            featureId: toolId,
+            featureId: supportId,
             action: "skip",
             sourceType: "system",
             reason: `Feature "${supportId}" not configured at any level`,
@@ -239,57 +256,39 @@ export class PnpPolicySource {
         });
     }
     /**
-     * Map a QTI / PNP support id (e.g. `"calculator-basic"`) to the
-     * registered tool id that owns it.
-     *
-     * Resolution rules:
-     *
-     *   1. **Multiple tools register the same support id:** the
-     *      *first-registered* tool wins. `ToolRegistry.getToolsByPNPSupport`
-     *      returns a `Set<string>` whose iteration order matches the
-     *      `register(...)` insertion order, so the result is
-     *      deterministic across runs but order-sensitive at registration
-     *      time. This is an unusual configuration — the typical case is
-     *      one tool per support id — but it is reachable when an
-     *      integrator overrides a default tool with a replacement that
-     *      claims the same `pnpSupportIds`. In that case the integrator
-     *      should `unregister(...)` the default before registering the
-     *      replacement.
-     *
-     *   2. **No tool registers the support id:** the support id is
-     *      returned verbatim as the `featureId` for provenance trails
-     *      and `ToolPolicyEntry.toolId`. This lets hosts use raw QTI
-     *      strings for tools the registry does not (yet) carry without
-     *      losing them in policy evaluation.
-     *
-     * `tests/policy/PnpPolicySource.test.ts` locks this mapping behavior.
+     * The named ids no tool is registered under, with the rules naming each in
+     * precedence order. A support id is the id of the tool it grants, so an id
+     * missing from the registry matches nothing placed.
      */
-    mapSupportToToolId(supportId, out) {
-        const toolIds = this.toolRegistry.getToolsByPNPSupport(supportId);
-        if (toolIds.size === 0) {
-            // An empty registry means there is nothing to check the id against, not
-            // that the id is wrong — reporting it there would fire on every support
-            // id for a host that supplies no registry, which
-            // `tool-config-validation` already warns about once.
-            if (this.toolRegistry.getAllTools().length > 0) {
-                out.unmappedSupportIds.add(supportId);
+    unmappedIds(pnp, settings, itemSettings) {
+        const unmapped = new Map();
+        if (this.toolRegistry.getAllTools().length === 0)
+            return unmapped;
+        const named = [
+            ["district-block", settings?.districtPolicy?.blockedTools],
+            [
+                "test-admin-override",
+                Object.keys(settings?.testAdministration?.toolOverrides ?? {}),
+            ],
+            ["item-restriction", itemSettings?.restrictedTools],
+            ["pnp-prohibited", pnp?.prohibitedSupports],
+            ["item-requirement", itemSettings?.requiredTools],
+            ["district-requirement", settings?.districtPolicy?.requiredTools],
+            ["pnp-support", pnp?.supports],
+        ];
+        for (const [rule, ids] of named) {
+            for (const id of ids ?? []) {
+                if (this.toolRegistry.has(id))
+                    continue;
+                const rules = unmapped.get(id) ?? [];
+                if (!rules.includes(rule))
+                    rules.push(rule);
+                unmapped.set(id, rules);
             }
-            return supportId;
         }
-        return Array.from(toolIds)[0];
+        return unmapped;
     }
-    /**
-     * Resolve tool-specific settings, item-level taking precedence over
-     * assessment-level.
-     *
-     * Uses `??` (nullish-coalescing). Tool config values are typed `unknown` and may legitimately
-     * be `false` / `0` / `""` (e.g. a tool whose canonical "off" config
-     * is the literal `false`). `||` would treat those as missing and
-     * silently fall through to the assessment-level config, masking the
-     * authored item-level intent. `??` only falls through on
-     * `null`/`undefined`, which matches the semantic of "value not
-     * provided."
-     */
+    /** Tool parameters: the item's entry, else the assessment's. */
     resolveToolSettings(supportId, ctx) {
         return (ctx.itemSettings?.toolParameters?.[supportId] ??
             ctx.toolConfigs?.[supportId]);

package/dist/runtime/SectionControllerBinding.d.ts

@@ -0,0 +1,279 @@
+/**
+ * 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";
+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 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>;
+    getRegistry(): RuntimeRegistry;
+    dispose(): Promise<void>;
+}
+export {};