@intellectif/lk-core 0.14.0 → 0.15.0

package/dist/index.js

@@ -16,22 +16,31 @@ import {
   roundGrade,
   score,
   validateSpeechAssessment
-} from "./chunk-RTIR6R2U.js";
+} from "./chunk-L6YBQXSB.js";
 import {
   XAPIVerb,
   XAPI_VERB_DISPLAY,
   validateXAPIStatement,
   xAPIBuilder,
   xapiDefinitionFor
-} from "./chunk-R7PV3XIC.js";
+} from "./chunk-54XYQ3CS.js";
 import {
+  INTERACTIVE_VIDEO_ITEM_TYPES,
   ItemGroupSchema,
+  MediaTimelineSchema,
   RedactedItemGroupSchema,
   RedactedStimulusSchema,
   StimulusSchema,
+  TIMELINE_MAX_CHAPTERS,
+  TIMELINE_MAX_ITEMS,
+  TIMELINE_MAX_QUIZZES,
+  TIMELINE_MAX_TITLE_LENGTH,
+  TimelineChapterSchema,
+  TimelineCueSchema,
   dictationJsonSchema,
   fillInTheBlanksJsonSchema,
   gapSelectJsonSchema,
+  isInteractiveVideoItemType,
   itemGroupJsonSchema,
   jsonSchemaFor,
   multipleChoiceJsonSchema,
@@ -40,7 +49,7 @@ import {
   validateActivity,
   validateItemGroup,
   writtenResponseJsonSchema
-} from "./chunk-NBADQ3JU.js";
+} from "./chunk-EEMVWBPP.js";
 import {
   ActivitySchemaError,
   BlankConfigSchema,
@@ -65,6 +74,7 @@ import {
   MEDIA_FIELD_POLICY,
   MediaPlaybackSchema,
   MediaSchema,
+  MediaTrackSchema,
   MediaUrlSchema,
   MultipleChoiceDataSchema,
   MultipleChoiceOptionMediaSchema,
@@ -124,7 +134,7 @@ import {
   registeredActivityTypes,
   withValidationScope,
   writtenResponseType
-} from "./chunk-6RND47QE.js";
+} from "./chunk-DPHX4E7X.js";
 
 // src/content-hash.ts
 function canonicalJson(value, seen = /* @__PURE__ */ new Set()) {
@@ -226,6 +236,20 @@ function keyOf(entry) {
   }
   return key;
 }
+function inQuizOrder(items, timeline) {
+  const placement = /* @__PURE__ */ new Map();
+  timeline.cues.forEach((cue, cueIndex) => {
+    cue.itemIds.forEach((itemId, position) => {
+      if (!placement.has(itemId)) {
+        placement.set(itemId, { at: cue.at, cue: cueIndex, position });
+      }
+    });
+  });
+  const unplaced = { at: Number.POSITIVE_INFINITY, cue: Number.POSITIVE_INFINITY, position: 0 };
+  return items.map((entry) => ({ entry, place: placement.get(entry.item.id) ?? unplaced })).sort(
+    (a, b) => a.place.at - b.place.at || a.place.cue - b.place.cue || a.place.position - b.place.position || a.entry.itemIndex - b.entry.itemIndex
+  ).map(({ entry }) => entry);
+}
 function flattenSequence(entries, options = {}) {
   const shuffleEntries = options.shuffleEntries === true;
   const needsSeed = shuffleEntries || entries.some((entry) => isItemGroup(entry) && entry.shuffle === "within-group");
@@ -249,11 +273,20 @@ function flattenSequence(entries, options = {}) {
         `flattenSequence: item group "${entry.id}" has no items. An empty group would silently remove its stimulus and its questions from the presented sequence.`
       );
     }
+    const timeline = entry.timeline;
+    if (timeline !== void 0 && entry.shuffle === "within-group") {
+      throw new Error(
+        `flattenSequence: item group "${entry.id}" has a timeline and shuffle: "within-group". An interactive video presents its questions in the order its quizzes open.`
+      );
+    }
     const items = entry.items.map((item, itemIndex) => ({ item, itemIndex }));
-    const presented = entry.shuffle === "within-group" ? seededShuffle(items, `${seed}:group:${entry.id}`) : items;
+    const presented = timeline !== void 0 ? inQuizOrder(items, timeline) : entry.shuffle === "within-group" ? seededShuffle(items, `${seed}:group:${entry.id}`) : items;
     const size = presented.length;
     presented.forEach(({ item, itemIndex }, position) => {
+      const cue = timeline?.cues.find((candidate) => candidate.itemIds.includes(item.id));
       slots.push({
+        // Slot ids stay AUTHORED — the item's index or its key — whatever the
+        // presented order: moving a quiz must never re-map a stored answer.
         slotId: `${entryKey}.${keyOf(item) ?? String(itemIndex)}`,
         index: slots.length,
         activity: item,
@@ -262,7 +295,9 @@ function flattenSequence(entries, options = {}) {
           ...entry.title !== void 0 ? { title: entry.title } : {},
           stimulus: entry.stimulus,
           position,
-          size
+          size,
+          ...timeline !== void 0 ? { timeline } : {},
+          ...cue !== void 0 ? { cue } : {}
         }
       });
     });
@@ -445,7 +480,14 @@ function planSlot(slot, points) {
       group: {
         id: slot.group.id,
         ...slot.group.title !== void 0 ? { title: slot.group.title } : {},
-        stimulusHash: contentHash(slot.group.stimulus)
+        stimulusHash: contentHash(slot.group.stimulus),
+        ...slot.group.cue !== void 0 ? {
+          cue: {
+            id: slot.group.cue.id,
+            at: slot.group.cue.at,
+            ...slot.group.cue.required !== void 0 ? { required: slot.group.cue.required } : {}
+          }
+        } : {}
       }
     } : {},
     ...mediaBudgets !== void 0 ? { mediaBudgets } : {}
@@ -479,6 +521,7 @@ function verifyAttemptPlan(plan, current) {
   const addedSlotIds = current.slots.filter((s) => !before.has(s.slotId)).map((s) => s.slotId);
   const changedSlotIds = [];
   const changedStimulusSlotIds = [];
+  const changedCueSlotIds = [];
   const changedPointsSlotIds = [];
   const reorderedSlotIds = [];
   for (const slot of plan.slots) {
@@ -492,6 +535,9 @@ function verifyAttemptPlan(plan, current) {
     if (now.group?.stimulusHash !== slot.group?.stimulusHash) {
       changedStimulusSlotIds.push(slot.slotId);
     }
+    if (contentHash(now.group?.cue ?? null) !== contentHash(slot.group?.cue ?? null)) {
+      changedCueSlotIds.push(slot.slotId);
+    }
     if (now.points !== slot.points) {
       changedPointsSlotIds.push(slot.slotId);
     }
@@ -500,11 +546,12 @@ function verifyAttemptPlan(plan, current) {
     }
   }
   return {
-    matches: missingSlotIds.length === 0 && addedSlotIds.length === 0 && changedSlotIds.length === 0 && changedStimulusSlotIds.length === 0 && changedPointsSlotIds.length === 0 && reorderedSlotIds.length === 0,
+    matches: missingSlotIds.length === 0 && addedSlotIds.length === 0 && changedSlotIds.length === 0 && changedStimulusSlotIds.length === 0 && changedCueSlotIds.length === 0 && changedPointsSlotIds.length === 0 && reorderedSlotIds.length === 0,
     missingSlotIds,
     addedSlotIds,
     changedSlotIds,
     changedStimulusSlotIds,
+    changedCueSlotIds,
     changedPointsSlotIds,
     reorderedSlotIds
   };
@@ -652,6 +699,14 @@ function createItemGroupDraft(context) {
     items: []
   };
 }
+function createInteractiveVideoDraft(context) {
+  const draft = createItemGroupDraft(context);
+  return {
+    ...draft,
+    stimulus: { id: draft.stimulus.id, kind: "video", media: { type: "video", url: "" } },
+    timeline: { cues: [] }
+  };
+}
 function validateItemGroupDraft(draft) {
   return withValidationScope(() => validateItemGroupDraftInScope(draft));
 }
@@ -676,6 +731,9 @@ function validateItemGroupDraftInScope(draft) {
     );
   }
   issues.push(...checkItems(draft));
+  if (draft.timeline !== void 0 && draft.timeline !== null) {
+    issues.push(...checkTimeline(draft));
+  }
   if (groupCaptionsRevealDictation(draft, (captionsUrl) => !isUnwritten(captionsUrl))) {
     issues.push(
       issue(
@@ -722,6 +780,183 @@ function validateItemGroupDraftInScope(draft) {
   const invalid = issues.some((found) => found.severity !== "incomplete");
   return { status: invalid ? "invalid" : "incomplete", issues };
 }
+function checkTimeline(draft) {
+  const issues = [];
+  const timeline = draft.timeline;
+  if (!isRecord(timeline)) {
+    return issues;
+  }
+  const stimulus = isRecord(draft.stimulus) ? draft.stimulus : void 0;
+  if (stimulus !== void 0 && !isUnwritten(stimulus.kind) && stimulus.kind !== "video") {
+    issues.push(
+      issue(
+        "ig_timeline_stimulus_kind",
+        ["stimulus", "kind"],
+        "An interactive video needs a video: quizzes open at moments of it."
+      )
+    );
+  } else if (stimulus !== void 0 && isRecord(stimulus.media) && !isUnwritten(stimulus.media.type) && stimulus.media.type !== "video") {
+    issues.push(
+      issue(
+        "ig_timeline_stimulus_kind",
+        ["stimulus", "media", "type"],
+        "Upload a video file. An embedded player from another site cannot be paused when a quiz opens."
+      )
+    );
+  }
+  if (draft.shuffle === "within-group") {
+    issues.push(
+      issue(
+        "ig_timeline_shuffle",
+        ["shuffle"],
+        "The questions of an interactive video appear in the order their quizzes open, so they cannot be shuffled."
+      )
+    );
+  }
+  const items = Array.isArray(draft.items) ? draft.items : [];
+  const itemIndexById = /* @__PURE__ */ new Map();
+  items.forEach((item, index) => {
+    if (!isRecord(item)) {
+      return;
+    }
+    if (typeof item.id === "string" && item.id !== "") {
+      itemIndexById.set(item.id, index);
+    }
+    const type = item.type;
+    if (typeof type === "string" && type !== "" && type !== "item-group" && !isInteractiveVideoItemType(type) && getActivityTypeDescriptor(type) !== void 0) {
+      issues.push(
+        issue(
+          "ig_timeline_item_type",
+          ["items", index, "type"],
+          `An interactive video can hold ${INTERACTIVE_VIDEO_ITEM_TYPES.join(", ")} questions only.`
+        )
+      );
+    }
+    if (type === "dictation" && isUnset(item.media)) {
+      issues.push(
+        issue(
+          "ig_timeline_dictation_media",
+          ["items", index, "media"],
+          "Add the recording this dictation plays: inside a video it cannot play the video."
+        )
+      );
+    }
+  });
+  const cues = Array.isArray(timeline.cues) ? timeline.cues : [];
+  const quizIds = /* @__PURE__ */ new Set();
+  const placed = /* @__PURE__ */ new Set();
+  cues.forEach((cue, cueIndex) => {
+    if (!isRecord(cue)) {
+      return;
+    }
+    const at = (field, ...rest) => [
+      "timeline",
+      "cues",
+      cueIndex,
+      field,
+      ...rest
+    ];
+    if (isMissingId(cue.id)) {
+      issues.push(issue("ig_timeline_quiz_id_required", at("id"), "This quiz has no id."));
+    } else if (typeof cue.id === "string") {
+      if (quizIds.has(cue.id)) {
+        issues.push(
+          issue("ig_timeline_quiz_id_duplicate", at("id"), `Two quizzes share the id "${cue.id}".`)
+        );
+      }
+      quizIds.add(cue.id);
+    }
+    if (isUnset(cue.at)) {
+      issues.push(
+        issue(
+          "ig_timeline_quiz_time_required",
+          at("at"),
+          "Choose when in the video this quiz opens."
+        )
+      );
+    } else if (typeof cue.at !== "number" || !Number.isFinite(cue.at) || cue.at < 0) {
+      issues.push(
+        issue(
+          "ig_timeline_quiz_time_invalid",
+          at("at"),
+          "A quiz opens at a number of seconds, 0 or more."
+        )
+      );
+    }
+    if (isUnset(cue.itemIds) || Array.isArray(cue.itemIds) && cue.itemIds.length === 0) {
+      issues.push(
+        issue("ig_timeline_quiz_empty", at("itemIds"), "Add at least one question to this quiz.")
+      );
+      return;
+    }
+    if (!Array.isArray(cue.itemIds)) {
+      return;
+    }
+    cue.itemIds.forEach((itemId, position) => {
+      if (typeof itemId !== "string") {
+        return;
+      }
+      if (!itemIndexById.has(itemId)) {
+        issues.push(
+          issue(
+            "ig_timeline_quiz_unknown_item",
+            at("itemIds", position),
+            `This quiz names a question that is not in the video ("${itemId}").`
+          )
+        );
+      } else if (placed.has(itemId)) {
+        issues.push(
+          issue(
+            "ig_timeline_item_duplicate",
+            at("itemIds", position),
+            "This question is already in a quiz: each question belongs to one quiz."
+          )
+        );
+      }
+      placed.add(itemId);
+    });
+  });
+  for (const [itemId, index] of itemIndexById) {
+    if (!placed.has(itemId)) {
+      issues.push(
+        issue(
+          "ig_timeline_item_unplaced",
+          ["items", index],
+          "Add this question to a quiz, or the video never shows it."
+        )
+      );
+    }
+  }
+  const chapters = Array.isArray(timeline.chapters) ? timeline.chapters : [];
+  let previousAt;
+  chapters.forEach((chapter, index) => {
+    if (!isRecord(chapter)) {
+      return;
+    }
+    if (isUnwritten(chapter.title)) {
+      issues.push(
+        issue(
+          "ig_timeline_chapter_title",
+          ["timeline", "chapters", index, "title"],
+          "Give this chapter a title."
+        )
+      );
+    }
+    if (typeof chapter.at === "number" && Number.isFinite(chapter.at)) {
+      if (previousAt !== void 0 && chapter.at <= previousAt) {
+        issues.push(
+          issue(
+            "ig_timeline_chapter_order",
+            ["timeline", "chapters", index, "at"],
+            "Chapters must start in order, each after the one before it."
+          )
+        );
+      }
+      previousAt = chapter.at;
+    }
+  });
+  return issues;
+}
 function checkGroupIdentity(draft) {
   const issues = [];
   if (draft.schemaVersion !== "1.0") {
@@ -1127,7 +1362,25 @@ var ITEM_GROUP_FIELD_POLICY = {
   // and identity has to cross the redaction boundary intact.
   slotKey: "public",
   shuffle: "public",
-  stimulus: STIMULUS_FIELD_POLICY
+  stimulus: STIMULUS_FIELD_POLICY,
+  // Public, and classified key by key rather than as one leaf: the learner's
+  // player needs every part of it, none of it is a key — and a leaf would hand
+  // over the author's object by reference, with whatever else was parked in it.
+  timeline: {
+    // Applies to every element of the array.
+    cues: {
+      id: "public",
+      at: "public",
+      itemIds: "public",
+      title: "public",
+      required: "public"
+    },
+    chapters: {
+      at: "public",
+      title: "public"
+    },
+    navigation: "public"
+  }
 };
 function redactItemGroup(group, options = {}) {
   const reveal = options.reveal ?? "none";
@@ -1197,6 +1450,41 @@ function assertRedactedItemGroup(data) {
     }
   });
 }
+
+// src/timeline.ts
+function readMediaProgress(value, duration) {
+  let version;
+  let at;
+  let furthest;
+  try {
+    if (typeof value !== "object" || value === null) {
+      return null;
+    }
+    ({ progressVersion: version, at, furthest } = value);
+  } catch {
+    return null;
+  }
+  if (version !== "1.0" || typeof at !== "number" || !Number.isFinite(at)) {
+    return null;
+  }
+  const end = typeof duration === "number" && Number.isFinite(duration) && duration >= 0 ? duration : Number.POSITIVE_INFINITY;
+  const clampedAt = Math.min(Math.max(0, at), end);
+  const reached = typeof furthest === "number" && Number.isFinite(furthest) ? furthest : clampedAt;
+  return {
+    progressVersion: "1.0",
+    at: clampedAt,
+    furthest: Math.min(Math.max(clampedAt, reached), end)
+  };
+}
+function composeTimelineScore(entryKey, items, policy) {
+  const own = items.filter((item) => entryKeyOf(item.slotId) === entryKey);
+  if (own.length === 0) {
+    throw new Error(
+      `composeTimelineScore: no scored item belongs to entry "${entryKey}". Pass the video's slotKey (or its position in the sequence), and the items of the attempt that holds it.`
+    );
+  }
+  return composeAssessmentScore([{ id: entryKey, weight: 1, items: own }], policy);
+}
 export {
   ActivitySchemaError,
   BlankConfigSchema,
@@ -1217,9 +1505,12 @@ export {
   GapSelectChoiceSchema,
   GapSelectDataSchema,
   GapSelectGapSchema,
+  INTERACTIVE_VIDEO_ITEM_TYPES,
   ItemGroupSchema,
   MediaPlaybackSchema,
   MediaSchema,
+  MediaTimelineSchema,
+  MediaTrackSchema,
   MediaUrlSchema,
   MultipleChoiceDataSchema,
   MultipleChoiceOptionMediaSchema,
@@ -1250,7 +1541,13 @@ export {
   RedactedWrittenResponseDataSchema,
   SPEECH_ASSESSMENT_MAX_WORDS,
   StimulusSchema,
+  TIMELINE_MAX_CHAPTERS,
+  TIMELINE_MAX_ITEMS,
+  TIMELINE_MAX_QUIZZES,
+  TIMELINE_MAX_TITLE_LENGTH,
   TextMatchPolicySchema,
+  TimelineChapterSchema,
+  TimelineCueSchema,
   UnknownActivityTypeError,
   WrittenResponseDataSchema,
   WrittenResponseRubricCriterionSchema,
@@ -1264,10 +1561,12 @@ export {
   canonicalJson,
   classifyBand,
   composeAssessmentScore,
+  composeTimelineScore,
   computePassThreshold,
   contentHash,
   countWords,
   createDraft,
+  createInteractiveVideoDraft,
   createItemGroupDraft,
   defineActivityType,
   dictationJsonSchema,
@@ -1290,6 +1589,7 @@ export {
   hasGrade,
   hashSeed,
   inspectWav,
+  isInteractiveVideoItemType,
   isItemGroup,
   itemGroupJsonSchema,
   jsonSchemaFor,
@@ -1303,6 +1603,7 @@ export {
   planMediaBudgets,
   readAloudJsonSchema,
   readAloudType,
+  readMediaProgress,
   redact,
   redactItemGroup,
   registerActivityType,