@lessonkit/react 1.3.0 → 1.3.1

package/dist/index.cjs

@@ -99,6 +99,7 @@ var import_core8 = require("@lessonkit/core");
 
 // src/runtime/observability.ts
 var import_xapi = require("@lessonkit/xapi");
+var import_meta = {};
 function createXapiQueueFromObservability(observability) {
   const opts = {};
   if (observability?.onXapiQueueDepth) {
@@ -109,6 +110,44 @@ function createXapiQueueFromObservability(observability) {
   }
   return (0, import_xapi.createInMemoryXAPIQueue)(opts);
 }
+function wrapBatchSink(batchSink, observability) {
+  if (!batchSink || !observability?.onTelemetrySinkError) return batchSink;
+  const onError = observability.onTelemetrySinkError;
+  return async (events) => {
+    try {
+      await batchSink(events);
+    } catch (err) {
+      onError(err, { sinkId: "tracking-batch" });
+      throw err;
+    }
+  };
+}
+function warnMissingProductionObservability(observability, opts) {
+  let isProduction = false;
+  try {
+    isProduction = import_meta.env?.PROD === true;
+  } catch {
+  }
+  if (!isProduction) {
+    const g = globalThis;
+    isProduction = typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production";
+  }
+  if (!isProduction) return;
+  if (!opts.trackingEnabled && !opts.xapiEnabled) return;
+  const hooks = [
+    observability?.onTelemetrySinkError,
+    observability?.onTelemetryBufferDrop,
+    observability?.onXapiQueueDepth,
+    observability?.onXapiQueueCap,
+    observability?.onLxpackBridgeMiss
+  ];
+  if (hooks.some(Boolean)) return;
+  if (typeof console !== "undefined") {
+    console.warn(
+      "[lessonkit] Production deployment without observability hooks \u2014 telemetry/xAPI failures and buffer drops will be silent. See https://lessonkit.readthedocs.io/en/latest/guides/react-developers/production-checklist.html"
+    );
+  }
+}
 function wrapTrackingSink(sink, observability) {
   if (!sink || !observability?.onTelemetrySinkError) return sink;
   const onError = observability.onTelemetrySinkError;
@@ -235,6 +274,7 @@ function createXapiClientFromConfig(config, queue) {
   return (0, import_xapi3.createXAPIClient)({
     courseId: config.courseId,
     transport: config.xapi?.transport,
+    exitTransport: config.xapi?.exitTransport,
     queue
   });
 }
@@ -283,6 +323,7 @@ async function emitCourseStartedNonTrackingPipeline(opts) {
     const statement = (0, import_xapi4.telemetryEventToXAPIStatement)(opts.event);
     if (statement) {
       opts.xapi.send(statement);
+      await opts.xapi.flush();
       xapiStatementSent = true;
     }
   }
@@ -318,7 +359,7 @@ function emitTelemetryWithPlugins(opts) {
 }
 
 // src/provider/courseStarted/emit.ts
-var courseStartedTrackingFlightKey = null;
+var courseStartedTrackingFlights = /* @__PURE__ */ new Map();
 function isTrackingActive(tracking) {
   return tracking?.enabled !== false;
 }
@@ -346,25 +387,40 @@ async function emitCourseStartedToTracking(tracking, storage, sessionId, courseI
   if ((0, import_core5.hasCourseStartedEmittedToTracking)(storage, sessionId, courseId)) {
     return true;
   }
-  if (courseStartedTrackingFlightKey === flightKey) {
-    return false;
+  const existing = courseStartedTrackingFlights.get(flightKey);
+  if (existing) {
+    const settled = await existing;
+    if (settled) return true;
   }
-  courseStartedTrackingFlightKey = flightKey;
-  try {
-    if (shouldCommit && !shouldCommit()) return false;
-    tracking.track(event);
-    (0, import_core5.markCourseStartedEmittedToTracking)(storage, sessionId, courseId);
-    const delivered = await tracking.flush?.();
-    if (delivered === false) return false;
-    if (shouldCommit && !shouldCommit()) return false;
-    return true;
-  } catch {
-    return false;
-  } finally {
-    if (courseStartedTrackingFlightKey === flightKey) {
-      courseStartedTrackingFlightKey = null;
+  let resolveFlight;
+  const flight = new Promise((resolve) => {
+    resolveFlight = resolve;
+  });
+  courseStartedTrackingFlights.set(flightKey, flight);
+  void (async () => {
+    try {
+      if (shouldCommit && !shouldCommit()) {
+        resolveFlight(false);
+        return;
+      }
+      tracking.track(event);
+      const delivered = await tracking.flush?.();
+      if (delivered === false) {
+        resolveFlight(false);
+        return;
+      }
+      if ((0, import_core5.markCourseStartedEmittedToTracking)(storage, sessionId, courseId) === false) {
+        resolveFlight(false);
+        return;
+      }
+      resolveFlight(true);
+    } catch {
+      resolveFlight(false);
+    } finally {
+      courseStartedTrackingFlights.delete(flightKey);
     }
-  }
+  })();
+  return flight;
 }
 async function emitCourseStartedPipelineOnly(opts) {
   try {
@@ -378,8 +434,10 @@ async function emitCourseStartedPipelineOnly(opts) {
       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 ((0, import_core5.markCourseStarted)(opts.storage, opts.sessionId, opts.courseId) === false) return "failed";
+    if ((0, import_core5.markCourseStartedPipelineDelivered)(opts.storage, opts.sessionId, opts.courseId) === false) {
+      return "failed";
+    }
     if (xapiStatementSent) {
       opts.onXapiStatementSent?.();
     }
@@ -430,7 +488,9 @@ async function emitCourseStartedToTrackingOnly(opts) {
       extraSinks: opts.extraSinks,
       skipXapi: true
     });
-    (0, import_core5.markCourseStartedPipelineDelivered)(opts.storage, opts.sessionId, opts.courseId);
+    if ((0, import_core5.markCourseStartedPipelineDelivered)(opts.storage, opts.sessionId, opts.courseId) === false) {
+      return "failed";
+    }
     return "emitted";
   } catch {
     return "failed";
@@ -490,6 +550,7 @@ function createTrackingClientFromConfig(config, observability) {
     sink: config.tracking?.sink,
     batchSink: config.tracking?.batchSink,
     batch: config.tracking?.batch,
+    exitBatchSink: config.tracking?.exitBatchSink,
     onBufferDrop: observability?.onTelemetryBufferDrop
   });
 }
@@ -565,6 +626,7 @@ function useLessonkitProviderRuntime(config) {
   const pendingCourseIdResetRef = (0, import_react.useRef)(false);
   const prevUseV2RuntimeRef = (0, import_react.useRef)(useV2Runtime);
   const xapiCourseStartedSentOnClientRef = (0, import_react.useRef)(false);
+  const xapiBootstrapSendRef = (0, import_react.useRef)(false);
   if (prevUseV2RuntimeRef.current !== useV2Runtime) {
     prevUseV2RuntimeRef.current = useV2Runtime;
     if (useV2Runtime) {
@@ -637,19 +699,22 @@ function useLessonkitProviderRuntime(config) {
       xapiQueueRef.current = createXapiQueueFromObservability(observabilityRef.current);
       prevXapiCourseIdRef.current = courseId;
       xapiCourseStartedSentOnClientRef.current = false;
+      xapiBootstrapSendRef.current = false;
     }
     const prev = xapiRef.current;
     const next = createXapiClientFromConfig(normalizedConfig, xapiQueueRef.current);
     xapiRef.current = next;
     setXapi(next);
+    let bootstrapSent = false;
+    let bootstrapAlreadyStarted = false;
     if (next) {
       const sessionId = sessionIdRef.current;
       const cid = courseIdRef.current;
       const trackingActive = isTrackingActive(normalizedConfig.tracking);
-      const alreadyStarted = (0, import_core5.hasCourseStarted)(defaultStorage, sessionId, cid);
+      bootstrapAlreadyStarted = (0, import_core5.hasCourseStarted)(defaultStorage, sessionId, cid);
       const clientChanged = !prev || prev !== next;
-      const skipBootstrap = trackingActive && !alreadyStarted;
-      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && (!alreadyStarted || clientChanged);
+      const skipBootstrap = trackingActive && !bootstrapAlreadyStarted;
+      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && !xapiBootstrapSendRef.current && (!bootstrapAlreadyStarted || clientChanged);
       if (needsBootstrap) {
         try {
           const event = buildCourseStartedEvent({
@@ -660,15 +725,12 @@ function useLessonkitProviderRuntime(config) {
             user: userRef.current,
             lxpackBridge: lxpackBridgeModeRef.current
           });
-          if (event === null) {
-          } else {
+          if (event !== null) {
             const statement = (0, import_xapi5.telemetryEventToXAPIStatement)(event);
             if (statement) {
               next.send(statement);
-              if (!alreadyStarted) {
-                (0, import_core5.markCourseStarted)(defaultStorage, sessionId, cid);
-              }
-              xapiCourseStartedSentOnClientRef.current = true;
+              xapiBootstrapSendRef.current = true;
+              bootstrapSent = true;
             }
           }
         } catch {
@@ -686,6 +748,12 @@ function useLessonkitProviderRuntime(config) {
       if (cancelled) return;
       try {
         await next?.flush();
+        if (bootstrapSent && !cancelled) {
+          if (!bootstrapAlreadyStarted) {
+            (0, import_core5.markCourseStarted)(defaultStorage, sessionIdRef.current, courseIdRef.current);
+          }
+          xapiCourseStartedSentOnClientRef.current = true;
+        }
       } catch {
       }
     })();
@@ -714,7 +782,10 @@ function useLessonkitProviderRuntime(config) {
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
     const baseSink = wrapTrackingSink(normalizedConfig.tracking?.sink, observabilityRef.current);
-    const userBatchSink = normalizedConfig.tracking?.batchSink;
+    const userBatchSink = wrapBatchSink(
+      normalizedConfig.tracking?.batchSink,
+      observabilityRef.current
+    );
     assertTrackingSinkConfig(normalizedConfig.tracking);
     const sink = pluginHostRef.current && baseSink ? (
       /* v8 ignore next -- composeTrackingSink may return null; fall back to base sink */
@@ -868,7 +939,11 @@ function useLessonkitProviderRuntime(config) {
           user: userRef.current,
           lxpackBridge: lxpackBridgeModeRef.current,
           onLxpackBridgeMiss,
-          extraSinks: extraSinksRef.current
+          extraSinks: extraSinksRef.current,
+          skipXapi: xapiCourseStartedSentOnClientRef.current,
+          onXapiStatementSent: () => {
+            xapiCourseStartedSentOnClientRef.current = true;
+          }
         });
         courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
       }
@@ -924,20 +999,39 @@ function useLessonkitProviderRuntime(config) {
   }, []);
   (0, import_react.useEffect)(() => {
     if (typeof document === "undefined") return;
-    const flushOnExit = () => {
-      void xapiRef.current?.flush();
-      void trackingRef.current?.flush?.();
+    const flushOnPageExit = () => {
+      try {
+        xapiRef.current?.flushOnExit?.();
+        trackingRef.current?.flushOnExit?.();
+      } finally {
+        void xapiRef.current?.flush();
+        void trackingRef.current?.flush?.();
+      }
     };
     const onVisibilityChange = () => {
-      if (document.visibilityState === "hidden") flushOnExit();
+      if (document.visibilityState === "hidden") flushOnPageExit();
     };
     document.addEventListener("visibilitychange", onVisibilityChange);
-    window.addEventListener("pagehide", flushOnExit);
+    window.addEventListener("pagehide", flushOnPageExit);
     return () => {
       document.removeEventListener("visibilitychange", onVisibilityChange);
-      window.removeEventListener("pagehide", flushOnExit);
+      window.removeEventListener("pagehide", flushOnPageExit);
     };
   }, []);
+  (0, import_react.useEffect)(() => {
+    warnMissingProductionObservability(observabilityRef.current, {
+      trackingEnabled: isTrackingActive(normalizedConfig.tracking),
+      xapiEnabled: normalizedConfig.xapi?.enabled !== false && Boolean(
+        normalizedConfig.xapi?.client || normalizedConfig.xapi?.transport || normalizedConfig.xapi?.enabled === true
+      )
+    });
+  }, [
+    normalizedConfig.tracking,
+    normalizedConfig.xapi?.enabled,
+    normalizedConfig.xapi?.client,
+    normalizedConfig.xapi?.transport,
+    normalizedConfig.observability
+  ]);
   const setActiveLesson = (0, import_react.useCallback)(
     (lessonId) => {
       if (useV2Runtime && headlessRef.current) {
@@ -2210,9 +2304,13 @@ function FillInTheBlanksInner(props, ref) {
   const [submitted, setSubmitted] = (0, import_react16.useState)(false);
   const completedRef = (0, import_react16.useRef)(false);
   const answeredRef = (0, import_react16.useRef)(false);
+  const checkSnapshotRef = (0, import_react16.useRef)(null);
+  const telemetryReplayedRef = (0, import_react16.useRef)(false);
   const reset = () => {
     completedRef.current = false;
     answeredRef.current = false;
+    checkSnapshotRef.current = null;
+    telemetryReplayedRef.current = false;
     setPassed(false);
     setValues(Object.fromEntries(blanks.map((b) => [b.id, ""])));
     setShowSolutions(false);
@@ -2229,6 +2327,31 @@ function FillInTheBlanksInner(props, ref) {
   });
   const maxScore = blanks.length;
   const passedThreshold = meetsPassingThreshold(score, maxScore || 1, props.passingScore);
+  const replayTelemetry = (nextValues, nextPassed, nextSubmitted, nextScore, nextMaxScore) => {
+    if (telemetryReplayedRef.current || !nextSubmitted && !nextPassed) return;
+    telemetryReplayedRef.current = true;
+    const nextPassedThreshold = meetsPassingThreshold(
+      nextScore,
+      nextMaxScore || 1,
+      props.passingScore
+    );
+    assessment.answer({
+      checkId,
+      interactionType: INTERACTION3,
+      question: props.template,
+      response: nextValues,
+      correct: nextPassedThreshold
+    });
+    if (nextPassed || nextPassedThreshold) {
+      assessment.complete({
+        checkId,
+        interactionType: INTERACTION3,
+        score: nextScore,
+        maxScore: nextMaxScore,
+        passingScore: props.passingScore ?? nextMaxScore
+      });
+    }
+  };
   const handle = (0, import_react16.useMemo)(
     () => buildAssessmentHandle({
       checkId,
@@ -2248,20 +2371,33 @@ function FillInTheBlanksInner(props, ref) {
       getCurrentState: () => ({ values, passed, showSolutions, submitted }),
       resume: (state) => {
         const raw = state.values;
-        if (raw && typeof raw === "object") setValues({ ...raw });
+        let nextValues = values;
+        if (raw && typeof raw === "object") {
+          nextValues = { ...raw };
+          setValues(nextValues);
+        }
+        let nextPassed = passed;
+        let nextSubmitted = submitted;
         readBooleanStateField(state, "passed", (value) => {
+          nextPassed = value;
           setPassed(value);
           completedRef.current = value;
           answeredRef.current = value;
         });
         readBooleanStateField(state, "showSolutions", setShowSolutions);
         readBooleanStateField(state, "submitted", (value) => {
+          nextSubmitted = value;
           setSubmitted(value);
           if (value) answeredRef.current = true;
         });
+        let nextScore = 0;
+        blanks.forEach((b) => {
+          if ((nextValues[b.id] ?? "").trim().toLowerCase() === b.answer.toLowerCase()) nextScore += 1;
+        });
+        replayTelemetry(nextValues, nextPassed, nextSubmitted, nextScore, blanks.length);
       }
     }),
-    [allFilled, checkId, maxScore, passed, passedThreshold, score, showSolutions, submitted, values]
+    [allFilled, assessment, blanks, checkId, maxScore, passed, passedThreshold, props.passingScore, props.template, score, showSolutions, submitted, values]
   );
   useAssessmentHandleRegistration(checkId, handle, ref);
   const check = () => {
@@ -2272,7 +2408,10 @@ function FillInTheBlanksInner(props, ref) {
       return;
     }
     if (!allFilled) return;
-    if (answeredRef.current || submitted) return;
+    if (passed) return;
+    const snapshot = JSON.stringify(values);
+    if (checkSnapshotRef.current === snapshot) return;
+    checkSnapshotRef.current = snapshot;
     answeredRef.current = true;
     setSubmitted(true);
     assessment.answer({
@@ -2297,12 +2436,13 @@ function FillInTheBlanksInner(props, ref) {
   (0, import_react16.useEffect)(() => {
     if (!allFilled) {
       answeredRef.current = false;
+      checkSnapshotRef.current = null;
       setSubmitted(false);
     }
   }, [allFilled]);
   (0, import_react16.useEffect)(() => {
-    if (props.autoCheck && allFilled) check();
-  }, [allFilled, props.autoCheck, values, passedThreshold]);
+    if (props.autoCheck && allFilled && !passed) check();
+  }, [allFilled, props.autoCheck, values, passedThreshold, passed]);
   const reveal = showSolutions || passed && props.enableSolutionsButton;
   return /* @__PURE__ */ (0, import_jsx_runtime10.jsxs)("section", { "aria-label": "Fill in the Blanks", "data-lk-check-id": checkId, children: [
     /* @__PURE__ */ (0, import_jsx_runtime10.jsx)("p", { children: parsed.parts.map((part, i) => {
@@ -2361,9 +2501,13 @@ function DragTheWordsInner(props, ref) {
   const [submitted, setSubmitted] = (0, import_react17.useState)(false);
   const completedRef = (0, import_react17.useRef)(false);
   const answeredRef = (0, import_react17.useRef)(false);
+  const checkSnapshotRef = (0, import_react17.useRef)(null);
+  const telemetryReplayedRef = (0, import_react17.useRef)(false);
   const reset = () => {
     completedRef.current = false;
     answeredRef.current = false;
+    checkSnapshotRef.current = null;
+    telemetryReplayedRef.current = false;
     setPassed(false);
     setSubmitted(false);
     setZones(Object.fromEntries(answers.map((_, i) => [`zone-${i}`, ""])));
@@ -2381,6 +2525,31 @@ function DragTheWordsInner(props, ref) {
   });
   const maxScore = answers.length;
   const passedThreshold = meetsPassingThreshold(score, maxScore || 1, props.passingScore);
+  const replayTelemetry = (nextZones, nextPassed, nextSubmitted, nextScore, nextMaxScore) => {
+    if (telemetryReplayedRef.current || !nextSubmitted && !nextPassed) return;
+    telemetryReplayedRef.current = true;
+    const nextPassedThreshold = meetsPassingThreshold(
+      nextScore,
+      nextMaxScore || 1,
+      props.passingScore
+    );
+    assessment.answer({
+      checkId,
+      interactionType: INTERACTION4,
+      question: props.template,
+      response: nextZones,
+      correct: nextPassedThreshold
+    });
+    if (nextPassed || nextPassedThreshold) {
+      assessment.complete({
+        checkId,
+        interactionType: INTERACTION4,
+        score: nextScore,
+        maxScore: nextMaxScore,
+        passingScore: props.passingScore ?? nextMaxScore
+      });
+    }
+  };
   const handle = (0, import_react17.useMemo)(
     () => buildAssessmentHandle({
       checkId,
@@ -2401,22 +2570,35 @@ function DragTheWordsInner(props, ref) {
       getCurrentState: () => ({ zones, pool, passed, keyboardWord, submitted }),
       resume: (state) => {
         const rawZones = state.zones;
-        if (rawZones && typeof rawZones === "object") setZones({ ...rawZones });
+        let nextZones = zones;
+        if (rawZones && typeof rawZones === "object") {
+          nextZones = { ...rawZones };
+          setZones(nextZones);
+        }
         if (Array.isArray(state.pool)) setPool([...state.pool]);
+        let nextPassed = passed;
+        let nextSubmitted = submitted;
         readBooleanStateField(state, "passed", (value) => {
+          nextPassed = value;
           setPassed(value);
           completedRef.current = value;
           answeredRef.current = value;
         });
         readBooleanStateField(state, "submitted", (value) => {
+          nextSubmitted = value;
           setSubmitted(value);
           if (value) answeredRef.current = true;
         });
         const kw = state.keyboardWord;
         if (kw === null || typeof kw === "string") setKeyboardWord(kw ?? null);
+        let nextScore = 0;
+        answers.forEach((ans, i) => {
+          if ((nextZones[`zone-${i}`] ?? "").trim().toLowerCase() === ans.toLowerCase()) nextScore += 1;
+        });
+        replayTelemetry(nextZones, nextPassed, nextSubmitted, nextScore, answers.length);
       }
     }),
-    [allFilled, checkId, keyboardWord, maxScore, passed, passedThreshold, pool, score, submitted, zones]
+    [allFilled, answers, assessment, checkId, keyboardWord, maxScore, passed, passedThreshold, pool, props.passingScore, props.template, score, submitted, zones]
   );
   useAssessmentHandleRegistration(checkId, handle, ref);
   const placeInZone = (zoneId, word) => {
@@ -2446,7 +2628,10 @@ function DragTheWordsInner(props, ref) {
       return;
     }
     if (!allFilled) return;
-    if (answeredRef.current || submitted) return;
+    if (passed) return;
+    const snapshot = JSON.stringify(zones);
+    if (checkSnapshotRef.current === snapshot) return;
+    checkSnapshotRef.current = snapshot;
     answeredRef.current = true;
     setSubmitted(true);
     assessment.answer({
@@ -2471,12 +2656,13 @@ function DragTheWordsInner(props, ref) {
   (0, import_react17.useEffect)(() => {
     if (!allFilled) {
       answeredRef.current = false;
+      checkSnapshotRef.current = null;
       setSubmitted(false);
     }
   }, [allFilled]);
   (0, import_react17.useEffect)(() => {
-    if (props.autoCheck && allFilled) check();
-  }, [allFilled, props.autoCheck, zones, passedThreshold]);
+    if (props.autoCheck && allFilled && !passed) check();
+  }, [allFilled, props.autoCheck, zones, passedThreshold, passed]);
   return /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("section", { "aria-label": "Drag the Words", "data-lk-check-id": checkId, children: [
     /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("p", { children: "Drag words into the blanks (or select a word, then activate a blank)." }),
     /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("div", { role: "list", "aria-label": "Word bank", "data-testid": "word-bank", children: pool.map((word) => /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(
@@ -2876,6 +3062,8 @@ function useCompoundPersistence(opts) {
   }, [ctx, opts.index, opts.pageCount]);
   const buildStateRef = (0, import_react21.useRef)(buildState);
   buildStateRef.current = buildState;
+  const persistNowRef = (0, import_react21.useRef)(() => {
+  });
   const finalizeHydration = (0, import_react21.useCallback)(
     (childStates) => {
       loadedChildStatesRef.current = {
@@ -2884,6 +3072,7 @@ function useCompoundPersistence(opts) {
       };
       skipSaveUntilHydratedRef.current = false;
       pendingChildResumeRef.current = null;
+      queueMicrotask(() => persistNowRef.current());
     },
     []
   );
@@ -2896,6 +3085,14 @@ function useCompoundPersistence(opts) {
       alreadyResumed: resumedChildKeysRef.current
     });
     if (!applied) {
+      if (handles.size === 0) {
+        const registeredOnly2 = stripOrphanChildStates(handles, pending.childStates);
+        resumeChildHandles(handles, registeredOnly2, {
+          alreadyResumed: resumedChildKeysRef.current
+        });
+        finalizeHydration(registeredOnly2);
+        return;
+      }
       const handlesAtWait = handles.size;
       queueMicrotask(() => {
         if (pendingChildResumeRef.current !== pending) return;
@@ -2929,8 +3126,12 @@ function useCompoundPersistence(opts) {
   });
   const persistNow = (0, import_react21.useCallback)(() => {
     if (!opts.enabled || !opts.courseId) return;
+    if (skipSaveUntilHydratedRef.current) return;
     saveResume(buildStateRef.current());
   }, [opts.enabled, opts.courseId, saveResume]);
+  (0, import_react21.useEffect)(() => {
+    persistNowRef.current = persistNow;
+  }, [persistNow]);
   const notifyImperativeResume = (0, import_react21.useCallback)(
     (state) => {
       const clamped = (0, import_core14.clampCompoundPageIndex)(state.activePageIndex, opts.pageCount);
@@ -2952,12 +3153,12 @@ function useCompoundPersistence(opts) {
       }
     };
   }, [bridgeRef, notifyImperativeResume]);
-  (0, import_react21.useEffect)(() => {
-    persistNow();
-  }, [persistNow, opts.index, opts.pageCount, handlesVersion]);
   (0, import_react21.useEffect)(() => {
     applyPendingChildResume();
   }, [opts.index, handlesVersion, applyPendingChildResume]);
+  (0, import_react21.useEffect)(() => {
+    persistNow();
+  }, [persistNow, opts.index, opts.pageCount, handlesVersion]);
   (0, import_react21.useEffect)(() => {
     if (!opts.enabled || !opts.courseId || typeof document === "undefined") return;
     const flushOnExit = () => {
@@ -3900,13 +4101,34 @@ function FindHotspotInner(props, ref) {
   const checkId = (0, import_react36.useMemo)(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
   const [selected, setSelected] = (0, import_react36.useState)(null);
   const [checked, setChecked] = (0, import_react36.useState)(false);
+  const telemetryReplayedRef = (0, import_react36.useRef)(false);
   const assessment = useAssessmentState(props.enclosingLessonId);
   const targetIdsKey = props.targets.map((t) => t.id).join("\0");
   (0, import_react36.useEffect)(() => {
     setSelected(null);
     setChecked(false);
+    telemetryReplayedRef.current = false;
   }, [checkId, props.correctTargetId, targetIdsKey]);
   const correct = selected === props.correctTargetId;
+  const replayTelemetry = (nextSelected, nextChecked, nextCorrect) => {
+    if (telemetryReplayedRef.current || !nextChecked || nextSelected === null) return;
+    telemetryReplayedRef.current = true;
+    assessment.answer({
+      checkId,
+      interactionType: INTERACTION6,
+      response: nextSelected,
+      correct: nextCorrect
+    });
+    if (nextCorrect) {
+      assessment.complete({
+        checkId,
+        interactionType: INTERACTION6,
+        score: 1,
+        maxScore: 1,
+        passingScore: props.passingScore ?? 1
+      });
+    }
+  };
   const handle = (0, import_react36.useMemo)(
     () => buildAssessmentHandle({
       checkId,
@@ -3916,6 +4138,7 @@ function FindHotspotInner(props, ref) {
       resetTask: () => {
         setSelected(null);
         setChecked(false);
+        telemetryReplayedRef.current = false;
       },
       showSolutions: () => setSelected(props.correctTargetId),
       getXAPIData: () => ({
@@ -3928,15 +4151,23 @@ function FindHotspotInner(props, ref) {
       }),
       getCurrentState: () => ({ selected, checked }),
       resume: (state) => {
-        const nextSelected = readStringField(state, "selected");
-        if (typeof nextSelected === "string" || nextSelected === null) {
-          const valid = nextSelected === null || props.targets.some((t) => t.id === nextSelected);
-          setSelected(valid ? nextSelected : null);
+        let nextSelected = selected;
+        const rawSelected = readStringField(state, "selected");
+        if (typeof rawSelected === "string" || rawSelected === null) {
+          const valid = rawSelected === null || props.targets.some((t) => t.id === rawSelected);
+          nextSelected = valid ? rawSelected : null;
+          setSelected(nextSelected);
         }
-        readBooleanStateField(state, "checked", setChecked);
+        let nextChecked = checked;
+        readBooleanStateField(state, "checked", (value) => {
+          nextChecked = value;
+          setChecked(value);
+        });
+        const nextCorrect = nextSelected === props.correctTargetId;
+        replayTelemetry(nextSelected, nextChecked, nextCorrect);
       }
     }),
-    [checkId, selected, checked, correct, props.correctTargetId, props.targets]
+    [assessment, checkId, checked, correct, props.correctTargetId, props.passingScore, props.targets, selected]
   );
   useAssessmentHandleRegistration(checkId, handle, ref);
   const selectTarget = (id) => {

package/dist/index.d.cts

@@ -4,6 +4,7 @@ import * as _lessonkit_core from '@lessonkit/core';
 import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LessonkitPlugin, ProgressState, StoragePort, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, AssessmentHandle, BlockId, AssessmentBaseProps, AssessmentBehaviour, CompoundHandle, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
 export { AssessmentAnsweredData, AssessmentBaseProps, AssessmentBehaviour, AssessmentCompletedData, AssessmentHandle, AssessmentInteractionType, AssessmentScoreInput, AssessmentScoreResult, AssessmentXAPIData, CompoundBaseProps, CompoundHandle, CompoundResumeState, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, PluginHost, PluginRegistry, TelemetryPipelineSink, buildTelemetryEvent, createLessonkitRuntime, createPluginRegistry, createTelemetryPipeline, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin } from '@lessonkit/core';
 import { McqAssessmentDescriptor } from '@lessonkit/lxpack';
+import * as _lessonkit_xapi from '@lessonkit/xapi';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
 import { LxpackBridgeMode } from '@lessonkit/lxpack/bridge';
 import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
@@ -37,6 +38,8 @@ type LessonkitConfig = {
         enabled?: boolean;
         sink?: (event: Parameters<TrackingClient["track"]>[0]) => void | Promise<void>;
         batchSink?: (events: Parameters<TrackingClient["track"]>[0][]) => void | Promise<void>;
+        /** Keepalive batch delivery for pagehide (e.g. from createFetchBatchSink). */
+        exitBatchSink?: (events: Parameters<TrackingClient["track"]>[0][]) => void | Promise<void>;
         batch?: {
             enabled?: boolean;
             flushIntervalMs?: number;
@@ -46,6 +49,8 @@ type LessonkitConfig = {
     xapi?: {
         enabled?: boolean;
         transport?: XAPITransport;
+        /** Keepalive transport for pagehide (e.g. from createFetchTransport). */
+        exitTransport?: _lessonkit_xapi.XAPIExitTransport;
         client?: XAPIClient;
     };
     lxpack?: {