@pie-players/pie-players-shared 0.3.67 → 0.3.68

package/dist/timed-media/state.js

@@ -0,0 +1,357 @@
+/**
+ * The cue reduction: media position plus delivery state in, cue state and the
+ * effects the port must be driven with out.
+ *
+ * Pure and Node-safe, which is what makes cue policy testable without a browser
+ * and what keeps it out of every layout that hosts timed media. The caller owns
+ * the port and applies the effects; nothing here touches media.
+ */
+export const TIMED_MEDIA_SLICE_VERSION = 1;
+/**
+ * How far past the furthest reached position a seek may land before it is
+ * clamped. A native element reports `currentTime` from `timeupdate`, which fires
+ * about four times a second, so the furthest recorded position trails real
+ * playback by up to a quarter second; clamping at exactly the recorded value
+ * would fight a learner nudging the scrubber where they already are.
+ */
+const SEEK_AHEAD_TOLERANCE_SECONDS = 0.5;
+/** Media positions are compared in seconds; a millisecond is below resolution. */
+const TIME_EPSILON_SECONDS = 1e-3;
+/**
+ * How much new ground playback covers before the furthest position is worth
+ * republishing for.
+ *
+ * Position renders nowhere, so this exists only to bound what a reload hands back:
+ * `allowSeekAhead: false` clamps against the persisted `maxPositionSeconds`, and a
+ * section whose next cue is minutes away would otherwise persist nothing in
+ * between.
+ */
+const POSITION_PERSIST_BUCKET_SECONDS = 10;
+export function createTimedMediaState() {
+    return {
+        version: TIMED_MEDIA_SLICE_VERSION,
+        mediaCurrentTime: 0,
+        maxPositionSeconds: 0,
+        mediaCompleted: false,
+        visitedCueIdentifiers: [],
+        completedCueIdentifiers: [],
+        aggregateComplete: false,
+    };
+}
+function toFiniteSeconds(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < 0)
+        return fallback;
+    return numeric;
+}
+/**
+ * A cue is reached once playback has passed its start, and stays reached.
+ *
+ * The end bound does not un-reach it, and seeking past a cue's whole window still
+ * reaches it. That is deliberate: the alternative lets a learner who is allowed
+ * to seek ahead jump over a checkpoint the author wrote, and a gate that can be
+ * skipped is not a gate.
+ */
+function isCueReached(cue, seconds) {
+    return seconds + TIME_EPSILON_SECONDS >= cue.range.startSeconds;
+}
+/**
+ * Whether one item satisfies a gate condition.
+ *
+ * `undefined` correctness is "no Try yet" and never satisfies a correctness
+ * condition. `"unknown"` is an item no loaded controller can score, and the
+ * authored `onUnknownCorrectness` decides it — never collapsed into
+ * `"incorrect"`, which would hold a learner behind an item nothing can release.
+ */
+function itemSatisfiesGate(cue, itemId, delivery) {
+    if (cue.releaseOn === "responded") {
+        return delivery.respondedByItemId[itemId] === true;
+    }
+    const correctness = delivery.correctnessByItemId[itemId];
+    if (correctness === undefined)
+        return false;
+    if (correctness === "unknown")
+        return cue.onUnknownCorrectness === "release";
+    if (cue.releaseOn === "correct")
+        return correctness === "correct";
+    return correctness === "correct" || correctness === "partial";
+}
+/** Every item a gate names has to satisfy it; one unanswered item still holds. */
+function isGateReleased(cue, delivery) {
+    if (cue.itemRefs.length === 0)
+        return true;
+    return cue.itemRefs.every((itemId) => itemSatisfiesGate(cue, itemId, delivery));
+}
+function sameStringList(left, right) {
+    if (left.length !== right.length)
+        return false;
+    return left.every((value, index) => value === right[index]);
+}
+/**
+ * Advance cue state.
+ *
+ * Two things are monotonic by design. A cue stays visited and its items stay
+ * revealed once reached, because un-revealing an item a learner has already
+ * answered would take a response off the screen. And a released gate stays
+ * complete, so a retry that lowers correctness cannot re-trap a learner
+ * mid-playback — the same reasoning that keeps `firstCorrectTry` from being
+ * overwritten by a later incorrect Try.
+ */
+export function reduceTimedMediaState(args) {
+    const { state, data, delivery, input } = args;
+    const effects = { pause: false };
+    let nextTime = state.mediaCurrentTime;
+    let mediaCompleted = state.mediaCompleted;
+    switch (input.kind) {
+        case "time":
+            nextTime = toFiniteSeconds(input.currentTimeSeconds, state.mediaCurrentTime);
+            break;
+        case "seek": {
+            const requested = toFiniteSeconds(input.currentTimeSeconds, state.mediaCurrentTime);
+            if (!data.playbackPolicy.allowSeekAhead &&
+                requested >
+                    state.maxPositionSeconds + SEEK_AHEAD_TOLERANCE_SECONDS) {
+                effects.seekToSeconds = state.maxPositionSeconds;
+                nextTime = state.maxPositionSeconds;
+            }
+            else {
+                nextTime = requested;
+            }
+            break;
+        }
+        case "ended":
+            nextTime = toFiniteSeconds(input.currentTimeSeconds, state.mediaCurrentTime);
+            mediaCompleted = true;
+            break;
+        case "delivery-changed":
+            break;
+    }
+    const maxPositionSeconds = Math.max(state.maxPositionSeconds, nextTime);
+    const visitedCueIdentifiers = [...state.visitedCueIdentifiers];
+    const visitedSet = new Set(visitedCueIdentifiers);
+    for (const cue of data.cues) {
+        if (visitedSet.has(cue.identifier))
+            continue;
+        if (!isCueReached(cue, nextTime))
+            continue;
+        visitedSet.add(cue.identifier);
+        visitedCueIdentifiers.push(cue.identifier);
+        // Only the last activation of a reduction is reported: a seek that crosses
+        // several cues at once has one place for focus to go, and that is the
+        // furthest one, which is where the learner now is.
+        effects.activatedCueIdentifier = cue.identifier;
+    }
+    const completedSet = new Set(state.completedCueIdentifiers);
+    let holdingGate = null;
+    for (const cue of data.cues) {
+        if (!visitedSet.has(cue.identifier))
+            continue;
+        if (completedSet.has(cue.identifier))
+            continue;
+        if (!cue.holdsPlayback) {
+            // A reveal or metadata cue has no condition to satisfy, and a gate under
+            // `pauseOnRequiredCue: false` has had its hold switched off wholesale.
+            completedSet.add(cue.identifier);
+            continue;
+        }
+        if (isGateReleased(cue, delivery)) {
+            completedSet.add(cue.identifier);
+            effects.releasedCueIdentifier = cue.identifier;
+            continue;
+        }
+        // Authored order decides which of two open gates holds, and only the first
+        // one does — playback is stopped either way, and reporting both would give
+        // the layout two places to send focus.
+        if (!holdingGate)
+            holdingGate = cue;
+    }
+    const completedCueIdentifiers = data.cues
+        .map((cue) => cue.identifier)
+        .filter((identifier) => completedSet.has(identifier));
+    effects.pause = holdingGate !== null;
+    const activeCueIdentifier = holdingGate?.identifier ??
+        visitedCueIdentifiers[visitedCueIdentifiers.length - 1];
+    const aggregateComplete = completedCueIdentifiers.length === data.cues.length &&
+        delivery.itemsComplete &&
+        (data.playbackPolicy.requireMediaCompletion ? mediaCompleted : true);
+    const next = {
+        version: TIMED_MEDIA_SLICE_VERSION,
+        mediaCurrentTime: nextTime,
+        maxPositionSeconds,
+        mediaCompleted,
+        visitedCueIdentifiers,
+        completedCueIdentifiers,
+        activeCueIdentifier,
+        aggregateComplete,
+    };
+    const changed = next.mediaCurrentTime !== state.mediaCurrentTime ||
+        next.maxPositionSeconds !== state.maxPositionSeconds ||
+        next.mediaCompleted !== state.mediaCompleted ||
+        next.activeCueIdentifier !== state.activeCueIdentifier ||
+        next.aggregateComplete !== state.aggregateComplete ||
+        !sameStringList(next.visitedCueIdentifiers, state.visitedCueIdentifiers) ||
+        !sameStringList(next.completedCueIdentifiers, state.completedCueIdentifiers);
+    return { state: changed ? next : state, effects, changed };
+}
+/**
+ * Which policies the attached port can actually carry out.
+ *
+ * Absent a port there is nothing to degrade *from* yet, so an unattached section
+ * reports its authored intent rather than a capability gap it has not measured.
+ */
+export function resolveTimedMediaEnforcement(args) {
+    const degradations = [];
+    const wantsPause = args.playbackPolicy.pauseOnRequiredCue && args.hasGate;
+    const wantsSeekLock = !args.playbackPolicy.allowSeekAhead;
+    const canPause = args.capabilities ? args.capabilities.canPause : true;
+    const canRestrictSeeking = args.capabilities
+        ? args.capabilities.canRestrictSeeking
+        : true;
+    if (wantsPause && !canPause) {
+        degradations.push({
+            policy: "pause-on-required-cue",
+            capability: "canPause",
+            message: "The media time source cannot pause, so gate cues are advisory: they fire and record state, and playback continues.",
+        });
+    }
+    if (wantsSeekLock && !canRestrictSeeking) {
+        degradations.push({
+            policy: "restrict-seek-ahead",
+            capability: "canRestrictSeeking",
+            message: "The media time source cannot restrict seeking, so allowSeekAhead: false is advisory: a learner can seek past cues.",
+        });
+    }
+    return {
+        pause: wantsPause && !canPause ? "advisory" : "enforced",
+        seek: wantsSeekLock && !canRestrictSeeking ? "advisory" : "enforced",
+        degradations,
+    };
+}
+/** The gate a layout renders, or `null` when nothing is holding. */
+function resolveGateView(args) {
+    const visited = new Set(args.state.visitedCueIdentifiers);
+    const completed = new Set(args.state.completedCueIdentifiers);
+    for (const cue of args.data.cues) {
+        if (!cue.holdsPlayback || !cue.releaseOn)
+            continue;
+        if (!visited.has(cue.identifier))
+            continue;
+        if (completed.has(cue.identifier))
+            continue;
+        return {
+            cueIdentifier: cue.identifier,
+            itemRefs: [...cue.itemRefs],
+            releaseOn: cue.releaseOn,
+            holding: !isGateReleased(cue, args.delivery),
+            enforcement: args.pauseEnforcement,
+        };
+    }
+    return null;
+}
+/**
+ * Whether a cue decides when its items are delivered.
+ *
+ * A `metadata` cue does not: it records state and reveals nothing, so the items it
+ * names stay ordinary items. One predicate for both id sets below, because a cue
+ * counted as sequencing but never as revealing hides its items for the whole
+ * section.
+ */
+function cueSequencesDelivery(cue) {
+    return cue.activation !== "metadata";
+}
+/** Canonical ids of every item the timeline sequences, in cue order. */
+function resolveSequencedItemIds(data) {
+    const sequenced = [];
+    for (const cue of data.cues) {
+        if (!cueSequencesDelivery(cue))
+            continue;
+        for (const itemId of cue.itemRefs) {
+            if (!sequenced.includes(itemId))
+                sequenced.push(itemId);
+        }
+    }
+    return sequenced;
+}
+/** Canonical ids of items a visited cue has revealed, in cue order. */
+function resolveRevealedItemIds(data, state) {
+    const visited = new Set(state.visitedCueIdentifiers);
+    const revealed = [];
+    for (const cue of data.cues) {
+        if (!cueSequencesDelivery(cue))
+            continue;
+        if (!visited.has(cue.identifier))
+            continue;
+        for (const itemId of cue.itemRefs) {
+            if (!revealed.includes(itemId))
+                revealed.push(itemId);
+        }
+    }
+    return revealed;
+}
+/**
+ * Derive the view layouts read. Recomputed from state on every republish rather
+ * than stored, so there is one source of truth and no mirror to go stale.
+ */
+export function resolveTimedMediaProjection(args) {
+    const hasGate = args.data.cues.some((cue) => cue.activation === "gate");
+    const enforcement = resolveTimedMediaEnforcement({
+        playbackPolicy: args.data.playbackPolicy,
+        capabilities: args.capabilities,
+        hasGate,
+    });
+    return {
+        version: 1,
+        stimulusRenderableId: args.data.stimulusRenderableId,
+        cues: args.data.cues,
+        playbackPolicy: args.data.playbackPolicy,
+        mediaAttached: args.capabilities !== null,
+        enforcement: { pause: enforcement.pause, seek: enforcement.seek },
+        degradations: enforcement.degradations,
+        revealedItemIds: resolveRevealedItemIds(args.data, args.state),
+        sequencedItemIds: resolveSequencedItemIds(args.data),
+        activeCueIdentifier: args.state.activeCueIdentifier,
+        gate: resolveGateView({
+            data: args.data,
+            state: args.state,
+            delivery: args.delivery,
+            pauseEnforcement: enforcement.pause,
+        }),
+        visitedCueIdentifiers: [...args.state.visitedCueIdentifiers],
+        completedCueIdentifiers: [...args.state.completedCueIdentifiers],
+        mediaCurrentTime: args.state.mediaCurrentTime,
+        maxPositionSeconds: args.state.maxPositionSeconds,
+        mediaCompleted: args.state.mediaCompleted,
+        aggregateComplete: args.state.aggregateComplete === true,
+    };
+}
+/**
+ * The projection facts that change what a layout renders, as one string.
+ *
+ * One implementation for the two callers that have to agree: `SectionController`
+ * decides whether to emit on it, and the toolkit folds it into the composition
+ * revision key. Two encodings drift silently in either direction — the controller
+ * emits a change the toolkit coalesces away, or the toolkit republishes for a
+ * change the controller never announced.
+ *
+ * `mediaCurrentTime` is absent because it moves about four times a second and
+ * nothing renders it. `maxPositionSeconds` enters only as a coarse bucket; see
+ * `POSITION_PERSIST_BUCKET_SECONDS`.
+ */
+export function timedMediaProjectionSignature(projection) {
+    if (!projection)
+        return "";
+    return [
+        (projection.visitedCueIdentifiers ?? []).join(","),
+        (projection.completedCueIdentifiers ?? []).join(","),
+        (projection.revealedItemIds ?? []).join(","),
+        projection.activeCueIdentifier ?? "",
+        projection.gate?.cueIdentifier ?? "",
+        projection.gate?.holding === true ? "1" : "0",
+        projection.enforcement?.pause ?? "",
+        projection.enforcement?.seek ?? "",
+        projection.mediaAttached === true ? "1" : "0",
+        projection.mediaCompleted === true ? "1" : "0",
+        projection.aggregateComplete === true ? "1" : "0",
+        String(Math.floor((projection.maxPositionSeconds ?? 0) / POSITION_PERSIST_BUCKET_SECONDS)),
+    ].join(":");
+}

package/dist/timed-media/types.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Timed-media section vocabulary.
+ *
+ * A **Cue** is a window on a media timeline that activates one or more of the
+ * section's item refs. A **Media Time Source** is the port the section reaches
+ * media through — never a library API, so a host can supply its own media
+ * element without shipping a PIE element.
+ *
+ * See `docs/prds/timed-media-section-contract.md` for the ratified contract and
+ * `docs/architecture/timed-media-section.md` for the layer-ownership record.
+ */
+import type { FormativeCorrectness } from "../formative/types.js";
+import type { MediaFragmentRange } from "../types/index.js";
+/**
+ * What a cue does to the items it names.
+ *
+ * - `reveal`: the items become visible when the media reaches the cue.
+ * - `gate`: as `reveal`, and playback is held until the release condition holds.
+ * - `metadata`: state and events only — an author-visible timeline marker that
+ *   reveals nothing and gates nothing.
+ */
+export type TimedMediaCueActivation = "reveal" | "gate" | "metadata";
+/**
+ * The condition over delivery state that releases a gate.
+ *
+ * Named from the shipped formative vocabulary rather than defined here, which is
+ * the whole reason formative delivery sequenced first — see
+ * `docs/adr/0001-formative-delivery-before-timed-media.md`. `"responded"` is the
+ * response-only case, and it reads item completion rather than Try state so a
+ * gate works in a section that does not deliver formatively at all.
+ */
+export type TimedMediaGateCondition = "responded" | "correct" | "partial-or-better";
+/**
+ * What a gate does when the item cannot be auto-scored — `FormativeCorrectness`
+ * of `"unknown"`, which is the honest state of an item holding a rubric element
+ * rather than a defect to design around.
+ *
+ * Required on a gate whose condition is a correctness condition; see
+ * `normalizeTimedMediaSectionData`. Not defaulted, because both answers are
+ * defensible and the wrong silent one either traps a learner behind an item
+ * nothing can score or waves through the checkpoint the author wrote.
+ */
+export type TimedMediaUnknownCorrectness = "release" | "hold";
+export interface TimedMediaCuePolicy {
+    activation: TimedMediaCueActivation;
+    /** Required for `activation: "gate"`; ignored otherwise. */
+    releaseOn?: TimedMediaGateCondition;
+    /** Required when `releaseOn` names correctness; ignored otherwise. */
+    onUnknownCorrectness?: TimedMediaUnknownCorrectness;
+}
+export interface TimedMediaCue {
+    identifier: string;
+    /**
+     * The window in which this cue is active, reusing the ratified range type. A
+     * point cue omits `endSeconds`.
+     *
+     * Carried beside the asset rather than inside `MediaAssetRef` because a range
+     * describes a *use* of an asset. Here that use is activation, not a slice to
+     * play, so it implies no seeking — the opposite of what the two shipped
+     * catalog consumers read the same shape as.
+     */
+    range: MediaFragmentRange;
+    /** Identifiers of this section's `assessmentItemRefs`. */
+    itemRefs: string[];
+    policy: TimedMediaCuePolicy;
+}
+export interface TimedMediaPlaybackPolicy {
+    /** `false` clamps a forward seek to the furthest position already reached. */
+    allowSeekAhead: boolean;
+    /** `false` turns every `gate` cue into a `reveal`: nothing holds playback. */
+    pauseOnRequiredCue: boolean;
+    /** Whether `aggregateComplete` requires the media to have ended. */
+    requireMediaCompletion: boolean;
+}
+/**
+ * Authored scoring intent. Accepted, validated and persisted; PIE computes no
+ * aggregate outcome from it yet and supplies no default, so a section that omits
+ * it is not silently assigned one.
+ *
+ * No `weighted-child-outcomes`: no weight is authorable on a cue, an item ref or
+ * the section, so the strategy would name a capability PIE does not have. Where
+ * weights live is the score contract's question, and a host that already has its
+ * own weights says `host-defined`.
+ */
+export interface TimedMediaScoringPolicy {
+    strategy: "sum-child-outcomes" | "average-child-outcomes" | "host-defined";
+}
+/**
+ * The authored `timedMedia` payload, carried on `AssessmentSection`.
+ *
+ * No media payload: `stimulusRef` names the renderable that supplies the time
+ * source, authored as a `class: "stimulus"` rubric block whose passage config
+ * mounts the media element. The passage owns the asset and its accessibility
+ * catalogs, because a passage is a Catalog Owner and a media blob is not.
+ */
+export interface TimedMediaSectionData {
+    /**
+     * The rubric block identifier or passage id of the stimulus renderable.
+     * Required, and validated to resolve within this section: a section carrying
+     * cues with no resolvable stimulus is malformed, because the alternative is
+     * cues that silently never fire.
+     */
+    stimulusRef: string;
+    cues: TimedMediaCue[];
+    playbackPolicy: TimedMediaPlaybackPolicy;
+    scoringPolicy?: TimedMediaScoringPolicy;
+}
+/** A cue after validation, with every optional field decided. */
+export interface ResolvedTimedMediaCue {
+    identifier: string;
+    range: MediaFragmentRange;
+    /** Filtered to item refs this section actually holds. */
+    itemRefs: string[];
+    activation: TimedMediaCueActivation;
+    /** Present only for a cue that holds playback. */
+    releaseOn?: TimedMediaGateCondition;
+    onUnknownCorrectness?: TimedMediaUnknownCorrectness;
+    /**
+     * Whether this cue holds playback: `activation: "gate"` and a playback policy
+     * that has not switched gating off wholesale.
+     */
+    holdsPlayback: boolean;
+}
+/** The authored data after validation. */
+export interface ResolvedTimedMediaSectionData {
+    stimulusRef: string;
+    /** The renderable id the stimulus resolved to, which the layout renders. */
+    stimulusRenderableId: string;
+    cues: ResolvedTimedMediaCue[];
+    playbackPolicy: TimedMediaPlaybackPolicy;
+    scoringPolicy?: TimedMediaScoringPolicy;
+}
+/**
+ * What a gated item's resolved formative policy leaves the learner.
+ *
+ * Read by validation, not by the reduction: a gate on correctness over an item
+ * with a finite Try budget is a dead end, and so is one over an item that does not
+ * deliver formatively at all — no Try means no correctness, ever.
+ */
+export type TimedMediaItemTryBudget = "unlimited" | "finite" | "not-formative";
+export interface TimedMediaValidationError {
+    /** Machine-readable, so a host can branch without parsing prose. */
+    code: "missing-stimulus-ref" | "unresolved-stimulus-ref"
+    /**
+     * Reported at runtime rather than by validation: `stimulusRef` resolved, but
+     * the renderable it names exposed no Media Time Source, so no cue can fire.
+     * Whether a renderable mounts media is not knowable from authored data.
+     */
+     | "stimulus-exposes-no-time-source" | "no-cues" | "duplicate-cue-identifier" | "invalid-cue-identifier" | "invalid-cue-range" | "invalid-cue-activation" | "unknown-item-ref" | "missing-item-refs" | "missing-release-condition" | "missing-unknown-correctness" | "gate-requires-unlimited-tries" | "invalid-playback-policy" | "invalid-scoring-policy";
+    message: string;
+    /** The cue the error is about, where it is about one. */
+    cueIdentifier?: string;
+}
+export interface TimedMediaValidationResult {
+    data: ResolvedTimedMediaSectionData | null;
+    errors: TimedMediaValidationError[];
+}
+/**
+ * What the adapter can actually do, as opposed to what the section would like.
+ *
+ * Declared by the port rather than assumed by the section: a third-party embed
+ * commonly exposes time and nothing else. Where a capability is missing the
+ * matching policy degrades from enforced to advisory — cues still fire and state
+ * is still recorded — and the degradation is reported as a recoverable framework
+ * warning, because a seek lock that does not lock reads to an author as one that
+ * does.
+ */
+export interface MediaTimeSourceCapabilities {
+    canPause: boolean;
+    canRestrictSeeking: boolean;
+}
+/** Structurally `TimeRanges`, so a native media element satisfies it as-is. */
+export interface MediaTimeRanges {
+    readonly length: number;
+    start(index: number): number;
+    end(index: number): number;
+}
+export type MediaTimeSourceNotification = {
+    type: "time";
+    currentTime: number;
+} | {
+    type: "seek";
+    currentTime: number;
+} | {
+    type: "play";
+    currentTime: number;
+} | {
+    type: "pause";
+    currentTime: number;
+} | {
+    type: "ended";
+    currentTime: number;
+};
+/**
+ * The only way the section reaches media.
+ *
+ * Shaped after `HTMLMediaElement` deliberately: the browser's own surface is the
+ * one every adapter author already knows, and a native `<video>` satisfies it
+ * through the few lines in `createMediaElementTimeSource`. That is what keeps the
+ * media-player dependency question reversible instead of load-bearing.
+ *
+ * Two departures from the element, both to make capability honest. Seeking is
+ * `seekTo(seconds)` rather than a writable `currentTime`, because a writable
+ * property gives a source that cannot seek no way to say so; and `capabilities`
+ * has no element equivalent at all.
+ */
+export interface MediaTimeSource {
+    readonly currentTime: number;
+    /** `NaN` until metadata loads, as on the element. */
+    readonly duration: number;
+    readonly paused: boolean;
+    readonly seekable: MediaTimeRanges | null;
+    readonly capabilities: MediaTimeSourceCapabilities;
+    play(): Promise<void> | void;
+    pause(): void;
+    seekTo(seconds: number): void;
+    subscribe(listener: (notification: MediaTimeSourceNotification) => void): () => void;
+}
+/**
+ * The persisted slice, carried on `SectionControllerSessionState.timedMedia`.
+ *
+ * One shape live and persisted, unlike formative's split between a per-item
+ * reducer state and a slice: timed-media state is section-scoped, so there is
+ * nothing to key.
+ */
+export interface TimedMediaSectionSessionSlice {
+    version: 1;
+    mediaCurrentTime: number;
+    /**
+     * Furthest position reached, which is what `allowSeekAhead: false` clamps
+     * against. Persisted rather than derived because a reload would otherwise hand
+     * the learner the whole timeline back — an addition to the contract's session
+     * sketch, recorded in the PRD.
+     */
+    maxPositionSeconds: number;
+    mediaCompleted: boolean;
+    visitedCueIdentifiers: string[];
+    completedCueIdentifiers: string[];
+    activeCueIdentifier?: string;
+    aggregateComplete?: boolean;
+}
+/**
+ * Delivery state a gate condition reads, supplied by the caller so this module
+ * stays pure and depends on neither the controller nor the formative module's
+ * live state.
+ */
+export interface TimedMediaDeliveryState {
+    /** Item completion by canonical id: the `"responded"` condition's signal. */
+    respondedByItemId: Record<string, boolean>;
+    /** Last Try correctness by canonical id; absent means no Try yet. */
+    correctnessByItemId: Record<string, FormativeCorrectness | undefined>;
+    /** Whether every item in the section reports completion. */
+    itemsComplete: boolean;
+}
+export type TimedMediaInput = {
+    kind: "time";
+    currentTimeSeconds: number;
+} | {
+    kind: "seek";
+    currentTimeSeconds: number;
+} | {
+    kind: "ended";
+    currentTimeSeconds?: number;
+}
+/** Delivery state changed under a held gate; re-evaluate releases. */
+ | {
+    kind: "delivery-changed";
+};
+/**
+ * What the caller must do to the port after a reduction. Advisory when the port
+ * lacks the capability, which the caller reports rather than silently skipping.
+ */
+export interface TimedMediaEffects {
+    /** A gate is holding and playback should stop. */
+    pause: boolean;
+    /** A forward seek exceeded policy and should be clamped here. */
+    seekToSeconds?: number;
+    /** Cue that activated in this reduction, for focus and announcement. */
+    activatedCueIdentifier?: string;
+    /** Cue whose gate released in this reduction, for announcement. */
+    releasedCueIdentifier?: string;
+}
+export interface TimedMediaReduction {
+    state: TimedMediaSectionSessionSlice;
+    effects: TimedMediaEffects;
+    /** `false` when the reduction produced the state it was given. */
+    changed: boolean;
+}
+export type TimedMediaEnforcement = "enforced" | "advisory";
+export interface TimedMediaDegradation {
+    policy: "pause-on-required-cue" | "restrict-seek-ahead";
+    /** The capability the port does not have. */
+    capability: keyof MediaTimeSourceCapabilities;
+    message: string;
+}
+export interface TimedMediaGateView {
+    cueIdentifier: string;
+    itemRefs: string[];
+    releaseOn: TimedMediaGateCondition;
+    /** The gate is active and its condition does not hold. */
+    holding: boolean;
+    /** Whether holding actually stops playback, or is merely recorded. */
+    enforcement: TimedMediaEnforcement;
+}
+/**
+ * What layouts read off the composition model. Derived, never persisted — the
+ * slice above is the state, this is the view of it.
+ */
+export interface TimedMediaSectionProjection {
+    version: 1;
+    stimulusRenderableId: string;
+    cues: ResolvedTimedMediaCue[];
+    playbackPolicy: TimedMediaPlaybackPolicy;
+    /** Whether a media time source is attached; cues cannot fire without one. */
+    mediaAttached: boolean;
+    enforcement: {
+        pause: TimedMediaEnforcement;
+        seek: TimedMediaEnforcement;
+    };
+    degradations: TimedMediaDegradation[];
+    /** Canonical ids of items whose cue has activated. Monotonic. */
+    revealedItemIds: string[];
+    /**
+     * Canonical ids of every item the timeline sequences — named by a `reveal` or a
+     * `gate` cue. An item outside this set is delivered normally, including one a
+     * `metadata` cue names: metadata records state and reveals nothing, so naming an
+     * item on one must not take that item out of delivery.
+     */
+    sequencedItemIds: string[];
+    activeCueIdentifier?: string;
+    gate: TimedMediaGateView | null;
+    visitedCueIdentifiers: string[];
+    completedCueIdentifiers: string[];
+    mediaCurrentTime: number;
+    maxPositionSeconds: number;
+    mediaCompleted: boolean;
+    /**
+     * Every required cue complete, every item complete, and — where the policy
+     * requires it — the media ended. Deliberately three separate facts rather than
+     * one: a section can be item-complete with the video half watched.
+     */
+    aggregateComplete: boolean;
+}