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

package/dist/timed-media/policy.js

@@ -0,0 +1,297 @@
+/**
+ * Validation for authored timed-media section data.
+ *
+ * Authored, wire-facing and untrusted, so every field is checked here and the
+ * caller never hand-parses. Errors are returned rather than thrown: the section
+ * reports them as a framework error and delivers as an ordinary section, which is
+ * loud without costing the learner the content.
+ */
+/**
+ * Applied when `playbackPolicy` is absent entirely. The restrictive values are
+ * the defaults because a timed-media section is authored to sequence: a section
+ * that forgot the policy block reads as one that wanted sequencing, and the
+ * permissive reading would silently deliver an unsequenced video.
+ */
+export const TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS = {
+    allowSeekAhead: false,
+    pauseOnRequiredCue: true,
+    requireMediaCompletion: false,
+};
+const ACTIVATIONS = [
+    "reveal",
+    "gate",
+    "metadata",
+];
+const GATE_CONDITIONS = [
+    "responded",
+    "correct",
+    "partial-or-better",
+];
+const UNKNOWN_CORRECTNESS = [
+    "release",
+    "hold",
+];
+const SCORING_STRATEGIES = [
+    "sum-child-outcomes",
+    "average-child-outcomes",
+    "host-defined",
+];
+/** A gate on correctness has to say what an unscorable item does. */
+function isCorrectnessCondition(condition) {
+    return condition === "correct" || condition === "partial-or-better";
+}
+function trimmed(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizeRange(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const raw = value;
+    const start = Number(raw.startSeconds);
+    if (!Number.isFinite(start) || start < 0)
+        return null;
+    const end = Number(raw.endSeconds);
+    // An end at or before the start is a window that can never contain a
+    // position, so it is treated as no end — the same rule
+    // `normalizeMediaFragment` applies in the toolkit, kept identical on purpose.
+    if (!Number.isFinite(end) || end <= start)
+        return { startSeconds: start };
+    return { startSeconds: start, endSeconds: end };
+}
+function normalizePlaybackPolicy(value) {
+    if (value === undefined || value === null) {
+        return { policy: { ...TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS }, error: null };
+    }
+    if (typeof value !== "object") {
+        return {
+            policy: { ...TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS },
+            error: {
+                code: "invalid-playback-policy",
+                message: "timedMedia.playbackPolicy must be an object.",
+            },
+        };
+    }
+    const raw = value;
+    return {
+        policy: {
+            allowSeekAhead: typeof raw.allowSeekAhead === "boolean"
+                ? raw.allowSeekAhead
+                : TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS.allowSeekAhead,
+            pauseOnRequiredCue: typeof raw.pauseOnRequiredCue === "boolean"
+                ? raw.pauseOnRequiredCue
+                : TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS.pauseOnRequiredCue,
+            requireMediaCompletion: typeof raw.requireMediaCompletion === "boolean"
+                ? raw.requireMediaCompletion
+                : TIMED_MEDIA_PLAYBACK_POLICY_DEFAULTS.requireMediaCompletion,
+        },
+        error: null,
+    };
+}
+function normalizeScoringPolicy(value) {
+    if (value === undefined || value === null) {
+        return { policy: undefined, error: null };
+    }
+    const strategy = value && typeof value === "object"
+        ? value.strategy
+        : undefined;
+    const known = SCORING_STRATEGIES.find((candidate) => candidate === strategy);
+    if (!known) {
+        return {
+            policy: undefined,
+            error: {
+                code: "invalid-scoring-policy",
+                message: `timedMedia.scoringPolicy.strategy must be one of ${SCORING_STRATEGIES.join(", ")}.`,
+            },
+        };
+    }
+    return { policy: { strategy: known }, error: null };
+}
+/**
+ * Validate authored `timedMedia` against the section it belongs to.
+ *
+ * `resolveStimulusRenderableId` is supplied by the caller because the mapping
+ * from an authored `stimulusRef` to a rendered renderable id belongs to the
+ * content service that assigned that id — deriving it twice is two
+ * implementations of one mapping.
+ */
+export function normalizeTimedMediaSectionData(args) {
+    const errors = [];
+    if (!args.timedMedia || typeof args.timedMedia !== "object") {
+        return {
+            data: null,
+            errors: [
+                {
+                    code: "missing-stimulus-ref",
+                    message: "timedMedia must be an object carrying a stimulusRef.",
+                },
+            ],
+        };
+    }
+    const raw = args.timedMedia;
+    const stimulusRef = trimmed(raw.stimulusRef);
+    if (!stimulusRef) {
+        errors.push({
+            code: "missing-stimulus-ref",
+            message: "timedMedia.stimulusRef is required.",
+        });
+    }
+    const stimulusRenderableId = stimulusRef
+        ? args.resolveStimulusRenderableId(stimulusRef)
+        : undefined;
+    if (stimulusRef && !stimulusRenderableId) {
+        errors.push({
+            code: "unresolved-stimulus-ref",
+            message: `timedMedia.stimulusRef "${stimulusRef}" does not name a renderable in this section.`,
+        });
+    }
+    const { policy: playbackPolicy, error: playbackError } = normalizePlaybackPolicy(raw.playbackPolicy);
+    if (playbackError)
+        errors.push(playbackError);
+    const { policy: scoringPolicy, error: scoringError } = normalizeScoringPolicy(raw.scoringPolicy);
+    if (scoringError)
+        errors.push(scoringError);
+    const allowedItemIds = new Set(args.itemIdentifiers);
+    const rawCues = Array.isArray(raw.cues) ? raw.cues : [];
+    if (rawCues.length === 0) {
+        errors.push({
+            code: "no-cues",
+            message: "timedMedia.cues must hold at least one cue.",
+        });
+    }
+    const seenIdentifiers = new Set();
+    const cues = [];
+    for (const [index, entry] of rawCues.entries()) {
+        const cue = (entry ?? {});
+        const identifier = trimmed(cue.identifier);
+        if (!identifier) {
+            errors.push({
+                code: "invalid-cue-identifier",
+                message: `timedMedia.cues[${index}] has no identifier.`,
+            });
+            continue;
+        }
+        if (seenIdentifiers.has(identifier)) {
+            errors.push({
+                code: "duplicate-cue-identifier",
+                message: `Cue identifier "${identifier}" appears more than once.`,
+                cueIdentifier: identifier,
+            });
+            continue;
+        }
+        seenIdentifiers.add(identifier);
+        const range = normalizeRange(cue.range);
+        if (!range) {
+            errors.push({
+                code: "invalid-cue-range",
+                message: `Cue "${identifier}" needs a range with a finite, non-negative startSeconds.`,
+                cueIdentifier: identifier,
+            });
+            continue;
+        }
+        const cuePolicy = (cue.policy ?? {});
+        const activation = ACTIVATIONS.find((candidate) => candidate === cuePolicy.activation);
+        if (!activation) {
+            errors.push({
+                code: "invalid-cue-activation",
+                message: `Cue "${identifier}" needs policy.activation of ${ACTIVATIONS.join(", ")}.`,
+                cueIdentifier: identifier,
+            });
+            continue;
+        }
+        const rawItemRefs = Array.isArray(cue.itemRefs) ? cue.itemRefs : [];
+        const itemRefs = [];
+        for (const rawItemRef of rawItemRefs) {
+            const itemRef = trimmed(rawItemRef);
+            if (!itemRef)
+                continue;
+            if (!allowedItemIds.has(itemRef)) {
+                // Reported rather than dropped quietly: a cue naming an item the
+                // section does not hold is the exact authoring slip that produces a
+                // checkpoint the learner never sees.
+                errors.push({
+                    code: "unknown-item-ref",
+                    message: `Cue "${identifier}" names item ref "${itemRef}", which is not in this section.`,
+                    cueIdentifier: identifier,
+                });
+                continue;
+            }
+            if (!itemRefs.includes(itemRef))
+                itemRefs.push(itemRef);
+        }
+        if (itemRefs.length === 0 && activation !== "metadata") {
+            errors.push({
+                code: "missing-item-refs",
+                message: `Cue "${identifier}" activates no item; only a metadata cue may name none.`,
+                cueIdentifier: identifier,
+            });
+            continue;
+        }
+        let releaseOn;
+        let onUnknownCorrectness;
+        if (activation === "gate") {
+            releaseOn = GATE_CONDITIONS.find((candidate) => candidate === cuePolicy.releaseOn);
+            if (!releaseOn) {
+                errors.push({
+                    code: "missing-release-condition",
+                    message: `Gate cue "${identifier}" needs policy.releaseOn of ${GATE_CONDITIONS.join(", ")}.`,
+                    cueIdentifier: identifier,
+                });
+                continue;
+            }
+            if (isCorrectnessCondition(releaseOn)) {
+                onUnknownCorrectness = UNKNOWN_CORRECTNESS.find((candidate) => candidate === cuePolicy.onUnknownCorrectness);
+                if (!onUnknownCorrectness) {
+                    errors.push({
+                        code: "missing-unknown-correctness",
+                        message: `Gate cue "${identifier}" releases on correctness, so policy.onUnknownCorrectness must state "release" or "hold" for an item no controller can score.`,
+                        cueIdentifier: identifier,
+                    });
+                    continue;
+                }
+                // A correctness gate is only passable while the learner still has a Try
+                // to spend. Over an item with a finite budget the gate becomes
+                // unpassable the moment the budget runs out, and over an item that does
+                // not deliver formatively there is never a Try at all — in both cases
+                // nothing the learner can do releases playback, and no host action
+                // releases it either, because a forced reveal is not a correct answer.
+                // Refused here rather than released at runtime: releasing would deliver
+                // the opposite of what the author wrote, which is the silent degradation
+                // this contract exists to avoid.
+                const unpassable = itemRefs.filter((itemRef) => args.resolveItemTryBudget(itemRef) !== "unlimited");
+                if (unpassable.length > 0) {
+                    errors.push({
+                        code: "gate-requires-unlimited-tries",
+                        message: `Gate cue "${identifier}" releases on correctness, so every item it names needs formative delivery with maxTries: "unlimited" — otherwise a learner who runs out of Tries can never release playback. Offending item refs: ${unpassable.join(", ")}.`,
+                        cueIdentifier: identifier,
+                    });
+                    continue;
+                }
+            }
+        }
+        cues.push({
+            identifier,
+            range,
+            itemRefs,
+            activation,
+            releaseOn,
+            onUnknownCorrectness,
+            // A policy that switched pausing off wholesale turns every gate into a
+            // reveal, which is the author's own choice and needs no warning.
+            holdsPlayback: activation === "gate" && playbackPolicy.pauseOnRequiredCue,
+        });
+    }
+    if (errors.length > 0)
+        return { data: null, errors };
+    return {
+        data: {
+            stimulusRef,
+            stimulusRenderableId: stimulusRenderableId ?? "",
+            // Cue order is authored order, not time order: two cues may share a start
+            // and the author's sequence decides which gate holds first.
+            cues,
+            playbackPolicy,
+            scoringPolicy,
+        },
+        errors: [],
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Persistence for the timed-media slice.
+ *
+ * Same posture as the formative slice: an unreadable slice is rejected whole and
+ * delivery starts from clean cue state, while item sessions in the same snapshot
+ * are normalized separately and survive. A version bump here must never cost a
+ * learner their responses.
+ */
+import type { ResolvedTimedMediaSectionData, TimedMediaSectionSessionSlice } from "./types.js";
+export declare function toTimedMediaSectionSlice(state: TimedMediaSectionSessionSlice): TimedMediaSectionSessionSlice;
+/**
+ * Validate a persisted slice against the section it is restored into.
+ *
+ * Returns `null` for an absent slice or one this build cannot read — the caller
+ * treats both as "start clean", and the two are indistinguishable, which is what
+ * keeps pre-timed-media snapshots valid.
+ */
+export declare function normalizeTimedMediaSectionSlice(args: {
+    slice: unknown;
+    data: ResolvedTimedMediaSectionData | null;
+}): TimedMediaSectionSessionSlice | null;

package/dist/timed-media/session.js

@@ -0,0 +1,85 @@
+/**
+ * Persistence for the timed-media slice.
+ *
+ * Same posture as the formative slice: an unreadable slice is rejected whole and
+ * delivery starts from clean cue state, while item sessions in the same snapshot
+ * are normalized separately and survive. A version bump here must never cost a
+ * learner their responses.
+ */
+import { TIMED_MEDIA_SLICE_VERSION, createTimedMediaState } from "./state.js";
+function readNonNegativeNumber(value) {
+    const numeric = typeof value === "number" ? value : Number.NaN;
+    if (!Number.isFinite(numeric) || numeric < 0)
+        return undefined;
+    return numeric;
+}
+function readIdentifierList(value, allowed) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry !== "string")
+            continue;
+        const identifier = entry.trim();
+        // Filtered against the cues this section actually holds, matching how
+        // `normalizeApplySession` filters item sessions: a snapshot taken against
+        // an earlier revision of the section must not resurrect a cue that is gone.
+        if (!identifier || !allowed.has(identifier))
+            continue;
+        if (out.includes(identifier))
+            continue;
+        out.push(identifier);
+    }
+    return out;
+}
+export function toTimedMediaSectionSlice(state) {
+    return {
+        ...state,
+        version: TIMED_MEDIA_SLICE_VERSION,
+        visitedCueIdentifiers: [...state.visitedCueIdentifiers],
+        completedCueIdentifiers: [...state.completedCueIdentifiers],
+    };
+}
+/**
+ * Validate a persisted slice against the section it is restored into.
+ *
+ * Returns `null` for an absent slice or one this build cannot read — the caller
+ * treats both as "start clean", and the two are indistinguishable, which is what
+ * keeps pre-timed-media snapshots valid.
+ */
+export function normalizeTimedMediaSectionSlice(args) {
+    const { slice, data } = args;
+    if (!data)
+        return null;
+    if (!slice || typeof slice !== "object")
+        return null;
+    const raw = slice;
+    if (raw.version !== TIMED_MEDIA_SLICE_VERSION)
+        return null;
+    const allowedCueIds = new Set(data.cues.map((cue) => cue.identifier));
+    const base = createTimedMediaState();
+    const mediaCurrentTime = readNonNegativeNumber(raw.mediaCurrentTime) ?? base.mediaCurrentTime;
+    const visitedCueIdentifiers = readIdentifierList(raw.visitedCueIdentifiers, allowedCueIds);
+    const completedCueIdentifiers = readIdentifierList(raw.completedCueIdentifiers, allowedCueIds);
+    const activeCueIdentifier = typeof raw.activeCueIdentifier === "string" &&
+        allowedCueIds.has(raw.activeCueIdentifier)
+        ? raw.activeCueIdentifier
+        : undefined;
+    return {
+        version: TIMED_MEDIA_SLICE_VERSION,
+        mediaCurrentTime,
+        // Never below the restored position: a snapshot written before
+        // `maxPositionSeconds` existed, or one carrying a lower value than the
+        // position it also records, would hand back timeline the learner already
+        // spent under `allowSeekAhead: false`.
+        maxPositionSeconds: Math.max(readNonNegativeNumber(raw.maxPositionSeconds) ?? 0, mediaCurrentTime),
+        mediaCompleted: raw.mediaCompleted === true,
+        visitedCueIdentifiers,
+        // A cue cannot be complete without having been visited; a snapshot that says
+        // otherwise is inconsistent, and the visited set is the one that decides what
+        // is on screen.
+        completedCueIdentifiers: completedCueIdentifiers.filter((identifier) => visitedCueIdentifiers.includes(identifier)),
+        activeCueIdentifier,
+        aggregateComplete: raw.aggregateComplete === true,
+    };
+}

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

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+import type { MediaTimeSourceCapabilities, ResolvedTimedMediaSectionData, TimedMediaDegradation, TimedMediaDeliveryState, TimedMediaInput, TimedMediaReduction, TimedMediaSectionProjection, TimedMediaSectionSessionSlice } from "./types.js";
+export declare const TIMED_MEDIA_SLICE_VERSION: 1;
+export declare function createTimedMediaState(): TimedMediaSectionSessionSlice;
+/**
+ * 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 declare function reduceTimedMediaState(args: {
+    state: TimedMediaSectionSessionSlice;
+    data: ResolvedTimedMediaSectionData;
+    delivery: TimedMediaDeliveryState;
+    input: TimedMediaInput;
+}): TimedMediaReduction;
+/**
+ * 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 declare function resolveTimedMediaEnforcement(args: {
+    playbackPolicy: ResolvedTimedMediaSectionData["playbackPolicy"];
+    capabilities: MediaTimeSourceCapabilities | null;
+    hasGate: boolean;
+}): {
+    pause: "enforced" | "advisory";
+    seek: "enforced" | "advisory";
+    degradations: TimedMediaDegradation[];
+};
+/**
+ * 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 declare function resolveTimedMediaProjection(args: {
+    data: ResolvedTimedMediaSectionData;
+    state: TimedMediaSectionSessionSlice;
+    delivery: TimedMediaDeliveryState;
+    capabilities: MediaTimeSourceCapabilities | null;
+}): TimedMediaSectionProjection;
+/**
+ * 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 declare function timedMediaProjectionSignature(projection: TimedMediaSectionProjection | null | undefined): string;