@lessonkit/core 1.4.0 → 1.6.0

package/dist/index.js

@@ -1,5 +1,8 @@
 import {
+  ID_MAX_LENGTH,
+  ID_PATTERN,
   SESSION_STORAGE_KEY,
+  assertValidId,
   buildCourseStartedTelemetryEvent,
   buildTelemetryEvent,
   completeCourseWithTelemetry,
@@ -13,82 +16,33 @@ import {
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
   isDevEnvironment,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered,
+  markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
+  parseBlockId,
+  parseCheckId,
+  parseCourseId,
+  parseLessonId,
   resetSharedVolatileSessionIdForTests,
   resetStoragePortForTests,
   resetTelemetryBuilderWarningsForTests,
   resolveSessionId,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,
+  validateId,
   warnDev
-} from "./chunk-PEWFPVQ6.js";
-
-// src/identityTypes.ts
-var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
-var ID_MAX_LENGTH = 64;
+} from "./chunk-NGCHHJSM.js";
 
 // src/assertNever.ts
 function assertNever(value, message = "Unexpected value") {
   throw new Error(`${message}: ${String(value)}`);
 }
 
-// src/validateId.ts
-function validateId(input, path = "id") {
-  if (typeof input !== "string") {
-    return { ok: false, issues: [{ path, message: "id must be a string" }] };
-  }
-  const id = input.trim();
-  if (!id.length) {
-    return { ok: false, issues: [{ path, message: "id must not be empty" }] };
-  }
-  if (id.length > ID_MAX_LENGTH) {
-    return {
-      ok: false,
-      issues: [{ path, message: `id must be at most ${ID_MAX_LENGTH} characters` }]
-    };
-  }
-  if (!ID_PATTERN.test(id)) {
-    return {
-      ok: false,
-      issues: [
-        {
-          path,
-          message: "id must start with a letter and contain only letters, digits, underscores, and hyphens"
-        }
-      ]
-    };
-  }
-  return { ok: true, id };
-}
-function parseCourseId(input) {
-  const result = validateId(input, "courseId");
-  return result.ok ? result.id : null;
-}
-function parseLessonId(input) {
-  const result = validateId(input, "lessonId");
-  return result.ok ? result.id : null;
-}
-function parseCheckId(input) {
-  const result = validateId(input, "checkId");
-  return result.ok ? result.id : null;
-}
-function parseBlockId(input) {
-  const result = validateId(input, "blockId");
-  return result.ok ? result.id : null;
-}
-function assertValidId(input, path = "id") {
-  const result = validateId(input, path);
-  if (!result.ok) {
-    throw new Error(result.issues.map((i) => `${i.path}: ${i.message}`).join("; "));
-  }
-  return result.id;
-}
-
 // src/slugify.ts
 function shortHash(input) {
   let h = 0;
@@ -101,12 +55,26 @@ function uniqueFallbackId(input, usedIds) {
   const hash = shortHash(input);
   for (let n = 0; n < 100; n++) {
     const candidate = (n === 0 ? `id-${hash}` : `id-${hash}-${n}`).slice(0, 64);
-    const validated2 = validateId(candidate);
-    if (validated2.ok && !usedIds.has(validated2.id)) return validated2.id;
+    const validated = validateId(candidate);
+    if (validated.ok && !usedIds.has(validated.id)) return validated.id;
+  }
+  for (let attempt = 0; attempt < 100; attempt++) {
+    const randomSuffix = Math.random().toString(36).slice(2, 8);
+    const candidate = `id-${hash}-${randomSuffix}`.slice(0, 64);
+    const validated = validateId(candidate);
+    if (validated.ok && !usedIds.has(validated.id)) return validated.id;
   }
   const timed = `id-${hash}-${Date.now().toString(36)}`.slice(0, 64);
-  const validated = validateId(timed);
-  return validated.ok ? validated.id : `id-${hash}`;
+  const timedValidated = validateId(timed);
+  if (timedValidated.ok && !usedIds.has(timedValidated.id)) return timedValidated.id;
+  const cryptoApi = globalThis.crypto;
+  for (let attempt = 0; attempt < 1e3; attempt++) {
+    const suffix = typeof cryptoApi?.randomUUID === "function" ? cryptoApi.randomUUID().replace(/-/g, "").slice(0, 12) : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const candidate = `id-${hash}-${suffix}`.slice(0, 64);
+    const validated = validateId(candidate);
+    if (validated.ok && !usedIds.has(validated.id)) return validated.id;
+  }
+  throw new Error(`[lessonkit] unable to derive unique id for input: ${input.slice(0, 32)}`);
 }
 function slugifyId(input) {
   const slug = input.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-+/g, "-").slice(0, 64);
@@ -148,6 +116,13 @@ function buildLessonkitUrn(parts) {
     }
     urn += `:block:${blockId}`;
   }
+  if (parts.nodeId !== void 0) {
+    const nodeId = assertValidId(parts.nodeId, "nodeId");
+    if (parts.blockId === void 0) {
+      throw new Error("buildLessonkitUrn: nodeId requires blockId");
+    }
+    urn += `:node:${nodeId}`;
+  }
   return urn;
 }
 
@@ -192,23 +167,31 @@ function isPlainSerializableChildState(value) {
     (entry) => isValidChildResumeValue(entry)
   );
 }
-function parseCompoundResumeState(raw) {
+function parseCompoundResumeState(raw, opts) {
   if (!raw || typeof raw !== "object") return null;
   const obj = raw;
   if (obj.schemaVersion !== COMPOUND_RESUME_SCHEMA_VERSION) return null;
   if (typeof obj.activePageIndex !== "number" || !Number.isFinite(obj.activePageIndex)) return null;
   const childStates = {};
+  const droppedChildKeys = [];
   if (obj.childStates && typeof obj.childStates === "object" && !Array.isArray(obj.childStates)) {
     for (const [key, value] of Object.entries(obj.childStates)) {
       if (isPlainSerializableChildState(value)) {
         childStates[key] = value;
+      } else {
+        droppedChildKeys.push(key);
       }
     }
   }
+  if (droppedChildKeys.length > 0) {
+    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
   };
@@ -219,17 +202,21 @@ var COMPOUND_STATE_PREFIX = "lessonkit:compound:";
 function compoundStateStorageKey(courseId, compoundId) {
   return `${COMPOUND_STATE_PREFIX}${courseId}:${compoundId}`;
 }
-function loadCompoundState(storage, courseId, compoundId) {
+function loadCompoundState(storage, courseId, compoundId, opts) {
   const key = compoundStateStorageKey(courseId, compoundId);
   const raw = storage.getItem(key);
   if (!raw) return null;
   try {
-    const parsed = parseCompoundResumeState(JSON.parse(raw));
-    if (parsed === null && isDevEnvironment()) {
-      console.warn(`[lessonkit] Ignoring corrupt compound resume state at ${key}`);
+    const parsed = parseCompoundResumeState(JSON.parse(raw), opts);
+    if (parsed === null) {
+      opts?.onCorrupt?.();
+      if (isDevEnvironment()) {
+        console.warn(`[lessonkit] Ignoring corrupt compound resume state at ${key}`);
+      }
     }
     return parsed;
   } catch {
+    opts?.onCorrupt?.();
     if (isDevEnvironment()) {
       console.warn(`[lessonkit] Ignoring corrupt compound resume state at ${key}`);
     }
@@ -286,8 +273,110 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "FindHotspot",
   "FindMultipleHotspots",
   "ImageSlider",
+  "Embed",
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar",
   "ProgressTracker"
 ];
+var BRANCH_NODE_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",
+  "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",
@@ -318,7 +407,19 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "ImageHotspots",
   "FindHotspot",
   "FindMultipleHotspots",
-  "ImageSlider"
+  "ImageSlider",
+  "Embed",
+  "Chart",
+  "Table",
+  "ImageJuxtaposition",
+  "Timeline",
+  "ImageSequence",
+  "Collage",
+  "AudioRecorder",
+  "CombinationLock",
+  "QrContent",
+  "Crossword",
+  "AdventCalendar"
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
 var TIMED_CUE_ALLOWED_CHILD_TYPES = [
@@ -360,7 +461,11 @@ var ALLOWLISTS = {
   SlideDeck: SLIDE_DECK_ALLOWED_CHILD_TYPES,
   TimedCue: TIMED_CUE_ALLOWED_CHILD_TYPES,
   InteractiveVideo: INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
-  AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES
+  AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
+  BranchingScenario: BRANCHING_SCENARIO_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,
@@ -369,7 +474,11 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   SlideDeck: 2,
   TimedCue: 1,
   InteractiveVideo: 2,
-  AssessmentSequence: 1
+  AssessmentSequence: 1,
+  BranchingScenario: 2,
+  BranchNode: 1,
+  GameMap: 2,
+  MapStage: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -380,6 +489,82 @@ function isChildTypeAllowed(parent, childType) {
 var ACCORDION_FORBIDDEN_CHILD_TYPES = ["Accordion"];
 var BLOCKS_14_PAGE_SLIDE = PAGE_AND_SLIDE_14_BLOCKS;
 
+// src/branchGraph.ts
+function validateBranchGraph(startNodeId, nodes) {
+  const issues = [];
+  if (nodes.length === 0) {
+    issues.push({ code: "empty_graph", message: "Branch graph has no nodes" });
+    return { ok: false, issues, reachableNodeIds: [] };
+  }
+  const nodeIds = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    if (nodeIds.has(node.nodeId)) {
+      issues.push({
+        code: "duplicate_node_id",
+        message: `Duplicate nodeId "${node.nodeId}"`,
+        nodeId: node.nodeId
+      });
+    }
+    nodeIds.add(node.nodeId);
+  }
+  if (!nodeIds.has(startNodeId)) {
+    issues.push({
+      code: "start_not_found",
+      message: `startNodeId "${startNodeId}" does not match any BranchNode`,
+      nodeId: startNodeId
+    });
+  }
+  if (nodes.length > 1 && nodeIds.has(startNodeId)) {
+    const startNode = nodes.find((n) => n.nodeId === startNodeId);
+    if (startNode && startNode.choices.length === 0) {
+      issues.push({
+        code: "start_no_choices",
+        message: `startNodeId "${startNodeId}" has no BranchChoice children in a multi-node scenario`,
+        nodeId: startNodeId
+      });
+    }
+  }
+  for (const node of nodes) {
+    for (const choice of node.choices) {
+      if (!nodeIds.has(choice.targetNodeId)) {
+        issues.push({
+          code: "unknown_target",
+          message: `Choice from "${node.nodeId}" references unknown target "${choice.targetNodeId}"`,
+          nodeId: node.nodeId
+        });
+      }
+    }
+  }
+  const reachable = /* @__PURE__ */ new Set();
+  if (nodeIds.has(startNodeId)) {
+    const queue = [startNodeId];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (reachable.has(current)) continue;
+      reachable.add(current);
+      const node = nodes.find((n) => n.nodeId === current);
+      if (!node) continue;
+      for (const choice of node.choices) {
+        if (!reachable.has(choice.targetNodeId)) queue.push(choice.targetNodeId);
+      }
+    }
+  }
+  for (const nodeId of nodeIds) {
+    if (!reachable.has(nodeId)) {
+      issues.push({
+        code: "unreachable_node",
+        message: `Node "${nodeId}" is not reachable from startNodeId "${startNodeId}"`,
+        nodeId
+      });
+    }
+  }
+  return {
+    ok: issues.length === 0,
+    issues,
+    reachableNodeIds: [...reachable]
+  };
+}
+
 // src/telemetryCatalog.ts
 var telemetryCatalogVersion = 1;
 var TELEMETRY_EVENT_CATALOG = [
@@ -582,6 +767,94 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     dataFields: ["blockId", "fieldCount"],
     xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
     urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "branch_node_viewed",
+    description: "Learner viewed a node in a BranchingScenario",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "nodeId", "nodeIndex", "nodeTitle"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}:node:{nodeId}"
+  },
+  {
+    name: "branch_selected",
+    description: "Learner selected a branch choice in a BranchingScenario",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    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() {
@@ -613,22 +886,12 @@ function invokeTrackingSink(sink, event) {
     void result.catch((err) => warnDev("[lessonkit] tracking sink failed:", err));
   }
 }
-function invokePipelineSink(sinkId, emit) {
-  let result;
-  try {
-    result = emit();
-  } catch (err) {
-    warnDev(`[lessonkit] telemetry sink "${sinkId}" failed:`, err);
-    return;
-  }
-  if (result != null && typeof result.catch === "function") {
-    void result.catch(
-      (err) => warnDev(`[lessonkit] telemetry sink "${sinkId}" failed:`, err)
-    );
-  }
-}
 
 // src/trackingClient.ts
+function eventDedupKey(event) {
+  const id = event.id?.trim();
+  return id || void 0;
+}
 function createTrackingClient(opts) {
   const sink = opts?.sink;
   const batchSink = opts?.batchSink;
@@ -646,13 +909,14 @@ function createTrackingClient(opts) {
     let disposed2 = false;
     return {
       track: (event) => {
-        if (disposed2) return;
+        if (disposed2) return false;
         if (sink) {
           try {
             invokeTrackingSink(sink, event);
           } catch {
           }
         }
+        return true;
       },
       deliver: async (event) => {
         if (disposed2) return false;
@@ -665,19 +929,32 @@ function createTrackingClient(opts) {
     };
   }
   if (!sink && !batchSink) {
-    return { track: () => {
-    } };
+    return { track: () => true };
   }
   const buffer = [];
+  const pendingDeliverIds = /* @__PURE__ */ new Set();
   let flushInFlight = null;
-  let inflightExitBatch = null;
   let disposed = false;
   let disposing = false;
   let intervalId;
+  const clearPendingDeliverIds = (events) => {
+    for (const event of events) {
+      const key = eventDedupKey(event);
+      if (key) pendingDeliverIds.delete(key);
+    }
+  };
+  const isEventBuffered = (event) => {
+    const key = eventDedupKey(event);
+    if (!key) return false;
+    return buffer.some((buffered) => eventDedupKey(buffered) === key);
+  };
   const runFlush = () => {
     if (!buffer.length) return Promise.resolve(true);
     const events = buffer.splice(0, buffer.length);
-    inflightExitBatch = events;
+    for (const event of events) {
+      const key = eventDedupKey(event);
+      if (key) pendingDeliverIds.add(key);
+    }
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -687,7 +964,7 @@ function createTrackingClient(opts) {
           try {
             await sink?.(events[i]);
           } catch {
-            buffer.unshift(...events.slice(i));
+            buffer.unshift(...events);
             return;
           }
         }
@@ -698,12 +975,13 @@ function createTrackingClient(opts) {
         buffer.unshift(...events);
       }
     }).then(async () => {
+      if (succeeded) {
+        clearPendingDeliverIds(events);
+      }
       if (succeeded && buffer.length > 0 && !disposed) {
         return runFlush();
       }
       return succeeded;
-    }).finally(() => {
-      inflightExitBatch = null;
     });
   };
   const flush = () => {
@@ -724,18 +1002,27 @@ function createTrackingClient(opts) {
       if (!delivered) break;
     }
     if (buffer.length > 0) {
+      const droppedCount = buffer.length;
       if (isDevEnvironment()) {
         console.warn(
-          `[lessonkit] dropped ${buffer.length} buffered telemetry event(s) after dispose flush cap`
+          `[lessonkit] dropped ${droppedCount} buffered telemetry event(s) after dispose flush cap`
         );
       }
+      for (let i = 0; i < droppedCount; i++) {
+        opts?.onBufferDrop?.();
+      }
       buffer.length = 0;
+      pendingDeliverIds.clear();
     }
   };
   intervalId = flushIntervalMs > 0 ? globalThis.setInterval(() => void flush(), flushIntervalMs) : void 0;
   intervalId?.unref?.();
   const track = (event) => {
-    if (disposed || disposing) return;
+    if (disposed || disposing) return false;
+    const key = eventDedupKey(event);
+    if (key && (pendingDeliverIds.has(key) || isEventBuffered(event))) {
+      return true;
+    }
     if (buffer.length >= maxBufferSize) {
       opts?.onBufferDrop?.();
       if (!warnedBufferCap && isDevEnvironment()) {
@@ -744,29 +1031,37 @@ function createTrackingClient(opts) {
           `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; new events are dropped until the buffer drains.`
         );
       }
-      return;
+      return false;
     }
     buffer.push(event);
     if (buffer.length >= maxBatchSize) void flush();
+    return true;
   };
   return {
     track,
     deliver: async (event) => {
-      track(event);
+      const key = eventDedupKey(event);
+      if (key && (pendingDeliverIds.has(key) || isEventBuffered(event))) {
+        return flush();
+      }
+      if (!track(event)) return false;
+      if (key) pendingDeliverIds.add(key);
       return flush();
     },
     flush,
     flushOnExit: opts?.exitBatchSink ? () => {
-      const fromBuffer = buffer.splice(0, buffer.length);
-      const fromInflight = inflightExitBatch ? [...inflightExitBatch] : [];
-      const events = [...fromInflight, ...fromBuffer];
+      const events = buffer.splice(0, buffer.length);
       if (!events.length) return;
       try {
         const result = opts.exitBatchSink(events);
         if (result != null && typeof result.catch === "function") {
-          void result.catch(() => {
+          void result.then(() => {
+            clearPendingDeliverIds(events);
+          }).catch(() => {
             buffer.unshift(...events);
           });
+        } else {
+          clearPendingDeliverIds(events);
         }
       } catch {
         buffer.unshift(...events);
@@ -788,21 +1083,44 @@ function createTrackingClient(opts) {
 }
 
 // src/telemetryPipeline.ts
-function invokeSink(sink, event, emitCtx) {
-  invokePipelineSink(sink.id, () => sink.emit(event, emitCtx));
+var LIFECYCLE_TELEMETRY_EVENTS = /* @__PURE__ */ new Set([
+  "course_started",
+  "course_completed",
+  "lesson_started",
+  "lesson_completed",
+  "lesson_time_on_task"
+]);
+function isLifecycleTelemetryEvent(name) {
+  return LIFECYCLE_TELEMETRY_EVENTS.has(name);
+}
+async function invokeSink(sink, event, emitCtx) {
+  let result;
+  try {
+    result = sink.emit(event, emitCtx);
+  } catch (err) {
+    warnDev(`[lessonkit] telemetry sink "${sink.id}" failed:`, err);
+    return;
+  }
+  if (result != null && typeof result.then === "function") {
+    try {
+      await result;
+    } catch (err) {
+      warnDev(`[lessonkit] telemetry sink "${sink.id}" failed:`, err);
+    }
+  }
 }
 function createTelemetryPipeline(sinks) {
   const list = [...sinks];
   return {
     sinks: list,
-    emit(event, ctx) {
+    async emit(event, ctx) {
       const emitCtx = ctx ?? {
         courseId: event.courseId,
         sessionId: event.sessionId,
         attemptId: event.attemptId
       };
       for (const sink of list) {
-        invokeSink(sink, event, emitCtx);
+        await invokeSink(sink, event, emitCtx);
       }
     }
   };
@@ -841,6 +1159,11 @@ function createProgressController() {
         }
         return { didComplete: false };
       }
+      if (!lessonStartTimes.has(lessonId) && isDevEnvironment()) {
+        console.warn(
+          `[lessonkit] completeLesson("${lessonId}") called without activating the lesson first`
+        );
+      }
       completedLessonIds = new Set(completedLessonIds).add(lessonId);
       if (activeLessonId === lessonId) {
         activeLessonId = void 0;
@@ -874,6 +1197,20 @@ function warnDuplicatePlugin(id) {
   if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
   console.warn(`[lessonkit] plugin id "${id}" was registered more than once; using the latest definition`);
 }
+function stableUserHash(user) {
+  if (!user) return "";
+  const keys = Object.keys(user).sort();
+  const normalized = {};
+  for (const key of keys) {
+    normalized[key] = user[key];
+  }
+  let h = 0;
+  const serialized = JSON.stringify(normalized);
+  for (let i = 0; i < serialized.length; i++) {
+    h = Math.imul(31, h) + serialized.charCodeAt(i) >>> 0;
+  }
+  return h.toString(36);
+}
 function createPluginRegistry(plugins = []) {
   const registry = /* @__PURE__ */ new Map();
   for (const plugin of plugins) {
@@ -915,7 +1252,7 @@ function createPluginRegistry(plugins = []) {
   const composeTrackingSink = (sink, ctxSource) => {
     if (!sink) return void 0;
     const resolveCtx = () => typeof ctxSource === "function" ? ctxSource() : ctxSource;
-    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}\0${ctx.user?.id ?? ""}`;
+    const ctxKey = (ctx) => `${ctx.courseId}\0${ctx.sessionId ?? ""}\0${ctx.attemptId ?? ""}\0${stableUserHash(ctx.user)}`;
     const layers = [];
     let composed = sink;
     for (const plugin of list) {
@@ -962,6 +1299,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;
@@ -974,12 +1315,20 @@ 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,
     sessionId,
@@ -990,12 +1339,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());
@@ -1013,28 +1356,23 @@ function createLessonkitRuntime(config, ports = {}) {
     if (!event) return null;
     return applyPluginsToEvent(event);
   };
-  const wrapEmitFn = (emitFn) => {
-    return (name, data, lessonId) => {
-      const event = buildAndApply(name, data, lessonId);
-      if (event === null) return;
-      const eventLessonId = "lessonId" in event ? event.lessonId : lessonId;
-      const eventData = "data" in event ? event.data : data;
-      emitFn(event.name, eventData, eventLessonId);
-    };
+  const emitLifecycleEvent = (emitFn, name, data, lessonId) => {
+    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);
     if (!event) return;
     emit(event);
   };
   const emitLessonCompletedEvents = (lessonId, durationMs, emitFn) => {
-    const wrapped = wrapEmitFn(emitFn);
-    wrapped("lesson_completed", { lessonId, durationMs }, lessonId);
+    emitLifecycleEvent(emitFn, "lesson_completed", { lessonId, durationMs }, lessonId);
     if (durationMs !== void 0) {
-      wrapped("lesson_time_on_task", { lessonId, durationMs }, lessonId);
+      emitLifecycleEvent(emitFn, "lesson_time_on_task", { lessonId, durationMs }, lessonId);
     }
   };
+  const autoCompleteOnLessonSwitch = () => configSnapshot.autoCompleteOnLessonSwitch ?? true;
   return {
     get config() {
       return configSnapshot;
@@ -1047,7 +1385,12 @@ function createLessonkitRuntime(config, ports = {}) {
     },
     getProgressState: () => progress.getState(),
     getSession,
+    migrateSessionMarks(fromSessionId, toSessionId) {
+      if (disposed) return;
+      migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId);
+    },
     updateConfig(next) {
+      if (disposed) return;
       const previousCourseId = courseId;
       const sessionKeyBefore = JSON.stringify({ sessionId, attemptId, user });
       if (next.courseId !== void 0) configSnapshot.courseId = next.courseId;
@@ -1055,35 +1398,69 @@ function createLessonkitRuntime(config, ports = {}) {
         if (next.runtimeVersion === "v1") warnRuntimeV1Deprecated();
         configSnapshot.runtimeVersion = next.runtimeVersion;
       }
+      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());
       }
     },
     setActiveLesson(lessonId, emitFn) {
-      const wrapped = wrapEmitFn(emitFn);
+      if (disposed) return;
       const current = progress.getState();
       if (current.activeLessonId === lessonId) return;
       const previous = current.activeLessonId;
-      if (previous && previous !== lessonId && !current.completedLessonIds.has(previous)) {
+      if (autoCompleteOnLessonSwitch() && previous && previous !== lessonId && !current.completedLessonIds.has(previous)) {
         const completed = progress.completeLesson(previous, clock.nowMs());
         if (completed.didComplete) {
-          emitLessonCompletedEvents(previous, completed.durationMs, wrapped);
+          emitLessonCompletedEvents(previous, completed.durationMs, emitFn);
         }
       }
       if (current.completedLessonIds.has(lessonId)) {
@@ -1091,39 +1468,50 @@ function createLessonkitRuntime(config, ports = {}) {
         return;
       }
       progress.setActiveLesson(lessonId, clock.nowMs());
-      wrapped("lesson_started", { lessonId }, lessonId);
+      emitLifecycleEvent(emitFn, "lesson_started", { lessonId }, lessonId);
     },
     completeLesson(lessonId, emitFn) {
+      if (disposed) return;
       completeLessonWithTelemetry({
         progress,
         lessonId,
         nowMs: clock.nowMs(),
-        emitLessonCompleted: (id, durationMs) => emitLessonCompletedEvents(id, durationMs, wrapEmitFn(emitFn))
+        emitLessonCompleted: (id, durationMs) => emitLessonCompletedEvents(id, durationMs, emitFn)
       });
     },
     completeCourse(emitFn) {
+      if (disposed) return;
       completeCourseWithTelemetry({
         progress,
         nowMs: clock.nowMs(),
-        emitLessonCompleted: (id, durationMs) => emitLessonCompletedEvents(id, durationMs, wrapEmitFn(emitFn)),
-        emitCourseCompleted: () => wrapEmitFn(emitFn)("course_completed")
+        emitLessonCompleted: (id, durationMs) => emitLessonCompletedEvents(id, durationMs, emitFn),
+        emitCourseCompleted: () => emitLifecycleEvent(emitFn, "course_completed")
       });
     },
     track,
     scoreAssessment(input, lessonId) {
-      if (!pluginHost) return null;
+      if (disposed || !pluginHost) return null;
       return pluginHost.scoreAssessment(
         { ...input, lessonId: input.lessonId ?? lessonId },
         getPluginCtx()
       );
     },
     resetForCourseChange(nextCourseId) {
+      if (disposed) return;
       configSnapshot.courseId = nextCourseId;
       courseId = nextCourseId;
       progress = createProgressController();
+      if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.disposeAll();
+        pluginHost?.setupAll(getPluginCtx());
+      }
     },
     dispose() {
-      pluginHost?.disposeAll();
+      if (disposed) return;
+      disposed = true;
+      if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.disposeAll();
+      }
     }
   };
 }
@@ -1142,12 +1530,16 @@ export {
   ACCORDION_FORBIDDEN_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,
   SLIDE_ALLOWED_CHILD_TYPES,
@@ -1191,11 +1583,14 @@ export {
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
   isChildTypeAllowed,
+  isLifecycleTelemetryEvent,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered,
+  markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
   parseBlockId,
@@ -1214,5 +1609,6 @@ export {
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,
+  validateBranchGraph,
   validateId
 };