@lessonkit/core 1.5.0 → 1.7.0

package/dist/index.cjs

@@ -21,18 +21,22 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ACCORDION_FORBIDDEN_CHILD_TYPES: () => ACCORDION_FORBIDDEN_CHILD_TYPES,
+  ASSESSMENT_17_CHILD_TYPES: () => ASSESSMENT_17_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: () => ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BLOCKS_14_PAGE_SLIDE: () => BLOCKS_14_PAGE_SLIDE,
   BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: () => BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
   BRANCH_NODE_ALLOWED_CHILD_TYPES: () => BRANCH_NODE_ALLOWED_CHILD_TYPES,
   COMPOUND_MAX_NESTING_DEPTH: () => COMPOUND_MAX_NESTING_DEPTH,
   COMPOUND_RESUME_SCHEMA_VERSION: () => COMPOUND_RESUME_SCHEMA_VERSION,
+  GAME_MAP_ALLOWED_CHILD_TYPES: () => GAME_MAP_ALLOWED_CHILD_TYPES,
   ID_MAX_LENGTH: () => ID_MAX_LENGTH,
   ID_PATTERN: () => ID_PATTERN,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES: () => INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
   INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES: () => INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
+  MAP_STAGE_ALLOWED_CHILD_TYPES: () => MAP_STAGE_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES: () => PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY: () => SESSION_STORAGE_KEY,
+  SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES: () => SINGLE_CHOICE_SET_ALLOWED_CHILD_TYPES,
   SLIDE_ALLOWED_CHILD_TYPES: () => SLIDE_ALLOWED_CHILD_TYPES,
   SLIDE_DECK_ALLOWED_CHILD_TYPES: () => SLIDE_DECK_ALLOWED_CHILD_TYPES,
   TELEMETRY_EVENT_CATALOG: () => TELEMETRY_EVENT_CATALOG,
@@ -77,6 +81,7 @@ __export(index_exports, {
   hasCourseStartedXapiSent: () => hasCourseStartedXapiSent,
   isChildTypeAllowed: () => isChildTypeAllowed,
   isLifecycleTelemetryEvent: () => isLifecycleTelemetryEvent,
+  isMultiSelectMcq: () => isMultiSelectMcq,
   loadCompoundState: () => loadCompoundState,
   markCourseStarted: () => markCourseStarted,
   markCourseStartedEmittedToTracking: () => markCourseStartedEmittedToTracking,
@@ -84,6 +89,7 @@ __export(index_exports, {
   markCourseStartedXapiSent: () => markCourseStartedXapiSent,
   migrateCourseStartedMark: () => migrateCourseStartedMark,
   nowIso: () => nowIso,
+  orderChoicesByIndices: () => orderChoicesByIndices,
   parseBlockId: () => parseBlockId,
   parseCheckId: () => parseCheckId,
   parseCompoundResumeState: () => parseCompoundResumeState,
@@ -92,8 +98,12 @@ __export(index_exports, {
   resetSharedVolatileSessionIdForTests: () => resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests: () => resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests: () => resetTelemetryBuilderWarningsForTests,
+  resolveMcqCorrectAnswers: () => resolveMcqCorrectAnswers,
+  resolveMcqShuffleSeed: () => resolveMcqShuffleSeed,
   resolveSessionId: () => resolveSessionId,
   saveCompoundState: () => saveCompoundState,
+  scoreMcqSelection: () => scoreMcqSelection,
+  shuffleChoiceIndices: () => shuffleChoiceIndices,
   slugifyId: () => slugifyId,
   telemetryCatalogV2Version: () => telemetryCatalogV2Version,
   telemetryCatalogV3Version: () => telemetryCatalogV3Version,
@@ -240,7 +250,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");
     }
@@ -249,6 +259,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 = {}) {
@@ -310,9 +383,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
   };
@@ -362,6 +437,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",
@@ -406,7 +486,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",
@@ -440,9 +531,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",
@@ -475,7 +623,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 = [
@@ -491,7 +650,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 = [
@@ -508,8 +669,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,
@@ -519,7 +682,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,
@@ -530,7 +696,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];
@@ -835,6 +1004,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() {
@@ -931,6 +1172,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) {
@@ -940,7 +1185,7 @@ function createTrackingClient(opts) {
           try {
             await sink?.(events[i]);
           } catch {
-            buffer.unshift(...events.slice(i));
+            buffer.unshift(...events);
             return;
           }
         }
@@ -1064,7 +1309,8 @@ function randomSessionIdFallback() {
   if (g.crypto?.getRandomValues) {
     const bytes = new Uint8Array(16);
     g.crypto.getRandomValues(bytes);
-    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `s-${hex}`;
   }
   throw new Error(
     "[lessonkit] createSessionId requires crypto.randomUUID or crypto.getRandomValues"
@@ -1072,7 +1318,9 @@ function randomSessionIdFallback() {
 }
 function createSessionId() {
   const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
+  if (g.crypto?.randomUUID) {
+    return `s-${g.crypto.randomUUID().replace(/-/g, "")}`;
+  }
   return randomSessionIdFallback();
 }
 
@@ -1380,6 +1628,90 @@ var TELEMETRY_EVENT_REGISTRY = {
         data: opts.data
       };
     }
+  },
+  image_juxtaposition_changed: {
+    build: (opts, base) => ({
+      name: "image_juxtaposition_changed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  timeline_event_viewed: {
+    build: (opts, base) => ({
+      name: "timeline_event_viewed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  image_sequence_changed: {
+    build: (opts, base) => ({
+      name: "image_sequence_changed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  audio_recording_started: {
+    build: (opts, base) => ({
+      name: "audio_recording_started",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  audio_recording_completed: {
+    build: (opts, base) => ({
+      name: "audio_recording_completed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  qr_content_revealed: {
+    build: (opts, base) => ({
+      name: "qr_content_revealed",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  advent_door_opened: {
+    build: (opts, base) => ({
+      name: "advent_door_opened",
+      ...base,
+      lessonId: opts.lessonId,
+      data: opts.data
+    })
+  },
+  map_stage_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "map_stage_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("map_stage_viewed requires active lessonId");
+      return {
+        name: "map_stage_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  map_exit_selected: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "map_exit_selected") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("map_exit_selected requires active lessonId");
+      return {
+        name: "map_exit_selected",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
   }
 };
 function buildTelemetryEventFromRegistry(opts) {
@@ -1540,26 +1872,35 @@ function createMemoryBackedSessionStorage(session) {
       );
     }
   };
+  const bypassCacheForKey = (key) => key === "lessonkit:sessionId" || key.startsWith("lessonkit:course_started");
   return {
     getItem: (key) => {
       if (tombstones.has(key)) return null;
-      if (memory.has(key)) return memory.get(key);
+      if (!bypassCacheForKey(key) && memory.has(key)) return memory.get(key);
       try {
         const value = session.getItem(key);
-        if (value !== null) memory.set(key, value);
-        return value;
+        if (value !== null) {
+          memory.set(key, value);
+          return value;
+        }
+        if (bypassCacheForKey(key) && memory.has(key)) {
+          return memory.get(key);
+        }
+        if (bypassCacheForKey(key)) memory.delete(key);
+        return null;
       } catch {
         return memory.get(key) ?? null;
       }
     },
     setItem: (key, value) => {
       tombstones.delete(key);
-      memory.set(key, value);
       try {
         session.setItem(key, value);
+        memory.set(key, value);
         return true;
       } catch {
         warnPersistFailure();
+        memory.set(key, value);
         return false;
       }
     },
@@ -1672,6 +2013,29 @@ function createProgressController() {
 // src/session.ts
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
 var volatileSessionIds = /* @__PURE__ */ new WeakMap();
+var volatileStorageMarks = /* @__PURE__ */ new WeakMap();
+function rememberVolatileMark(storage, key) {
+  let keys = volatileStorageMarks.get(storage);
+  if (!keys) {
+    keys = /* @__PURE__ */ new Set();
+    volatileStorageMarks.set(storage, keys);
+  }
+  keys.add(key);
+}
+function hasVolatileMark(storage, key) {
+  return volatileStorageMarks.get(storage)?.has(key) ?? false;
+}
+function clearVolatileMark(storage, key) {
+  volatileStorageMarks.get(storage)?.delete(key);
+}
+function storageHasMark(storage, key) {
+  return storage.getItem(key) === "1" || hasVolatileMark(storage, key);
+}
+function storageSetMark(storage, key) {
+  const persisted = storage.setItem(key, "1");
+  if (!persisted) rememberVolatileMark(storage, key);
+  return persisted;
+}
 function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
@@ -1687,21 +2051,7 @@ function sessionKeySegment(sessionId) {
   const validated = validateId(sessionId);
   return validated.ok ? validated.id : encodeURIComponent(sessionId);
 }
-function resolveSessionId(storage, provided) {
-  if (provided !== void 0) {
-    const trimmed = provided.trim();
-    if (trimmed.length > 0) {
-      const validated = validateId(trimmed);
-      if (validated.ok) return validated.id;
-      if (isDevEnvironment2()) {
-        console.warn(
-          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
-        );
-      }
-    }
-  }
-  const existing = storage.getItem(SESSION_STORAGE_KEY);
-  if (existing) return existing;
+function resolveGeneratedSessionId(storage) {
   const volatile = volatileSessionIds.get(storage);
   if (volatile) return volatile;
   const id = createSessionId();
@@ -1717,6 +2067,50 @@ function resolveSessionId(storage, provided) {
   }
   return id;
 }
+function resolveFallbackSessionId(storage, options) {
+  const existing = storage.getItem(SESSION_STORAGE_KEY);
+  if (existing) {
+    const trimmedExisting = existing.trim();
+    const validatedExisting = validateId(trimmedExisting);
+    if (validatedExisting.ok) return validatedExisting.id;
+    storage.removeItem?.(SESSION_STORAGE_KEY);
+    if (isDevEnvironment2()) {
+      console.warn(
+        `[lessonkit] Invalid stored sessionId "${existing}"; generating a new id.`
+      );
+    }
+    const fallback = resolveGeneratedSessionId(storage);
+    options?.onInvalidSessionId?.({
+      invalidId: existing,
+      fallbackId: fallback,
+      source: "stored"
+    });
+    return fallback;
+  }
+  return resolveGeneratedSessionId(storage);
+}
+function resolveSessionId(storage, provided, options) {
+  if (provided !== void 0) {
+    const trimmed = provided.trim();
+    if (trimmed.length > 0) {
+      const validated = validateId(trimmed);
+      if (validated.ok) return validated.id;
+      if (isDevEnvironment2()) {
+        console.warn(
+          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
+        );
+      }
+      const fallback = resolveFallbackSessionId(storage, options);
+      options?.onInvalidSessionId?.({
+        invalidId: trimmed,
+        fallbackId: fallback,
+        source: "provided"
+      });
+      return fallback;
+    }
+  }
+  return resolveFallbackSessionId(storage, options);
+}
 function courseStartedStorageKey(sessionId, courseId) {
   return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
@@ -1731,35 +2125,35 @@ function courseStartedXapiStorageKey(sessionId, courseId) {
 }
 function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedStorageKey(sessionId, courseId));
 }
 function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedStorageKey(sessionId, courseId));
 }
 function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedTrackingStorageKey(sessionId, courseId));
 }
 function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedTrackingStorageKey(sessionId, courseId));
 }
 function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedPipelineStorageKey(sessionId, courseId));
 }
 function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedPipelineStorageKey(sessionId, courseId));
 }
 function hasCourseStartedXapiSent(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.getItem(courseStartedXapiStorageKey(sessionId, courseId)) === "1";
+  return storageHasMark(storage, courseStartedXapiStorageKey(sessionId, courseId));
 }
 function markCourseStartedXapiSent(storage, sessionId, courseId) {
   if (!courseId) return false;
-  return storage.setItem(courseStartedXapiStorageKey(sessionId, courseId), "1");
+  return storageSetMark(storage, courseStartedXapiStorageKey(sessionId, courseId));
 }
 function resetSharedVolatileSessionIdForTests() {
 }
@@ -1767,6 +2161,7 @@ function migrateStorageMark(storage, fromKey, toKey, hasMark) {
   if (!hasMark) return;
   if (storage.setItem(toKey, "1")) {
     storage.removeItem?.(fromKey);
+    clearVolatileMark(storage, fromKey);
   }
 }
 function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
@@ -1799,11 +2194,28 @@ function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId)
 
 // src/runtime/courseLifecycle.ts
 var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+var courseStartedEmittedInTab = /* @__PURE__ */ new Set();
 function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  if (courseStartedEmittedInTab.has(flightKey)) {
+    return Promise.resolve({
+      emitted: true,
+      marked: marked || markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+    });
+  }
   if (alreadyEmittedToSink) {
-    return Promise.resolve({ emitted: true, marked });
+    const markPersisted = marked ? true : markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+    return Promise.resolve({
+      emitted: true,
+      marked: markPersisted
+    });
+  }
+  if (marked && hasCourseStartedEmittedToTracking(ctx.storage, ctx.sessionId, ctx.courseId)) {
+    return Promise.resolve({
+      emitted: true,
+      marked: true
+    });
   }
   const existing = courseStartedEmitFlights.get(flightKey);
   if (existing) {
@@ -1812,15 +2224,19 @@ function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flight = Promise.resolve().then(() => {
     try {
       const emitted = deps.emitCourseStartedEvent(ctx);
-      if (emitted && !marked) {
-        markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+      if (emitted) {
+        courseStartedEmittedInTab.add(flightKey);
       }
+      const markPersisted = emitted && !marked ? markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId) : marked;
       return {
         emitted,
-        marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+        marked: markPersisted
       };
     } catch {
-      return { emitted: false, marked };
+      return {
+        emitted: false,
+        marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
+      };
     } finally {
       if (courseStartedEmitFlights.get(flightKey) === flight) {
         courseStartedEmitFlights.delete(flightKey);
@@ -1856,7 +2272,16 @@ function completeCourseWithTelemetry(opts) {
     });
   }
   const result = opts.progress.completeCourse();
-  if (!result.didComplete) return false;
+  if (!result.didComplete) {
+    const after = opts.progress.getState();
+    if (after.activeLessonId) {
+      const lessonResult = opts.progress.completeLesson(after.activeLessonId, opts.nowMs);
+      if (lessonResult.didComplete) {
+        opts.emitLessonCompleted(after.activeLessonId, lessonResult.durationMs);
+      }
+    }
+    return false;
+  }
   opts.emitCourseCompleted();
   return true;
 }
@@ -1979,6 +2404,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;
@@ -1991,12 +2420,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,
@@ -2008,12 +2444,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());
@@ -2035,7 +2465,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);
@@ -2077,21 +2506,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());
@@ -2146,15 +2606,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();
+      }
     }
   };
 }
@@ -2172,18 +2634,22 @@ function defineLifecyclePlugin(plugin) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   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,
@@ -2228,6 +2694,7 @@ function defineLifecyclePlugin(plugin) {
   hasCourseStartedXapiSent,
   isChildTypeAllowed,
   isLifecycleTelemetryEvent,
+  isMultiSelectMcq,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
@@ -2235,6 +2702,7 @@ function defineLifecyclePlugin(plugin) {
   markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
+  orderChoicesByIndices,
   parseBlockId,
   parseCheckId,
   parseCompoundResumeState,
@@ -2243,8 +2711,12 @@ function defineLifecyclePlugin(plugin) {
   resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
+  resolveMcqCorrectAnswers,
+  resolveMcqShuffleSeed,
   resolveSessionId,
   saveCompoundState,
+  scoreMcqSelection,
+  shuffleChoiceIndices,
   slugifyId,
   telemetryCatalogV2Version,
   telemetryCatalogV3Version,