@lessonkit/core 1.5.0 → 1.6.0

package/dist/index.cjs

@@ -27,10 +27,12 @@ __export(index_exports, {
   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,
   SLIDE_ALLOWED_CHILD_TYPES: () => SLIDE_ALLOWED_CHILD_TYPES,
@@ -240,7 +242,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");
     }
@@ -310,9 +312,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
   };
@@ -406,6 +410,16 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "ImageSlider",
   "Embed",
   "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
   "ProgressTracker"
 ];
 var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
@@ -440,9 +454,64 @@ var BRANCH_NODE_ALLOWED_CHILD_TYPES = [
   "ImageSlider",
   "Embed",
   "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
   "BranchChoice"
 ];
 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"
+];
 var INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES = ["Page"];
 var SLIDE_ALLOWED_CHILD_TYPES = [
   "Text",
@@ -475,7 +544,17 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "FindMultipleHotspots",
   "ImageSlider",
   "Embed",
-  "Chart"
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar"
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
 var TIMED_CUE_ALLOWED_CHILD_TYPES = [
@@ -519,7 +598,9 @@ 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
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
   Page: 1,
@@ -530,7 +611,9 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   InteractiveVideo: 2,
   AssessmentSequence: 1,
   BranchingScenario: 2,
-  BranchNode: 1
+  BranchNode: 1,
+  GameMap: 2,
+  MapStage: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -835,6 +918,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 +1086,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 +1099,7 @@ function createTrackingClient(opts) {
           try {
             await sink?.(events[i]);
           } catch {
-            buffer.unshift(...events.slice(i));
+            buffer.unshift(...events);
             return;
           }
         }
@@ -1064,7 +1223,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 +1232,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 +1542,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,13 +1786,15 @@ 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);
+        else if (bypassCacheForKey(key)) memory.delete(key);
         return value;
       } catch {
         return memory.get(key) ?? null;
@@ -1554,12 +1802,15 @@ function createMemoryBackedSessionStorage(session) {
     },
     setItem: (key, value) => {
       tombstones.delete(key);
-      memory.set(key, value);
       try {
         session.setItem(key, value);
+        memory.set(key, value);
         return true;
       } catch {
         warnPersistFailure();
+        if (!bypassCacheForKey(key)) {
+          memory.set(key, value);
+        }
         return false;
       }
     },
@@ -1701,7 +1952,17 @@ function resolveSessionId(storage, provided) {
     }
   }
   const existing = storage.getItem(SESSION_STORAGE_KEY);
-  if (existing) return existing;
+  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 volatile = volatileSessionIds.get(storage);
   if (volatile) return volatile;
   const id = createSessionId();
@@ -1803,7 +2064,17 @@ function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
   const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
   const marked = hasCourseStarted(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 +2083,16 @@ 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);
-      }
+      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 +2128,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 +2260,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 +2276,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 +2300,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 +2321,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 +2362,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 +2462,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();
+      }
     }
   };
 }
@@ -2178,10 +2496,12 @@ function defineLifecyclePlugin(plugin) {
   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,
   SLIDE_ALLOWED_CHILD_TYPES,