@lessonkit/core 1.3.1 → 1.5.0

package/dist/index.js

@@ -1,64 +1,48 @@
-// src/identityTypes.ts
-var ID_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
-var ID_MAX_LENGTH = 64;
+import {
+  ID_MAX_LENGTH,
+  ID_PATTERN,
+  SESSION_STORAGE_KEY,
+  assertValidId,
+  buildCourseStartedTelemetryEvent,
+  buildTelemetryEvent,
+  completeCourseWithTelemetry,
+  completeLessonWithTelemetry,
+  createDefaultClock,
+  createGlobalTimer,
+  createNoopStorage,
+  createSessionId,
+  createSessionStoragePort,
+  getTabSessionId,
+  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-KFXFQ6B2.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;
@@ -71,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);
@@ -118,6 +116,13 @@ function buildLessonkitUrn(parts) {
     }
     urn += `:block:${blockId}`;
   }
+  if (parts.nodeId !== void 0) {
+    const nodeId = assertValidId(parts.nodeId, "blockId");
+    if (parts.blockId === void 0) {
+      throw new Error("buildLessonkitUrn: nodeId requires blockId");
+    }
+    urn += `:node:${nodeId}`;
+  }
   return urn;
 }
 
@@ -162,19 +167,25 @@ 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;
   return {
     schemaVersion: COMPOUND_RESUME_SCHEMA_VERSION,
@@ -184,32 +195,26 @@ function parseCompoundResumeState(raw) {
   };
 }
 
-// src/internal/env.ts
-function isDevEnvironment() {
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
-}
-function warnDev(message, err) {
-  if (!isDevEnvironment()) return;
-  console.warn(message, err instanceof Error ? err.message : err);
-}
-
 // src/compoundState.ts
 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}`);
     }
@@ -224,10 +229,23 @@ function clearCompoundState(storage, courseId, compoundId) {
 }
 
 // src/compoundAllowlists.ts
+var PAGE_AND_SLIDE_14_BLOCKS = [
+  "Video",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz"
+];
 var PAGE_ALLOWED_CHILD_TYPES = [
   "Text",
   "Heading",
   "Image",
+  "Video",
   "Scenario",
   "Reflection",
   "Quiz",
@@ -237,6 +255,15 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "DragAndDrop",
   "DragTheWords",
   "MarkTheWords",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz",
   "Accordion",
   "DialogCards",
   "Flashcards",
@@ -244,13 +271,51 @@ var PAGE_ALLOWED_CHILD_TYPES = [
   "FindHotspot",
   "FindMultipleHotspots",
   "ImageSlider",
+  "Embed",
+  "Chart",
   "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",
+  "BranchChoice"
+];
+var BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES = ["BranchNode"];
 var INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES = ["Page"];
 var SLIDE_ALLOWED_CHILD_TYPES = [
   "Text",
   "Heading",
   "Image",
+  "Video",
   "Scenario",
   "Reflection",
   "Quiz",
@@ -260,15 +325,42 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "DragAndDrop",
   "DragTheWords",
   "MarkTheWords",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "InformationWall",
+  "ParallaxSlideshow",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz",
   "Accordion",
   "DialogCards",
   "Flashcards",
   "ImageHotspots",
   "FindHotspot",
   "FindMultipleHotspots",
-  "ImageSlider"
+  "ImageSlider",
+  "Embed",
+  "Chart"
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
+var TIMED_CUE_ALLOWED_CHILD_TYPES = [
+  "Text",
+  "Heading",
+  "Image",
+  "Quiz",
+  "TrueFalse",
+  "FillInTheBlanks",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "MemoryGame",
+  "Questionnaire",
+  "Essay",
+  "ArithmeticQuiz"
+];
+var INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES = ["TimedCue"];
 var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
   "TrueFalse",
   "FillInTheBlanks",
@@ -278,21 +370,34 @@ var ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES = [
   "Quiz",
   "KnowledgeCheck",
   "FindHotspot",
-  "FindMultipleHotspots"
+  "FindMultipleHotspots",
+  "Summary",
+  "ImagePairing",
+  "ImageSequencing",
+  "ArithmeticQuiz",
+  "Essay"
 ];
 var ALLOWLISTS = {
   Page: PAGE_ALLOWED_CHILD_TYPES,
   InteractiveBook: INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
   Slide: SLIDE_ALLOWED_CHILD_TYPES,
   SlideDeck: SLIDE_DECK_ALLOWED_CHILD_TYPES,
-  AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES
+  TimedCue: TIMED_CUE_ALLOWED_CHILD_TYPES,
+  InteractiveVideo: INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
+  AssessmentSequence: ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
+  BranchingScenario: BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
+  BranchNode: BRANCH_NODE_ALLOWED_CHILD_TYPES
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
   Page: 1,
   InteractiveBook: 2,
   Slide: 1,
   SlideDeck: 2,
-  AssessmentSequence: 1
+  TimedCue: 1,
+  InteractiveVideo: 2,
+  AssessmentSequence: 1,
+  BranchingScenario: 2,
+  BranchNode: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -301,6 +406,83 @@ function isChildTypeAllowed(parent, childType) {
   return ALLOWLISTS[parent].includes(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;
@@ -456,6 +638,70 @@ var TELEMETRY_EVENT_CATALOG_V3 = [
     dataFields: ["blockId", "slideIndex"],
     xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
     urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "video_cue_reached",
+    description: "Learner reached a timed cue in an Interactive Video",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "cueIndex", "atSeconds", "cueLabel"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "video_segment_completed",
+    description: "Learner completed a timed segment in an Interactive Video",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "segmentIndex", "atSeconds", "segmentLabel"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/completed",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "memory_card_flipped",
+    description: "Learner flipped a memory game card",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "cardIndex", "face"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "information_wall_search",
+    description: "Learner searched an information wall",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "query", "resultCount"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "parallax_slide_viewed",
+    description: "Learner viewed a slide in a parallax slideshow",
+    requiredFields: ["courseId", "sessionId", "timestamp"],
+    dataFields: ["blockId", "slideIndex"],
+    xapiVerb: "http://adlnet.gov/expapi/verbs/experienced",
+    urnPattern: "urn:lessonkit:course:{courseId}:lesson:{lessonId}:block:{blockId}"
+  },
+  {
+    name: "questionnaire_submitted",
+    description: "Learner submitted an unscored questionnaire",
+    requiredFields: ["courseId", "lessonId", "sessionId", "timestamp"],
+    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}"
   }
 ];
 function buildTelemetryCatalogV3() {
@@ -463,34 +709,36 @@ function buildTelemetryCatalogV3() {
 }
 
 // src/internal/sinkInvoke.ts
-function invokeTrackingSink(sink, event) {
-  let result;
+async function invokeTrackingSinkWithResult(sink, event) {
   try {
-    result = sink(event);
+    const result = sink(event);
+    if (result != null && typeof result.then === "function") {
+      await result;
+    }
+    return true;
   } catch (err) {
     warnDev("[lessonkit] tracking sink failed:", err);
-    throw err;
-  }
-  if (result != null && typeof result.catch === "function") {
-    void result.catch((err) => warnDev("[lessonkit] tracking sink failed:", err));
+    return false;
   }
 }
-function invokePipelineSink(sinkId, emit) {
+function invokeTrackingSink(sink, event) {
   let result;
   try {
-    result = emit();
+    result = sink(event);
   } catch (err) {
-    warnDev(`[lessonkit] telemetry sink "${sinkId}" failed:`, err);
-    return;
+    warnDev("[lessonkit] tracking sink failed:", err);
+    throw err;
   }
   if (result != null && typeof result.catch === "function") {
-    void result.catch(
-      (err) => warnDev(`[lessonkit] telemetry sink "${sinkId}" failed:`, err)
-    );
+    void result.catch((err) => warnDev("[lessonkit] tracking sink 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;
@@ -508,8 +756,19 @@ function createTrackingClient(opts) {
     let disposed2 = false;
     return {
       track: (event) => {
-        if (disposed2) return;
-        if (sink) invokeTrackingSink(sink, event);
+        if (disposed2) return false;
+        if (sink) {
+          try {
+            invokeTrackingSink(sink, event);
+          } catch {
+          }
+        }
+        return true;
+      },
+      deliver: async (event) => {
+        if (disposed2) return false;
+        if (!sink) return true;
+        return invokeTrackingSinkWithResult(sink, event);
       },
       dispose: () => {
         disposed2 = true;
@@ -517,19 +776,28 @@ 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;
     let succeeded = false;
     return Promise.resolve().then(async () => {
       if (batchSink) {
@@ -550,12 +818,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 = () => {
@@ -576,44 +845,66 @@ 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 false;
+    const key = eventDedupKey(event);
+    if (key && (pendingDeliverIds.has(key) || isEventBuffered(event))) {
+      return true;
+    }
+    if (buffer.length >= maxBufferSize) {
+      opts?.onBufferDrop?.();
+      if (!warnedBufferCap && isDevEnvironment()) {
+        warnedBufferCap = true;
+        console.warn(
+          `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; new events are dropped until the buffer drains.`
+        );
+      }
+      return false;
+    }
+    buffer.push(event);
+    if (buffer.length >= maxBatchSize) void flush();
+    return true;
+  };
   return {
-    track: (event) => {
-      if (disposed || disposing) return;
-      if (buffer.length >= maxBufferSize) {
-        opts?.onBufferDrop?.();
-        if (!warnedBufferCap && isDevEnvironment()) {
-          warnedBufferCap = true;
-          console.warn(
-            `[lessonkit] telemetry batch buffer capped at ${maxBufferSize} events; new events are dropped until the buffer drains.`
-          );
-        }
-        return;
+    track,
+    deliver: async (event) => {
+      const key = eventDedupKey(event);
+      if (key && (pendingDeliverIds.has(key) || isEventBuffered(event))) {
+        return flush();
       }
-      buffer.push(event);
-      if (buffer.length >= maxBatchSize) void 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);
@@ -634,282 +925,45 @@ function createTrackingClient(opts) {
   };
 }
 
-// src/ids.ts
-function createSessionId() {
-  const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
-  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
-}
-
-// src/time.ts
-function nowIso() {
-  return (/* @__PURE__ */ new Date()).toISOString();
-}
-
-// src/telemetry/eventRegistry.ts
-function resolveLessonId(opts, eventName) {
-  const lessonId = opts.lessonId ?? opts.data?.lessonId;
-  if (!lessonId) throw new Error(`${eventName} requires lessonId`);
-  return lessonId;
-}
-function withLessonScopedData(name, base, lessonId, data) {
-  return { name, ...base, lessonId, data: { ...data, lessonId } };
-}
-var TELEMETRY_EVENT_REGISTRY = {
-  course_started: {
-    build: (_opts, base) => ({ name: "course_started", ...base })
-  },
-  course_completed: {
-    build: (_opts, base) => ({ name: "course_completed", ...base })
-  },
-  lesson_started: {
-    requiresLessonId: true,
-    build: (opts, base) => {
-      if (opts.name !== "lesson_started") throw new Error("unexpected event");
-      const lessonId = resolveLessonId(opts, "lesson_started");
-      return withLessonScopedData("lesson_started", base, lessonId, opts.data);
-    }
-  },
-  lesson_completed: {
-    requiresLessonId: true,
-    build: (opts, base) => {
-      if (opts.name !== "lesson_completed") throw new Error("unexpected event");
-      const lessonId = resolveLessonId(opts, opts.name);
-      return withLessonScopedData(opts.name, base, lessonId, opts.data);
-    }
-  },
-  lesson_time_on_task: {
-    requiresLessonId: true,
-    build: (opts, base) => {
-      if (opts.name !== "lesson_time_on_task") throw new Error("unexpected event");
-      const lessonId = resolveLessonId(opts, opts.name);
-      return withLessonScopedData(opts.name, base, lessonId, opts.data);
-    }
-  },
-  quiz_answered: {
-    requiresLessonId: true,
-    tryBuildMissingLessonWarning: "quiz",
-    build: (opts, base) => {
-      if (opts.name !== "quiz_answered") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
-      return {
-        name: "quiz_answered",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  quiz_completed: {
-    requiresLessonId: true,
-    tryBuildMissingLessonWarning: "quiz",
-    build: (opts, base) => {
-      if (opts.name !== "quiz_completed") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
-      return {
-        name: "quiz_completed",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  assessment_answered: {
-    requiresLessonId: true,
-    tryBuildMissingLessonWarning: "assessment",
-    build: (opts, base) => {
-      if (opts.name !== "assessment_answered") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("assessment_answered requires active lessonId");
-      return {
-        name: "assessment_answered",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  assessment_completed: {
-    requiresLessonId: true,
-    tryBuildMissingLessonWarning: "assessment",
-    build: (opts, base) => {
-      if (opts.name !== "assessment_completed") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("assessment_completed requires active lessonId");
-      return {
-        name: "assessment_completed",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  interaction: {
-    build: (opts, base) => {
-      if (opts.name !== "interaction") throw new Error("unexpected event");
-      return {
-        name: "interaction",
-        ...base,
-        lessonId: opts.lessonId,
-        data: opts.data
-      };
-    }
-  },
-  book_page_viewed: {
-    requiresLessonId: true,
-    build: (opts, base) => {
-      if (opts.name !== "book_page_viewed") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("book_page_viewed requires active lessonId");
-      return {
-        name: "book_page_viewed",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  slide_viewed: {
-    requiresLessonId: true,
-    build: (opts, base) => {
-      if (opts.name !== "slide_viewed") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("slide_viewed requires active lessonId");
-      return {
-        name: "slide_viewed",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  compound_page_viewed: {
-    requiresLessonId: true,
-    build: (opts, base) => {
-      if (opts.name !== "compound_page_viewed") throw new Error("unexpected event");
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("compound_page_viewed requires active lessonId");
-      return {
-        name: "compound_page_viewed",
-        ...base,
-        lessonId,
-        data: opts.data
-      };
-    }
-  },
-  hotspot_opened: {
-    build: (opts, base) => {
-      if (opts.name !== "hotspot_opened") throw new Error("unexpected event");
-      return {
-        name: "hotspot_opened",
-        ...base,
-        lessonId: opts.lessonId,
-        data: opts.data
-      };
-    }
-  },
-  accordion_section_toggled: {
-    build: (opts, base) => {
-      if (opts.name !== "accordion_section_toggled") throw new Error("unexpected event");
-      return {
-        name: "accordion_section_toggled",
-        ...base,
-        lessonId: opts.lessonId,
-        data: opts.data
-      };
-    }
-  },
-  flashcard_flipped: {
-    build: (opts, base) => {
-      if (opts.name !== "flashcard_flipped") throw new Error("unexpected event");
-      return {
-        name: "flashcard_flipped",
-        ...base,
-        lessonId: opts.lessonId,
-        data: opts.data
-      };
-    }
-  },
-  image_slider_changed: {
-    build: (opts, base) => {
-      if (opts.name !== "image_slider_changed") throw new Error("unexpected event");
-      return {
-        name: "image_slider_changed",
-        ...base,
-        lessonId: opts.lessonId,
-        data: opts.data
-      };
-    }
-  }
-};
-function buildTelemetryEventFromRegistry(opts) {
-  const entry = TELEMETRY_EVENT_REGISTRY[opts.name];
-  if (!entry) {
-    throw new Error("Unexpected value");
+// src/telemetryPipeline.ts
+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;
   }
-  const base = {
-    timestamp: opts.timestamp ?? nowIso(),
-    courseId: opts.courseId,
-    sessionId: opts.sessionId,
-    attemptId: opts.attemptId,
-    user: opts.user
-  };
-  return entry.build(opts, base);
-}
-function getTelemetryEventRegistryEntry(name) {
-  return TELEMETRY_EVENT_REGISTRY[name];
-}
-
-// src/telemetryBuilder.ts
-var warnedMissingQuizLesson = false;
-var warnedMissingAssessmentLesson = false;
-function resetTelemetryBuilderWarningsForTests() {
-  warnedMissingQuizLesson = false;
-  warnedMissingAssessmentLesson = false;
-}
-function buildTelemetryEvent(opts) {
-  return buildTelemetryEventFromRegistry(opts);
-}
-function tryBuildTelemetryEvent(opts) {
-  const entry = getTelemetryEventRegistryEntry(opts.name);
-  if (entry.requiresLessonId && !opts.lessonId && entry.tryBuildMissingLessonWarning) {
-    if (isDevEnvironment()) {
-      if (entry.tryBuildMissingLessonWarning === "quiz" && !warnedMissingQuizLesson) {
-        warnedMissingQuizLesson = true;
-        console.warn(
-          `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
-        );
-      }
-      if (entry.tryBuildMissingLessonWarning === "assessment" && !warnedMissingAssessmentLesson) {
-        warnedMissingAssessmentLesson = true;
-        console.warn(
-          `[lessonkit] ${opts.name} skipped: wrap assessment blocks in <Lesson> so an active lessonId is available`
-        );
-      }
+  if (result != null && typeof result.then === "function") {
+    try {
+      await result;
+    } catch (err) {
+      warnDev(`[lessonkit] telemetry sink "${sink.id}" failed:`, err);
     }
-    return null;
   }
-  return buildTelemetryEvent(opts);
-}
-
-// src/telemetryPipeline.ts
-function invokeSink(sink, event, emitCtx) {
-  invokePipelineSink(sink.id, () => sink.emit(event, emitCtx));
 }
 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);
       }
     }
   };
@@ -923,109 +977,6 @@ function createTrackingPipelineSink(id, track) {
   };
 }
 
-// src/ports.ts
-function createDefaultClock() {
-  return {
-    nowMs: () => Date.now(),
-    nowIso: () => (/* @__PURE__ */ new Date()).toISOString()
-  };
-}
-function createNoopStorage() {
-  return {
-    getItem: () => null,
-    setItem: () => true
-  };
-}
-function createMemoryBackedSessionStorage(session) {
-  const memory = /* @__PURE__ */ new Map();
-  let warnedPersistFailure = false;
-  const warnPersistFailure = () => {
-    if (warnedPersistFailure) return;
-    warnedPersistFailure = true;
-    const g = globalThis;
-    if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "development") {
-      console.warn(
-        "[lessonkit] sessionStorage is unavailable or failed; using in-memory session dedupe for this tab (may reset on full reload)."
-      );
-    }
-  };
-  return {
-    getItem: (key) => {
-      if (memory.has(key)) return memory.get(key);
-      try {
-        const value = session.getItem(key);
-        if (value !== null) memory.set(key, value);
-        return value;
-      } catch {
-        return memory.get(key) ?? null;
-      }
-    },
-    setItem: (key, value) => {
-      memory.set(key, value);
-      try {
-        session.setItem(key, value);
-        return true;
-      } catch {
-        warnPersistFailure();
-        return false;
-      }
-    },
-    removeItem: (key) => {
-      memory.delete(key);
-      try {
-        session.removeItem(key);
-      } catch {
-        warnPersistFailure();
-      }
-    },
-    resetForTests: () => {
-      memory.clear();
-    }
-  };
-}
-function resetStoragePortForTests(storage) {
-  storage.resetForTests?.();
-}
-function createInMemorySessionStoragePort() {
-  const memory = /* @__PURE__ */ new Map();
-  return {
-    getItem: (key) => memory.get(key) ?? null,
-    setItem: (key, value) => {
-      memory.set(key, value);
-      return true;
-    },
-    removeItem: (key) => {
-      memory.delete(key);
-    },
-    resetForTests: () => {
-      memory.clear();
-    }
-  };
-}
-function resolveBrowserSessionStorage() {
-  try {
-    if (typeof sessionStorage === "undefined" || sessionStorage == null) {
-      return null;
-    }
-    return sessionStorage;
-  } catch {
-    return null;
-  }
-}
-function createSessionStoragePort() {
-  const session = resolveBrowserSessionStorage();
-  if (!session) {
-    return createInMemorySessionStoragePort();
-  }
-  return createMemoryBackedSessionStorage(session);
-}
-function createGlobalTimer() {
-  return {
-    setInterval: (fn, ms) => globalThis.setInterval(fn, ms),
-    clearInterval: (id) => globalThis.clearInterval(id)
-  };
-}
-
 // src/progress.ts
 function createProgressController() {
   let activeLessonId;
@@ -1051,6 +1002,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;
@@ -1068,153 +1024,6 @@ function createProgressController() {
   };
 }
 
-// src/session.ts
-var SESSION_STORAGE_KEY = "lessonkit:sessionId";
-var volatileSessionIds = /* @__PURE__ */ new WeakMap();
-var sharedVolatileSessionId = null;
-function isDevEnvironment2() {
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
-}
-function getTabSessionId(storage) {
-  return storage.getItem(SESSION_STORAGE_KEY);
-}
-var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
-var COURSE_STARTED_TRACKING_PREFIX = "lessonkit:course_started_tracking:";
-var COURSE_STARTED_PIPELINE_PREFIX = "lessonkit:course_started_pipeline:";
-function resolveSessionId(storage, provided) {
-  if (provided !== void 0) {
-    const trimmed = provided.trim();
-    if (trimmed.length > 0) return trimmed;
-  }
-  const existing = storage.getItem(SESSION_STORAGE_KEY);
-  if (existing) return existing;
-  const volatile = volatileSessionIds.get(storage);
-  if (volatile) return volatile;
-  const id = createSessionId();
-  const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
-  if (!persisted) {
-    if (!sharedVolatileSessionId) {
-      sharedVolatileSessionId = id;
-    }
-    volatileSessionIds.set(storage, sharedVolatileSessionId);
-    if (isDevEnvironment2()) {
-      console.warn(
-        "[lessonkit] session id could not be persisted; reusing in-memory id for this tab."
-      );
-    }
-    return sharedVolatileSessionId;
-  }
-  return id;
-}
-function courseStartedStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
-}
-function courseStartedTrackingStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionId}:${courseId ?? ""}`;
-}
-function courseStartedPipelineStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionId}:${courseId ?? ""}`;
-}
-function hasCourseStarted(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
-}
-function markCourseStarted(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
-}
-function hasCourseStartedEmittedToTracking(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.getItem(courseStartedTrackingStorageKey(sessionId, courseId)) === "1";
-}
-function markCourseStartedEmittedToTracking(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.setItem(courseStartedTrackingStorageKey(sessionId, courseId), "1");
-}
-function hasCourseStartedPipelineDelivered(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.getItem(courseStartedPipelineStorageKey(sessionId, courseId)) === "1";
-}
-function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
-}
-function resetSharedVolatileSessionIdForTests() {
-  sharedVolatileSessionId = null;
-}
-function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
-  if (!courseId || fromSessionId === toSessionId) return;
-  if (hasCourseStarted(storage, fromSessionId, courseId)) {
-    markCourseStarted(storage, toSessionId, courseId);
-    storage.removeItem?.(courseStartedStorageKey(fromSessionId, courseId));
-  }
-  if (hasCourseStartedEmittedToTracking(storage, fromSessionId, courseId)) {
-    markCourseStartedEmittedToTracking(storage, toSessionId, courseId);
-    storage.removeItem?.(courseStartedTrackingStorageKey(fromSessionId, courseId));
-  }
-  if (hasCourseStartedPipelineDelivered(storage, fromSessionId, courseId)) {
-    markCourseStartedPipelineDelivered(storage, toSessionId, courseId);
-    storage.removeItem?.(courseStartedPipelineStorageKey(fromSessionId, courseId));
-  }
-}
-
-// src/runtime/courseLifecycle.ts
-var courseStartedEmitFlights = /* @__PURE__ */ new Set();
-function tryEmitCourseStarted(ctx, deps, alreadyEmittedToSink) {
-  const flightKey = `${ctx.sessionId}:${ctx.courseId}`;
-  const marked = hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
-  if (alreadyEmittedToSink) {
-    return { emitted: true, marked };
-  }
-  if (courseStartedEmitFlights.has(flightKey)) {
-    return { emitted: false, marked };
-  }
-  courseStartedEmitFlights.add(flightKey);
-  try {
-    const emitted = deps.emitCourseStartedEvent(ctx);
-    if (emitted && !marked) {
-      markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
-    }
-    return {
-      emitted,
-      marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
-    };
-  } finally {
-    courseStartedEmitFlights.delete(flightKey);
-  }
-}
-function buildCourseStartedTelemetryEvent(ctx) {
-  return buildTelemetryEvent({
-    name: "course_started",
-    courseId: ctx.courseId,
-    sessionId: ctx.sessionId,
-    attemptId: ctx.attemptId,
-    user: ctx.user
-  });
-}
-function completeLessonWithTelemetry(opts) {
-  const result = opts.progress.completeLesson(opts.lessonId, opts.nowMs);
-  if (!result.didComplete) return false;
-  opts.emitLessonCompleted(opts.lessonId, result.durationMs);
-  return true;
-}
-function completeCourseWithTelemetry(opts) {
-  const current = opts.progress.getState();
-  if (current.activeLessonId) {
-    completeLessonWithTelemetry({
-      progress: opts.progress,
-      lessonId: current.activeLessonId,
-      nowMs: opts.nowMs,
-      emitLessonCompleted: opts.emitLessonCompleted
-    });
-  }
-  const result = opts.progress.completeCourse();
-  if (!result.didComplete) return false;
-  opts.emitCourseCompleted();
-  return true;
-}
-
 // src/plugins/context.ts
 function buildPluginContext(opts) {
   return {
@@ -1231,6 +1040,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) {
@@ -1272,7 +1095,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) {
@@ -1337,6 +1160,7 @@ function createLessonkitRuntime(config, ports = {}) {
   let courseId = configSnapshot.courseId;
   let progress = createProgressController();
   let pluginHost = resolvePluginHost(configSnapshot.plugins);
+  let disposed = false;
   const getPluginCtx = () => buildPluginContext({
     courseId,
     sessionId,
@@ -1370,28 +1194,24 @@ 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;
@@ -1404,7 +1224,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;
@@ -1412,6 +1237,9 @@ function createLessonkitRuntime(config, ports = {}) {
         if (next.runtimeVersion === "v1") warnRuntimeV1Deprecated();
         configSnapshot.runtimeVersion = next.runtimeVersion;
       }
+      if (next.autoCompleteOnLessonSwitch !== void 0) {
+        configSnapshot.autoCompleteOnLessonSwitch = next.autoCompleteOnLessonSwitch;
+      }
       if (next.session !== void 0) {
         configSnapshot.session = { ...configSnapshot.session, ...next.session };
       }
@@ -1420,61 +1248,75 @@ function createLessonkitRuntime(config, ports = {}) {
       if (next.courseId !== void 0 && next.courseId !== previousCourseId) {
         progress = createProgressController();
       }
-      if (next.plugins !== void 0 && next.plugins !== pluginHost) {
+      if (next.plugins !== void 0 && next.plugins !== configSnapshot.plugins) {
         pluginHost?.disposeAll();
         configSnapshot.plugins = next.plugins;
         pluginHost = resolvePluginHost(configSnapshot.plugins);
-        pluginHost?.setupAll(getPluginCtx());
+        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;
-      if (current.completedLessonIds.has(lessonId)) {
-        progress.setActiveLesson(lessonId, clock.nowMs());
-        return;
-      }
       const previous = current.activeLessonId;
-      if (previous && previous !== lessonId) {
+      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)) {
+        progress.setActiveLesson(lessonId, clock.nowMs());
+        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;
-      return pluginHost.scoreAssessment(input, getPluginCtx());
+    scoreAssessment(input, lessonId) {
+      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();
+      pluginHost?.disposeAll();
+      if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.setupAll(getPluginCtx());
+      }
     },
     dispose() {
+      if (disposed) return;
+      disposed = true;
       pluginHost?.disposeAll();
     }
   };
@@ -1493,11 +1335,15 @@ function defineLifecyclePlugin(plugin) {
 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,
   ID_MAX_LENGTH,
   ID_PATTERN,
   INTERACTIVE_BOOK_ALLOWED_CHILD_TYPES,
+  INTERACTIVE_VIDEO_ALLOWED_CHILD_TYPES,
   PAGE_ALLOWED_CHILD_TYPES,
   SESSION_STORAGE_KEY,
   SLIDE_ALLOWED_CHILD_TYPES,
@@ -1505,6 +1351,7 @@ export {
   TELEMETRY_EVENT_CATALOG,
   TELEMETRY_EVENT_CATALOG_V2,
   TELEMETRY_EVENT_CATALOG_V3,
+  TIMED_CUE_ALLOWED_CHILD_TYPES,
   assertNever,
   assertValidId,
   buildCourseStartedTelemetryEvent,
@@ -1540,11 +1387,14 @@ export {
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
   isChildTypeAllowed,
+  isLifecycleTelemetryEvent,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered,
+  markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
   parseBlockId,
@@ -1563,5 +1413,6 @@ export {
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,
+  validateBranchGraph,
   validateId
 };