@lessonkit/react 1.0.0 → 1.0.2

package/block-catalog.v1.json

@@ -247,6 +247,12 @@
           "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": [

package/dist/index.cjs

@@ -70,8 +70,8 @@ var import_react2 = require("react");
 // src/provider/useLessonkitProviderRuntime.ts
 var import_react = require("react");
 var import_core8 = require("@lessonkit/core");
-var import_xapi3 = require("@lessonkit/xapi");
 var import_xapi4 = require("@lessonkit/xapi");
+var import_xapi5 = require("@lessonkit/xapi");
 
 // src/runtime/emitTelemetry.ts
 var import_core2 = require("@lessonkit/core");
@@ -169,6 +169,60 @@ function createXapiClientFromConfig(config, queue) {
 // src/runtime/session.ts
 var import_core5 = require("@lessonkit/core");
 
+// src/runtime/courseStartedPipeline.ts
+var import_xapi3 = require("@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 = (0, import_xapi3.telemetryEventToXAPIStatement)(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
 var import_core6 = require("@lessonkit/core");
 function createReactPluginHost(plugins) {
@@ -217,11 +271,13 @@ 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;
 }
-var noopTrackingClient = { track: () => {
-} };
+function isCourseStartedSinkSettled(result) {
+  return result === "emitted";
+}
 function buildCourseStartedEvent(opts) {
   const pluginCtx = buildPluginContext({
     courseId: opts.courseId,
@@ -238,85 +294,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 ((0, import_core5.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;
+    (0, import_core5.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";
     (0, import_core5.markCourseStarted)(opts.storage, opts.sessionId, opts.courseId);
-    return true;
+    (0, import_core5.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 = (0, import_core5.hasCourseStartedEmittedToTracking)(
     opts.storage,
     opts.sessionId,
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      (0, import_core5.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 = (0, import_core5.hasCourseStartedEmittedToTracking)(
     opts.storage,
     opts.sessionId,
     opts.courseId
   );
   if (!trackingAlreadyEmitted) {
-    try {
-      opts.tracking.track(event);
-      (0, import_core5.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;
+    (0, import_core5.markCourseStartedPipelineDelivered)(opts.storage, opts.sessionId, opts.courseId);
+    return "emitted";
   } catch {
-    return false;
+    return "failed";
   }
 }
-function emitPendingCourseStarted(opts) {
+async function emitPendingCourseStarted(opts) {
   const trackingEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
     opts.storage,
     opts.sessionId,
@@ -328,13 +412,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 = (0, import_core5.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;
@@ -375,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);
@@ -394,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,
@@ -411,6 +512,7 @@ function useLessonkitProviderRuntime(config) {
     }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
   }
   if (useV2Runtime && headlessRef.current) {
     progressRef.current = headlessRef.current.progress;
@@ -421,7 +523,7 @@ function useLessonkitProviderRuntime(config) {
   }, []);
   const activeLessonIdRef = (0, import_react.useRef)(progress.activeLessonId);
   activeLessonIdRef.current = progress.activeLessonId;
-  const xapiQueueRef = (0, import_react.useRef)((0, import_xapi3.createInMemoryXAPIQueue)());
+  const xapiQueueRef = (0, import_react.useRef)((0, import_xapi4.createInMemoryXAPIQueue)());
   const xapiRef = (0, import_react.useRef)(null);
   const [xapi, setXapi] = (0, import_react.useState)(null);
   const prevXapiCourseIdRef = (0, import_react.useRef)(normalizedCourseId);
@@ -442,7 +544,7 @@ function useLessonkitProviderRuntime(config) {
         }
         void xapiRef.current?.flush();
       }
-      xapiQueueRef.current = (0, import_xapi3.createInMemoryXAPIQueue)();
+      xapiQueueRef.current = (0, import_xapi4.createInMemoryXAPIQueue)();
       prevXapiCourseIdRef.current = courseId;
       xapiCourseStartedSentOnClientRef.current = false;
     }
@@ -460,21 +562,24 @@ function useLessonkitProviderRuntime(config) {
       const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && (!alreadyStarted || clientChanged);
       if (needsBootstrap) {
         try {
-          const statement = (0, import_xapi4.telemetryEventToXAPIStatement)(
-            (0, import_core2.buildTelemetryEvent)({
-              name: "course_started",
-              courseId: cid,
-              sessionId,
-              attemptId: attemptIdRef.current,
-              user: userRef.current
-            })
-          );
-          if (statement) {
-            next.send(statement);
-            if (!alreadyStarted) {
-              (0, import_core5.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 = (0, import_xapi5.telemetryEventToXAPIStatement)(event);
+            if (statement) {
+              next.send(statement);
+              if (!alreadyStarted) {
+                (0, import_core5.markCourseStarted)(defaultStorage, sessionId, cid);
+              }
+              xapiCourseStartedSentOnClientRef.current = true;
             }
-            xapiCourseStartedSentOnClientRef.current = true;
           }
         } catch {
         }
@@ -545,29 +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 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) {
-        (0, import_core5.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);
       }
@@ -644,7 +759,7 @@ function useLessonkitProviderRuntime(config) {
       } catch {
       }
       if (!courseStartedEmittedToSinkRef.current) {
-        const emitted = emitPendingCourseStarted({
+        const result = await emitPendingCourseStarted({
           pluginHost: pluginHostRef.current,
           tracking: trackingRef.current,
           xapi: xapiRef.current,
@@ -656,7 +771,7 @@ function useLessonkitProviderRuntime(config) {
           lxpackBridge: lxpackBridgeModeRef.current,
           extraSinks: extraSinksRef.current
         });
-        courseStartedEmittedToSinkRef.current = emitted;
+        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
       }
     })();
   }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress]);
@@ -670,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();
@@ -888,11 +1006,15 @@ 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";
 }
 function normalizeComponentId(id, path) {
+  if (path === "courseId") return (0, import_core9.assertValidId)(id, "courseId");
+  if (path === "lessonId") return (0, import_core9.assertValidId)(id, "lessonId");
+  if (path === "checkId") return (0, import_core9.assertValidId)(id, "checkId");
+  if (path === "blockId") return (0, import_core9.assertValidId)(id, "blockId");
   return (0, import_core9.assertValidId)(id, path);
 }
 
@@ -900,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."
@@ -943,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();
@@ -954,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]);
@@ -1014,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(
@@ -1026,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);
@@ -1051,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 }),
@@ -1386,7 +1523,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"],