@lessonkit/react 1.0.0 → 1.0.2

package/dist/index.js

@@ -16,7 +16,7 @@ import {
 } from "react";
 import { createLessonkitRuntime, createTrackingClient as createTrackingClient2, assertValidId } from "@lessonkit/core";
 import { createInMemoryXAPIQueue } from "@lessonkit/xapi";
-import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
+import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement3 } from "@lessonkit/xapi";
 
 // src/runtime/emitTelemetry.ts
 import { buildTelemetryEvent, tryBuildTelemetryEvent } from "@lessonkit/core";
@@ -135,9 +135,65 @@ import {
   markCourseStarted,
   hasCourseStartedEmittedToTracking,
   markCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
+  markCourseStartedPipelineDelivered,
   migrateCourseStartedMark
 } from "@lessonkit/core";
 
+// src/runtime/courseStartedPipeline.ts
+import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
+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);
+    if (statement) {
+      opts.xapi.send(statement);
+      xapiStatementSent = true;
+    }
+  }
+  forwardTelemetryToLxpack(opts.event, opts.lxpackBridge);
+  const emitCtx = {
+    courseId: opts.event.courseId,
+    sessionId: opts.event.sessionId,
+    attemptId: opts.event.attemptId
+  };
+  await emitExtraSinks(opts.extraSinks ?? [], opts.event, emitCtx);
+  return { xapiStatementSent };
+}
+
 // src/runtime/plugins.ts
 import { createPluginRegistry } from "@lessonkit/core";
 function createReactPluginHost(plugins) {
@@ -186,11 +242,13 @@ 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;
 }
-var noopTrackingClient = { track: () => {
-} };
+function isCourseStartedSinkSettled(result) {
+  return result === "emitted";
+}
 function buildCourseStartedEvent(opts) {
   const pluginCtx = buildPluginContext({
     courseId: opts.courseId,
@@ -207,85 +265,113 @@ function buildCourseStartedEvent(opts) {
   });
   return opts.pluginHost ? opts.pluginHost.runTelemetry(built, pluginCtx) : built;
 }
-function emitCourseStartedPipelineOnly(opts) {
-  const pluginCtx = buildPluginContext({
-    courseId: opts.courseId,
-    sessionId: opts.sessionId,
-    attemptId: opts.attemptId,
-    user: opts.user
-  });
+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 {
-    emitTelemetryWithPlugins({
-      pluginHost: null,
-      tracking: noopTrackingClient,
-      xapi: opts.xapi,
+    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 {
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    const { xapiStatementSent } = await emitCourseStartedNonTrackingPipeline({
       event: opts.event,
-      pluginCtx,
+      xapi: opts.xapi,
       lxpackBridge: opts.lxpackBridge,
-      extraSinks: opts.extraSinks
+      extraSinks: opts.extraSinks,
+      skipXapi: opts.skipXapi
     });
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
     markCourseStarted(opts.storage, opts.sessionId, opts.courseId);
-    return true;
+    markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId);
+    if (xapiStatementSent) {
+      opts.onXapiStatementSent?.();
+    }
+    return "emitted";
   } catch {
-    return false;
+    return "failed";
   }
 }
-function emitCourseStarted(opts) {
+async function emitCourseStarted(opts) {
   const event = buildCourseStartedEvent(opts);
-  if (event === null) return true;
+  if (event === null) return "filtered";
   const trackingAlreadyEmitted = hasCourseStartedEmittedToTracking(
     opts.storage,
     opts.sessionId,
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      markCourseStartedEmittedToTracking(opts.storage, opts.sessionId, opts.courseId);
-    } catch {
-      return false;
-    }
+    const tracked = await emitCourseStartedToTracking(
+      opts.tracking,
+      opts.storage,
+      opts.sessionId,
+      opts.courseId,
+      event,
+      opts.shouldCommit
+    );
+    if (!tracked) return "failed";
   }
-  return emitCourseStartedPipelineOnly({ ...opts, event });
+  return emitCourseStartedPipelineOnly({
+    ...opts,
+    event,
+    skipXapi: opts.skipXapi,
+    onXapiStatementSent: opts.onXapiStatementSent,
+    shouldCommit: opts.shouldCommit
+  });
 }
-function emitCourseStartedToTrackingOnly(opts) {
+async function emitCourseStartedToTrackingOnly(opts) {
   const event = buildCourseStartedEvent(opts);
-  if (event === null) return true;
+  if (event === null) return "filtered";
   const trackingAlreadyEmitted = hasCourseStartedEmittedToTracking(
     opts.storage,
     opts.sessionId,
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      markCourseStartedEmittedToTracking(opts.storage, opts.sessionId, opts.courseId);
-    } catch {
-      return false;
-    }
+    const tracked = await emitCourseStartedToTracking(
+      opts.tracking,
+      opts.storage,
+      opts.sessionId,
+      opts.courseId,
+      event,
+      opts.shouldCommit
+    );
+    if (!tracked) return "failed";
   }
-  const pluginCtx = buildPluginContext({
-    courseId: opts.courseId,
-    sessionId: opts.sessionId,
-    attemptId: opts.attemptId,
-    user: opts.user
-  });
   try {
-    emitTelemetryWithPlugins({
-      pluginHost: null,
-      tracking: noopTrackingClient,
-      xapi: null,
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    await emitCourseStartedNonTrackingPipeline({
       event,
-      pluginCtx,
+      xapi: null,
       lxpackBridge: opts.lxpackBridge,
-      extraSinks: opts.extraSinks
+      extraSinks: opts.extraSinks,
+      skipXapi: true
     });
-    return true;
+    markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId);
+    return "emitted";
   } catch {
-    return false;
+    return "failed";
   }
 }
-function emitPendingCourseStarted(opts) {
+async function emitPendingCourseStarted(opts) {
   const trackingEmitted = hasCourseStartedEmittedToTracking(
     opts.storage,
     opts.sessionId,
@@ -297,13 +383,28 @@ function emitPendingCourseStarted(opts) {
   }
   if (trackingEmitted && !sessionStarted) {
     const event = buildCourseStartedEvent(opts);
-    if (event === null) return true;
+    if (event === null) return "filtered";
     return emitCourseStartedPipelineOnly({ ...opts, event });
   }
   if (!trackingEmitted && !sessionStarted) {
     return emitCourseStarted(opts);
   }
-  return true;
+  const pipelineDelivered = hasCourseStartedPipelineDelivered(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (sessionStarted && trackingEmitted && !pipelineDelivered) {
+    const event = buildCourseStartedEvent(opts);
+    if (event === null) return "filtered";
+    return emitCourseStartedPipelineOnly({
+      ...opts,
+      event,
+      skipXapi: opts.skipXapi,
+      onXapiStatementSent: opts.onXapiStatementSent
+    });
+  }
+  return "emitted";
 }
 function assertTrackingSinkConfig(tracking) {
   if (!tracking?.sink || !tracking?.batchSink) return;
@@ -344,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);
@@ -363,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,
@@ -380,6 +483,7 @@ function useLessonkitProviderRuntime(config) {
     }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
   }
   if (useV2Runtime && headlessRef.current) {
     progressRef.current = headlessRef.current.progress;
@@ -429,21 +533,24 @@ function useLessonkitProviderRuntime(config) {
       const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && (!alreadyStarted || clientChanged);
       if (needsBootstrap) {
         try {
-          const statement = telemetryEventToXAPIStatement2(
-            buildTelemetryEvent({
-              name: "course_started",
-              courseId: cid,
-              sessionId,
-              attemptId: attemptIdRef.current,
-              user: userRef.current
-            })
-          );
-          if (statement) {
-            next.send(statement);
-            if (!alreadyStarted) {
-              markCourseStarted(defaultStorage, sessionId, cid);
+          const event = buildCourseStartedEvent({
+            pluginHost: pluginHostRef.current,
+            courseId: cid,
+            sessionId,
+            attemptId: attemptIdRef.current,
+            user: userRef.current,
+            lxpackBridge: lxpackBridgeModeRef.current
+          });
+          if (event === null) {
+          } else {
+            const statement = telemetryEventToXAPIStatement3(event);
+            if (statement) {
+              next.send(statement);
+              if (!alreadyStarted) {
+                markCourseStarted(defaultStorage, sessionId, cid);
+              }
+              xapiCourseStartedSentOnClientRef.current = true;
             }
-            xapiCourseStartedSentOnClientRef.current = true;
           }
         } catch {
         }
@@ -514,29 +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 emitted = 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
-      });
-      if (emitted) {
-        markCourseStartedEmittedToTracking(defaultStorage, sessionId, cid);
-      }
-      courseStartedEmittedToSinkRef.current = emitted;
-    } 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);
       }
@@ -613,7 +730,7 @@ function useLessonkitProviderRuntime(config) {
       } catch {
       }
       if (!courseStartedEmittedToSinkRef.current) {
-        const emitted = emitPendingCourseStarted({
+        const result = await emitPendingCourseStarted({
           pluginHost: pluginHostRef.current,
           tracking: trackingRef.current,
           xapi: xapiRef.current,
@@ -625,7 +742,7 @@ function useLessonkitProviderRuntime(config) {
           lxpackBridge: lxpackBridgeModeRef.current,
           extraSinks: extraSinksRef.current
         });
-        courseStartedEmittedToSinkRef.current = emitted;
+        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
       }
     })();
   }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress]);
@@ -639,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();
@@ -857,11 +977,15 @@ 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";
 }
 function normalizeComponentId(id, path) {
+  if (path === "courseId") return assertValidId2(id, "courseId");
+  if (path === "lessonId") return assertValidId2(id, "lessonId");
+  if (path === "checkId") return assertValidId2(id, "checkId");
+  if (path === "blockId") return assertValidId2(id, "blockId");
   return assertValidId2(id, path);
 }
 
@@ -869,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."
@@ -912,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();
@@ -923,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]);
@@ -983,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(
@@ -995,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);
@@ -1020,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 }),
@@ -1378,7 +1517,13 @@ var BLOCK_CATALOG = [
       { name: "checkId", type: "CheckId", required: true, description: "Stable check identifier for telemetry and LXPack assessments." },
       { name: "question", type: "string", required: true, description: "Question text shown above choices." },
       { name: "choices", type: "string[]", required: true, description: "Radio button choice labels." },
-      { name: "answer", type: "string", required: true, description: "Correct choice value (must match one choice)." }
+      { name: "answer", type: "string", required: true, description: "Correct choice value (must match one choice)." },
+      {
+        name: "passingScore",
+        type: "number",
+        required: false,
+        description: "Minimum score required to pass (defaults to maxScore when omitted)."
+      }
     ],
     requiredIds: ["checkId"],
     parentConstraints: ["Lesson"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "1.0.0",
+  "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.0",
-    "@lessonkit/core": "1.0.0",
-    "@lessonkit/lxpack": "1.0.0",
-    "@lessonkit/themes": "1.0.0",
-    "@lessonkit/xapi": "1.0.0"
+    "@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"
   }
 }