@lessonkit/core 1.4.0 → 1.5.0

package/dist/index.cjs

@@ -23,6 +23,8 @@ __export(index_exports, {
   ACCORDION_FORBIDDEN_CHILD_TYPES: () => ACCORDION_FORBIDDEN_CHILD_TYPES,
   ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES: () => ASSESSMENT_SEQUENCE_ALLOWED_CHILD_TYPES,
   BLOCKS_14_PAGE_SLIDE: () => BLOCKS_14_PAGE_SLIDE,
+  BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES: () => BRANCHING_SCENARIO_ALLOWED_CHILD_TYPES,
+  BRANCH_NODE_ALLOWED_CHILD_TYPES: () => BRANCH_NODE_ALLOWED_CHILD_TYPES,
   COMPOUND_MAX_NESTING_DEPTH: () => COMPOUND_MAX_NESTING_DEPTH,
   COMPOUND_RESUME_SCHEMA_VERSION: () => COMPOUND_RESUME_SCHEMA_VERSION,
   ID_MAX_LENGTH: () => ID_MAX_LENGTH,
@@ -72,11 +74,14 @@ __export(index_exports, {
   hasCourseStarted: () => hasCourseStarted,
   hasCourseStartedEmittedToTracking: () => hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered: () => hasCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent: () => hasCourseStartedXapiSent,
   isChildTypeAllowed: () => isChildTypeAllowed,
+  isLifecycleTelemetryEvent: () => isLifecycleTelemetryEvent,
   loadCompoundState: () => loadCompoundState,
   markCourseStarted: () => markCourseStarted,
   markCourseStartedEmittedToTracking: () => markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered: () => markCourseStartedPipelineDelivered,
+  markCourseStartedXapiSent: () => markCourseStartedXapiSent,
   migrateCourseStartedMark: () => migrateCourseStartedMark,
   nowIso: () => nowIso,
   parseBlockId: () => parseBlockId,
@@ -95,6 +100,7 @@ __export(index_exports, {
   telemetryCatalogVersion: () => telemetryCatalogVersion,
   tryBuildTelemetryEvent: () => tryBuildTelemetryEvent,
   tryEmitCourseStarted: () => tryEmitCourseStarted,
+  validateBranchGraph: () => validateBranchGraph,
   validateId: () => validateId
 });
 module.exports = __toCommonJS(index_exports);
@@ -172,12 +178,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);
@@ -219,6 +239,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;
 }
 
@@ -263,19 +290,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,
@@ -300,17 +333,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}`);
     }
@@ -367,8 +404,45 @@ 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",
@@ -399,7 +473,9 @@ var SLIDE_ALLOWED_CHILD_TYPES = [
   "ImageHotspots",
   "FindHotspot",
   "FindMultipleHotspots",
-  "ImageSlider"
+  "ImageSlider",
+  "Embed",
+  "Chart"
 ];
 var SLIDE_DECK_ALLOWED_CHILD_TYPES = ["Slide"];
 var TIMED_CUE_ALLOWED_CHILD_TYPES = [
@@ -441,7 +517,9 @@ 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
 };
 var COMPOUND_MAX_NESTING_DEPTH = {
   Page: 1,
@@ -450,7 +528,9 @@ var COMPOUND_MAX_NESTING_DEPTH = {
   SlideDeck: 2,
   TimedCue: 1,
   InteractiveVideo: 2,
-  AssessmentSequence: 1
+  AssessmentSequence: 1,
+  BranchingScenario: 2,
+  BranchNode: 1
 };
 function getAllowedChildTypes(parent) {
   return ALLOWLISTS[parent];
@@ -461,6 +541,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 = [
@@ -663,6 +819,22 @@ 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}"
   }
 ];
 function buildTelemetryCatalogV3() {
@@ -694,22 +866,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;
@@ -727,13 +889,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;
@@ -746,19 +909,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) {
@@ -779,12 +951,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 = () => {
@@ -805,18 +978,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()) {
@@ -825,29 +1007,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);
@@ -869,10 +1059,21 @@ function createTrackingClient(opts) {
 }
 
 // src/ids.ts
+function randomSessionIdFallback() {
+  const g = globalThis;
+  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("");
+  }
+  throw new Error(
+    "[lessonkit] createSessionId requires crypto.randomUUID or crypto.getRandomValues"
+  );
+}
 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)}`;
+  return randomSessionIdFallback();
 }
 
 // src/time.ts
@@ -1151,6 +1352,34 @@ var TELEMETRY_EVENT_REGISTRY = {
         data: opts.data
       };
     }
+  },
+  branch_node_viewed: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "branch_node_viewed") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("branch_node_viewed requires active lessonId");
+      return {
+        name: "branch_node_viewed",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
+  },
+  branch_selected: {
+    requiresLessonId: true,
+    build: (opts, base) => {
+      if (opts.name !== "branch_selected") throw new Error("unexpected event");
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("branch_selected requires active lessonId");
+      return {
+        name: "branch_selected",
+        ...base,
+        lessonId,
+        data: opts.data
+      };
+    }
   }
 };
 function buildTelemetryEventFromRegistry(opts) {
@@ -1183,8 +1412,8 @@ function buildTelemetryEvent(opts) {
 }
 function tryBuildTelemetryEvent(opts) {
   const entry = getTelemetryEventRegistryEntry(opts.name);
-  if (entry.requiresLessonId && !opts.lessonId && entry.tryBuildMissingLessonWarning) {
-    if (isDevEnvironment()) {
+  if (entry.requiresLessonId && !opts.lessonId) {
+    if (isDevEnvironment() && entry.tryBuildMissingLessonWarning) {
       if (entry.tryBuildMissingLessonWarning === "quiz" && !warnedMissingQuizLesson) {
         warnedMissingQuizLesson = true;
         console.warn(
@@ -1204,21 +1433,44 @@ function tryBuildTelemetryEvent(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);
       }
     }
   };
@@ -1240,14 +1492,44 @@ function createDefaultClock() {
   };
 }
 function createNoopStorage() {
+  const memory = /* @__PURE__ */ new Map();
   return {
-    getItem: () => null,
-    setItem: () => true
+    getItem: (key) => memory.get(key) ?? null,
+    setItem: (key, value) => {
+      memory.set(key, value);
+      return true;
+    },
+    removeItem: (key) => {
+      memory.delete(key);
+    },
+    resetForTests: () => {
+      memory.clear();
+    }
   };
 }
 function createMemoryBackedSessionStorage(session) {
   const memory = /* @__PURE__ */ new Map();
+  const tombstones = /* @__PURE__ */ new Set();
   let warnedPersistFailure = false;
+  const syncFromStorageEvent = (key, newValue) => {
+    if (key === null) {
+      memory.clear();
+      tombstones.clear();
+      return;
+    }
+    tombstones.delete(key);
+    if (newValue === null) {
+      memory.delete(key);
+    } else {
+      memory.set(key, newValue);
+    }
+  };
+  if (typeof window !== "undefined") {
+    window.addEventListener("storage", (event) => {
+      if (event.storageArea !== sessionStorage) return;
+      syncFromStorageEvent(event.key, event.newValue);
+    });
+  }
   const warnPersistFailure = () => {
     if (warnedPersistFailure) return;
     warnedPersistFailure = true;
@@ -1260,6 +1542,7 @@ function createMemoryBackedSessionStorage(session) {
   };
   return {
     getItem: (key) => {
+      if (tombstones.has(key)) return null;
       if (memory.has(key)) return memory.get(key);
       try {
         const value = session.getItem(key);
@@ -1270,6 +1553,7 @@ function createMemoryBackedSessionStorage(session) {
       }
     },
     setItem: (key, value) => {
+      tombstones.delete(key);
       memory.set(key, value);
       try {
         session.setItem(key, value);
@@ -1283,12 +1567,15 @@ function createMemoryBackedSessionStorage(session) {
       memory.delete(key);
       try {
         session.removeItem(key);
+        tombstones.delete(key);
       } catch {
         warnPersistFailure();
+        tombstones.add(key);
       }
     },
     resetForTests: () => {
       memory.clear();
+      tombstones.clear();
     }
   };
 }
@@ -1360,6 +1647,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;
@@ -1380,7 +1672,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";
@@ -1391,10 +1682,23 @@ function getTabSessionId(storage) {
 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:";
+var COURSE_STARTED_XAPI_PREFIX = "lessonkit:course_started_xapi:";
+function sessionKeySegment(sessionId) {
+  const validated = validateId(sessionId);
+  return validated.ok ? validated.id : encodeURIComponent(sessionId);
+}
 function resolveSessionId(storage, provided) {
   if (provided !== void 0) {
     const trimmed = provided.trim();
-    if (trimmed.length > 0) return trimmed;
+    if (trimmed.length > 0) {
+      const validated = validateId(trimmed);
+      if (validated.ok) return validated.id;
+      if (isDevEnvironment2()) {
+        console.warn(
+          `[lessonkit] Invalid sessionId "${trimmed}"; falling back to tab or generated id.`
+        );
+      }
+    }
   }
   const existing = storage.getItem(SESSION_STORAGE_KEY);
   if (existing) return existing;
@@ -1403,27 +1707,27 @@ function resolveSessionId(storage, provided) {
   const id = createSessionId();
   const persisted = storage.setItem(SESSION_STORAGE_KEY, id);
   if (!persisted) {
-    if (!sharedVolatileSessionId) {
-      sharedVolatileSessionId = id;
-    }
-    volatileSessionIds.set(storage, sharedVolatileSessionId);
+    volatileSessionIds.set(storage, id);
     if (isDevEnvironment2()) {
       console.warn(
-        "[lessonkit] session id could not be persisted; reusing in-memory id for this tab."
+        "[lessonkit] session id could not be persisted; using in-memory id for this storage."
       );
     }
-    return sharedVolatileSessionId;
+    return id;
   }
   return id;
 }
 function courseStartedStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
+  return `${COURSE_STARTED_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
 function courseStartedTrackingStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionId}:${courseId ?? ""}`;
+  return `${COURSE_STARTED_TRACKING_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
 function courseStartedPipelineStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionId}:${courseId ?? ""}`;
+  return `${COURSE_STARTED_PIPELINE_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
+}
+function courseStartedXapiStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_XAPI_PREFIX}${sessionKeySegment(sessionId)}:${courseId ?? ""}`;
 }
 function hasCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return false;
@@ -1449,49 +1753,82 @@ function markCourseStartedPipelineDelivered(storage, sessionId, courseId) {
   if (!courseId) return false;
   return storage.setItem(courseStartedPipelineStorageKey(sessionId, courseId), "1");
 }
+function hasCourseStartedXapiSent(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.getItem(courseStartedXapiStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStartedXapiSent(storage, sessionId, courseId) {
+  if (!courseId) return false;
+  return storage.setItem(courseStartedXapiStorageKey(sessionId, courseId), "1");
+}
 function resetSharedVolatileSessionIdForTests() {
-  sharedVolatileSessionId = null;
+}
+function migrateStorageMark(storage, fromKey, toKey, hasMark) {
+  if (!hasMark) return;
+  if (storage.setItem(toKey, "1")) {
+    storage.removeItem?.(fromKey);
+  }
 }
 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));
-  }
+  migrateStorageMark(
+    storage,
+    courseStartedStorageKey(fromSessionId, courseId),
+    courseStartedStorageKey(toSessionId, courseId),
+    hasCourseStarted(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedTrackingStorageKey(fromSessionId, courseId),
+    courseStartedTrackingStorageKey(toSessionId, courseId),
+    hasCourseStartedEmittedToTracking(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedPipelineStorageKey(fromSessionId, courseId),
+    courseStartedPipelineStorageKey(toSessionId, courseId),
+    hasCourseStartedPipelineDelivered(storage, fromSessionId, courseId)
+  );
+  migrateStorageMark(
+    storage,
+    courseStartedXapiStorageKey(fromSessionId, courseId),
+    courseStartedXapiStorageKey(toSessionId, courseId),
+    hasCourseStartedXapiSent(storage, fromSessionId, courseId)
+  );
 }
 
 // src/runtime/courseLifecycle.ts
-var courseStartedEmitFlights = /* @__PURE__ */ new Set();
+var courseStartedEmitFlights = /* @__PURE__ */ new Map();
 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 };
+    return Promise.resolve({ emitted: true, marked });
   }
-  if (courseStartedEmitFlights.has(flightKey)) {
-    return { emitted: false, marked };
+  const existing = courseStartedEmitFlights.get(flightKey);
+  if (existing) {
+    return existing;
   }
-  courseStartedEmitFlights.add(flightKey);
-  try {
-    const emitted = deps.emitCourseStartedEvent(ctx);
-    if (emitted && !marked) {
-      markCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId);
+  const flight = Promise.resolve().then(() => {
+    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)
+      };
+    } catch {
+      return { emitted: false, marked };
+    } finally {
+      if (courseStartedEmitFlights.get(flightKey) === flight) {
+        courseStartedEmitFlights.delete(flightKey);
+      }
     }
-    return {
-      emitted,
-      marked: hasCourseStarted(ctx.storage, ctx.sessionId, ctx.courseId)
-    };
-  } finally {
-    courseStartedEmitFlights.delete(flightKey);
-  }
+  });
+  courseStartedEmitFlights.set(flightKey, flight);
+  return flight;
 }
 function buildCourseStartedTelemetryEvent(ctx) {
   return buildTelemetryEvent({
@@ -1540,6 +1877,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) {
@@ -1581,7 +1932,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) {
@@ -1646,6 +1997,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,
@@ -1679,28 +2031,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;
@@ -1713,7 +2061,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;
@@ -1721,6 +2074,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 };
       }
@@ -1742,14 +2098,14 @@ function createLessonkitRuntime(config, ports = {}) {
       }
     },
     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)) {
@@ -1757,38 +2113,47 @@ 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();
+      pluginHost?.disposeAll();
+      if (!configSnapshot.deferPluginSetup) {
+        pluginHost?.setupAll(getPluginCtx());
+      }
     },
     dispose() {
+      if (disposed) return;
+      disposed = true;
       pluginHost?.disposeAll();
     }
   };
@@ -1809,6 +2174,8 @@ function defineLifecyclePlugin(plugin) {
   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,
@@ -1858,11 +2225,14 @@ function defineLifecyclePlugin(plugin) {
   hasCourseStarted,
   hasCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
   isChildTypeAllowed,
+  isLifecycleTelemetryEvent,
   loadCompoundState,
   markCourseStarted,
   markCourseStartedEmittedToTracking,
   markCourseStartedPipelineDelivered,
+  markCourseStartedXapiSent,
   migrateCourseStartedMark,
   nowIso,
   parseBlockId,
@@ -1881,5 +2251,6 @@ function defineLifecyclePlugin(plugin) {
   telemetryCatalogVersion,
   tryBuildTelemetryEvent,
   tryEmitCourseStarted,
+  validateBranchGraph,
   validateId
 });