@lessonkit/core 1.5.0 → 1.7.0

package/dist/index.js

@@ -36,7 +36,7 @@ import {
   tryEmitCourseStarted,
   validateId,
   warnDev
-} from "./chunk-KFXFQ6B2.js";
+} from "./chunk-DTJGIMUU.js";
 
 // src/assertNever.ts
 function assertNever(value, message = "Unexpected value") {
@@ -117,7 +117,7 @@ function buildLessonkitUrn(parts) {
     urn += `:block:${blockId}`;
   }
   if (parts.nodeId !== void 0) {
-    const nodeId = assertValidId(parts.nodeId, "blockId");
+    const nodeId = assertValidId(parts.nodeId, "nodeId");
     if (parts.blockId === void 0) {
       throw new Error("buildLessonkitUrn: nodeId requires blockId");
     }
@@ -126,6 +126,69 @@ function buildLessonkitUrn(parts) {
   return urn;
 }
 
+// src/mcqAssessment.ts
+function resolveMcqCorrectAnswers(props) {
+  if (props.answers && props.answers.length > 1) {
+    return new Set(props.answers.map((a) => a.trim()).filter(Boolean));
+  }
+  const single = props.answers?.[0]?.trim() ?? props.answer.trim();
+  return new Set(single ? [single] : []);
+}
+function isMultiSelectMcq(props) {
+  return (props.answers?.length ?? 0) > 1;
+}
+function scoreMcqSelection(selected, correct, multi, passingScore) {
+  const maxScore = multi ? Math.max(correct.size, 1) : 1;
+  if (!selected || Array.isArray(selected) && selected.length === 0) {
+    return {
+      score: 0,
+      maxScore,
+      exactMatch: false,
+      hasWrongSelection: false,
+      passedThreshold: false
+    };
+  }
+  const selectedSet = new Set(
+    (Array.isArray(selected) ? selected : [selected]).map((s) => s.trim()).filter(Boolean)
+  );
+  let score = 0;
+  for (const label of selectedSet) {
+    if (correct.has(label)) score += 1;
+  }
+  const hasWrongSelection = [...selectedSet].some((label) => !correct.has(label));
+  const exactMatch = !hasWrongSelection && selectedSet.size === correct.size && [...correct].every((label) => selectedSet.has(label));
+  const threshold = passingScore ?? maxScore;
+  const passedThreshold = score >= threshold && !hasWrongSelection;
+  return { score, maxScore, exactMatch, hasWrongSelection, passedThreshold };
+}
+function hashSeedToNumber(seed) {
+  if (typeof seed === "number" && Number.isFinite(seed)) return Math.abs(Math.trunc(seed)) || 1;
+  let hash = 2166136261;
+  const text = String(seed);
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return hash >>> 0 || 1;
+}
+function shuffleChoiceIndices(length, seed) {
+  const indices = Array.from({ length }, (_, i) => i);
+  if (length <= 1) return indices;
+  let state = hashSeedToNumber(seed);
+  for (let i = length - 1; i > 0; i -= 1) {
+    state = Math.imul(state, 1664525) + 1013904223 >>> 0;
+    const j = state % (i + 1);
+    [indices[i], indices[j]] = [indices[j], indices[i]];
+  }
+  return indices;
+}
+function resolveMcqShuffleSeed(props) {
+  return props.shuffleSeed ?? props.checkId;
+}
+function orderChoicesByIndices(choices, orderIndices) {
+  return orderIndices.map((index) => choices[index] ?? "").filter((c) => c.length > 0);
+}
+
 // src/compound.ts
 var COMPOUND_RESUME_SCHEMA_VERSION = 1;
 function createCompoundResumeState(input = {}) {
@@ -187,9 +250,11 @@ function parseCompoundResumeState(raw, opts) {
     opts?.onDroppedChildKeys?.(droppedChildKeys);
   }
   const activeChapterIndex = typeof obj.activeChapterIndex === "number" && Number.isFinite(obj.activeChapterIndex) ? obj.activeChapterIndex : void 0;
+  const rawPageIndex = Math.max(0, Math.floor(obj.activePageIndex));
+  const activePageIndex = typeof opts?.pageCount === "number" && opts.pageCount > 0 ? clampCompoundPageIndex(rawPageIndex, opts.pageCount) : rawPageIndex;
   return {
     schemaVersion: COMPOUND_RESUME_SCHEMA_VERSION,
-    activePageIndex: Math.max(0, Math.floor(obj.activePageIndex)),
+    activePageIndex,
     ...activeChapterIndex !== void 0 ? { activeChapterIndex: Math.max(0, Math.floor(activeChapterIndex)) } : {},
     childStates
   };
@@ -229,6 +294,11 @@ function clearCompoundState(storage, courseId, compoundId) {
 }
 
 // src/compoundAllowlists.ts
+var ASSESSMENT_17_CHILD_TYPES = [
+  "SortParagraphs",
+  "GuessTheAnswer",
+  "MultimediaChoice"
+];
 var PAGE_AND_SLIDE_14_BLOCKS = [
   "Video",
   "Summary",
@@ -273,7 +343,18 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "ImageSlider",
   "Embed",
   "Chart",
-  "ProgressTracker"
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
+  "ProgressTracker",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "Text",
@@ -307,9 +388,66 @@ var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "ImageSlider",
   "Embed",
   "Chart",
-  "BranchChoice"
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
+  "BranchChoice",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES = ["BranchNode"];
+var GAME_MAP_ALLOWED_CHILD_TYPES = ["MapStage"];
+var MAP_STAGE_ALLOWED_CHILD_TYPES = [
+  "Text",
+  "Heading",
+  "Image",
+  "Video",
+  "Scenario",
+  "Reflection",
+  "Quiz",
+  "KnowledgeCheck",
+  "TrueFalse",
+  "FillInTheBlanks",
+  "DragAndDrop",
+  "DragTheWords",
+  "MarkTheWords",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz",
+  "Accordion",
+  "DialogCards",
+  "Flashcards",
+  "ImageHotspots",
+  "FindHotspot",
+  "FindMultipleHotspots",
+  "ImageSlider",
+  "Embed",
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
+  "MapExit",
+  ...ASSESSMENT_17_CHILD_TYPES
+];
 var INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES = ["Page"];
 var SLIDE_ALLOWED_CHILD_TYPES = [
   "Text",
@@ -342,7 +480,18 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "FindMultipleHotspots",
   "ImageSlider",
   "Embed",
-  "Chart"
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
 var TIMED_CUE_ALLOWED_CHILD_TYPES = [
@@ -358,7 +507,9 @@ var TIMED_CUE_ALLOWED_CHILD_TYPES = [
   "MemoryGame",
   "Questionnaire",
   "Essay",
-  "ArithmeticQuiz"
+  "ArithmeticQuiz",
+  "MultimediaChoice",
+  "GuessTheAnswer"
 ];
 var INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES = ["TimedCue"];
 var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
@@ -375,8 +526,10 @@ var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
   "ImagePairing",
   "ImageSequencing",
   "ArithmeticQuiz",
-  "Essay"
+  "Essay",
+  ...ASSESSMENT_17_CHILD_TYPES
 ];
+var SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES = ["Quiz", "KnowledgeCheck"];
 var ALLOWLISTS = {
   Page: PAGE_ALLOWED_CHILD_TYPES,
   InteractiveBook: INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
@@ -386,7 +539,10 @@ var ALLOWLISTS = {
   InteractiveVideo: INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BranchingScenario: BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
-  BranchNode: BRANCH_NODE_ALLOWED_CHILD_TYPES
+  BranchNode: BRANCH_NODE_ALLOWED_CHILD_TYPES,
+  GameMap: GAME_MAP_ALLOWED_CHILD_TYPES,
+  MapStage: MAP_STAGE_ALLOWED_CHILD_TYPES,
+  SingleChoiceSet: SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
   Page: 1,
@@ -397,7 +553,10 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   InteractiveVideo: 2,
   AssessmentSequence: 1,
   BranchingScenario: 2,
-  BranchNode: 1
+  BranchNode: 1,
+  GameMap: 2,
+  MapStage: 1,
+  SingleChoiceSet: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -702,6 +861,78 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     dataFields: ["blockId", "fromNodeId", "toNodeId", "label", "scoreWeight"],
     xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
     urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:node:{toNodeId}"
+  },
+  {
+    name: "image_juxtaposition_changed",
+    description: "Learner adjusted the before/after divider",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "position"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "timeline_event_viewed",
+    description: "Learner focused a timeline event",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "eventId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "image_sequence_changed",
+    description: "Learner changed the image sequence frame",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "frameIndex"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "audio_recording_started",
+    description: "Learner started an audio recording",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "audio_recording_completed",
+    description: "Learner completed an audio recording",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "qr_content_revealed",
+    description: "Learner revealed QR hidden content",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "advent_door_opened",
+    description: "Learner opened an advent calendar door",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "doorId", "day"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/interacted",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "map_stage_viewed",
+    description: "Learner viewed a stage in a GameMap",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "stageId", "stageIndex", "stageLabel"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:stage:{stageId}"
+  },
+  {
+    name: "map_exit_selected",
+    description: "Learner selected a map exit in a GameMap",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "fromStageId", "toStageId", "label", "scoreWeight"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/answered",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:stage:{toStageId}"
   }
 ];
 function buildTelemetryCatalogV3() {
@@ -798,6 +1029,10 @@ function createTrackingClient(opts) {
   const runFlush = () => {
     if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
+    for (const event of events) {
+      const key = eventDedupKey(event);
+      if (key) pendingDeliverIds.add(key);
+    }
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -807,7 +1042,7 @@ function createTrackingClient(opts) {
           try {
             await sink?.(events[i]);
           } catch {
-            buffer.unshift(...events.slice(i));
+            buffer.unshift(...events);
             return;
           }
         }
@@ -1142,6 +1377,10 @@ function resolvePluginHost(plugins) {
   if (Array.isArray(plugins) && plugins.length > 0) return createPluginRegistry(plugins);
   return null;
 }
+function pluginListFingerprint(plugins) {
+  if (!plugins || !Array.isArray(plugins)) return null;
+  return plugins.map((p) => `${p.id}\0${p.version ?? ""}`).join("\n");
+}
 function warnRuntimeV1Deprecated() {
   const g = globalThis;
   if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
@@ -1154,12 +1393,19 @@ function createLessonkitRuntime(config, ports = {}) {
   const storage = ports.storage ?? createSessionStoragePort();
   const clock = ports.clock ?? createDefaultClock();
   const configSnapshot = { ...config };
+  const hasExplicitSessionId = Boolean(configSnapshot.session?.sessionId?.trim());
+  let autoSessionId;
   let sessionId = resolveSessionId(storage, configSnapshot.session?.sessionId);
+  if (!hasExplicitSessionId) {
+    autoSessionId = sessionId;
+  }
   let attemptId = configSnapshot.session?.attemptId;
   let user = configSnapshot.session?.user;
   let courseId = configSnapshot.courseId;
+  let configuredSessionId = configSnapshot.session?.sessionId;
   let progress = createProgressController();
   let pluginHost = resolvePluginHost(configSnapshot.plugins);
+  let pluginFingerprint = pluginListFingerprint(configSnapshot.plugins);
   let disposed = false;
   const getPluginCtx = () => buildPluginContext({
     courseId,
@@ -1171,12 +1417,6 @@ function createLessonkitRuntime(config, ports = {}) {
     pluginHost?.setupAll(getPluginCtx());
   }
   const getSession = () => ({ sessionId, attemptId, user });
-  const syncSessionFromConfig = (next) => {
-    sessionId = resolveSessionId(storage, next.session?.sessionId);
-    attemptId = next.session?.attemptId;
-    user = next.session?.user;
-    courseId = next.courseId;
-  };
   const applyPluginsToEvent = (event) => {
     if (!pluginHost) return event;
     return pluginHost.runTelemetry(event, getPluginCtx());
@@ -1198,7 +1438,6 @@ function createLessonkitRuntime(config, ports = {}) {
     const event = buildAndApply(name, data, lessonId);
     if (event) emitFn(event);
   };
-  syncSessionFromConfig(configSnapshot);
   const track = (name, data, emit, lessonId) => {
     if (disposed) return;
     const event = buildAndApply(name, data, lessonId);
@@ -1240,21 +1479,52 @@ function createLessonkitRuntime(config, ports = {}) {
       if (next.autoCompleteOnLessonSwitch !== void 0) {
         configSnapshot.autoCompleteOnLessonSwitch = next.autoCompleteOnLessonSwitch;
       }
+      if (next.courseId !== void 0) {
+        courseId = next.courseId;
+      }
       if (next.session !== void 0) {
+        const previousSessionId = sessionId;
         configSnapshot.session = { ...configSnapshot.session, ...next.session };
+        const explicitSessionId = configSnapshot.session?.sessionId?.trim();
+        if (explicitSessionId) {
+          sessionId = resolveSessionId(storage, explicitSessionId);
+          autoSessionId = void 0;
+        } else {
+          sessionId = autoSessionId ?? resolveSessionId(storage, void 0);
+          if (!autoSessionId) autoSessionId = sessionId;
+        }
+        attemptId = configSnapshot.session?.attemptId;
+        user = configSnapshot.session?.user;
+        if (previousSessionId !== sessionId) {
+          const prevExplicit = configuredSessionId?.trim();
+          const nextExplicit = configSnapshot.session?.sessionId?.trim();
+          const isExplicitLearnerSwap = Boolean(prevExplicit) && Boolean(nextExplicit) && prevExplicit !== nextExplicit;
+          if (!isExplicitLearnerSwap) {
+            migrateCourseStartedMark(storage, previousSessionId, sessionId, courseId);
+          }
+        }
+        configuredSessionId = configSnapshot.session?.sessionId;
       }
-      syncSessionFromConfig(configSnapshot);
       const sessionKeyAfter = JSON.stringify({ sessionId, attemptId, user });
       if (next.courseId !== void 0 && next.courseId !== previousCourseId) {
         progress = createProgressController();
-      }
-      if (next.plugins !== void 0 && next.plugins !== configSnapshot.plugins) {
-        pluginHost?.disposeAll();
-        configSnapshot.plugins = next.plugins;
-        pluginHost = resolvePluginHost(configSnapshot.plugins);
         if (!configSnapshot.deferPluginSetup) {
+          pluginHost?.disposeAll();
           pluginHost?.setupAll(getPluginCtx());
         }
+      }
+      if (next.plugins !== void 0) {
+        const nextFingerprint = pluginListFingerprint(next.plugins);
+        const pluginsChanged = next.plugins !== configSnapshot.plugins || nextFingerprint !== null && nextFingerprint !== pluginFingerprint;
+        if (pluginsChanged) {
+          pluginHost?.disposeAll();
+          configSnapshot.plugins = next.plugins;
+          pluginFingerprint = nextFingerprint;
+          pluginHost = resolvePluginHost(configSnapshot.plugins);
+          if (!configSnapshot.deferPluginSetup) {
+            pluginHost?.setupAll(getPluginCtx());
+          }
+        }
       } else if (next.session !== void 0 && sessionKeyBefore !== sessionKeyAfter && pluginHost && !configSnapshot.deferPluginSetup) {
         pluginHost.disposeAll();
         pluginHost.setupAll(getPluginCtx());
@@ -1309,15 +1579,17 @@ function createLessonkitRuntime(config, ports = {}) {
       configSnapshot.courseId = nextCourseId;
       courseId = nextCourseId;
       progress = createProgressController();
-      pluginHost?.disposeAll();
       if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.disposeAll();
         pluginHost?.setupAll(getPluginCtx());
       }
     },
     dispose() {
       if (disposed) return;
       disposed = true;
-      pluginHost?.disposeAll();
+      if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.disposeAll();
+      }
     }
   };
 }
@@ -1334,18 +1606,22 @@ function defineLifecyclePlugin(plugin) {
 }
 export {
   ACCORDION_FORBIDDEN_CHILD_TYPES,
+  ASSESSMENT_17_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BLOCKS_14_PAGE_SLIDE,
   BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
   BRANCH_NODE_ALLOWED_CHILD_TYPES,
   COMPOUND_MAX_NESTING_DEPTH,
   COMPOUND_RESUME_SCHEMA_VERSION,
+  GAME_MAP_ALLOWED_CHILD_TYPES,
   ID_MAX_LENGTH,
   ID_PATTERN,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
   INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
+  MAP_STAGE_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY,
+  SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES,
   SLIDE_ALLOWED_CHILD_TYPES,
   SLIDE_DECK_ALLOWED_CHILD_TYPES,
   TELEMETRY_EVENT_CATALOG,
@@ -1390,6 +1666,7 @@ export {
   hasCourseStartedXapiSent,
   isChildTypeAllowed,
   isLifecycleTelemetryEvent,
+  isMultiSelectMcq,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
@@ -1397,6 +1674,7 @@ export {
   markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
+  orderChoicesByIndices,
   parseBlockId,
   parseCheckId,
   parseCompoundResumeState,
@@ -1405,8 +1683,12 @@ export {
   resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
+  resolveMcqCorrectAnswers,
+  resolveMcqShuffleSeed,
   resolveSessionId,
   saveCompoundState,
+  scoreMcqSelection,
+  shuffleChoiceIndices,
   slugifyId,
   telemetryCatalogV2Version,
   telemetryCatalogV3Version,