@lessonkit/react 1.0.1 → 1.0.2

package/dist/index.cjs

@@ -171,7 +171,40 @@ var import_core5 = require("@lessonkit/core");
 
 // src/runtime/courseStartedPipeline.ts
 var import_xapi3 = require("@lessonkit/xapi");
-function emitCourseStartedNonTrackingPipeline(opts) {
+function isDevEnvironment3() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnExtraSinkFailure(sinkId, err) {
+  if (isDevEnvironment3()) {
+    console.warn(
+      `[lessonkit] course_started extra sink "${sinkId}" failed:`,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+async function emitExtraSinks(sinks, event, emitCtx) {
+  await Promise.all(
+    sinks.map(async (sink) => {
+      let result;
+      try {
+        result = sink.emit(event, emitCtx);
+      } catch (err) {
+        warnExtraSinkFailure(sink.id, err);
+        throw err;
+      }
+      if (result != null && typeof result.then === "function") {
+        try {
+          await result;
+        } catch (err) {
+          warnExtraSinkFailure(sink.id, err);
+          throw err;
+        }
+      }
+    })
+  );
+}
+async function emitCourseStartedNonTrackingPipeline(opts) {
   let xapiStatementSent = false;
   if (!opts.skipXapi && opts.xapi) {
     const statement = (0, import_xapi3.telemetryEventToXAPIStatement)(opts.event);
@@ -186,9 +219,7 @@ function emitCourseStartedNonTrackingPipeline(opts) {
     sessionId: opts.event.sessionId,
     attemptId: opts.event.attemptId
   };
-  for (const sink of opts.extraSinks ?? []) {
-    sink.emit(opts.event, emitCtx);
-  }
+  await emitExtraSinks(opts.extraSinks ?? [], opts.event, emitCtx);
   return { xapiStatementSent };
 }
 
@@ -240,6 +271,7 @@ async function disposeTrackingClient(client) {
 // src/provider/useLessonkitProviderRuntime.ts
 var useIsoLayoutEffect = typeof window !== "undefined" ? import_react.useLayoutEffect : import_react.useEffect;
 var defaultStorage = (0, import_core3.createSessionStoragePort)();
+var courseStartedTrackingFlightKey = null;
 function isTrackingActive(tracking) {
   return tracking?.enabled !== false;
 }
@@ -262,15 +294,41 @@ function buildCourseStartedEvent(opts) {
   });
   return opts.pluginHost ? opts.pluginHost.runTelemetry(built, pluginCtx) : built;
 }
-function emitCourseStartedPipelineOnly(opts) {
+async function emitCourseStartedToTracking(tracking, storage, sessionId, courseId, event, shouldCommit) {
+  const flightKey = `${sessionId}:${courseId}`;
+  if ((0, import_core5.hasCourseStartedEmittedToTracking)(storage, sessionId, courseId)) {
+    return true;
+  }
+  if (courseStartedTrackingFlightKey === flightKey) {
+    return false;
+  }
+  courseStartedTrackingFlightKey = flightKey;
+  try {
+    if (shouldCommit && !shouldCommit()) return false;
+    tracking.track(event);
+    await tracking.flush?.();
+    if (shouldCommit && !shouldCommit()) return false;
+    (0, import_core5.markCourseStartedEmittedToTracking)(storage, sessionId, courseId);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (courseStartedTrackingFlightKey === flightKey) {
+      courseStartedTrackingFlightKey = null;
+    }
+  }
+}
+async function emitCourseStartedPipelineOnly(opts) {
   try {
-    const { xapiStatementSent } = emitCourseStartedNonTrackingPipeline({
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    const { xapiStatementSent } = await emitCourseStartedNonTrackingPipeline({
       event: opts.event,
       xapi: opts.xapi,
       lxpackBridge: opts.lxpackBridge,
       extraSinks: opts.extraSinks,
       skipXapi: opts.skipXapi
     });
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
     (0, import_core5.markCourseStarted)(opts.storage, opts.sessionId, opts.courseId);
     (0, import_core5.markCourseStartedPipelineDelivered)(opts.storage, opts.sessionId, opts.courseId);
     if (xapiStatementSent) {
@@ -281,7 +339,7 @@ function emitCourseStartedPipelineOnly(opts) {
     return "failed";
   }
 }
-function emitCourseStarted(opts) {
+async function emitCourseStarted(opts) {
   const event = buildCourseStartedEvent(opts);
   if (event === null) return "filtered";
   const trackingAlreadyEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
@@ -290,21 +348,25 @@ function emitCourseStarted(opts) {
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      (0, import_core5.markCourseStartedEmittedToTracking)(opts.storage, opts.sessionId, opts.courseId);
-    } catch {
-      return "failed";
-    }
+    const tracked = await emitCourseStartedToTracking(
+      opts.tracking,
+      opts.storage,
+      opts.sessionId,
+      opts.courseId,
+      event,
+      opts.shouldCommit
+    );
+    if (!tracked) return "failed";
   }
   return emitCourseStartedPipelineOnly({
     ...opts,
     event,
     skipXapi: opts.skipXapi,
-    onXapiStatementSent: opts.onXapiStatementSent
+    onXapiStatementSent: opts.onXapiStatementSent,
+    shouldCommit: opts.shouldCommit
   });
 }
-function emitCourseStartedToTrackingOnly(opts) {
+async function emitCourseStartedToTrackingOnly(opts) {
   const event = buildCourseStartedEvent(opts);
   if (event === null) return "filtered";
   const trackingAlreadyEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
@@ -313,15 +375,19 @@ function emitCourseStartedToTrackingOnly(opts) {
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      (0, import_core5.markCourseStartedEmittedToTracking)(opts.storage, opts.sessionId, opts.courseId);
-    } catch {
-      return "failed";
-    }
+    const tracked = await emitCourseStartedToTracking(
+      opts.tracking,
+      opts.storage,
+      opts.sessionId,
+      opts.courseId,
+      event,
+      opts.shouldCommit
+    );
+    if (!tracked) return "failed";
   }
   try {
-    emitCourseStartedNonTrackingPipeline({
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    await emitCourseStartedNonTrackingPipeline({
       event,
       xapi: null,
       lxpackBridge: opts.lxpackBridge,
@@ -334,7 +400,7 @@ function emitCourseStartedToTrackingOnly(opts) {
     return "failed";
   }
 }
-function emitPendingCourseStarted(opts) {
+async function emitPendingCourseStarted(opts) {
   const trackingEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
     opts.storage,
     opts.sessionId,
@@ -408,6 +474,7 @@ function useLessonkitProviderRuntime(config) {
   pluginHostRef.current = pluginHost;
   const progressRef = (0, import_react.useRef)((0, import_core4.createProgressController)());
   const courseStartedEmittedToSinkRef = (0, import_react.useRef)(false);
+  const courseStartedEmitGenerationRef = (0, import_react.useRef)(0);
   const prevCourseIdForProgressRef = (0, import_react.useRef)(normalizedCourseId);
   const pendingCourseIdResetRef = (0, import_react.useRef)(false);
   const prevUseV2RuntimeRef = (0, import_react.useRef)(useV2Runtime);
@@ -427,6 +494,7 @@ function useLessonkitProviderRuntime(config) {
     }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
   } else if (useV2Runtime && !headlessRef.current) {
     headlessRef.current = (0, import_core8.createLessonkitRuntime)({
       courseId: normalizedCourseId,
@@ -444,6 +512,7 @@ function useLessonkitProviderRuntime(config) {
     }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
   }
   if (useV2Runtime && headlessRef.current) {
     progressRef.current = headlessRef.current.progress;
@@ -581,30 +650,39 @@ function useLessonkitProviderRuntime(config) {
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
     const trackingActive = isTrackingActive(normalizedConfig.tracking);
+    const courseStartedFullySettled = (0, import_core5.hasCourseStartedEmittedToTracking)(defaultStorage, sessionId, cid) && (0, import_core5.hasCourseStarted)(defaultStorage, sessionId, cid) && (0, import_core5.hasCourseStartedPipelineDelivered)(defaultStorage, sessionId, cid);
     if (!trackingActive) {
       courseStartedEmittedToSinkRef.current = false;
-    } else if (!courseStartedEmittedToSinkRef.current) {
-      const result = emitPendingCourseStarted({
-        pluginHost: pluginHostRef.current,
-        tracking: next,
-        xapi: xapiRef.current,
-        storage: defaultStorage,
-        sessionId,
-        courseId: cid,
-        attemptId: attemptIdRef.current,
-        user: userRef.current,
-        lxpackBridge: lxpackBridgeModeRef.current,
-        extraSinks: extraSinksRef.current,
-        skipXapi: xapiCourseStartedSentOnClientRef.current,
-        onXapiStatementSent: () => {
-          xapiCourseStartedSentOnClientRef.current = true;
-        }
-      });
-      courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
-    } else if (trackingActive) {
+    } else if (courseStartedFullySettled) {
       courseStartedEmittedToSinkRef.current = true;
+    } else if (!courseStartedEmittedToSinkRef.current) {
+      const generation = ++courseStartedEmitGenerationRef.current;
+      const shouldCommit = () => generation === courseStartedEmitGenerationRef.current;
+      void (async () => {
+        if (generation !== courseStartedEmitGenerationRef.current) return;
+        const result = await emitPendingCourseStarted({
+          pluginHost: pluginHostRef.current,
+          tracking: next,
+          xapi: xapiRef.current,
+          storage: defaultStorage,
+          sessionId,
+          courseId: cid,
+          attemptId: attemptIdRef.current,
+          user: userRef.current,
+          lxpackBridge: lxpackBridgeModeRef.current,
+          extraSinks: extraSinksRef.current,
+          skipXapi: xapiCourseStartedSentOnClientRef.current,
+          onXapiStatementSent: () => {
+            xapiCourseStartedSentOnClientRef.current = true;
+          },
+          shouldCommit
+        });
+        if (generation !== courseStartedEmitGenerationRef.current) return;
+        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
+      })();
     }
     return () => {
+      courseStartedEmitGenerationRef.current += 1;
       if (prev !== trackingRef.current) {
         void disposeTrackingClient(prev);
       }
@@ -681,7 +759,7 @@ function useLessonkitProviderRuntime(config) {
       } catch {
       }
       if (!courseStartedEmittedToSinkRef.current) {
-        const result = emitPendingCourseStarted({
+        const result = await emitPendingCourseStarted({
           pluginHost: pluginHostRef.current,
           tracking: trackingRef.current,
           xapi: xapiRef.current,
@@ -707,7 +785,10 @@ function useLessonkitProviderRuntime(config) {
     [track]
   );
   const completeLesson = (0, import_react.useCallback)(
-    (lessonId) => {
+    (lessonId, opts) => {
+      if (opts?.courseId !== void 0 && opts.courseId !== courseIdRef.current) {
+        return;
+      }
       if (useV2Runtime && headlessRef.current) {
         headlessRef.current.completeLesson(lessonId, emitLifecycleEvent);
         syncProgress();
@@ -925,7 +1006,7 @@ function useEnclosingLessonId() {
 
 // src/runtime/validateComponentId.ts
 var import_core9 = require("@lessonkit/core");
-function isDevEnvironment3() {
+function isDevEnvironment4() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
@@ -941,7 +1022,7 @@ function normalizeComponentId(id, path) {
 var mountCounts = /* @__PURE__ */ new Map();
 var warnedConcurrentLessons = false;
 function registerLessonMount(lessonId) {
-  if (isDevEnvironment3() && mountCounts.size > 0 && !mountCounts.has(lessonId) && !warnedConcurrentLessons) {
+  if (isDevEnvironment4() && mountCounts.size > 0 && !mountCounts.has(lessonId) && !warnedConcurrentLessons) {
     warnedConcurrentLessons = true;
     console.warn(
       "[lessonkit] Multiple <Lesson> components are mounted; only one should be active at a time. Set autoCompleteOnUnmount={false} on routed lessons or unmount the previous lesson before showing the next."
@@ -984,9 +1065,18 @@ function Lesson(props) {
   const { setActiveLesson, config } = useLessonkit();
   const { completeLesson } = useCompletion();
   const lessonMountGenerationRef = (0, import_react5.useRef)(0);
+  const liveCourseIdRef = (0, import_react5.useRef)(config.courseId);
+  liveCourseIdRef.current = config.courseId;
   (0, import_react5.useEffect)(() => {
     const unregister = registerLessonMount(lessonId);
     const generation = ++lessonMountGenerationRef.current;
+    const mountedCourseId = config.courseId;
+    let effectSurvivedTick = false;
+    queueMicrotask(() => {
+      queueMicrotask(() => {
+        effectSurvivedTick = true;
+      });
+    });
     setActiveLesson(lessonId);
     return () => {
       unregister();
@@ -995,8 +1085,10 @@ function Lesson(props) {
       }
       if (!autoComplete) return;
       queueMicrotask(() => {
+        if (!effectSurvivedTick) return;
         if (lessonMountGenerationRef.current !== generation) return;
-        completeLesson(lessonId);
+        if (liveCourseIdRef.current !== mountedCourseId) return;
+        completeLesson(lessonId, { courseId: mountedCourseId });
       });
     };
   }, [lessonId, config.courseId, setActiveLesson, completeLesson, autoComplete]);
@@ -1055,11 +1147,10 @@ function KnowledgeCheck(props) {
   );
 }
 function Quiz(props) {
-  const checkId = (0, import_react5.useMemo)(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
   const enclosingLessonId = useEnclosingLessonId();
   const missingLesson = enclosingLessonId === void 0;
   (0, import_react5.useEffect)(() => {
-    if (!missingLesson || isDevEnvironment3()) return;
+    if (!missingLesson || isDevEnvironment4()) return;
     if (!warnedQuizOutsideLesson) {
       warnedQuizOutsideLesson = true;
       console.error(
@@ -1067,9 +1158,17 @@ function Quiz(props) {
       );
     }
   }, [missingLesson]);
-  if (missingLesson && isDevEnvironment3()) {
+  if (missingLesson && isDevEnvironment4()) {
     throw new Error("[lessonkit] <Quiz> must be wrapped in <Lesson>");
   }
+  if (missingLesson) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("section", { role: "alert", "aria-label": "Quiz configuration error", "data-lk-check-id": props.checkId, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: "Quiz must be placed inside a Lesson." }) });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(QuizInner, { ...props, enclosingLessonId });
+}
+function QuizInner(props) {
+  const { enclosingLessonId } = props;
+  const checkId = (0, import_react5.useMemo)(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
   const quiz = useQuizState(enclosingLessonId);
   const { plugins, config, session } = useLessonkit();
   const [selected, setSelected] = (0, import_react5.useState)(null);
@@ -1092,9 +1191,6 @@ function Quiz(props) {
     }
     return choice === props.answer;
   };
-  if (missingLesson) {
-    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("section", { role: "alert", "aria-label": "Quiz configuration error", "data-lk-check-id": checkId, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: "Quiz must be placed inside a Lesson." }) });
-  }
   const passed = quizPassed;
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Quiz", "data-lk-check-id": checkId, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: questionId, children: props.question }),

package/dist/index.d.cts

@@ -58,7 +58,9 @@ type LessonkitRuntime = {
         user?: TelemetryUser;
     };
     setActiveLesson: (lessonId: LessonId) => void;
-    completeLesson: (lessonId: LessonId) => void;
+    completeLesson: (lessonId: LessonId, opts?: {
+        courseId?: CourseId;
+    }) => void;
     completeCourse: () => void;
     track: <N extends TelemetryEventName>(name: N, data?: TelemetryDataFor<N>, opts?: {
         lessonId?: LessonId;
@@ -115,7 +117,9 @@ declare function useTracking(): {
     }) => void;
 };
 declare function useCompletion(): {
-    completeLesson: (lessonId: LessonId) => void;
+    completeLesson: (lessonId: LessonId, opts?: {
+        courseId?: _lessonkit_core.CourseId;
+    }) => void;
     completeCourse: () => void;
 };
 declare function useQuizState(enclosingLessonId?: LessonId): {

package/dist/index.d.ts

@@ -58,7 +58,9 @@ type LessonkitRuntime = {
         user?: TelemetryUser;
     };
     setActiveLesson: (lessonId: LessonId) => void;
-    completeLesson: (lessonId: LessonId) => void;
+    completeLesson: (lessonId: LessonId, opts?: {
+        courseId?: CourseId;
+    }) => void;
     completeCourse: () => void;
     track: <N extends TelemetryEventName>(name: N, data?: TelemetryDataFor<N>, opts?: {
         lessonId?: LessonId;
@@ -115,7 +117,9 @@ declare function useTracking(): {
     }) => void;
 };
 declare function useCompletion(): {
-    completeLesson: (lessonId: LessonId) => void;
+    completeLesson: (lessonId: LessonId, opts?: {
+        courseId?: _lessonkit_core.CourseId;
+    }) => void;
     completeCourse: () => void;
 };
 declare function useQuizState(enclosingLessonId?: LessonId): {

package/dist/index.js

@@ -142,7 +142,40 @@ import {
 
 // src/runtime/courseStartedPipeline.ts
 import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
-function emitCourseStartedNonTrackingPipeline(opts) {
+function isDevEnvironment3() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnExtraSinkFailure(sinkId, err) {
+  if (isDevEnvironment3()) {
+    console.warn(
+      `[lessonkit] course_started extra sink "${sinkId}" failed:`,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+async function emitExtraSinks(sinks, event, emitCtx) {
+  await Promise.all(
+    sinks.map(async (sink) => {
+      let result;
+      try {
+        result = sink.emit(event, emitCtx);
+      } catch (err) {
+        warnExtraSinkFailure(sink.id, err);
+        throw err;
+      }
+      if (result != null && typeof result.then === "function") {
+        try {
+          await result;
+        } catch (err) {
+          warnExtraSinkFailure(sink.id, err);
+          throw err;
+        }
+      }
+    })
+  );
+}
+async function emitCourseStartedNonTrackingPipeline(opts) {
   let xapiStatementSent = false;
   if (!opts.skipXapi && opts.xapi) {
     const statement = telemetryEventToXAPIStatement2(opts.event);
@@ -157,9 +190,7 @@ function emitCourseStartedNonTrackingPipeline(opts) {
     sessionId: opts.event.sessionId,
     attemptId: opts.event.attemptId
   };
-  for (const sink of opts.extraSinks ?? []) {
-    sink.emit(opts.event, emitCtx);
-  }
+  await emitExtraSinks(opts.extraSinks ?? [], opts.event, emitCtx);
   return { xapiStatementSent };
 }
 
@@ -211,6 +242,7 @@ async function disposeTrackingClient(client) {
 // src/provider/useLessonkitProviderRuntime.ts
 var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
 var defaultStorage = createSessionStoragePort();
+var courseStartedTrackingFlightKey = null;
 function isTrackingActive(tracking) {
   return tracking?.enabled !== false;
 }
@@ -233,15 +265,41 @@ function buildCourseStartedEvent(opts) {
   });
   return opts.pluginHost ? opts.pluginHost.runTelemetry(built, pluginCtx) : built;
 }
-function emitCourseStartedPipelineOnly(opts) {
+async function emitCourseStartedToTracking(tracking, storage, sessionId, courseId, event, shouldCommit) {
+  const flightKey = `${sessionId}:${courseId}`;
+  if (hasCourseStartedEmittedToTracking(storage, sessionId, courseId)) {
+    return true;
+  }
+  if (courseStartedTrackingFlightKey === flightKey) {
+    return false;
+  }
+  courseStartedTrackingFlightKey = flightKey;
+  try {
+    if (shouldCommit && !shouldCommit()) return false;
+    tracking.track(event);
+    await tracking.flush?.();
+    if (shouldCommit && !shouldCommit()) return false;
+    markCourseStartedEmittedToTracking(storage, sessionId, courseId);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (courseStartedTrackingFlightKey === flightKey) {
+      courseStartedTrackingFlightKey = null;
+    }
+  }
+}
+async function emitCourseStartedPipelineOnly(opts) {
   try {
-    const { xapiStatementSent } = emitCourseStartedNonTrackingPipeline({
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    const { xapiStatementSent } = await emitCourseStartedNonTrackingPipeline({
       event: opts.event,
       xapi: opts.xapi,
       lxpackBridge: opts.lxpackBridge,
       extraSinks: opts.extraSinks,
       skipXapi: opts.skipXapi
     });
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
     markCourseStarted(opts.storage, opts.sessionId, opts.courseId);
     markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId);
     if (xapiStatementSent) {
@@ -252,7 +310,7 @@ function emitCourseStartedPipelineOnly(opts) {
     return "failed";
   }
 }
-function emitCourseStarted(opts) {
+async function emitCourseStarted(opts) {
   const event = buildCourseStartedEvent(opts);
   if (event === null) return "filtered";
   const trackingAlreadyEmitted = hasCourseStartedEmittedToTracking(
@@ -261,21 +319,25 @@ function emitCourseStarted(opts) {
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      markCourseStartedEmittedToTracking(opts.storage, opts.sessionId, opts.courseId);
-    } catch {
-      return "failed";
-    }
+    const tracked = await emitCourseStartedToTracking(
+      opts.tracking,
+      opts.storage,
+      opts.sessionId,
+      opts.courseId,
+      event,
+      opts.shouldCommit
+    );
+    if (!tracked) return "failed";
   }
   return emitCourseStartedPipelineOnly({
     ...opts,
     event,
     skipXapi: opts.skipXapi,
-    onXapiStatementSent: opts.onXapiStatementSent
+    onXapiStatementSent: opts.onXapiStatementSent,
+    shouldCommit: opts.shouldCommit
   });
 }
-function emitCourseStartedToTrackingOnly(opts) {
+async function emitCourseStartedToTrackingOnly(opts) {
   const event = buildCourseStartedEvent(opts);
   if (event === null) return "filtered";
   const trackingAlreadyEmitted = hasCourseStartedEmittedToTracking(
@@ -284,15 +346,19 @@ function emitCourseStartedToTrackingOnly(opts) {
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      markCourseStartedEmittedToTracking(opts.storage, opts.sessionId, opts.courseId);
-    } catch {
-      return "failed";
-    }
+    const tracked = await emitCourseStartedToTracking(
+      opts.tracking,
+      opts.storage,
+      opts.sessionId,
+      opts.courseId,
+      event,
+      opts.shouldCommit
+    );
+    if (!tracked) return "failed";
   }
   try {
-    emitCourseStartedNonTrackingPipeline({
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    await emitCourseStartedNonTrackingPipeline({
       event,
       xapi: null,
       lxpackBridge: opts.lxpackBridge,
@@ -305,7 +371,7 @@ function emitCourseStartedToTrackingOnly(opts) {
     return "failed";
   }
 }
-function emitPendingCourseStarted(opts) {
+async function emitPendingCourseStarted(opts) {
   const trackingEmitted = hasCourseStartedEmittedToTracking(
     opts.storage,
     opts.sessionId,
@@ -379,6 +445,7 @@ function useLessonkitProviderRuntime(config) {
   pluginHostRef.current = pluginHost;
   const progressRef = useRef(createProgressController());
   const courseStartedEmittedToSinkRef = useRef(false);
+  const courseStartedEmitGenerationRef = useRef(0);
   const prevCourseIdForProgressRef = useRef(normalizedCourseId);
   const pendingCourseIdResetRef = useRef(false);
   const prevUseV2RuntimeRef = useRef(useV2Runtime);
@@ -398,6 +465,7 @@ function useLessonkitProviderRuntime(config) {
     }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
   } else if (useV2Runtime && !headlessRef.current) {
     headlessRef.current = createLessonkitRuntime({
       courseId: normalizedCourseId,
@@ -415,6 +483,7 @@ function useLessonkitProviderRuntime(config) {
     }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
   }
   if (useV2Runtime && headlessRef.current) {
     progressRef.current = headlessRef.current.progress;
@@ -552,30 +621,39 @@ function useLessonkitProviderRuntime(config) {
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
     const trackingActive = isTrackingActive(normalizedConfig.tracking);
+    const courseStartedFullySettled = hasCourseStartedEmittedToTracking(defaultStorage, sessionId, cid) && hasCourseStarted(defaultStorage, sessionId, cid) && hasCourseStartedPipelineDelivered(defaultStorage, sessionId, cid);
     if (!trackingActive) {
       courseStartedEmittedToSinkRef.current = false;
-    } else if (!courseStartedEmittedToSinkRef.current) {
-      const result = emitPendingCourseStarted({
-        pluginHost: pluginHostRef.current,
-        tracking: next,
-        xapi: xapiRef.current,
-        storage: defaultStorage,
-        sessionId,
-        courseId: cid,
-        attemptId: attemptIdRef.current,
-        user: userRef.current,
-        lxpackBridge: lxpackBridgeModeRef.current,
-        extraSinks: extraSinksRef.current,
-        skipXapi: xapiCourseStartedSentOnClientRef.current,
-        onXapiStatementSent: () => {
-          xapiCourseStartedSentOnClientRef.current = true;
-        }
-      });
-      courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
-    } else if (trackingActive) {
+    } else if (courseStartedFullySettled) {
       courseStartedEmittedToSinkRef.current = true;
+    } else if (!courseStartedEmittedToSinkRef.current) {
+      const generation = ++courseStartedEmitGenerationRef.current;
+      const shouldCommit = () => generation === courseStartedEmitGenerationRef.current;
+      void (async () => {
+        if (generation !== courseStartedEmitGenerationRef.current) return;
+        const result = await emitPendingCourseStarted({
+          pluginHost: pluginHostRef.current,
+          tracking: next,
+          xapi: xapiRef.current,
+          storage: defaultStorage,
+          sessionId,
+          courseId: cid,
+          attemptId: attemptIdRef.current,
+          user: userRef.current,
+          lxpackBridge: lxpackBridgeModeRef.current,
+          extraSinks: extraSinksRef.current,
+          skipXapi: xapiCourseStartedSentOnClientRef.current,
+          onXapiStatementSent: () => {
+            xapiCourseStartedSentOnClientRef.current = true;
+          },
+          shouldCommit
+        });
+        if (generation !== courseStartedEmitGenerationRef.current) return;
+        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
+      })();
     }
     return () => {
+      courseStartedEmitGenerationRef.current += 1;
       if (prev !== trackingRef.current) {
         void disposeTrackingClient(prev);
       }
@@ -652,7 +730,7 @@ function useLessonkitProviderRuntime(config) {
       } catch {
       }
       if (!courseStartedEmittedToSinkRef.current) {
-        const result = emitPendingCourseStarted({
+        const result = await emitPendingCourseStarted({
           pluginHost: pluginHostRef.current,
           tracking: trackingRef.current,
           xapi: xapiRef.current,
@@ -678,7 +756,10 @@ function useLessonkitProviderRuntime(config) {
     [track]
   );
   const completeLesson = useCallback(
-    (lessonId) => {
+    (lessonId, opts) => {
+      if (opts?.courseId !== void 0 && opts.courseId !== courseIdRef.current) {
+        return;
+      }
       if (useV2Runtime && headlessRef.current) {
         headlessRef.current.completeLesson(lessonId, emitLifecycleEvent);
         syncProgress();
@@ -896,7 +977,7 @@ function useEnclosingLessonId() {
 
 // src/runtime/validateComponentId.ts
 import { assertValidId as assertValidId2 } from "@lessonkit/core";
-function isDevEnvironment3() {
+function isDevEnvironment4() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
@@ -912,7 +993,7 @@ function normalizeComponentId(id, path) {
 var mountCounts = /* @__PURE__ */ new Map();
 var warnedConcurrentLessons = false;
 function registerLessonMount(lessonId) {
-  if (isDevEnvironment3() && mountCounts.size > 0 && !mountCounts.has(lessonId) && !warnedConcurrentLessons) {
+  if (isDevEnvironment4() && mountCounts.size > 0 && !mountCounts.has(lessonId) && !warnedConcurrentLessons) {
     warnedConcurrentLessons = true;
     console.warn(
       "[lessonkit] Multiple <Lesson> components are mounted; only one should be active at a time. Set autoCompleteOnUnmount={false} on routed lessons or unmount the previous lesson before showing the next."
@@ -955,9 +1036,18 @@ function Lesson(props) {
   const { setActiveLesson, config } = useLessonkit();
   const { completeLesson } = useCompletion();
   const lessonMountGenerationRef = useRef2(0);
+  const liveCourseIdRef = useRef2(config.courseId);
+  liveCourseIdRef.current = config.courseId;
   useEffect2(() => {
     const unregister = registerLessonMount(lessonId);
     const generation = ++lessonMountGenerationRef.current;
+    const mountedCourseId = config.courseId;
+    let effectSurvivedTick = false;
+    queueMicrotask(() => {
+      queueMicrotask(() => {
+        effectSurvivedTick = true;
+      });
+    });
     setActiveLesson(lessonId);
     return () => {
       unregister();
@@ -966,8 +1056,10 @@ function Lesson(props) {
       }
       if (!autoComplete) return;
       queueMicrotask(() => {
+        if (!effectSurvivedTick) return;
         if (lessonMountGenerationRef.current !== generation) return;
-        completeLesson(lessonId);
+        if (liveCourseIdRef.current !== mountedCourseId) return;
+        completeLesson(lessonId, { courseId: mountedCourseId });
       });
     };
   }, [lessonId, config.courseId, setActiveLesson, completeLesson, autoComplete]);
@@ -1026,11 +1118,10 @@ function KnowledgeCheck(props) {
   );
 }
 function Quiz(props) {
-  const checkId = useMemo3(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
   const enclosingLessonId = useEnclosingLessonId();
   const missingLesson = enclosingLessonId === void 0;
   useEffect2(() => {
-    if (!missingLesson || isDevEnvironment3()) return;
+    if (!missingLesson || isDevEnvironment4()) return;
     if (!warnedQuizOutsideLesson) {
       warnedQuizOutsideLesson = true;
       console.error(
@@ -1038,9 +1129,17 @@ function Quiz(props) {
       );
     }
   }, [missingLesson]);
-  if (missingLesson && isDevEnvironment3()) {
+  if (missingLesson && isDevEnvironment4()) {
     throw new Error("[lessonkit] <Quiz> must be wrapped in <Lesson>");
   }
+  if (missingLesson) {
+    return /* @__PURE__ */ jsx2("section", { role: "alert", "aria-label": "Quiz configuration error", "data-lk-check-id": props.checkId, children: /* @__PURE__ */ jsx2("p", { children: "Quiz must be placed inside a Lesson." }) });
+  }
+  return /* @__PURE__ */ jsx2(QuizInner, { ...props, enclosingLessonId });
+}
+function QuizInner(props) {
+  const { enclosingLessonId } = props;
+  const checkId = useMemo3(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
   const quiz = useQuizState(enclosingLessonId);
   const { plugins, config, session } = useLessonkit();
   const [selected, setSelected] = useState2(null);
@@ -1063,9 +1162,6 @@ function Quiz(props) {
     }
     return choice === props.answer;
   };
-  if (missingLesson) {
-    return /* @__PURE__ */ jsx2("section", { role: "alert", "aria-label": "Quiz configuration error", "data-lk-check-id": checkId, children: /* @__PURE__ */ jsx2("p", { children: "Quiz must be placed inside a Lesson." }) });
-  }
   const passed = quizPassed;
   return /* @__PURE__ */ jsxs("section", { "aria-label": "Quiz", "data-lk-check-id": checkId, children: [
     /* @__PURE__ */ jsx2("p", { id: questionId, children: props.question }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "private": false,
   "description": "React components and hooks for building learning experiences with LessonKit.",
   "license": "Apache-2.0",
@@ -56,11 +56,11 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@lessonkit/accessibility": "1.0.1",
-    "@lessonkit/core": "1.0.1",
-    "@lessonkit/lxpack": "1.0.1",
-    "@lessonkit/themes": "1.0.1",
-    "@lessonkit/xapi": "1.0.1"
+    "@lessonkit/accessibility": "1.0.2",
+    "@lessonkit/core": "1.0.2",
+    "@lessonkit/lxpack": "1.0.2",
+    "@lessonkit/themes": "1.0.2",
+    "@lessonkit/xapi": "1.0.2"
   },
   "devDependencies": {
     "@storybook/addon-essentials": "8.6.18",
@@ -80,6 +80,6 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   }
 }