@lessonkit/react 1.4.0 → 1.5.0

package/dist/{chunk-TDM3ARE7.js → chunk-7TJQJFYR.js}

@@ -52,103 +52,14 @@ function AssessmentLessonGuard(props) {
   return /* @__PURE__ */ jsx(Fragment, { children: props.children(enclosingLessonId) });
 }
 
-// src/runtime/productionGuard.ts
-function isProductionEnvironment() {
-  try {
-    if (import.meta.env?.PROD === true) return true;
-  } catch {
-  }
-  const g = globalThis;
-  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production";
-}
-function shouldEnforceProductionGuard() {
-  try {
-    if (import.meta.env?.MODE === "test") return false;
-  } catch {
-  }
-  return isProductionEnvironment();
-}
-function looksLikeConsoleSink(fn) {
-  if (typeof fn !== "function") return false;
-  const src = Function.prototype.toString.call(fn);
-  return /console\.(log|debug|info)\s*\(/.test(src);
-}
-function isTrackingDeliveryConfigured(tracking) {
-  if (!tracking || tracking.enabled === false) return false;
-  return Boolean(tracking.sink || tracking.batchSink);
-}
-function isXapiDeliveryConfigured(xapi) {
-  if (!xapi || xapi.enabled === false) return false;
-  if (xapi.client) return true;
-  return typeof xapi.transport === "function";
-}
-function trackingUsesConsole(config) {
-  const tracking = config.tracking;
-  if (!tracking || tracking.enabled === false) return false;
-  if (tracking.batchSink && looksLikeConsoleSink(tracking.batchSink)) return true;
-  if (tracking.sink && looksLikeConsoleSink(tracking.sink)) return true;
-  return false;
-}
-function xapiUsesConsole(config) {
-  const xapi = config.xapi;
-  if (!xapi || xapi.enabled === false || xapi.client) return false;
-  return typeof xapi.transport === "function" && looksLikeConsoleSink(xapi.transport);
-}
-function observabilityIncomplete(observability, opts) {
-  if (!opts.trackingEnabled && !opts.xapiEnabled) return false;
-  const required = [observability?.onLxpackBridgeMiss];
-  if (opts.trackingEnabled) {
-    required.push(observability?.onTelemetrySinkError, observability?.onTelemetryBufferDrop);
-  }
-  if (opts.xapiEnabled) {
-    required.push(
-      observability?.onXapiQueueDepth,
-      observability?.onXapiQueueCap,
-      observability?.onXapiTransportError
-    );
-  }
-  return required.some((hook) => !hook);
-}
-function requiredObservabilityHookCount(opts) {
-  let count = 1;
-  if (opts.trackingEnabled) count += 2;
-  if (opts.xapiEnabled) count += 3;
-  return count;
-}
-function assertProductionCourseConfig(config) {
-  if (!isProductionEnvironment()) return;
-  if (config.tracking && config.tracking.enabled !== false && !isTrackingDeliveryConfigured(config.tracking)) {
-    throw new Error(
-      "[lessonkit] Production build has tracking enabled but no sink or batchSink configured."
-    );
-  }
-  const trackingEnabled = isTrackingDeliveryConfigured(config.tracking);
-  const xapiEnabled = isXapiDeliveryConfigured(config.xapi);
-  if (trackingUsesConsole(config)) {
-    throw new Error(
-      "[lessonkit] Production build uses console telemetry sinks. Wire createFetchBatchSink or a real sink. See production checklist."
-    );
-  }
-  if (xapiUsesConsole(config)) {
-    throw new Error(
-      "[lessonkit] Production build uses console xAPI transport. Wire createFetchTransport to your LRS proxy. See production checklist."
-    );
-  }
-  if (observabilityIncomplete(config.observability, { trackingEnabled, xapiEnabled })) {
-    const hookCount = requiredObservabilityHookCount({ trackingEnabled, xapiEnabled });
-    throw new Error(
-      `[lessonkit] Production build missing observability hooks. Wire all ${hookCount} config.observability callbacks before go-live.`
-    );
-  }
-}
-
 // src/runtime/emitTelemetry.ts
 import { buildTelemetryEvent, tryBuildTelemetryEvent } from "@lessonkit/core";
 
 // src/runtime/telemetryPipeline.ts
 import {
   createTelemetryPipeline,
-  createTrackingPipelineSink
+  createTrackingPipelineSink,
+  isLifecycleTelemetryEvent
 } from "@lessonkit/core";
 import { telemetryEventToXAPIStatement } from "@lessonkit/xapi";
 
@@ -161,16 +72,22 @@ import {
   telemetryEventToLessonkit
 } from "@lessonkit/lxpack/bridge";
 var BRIDGE_MISS_EVENT_NAMES = /* @__PURE__ */ new Set([
+  "course_started",
   "course_completed",
   "lesson_completed",
+  "assessment_answered",
   "assessment_completed",
   "quiz_completed"
 ]);
 function forwardTelemetryToLxpack(event, mode = "auto", opts) {
-  if (mode === "auto" && opts?.onBridgeMiss && BRIDGE_MISS_EVENT_NAMES.has(event.name) && !getLxpackBridge()) {
+  const bridgeOpts = { allowedParentOrigins: opts?.allowedParentOrigins, mode };
+  if (mode === "auto" && opts?.onBridgeMiss && BRIDGE_MISS_EVENT_NAMES.has(event.name) && !getLxpackBridge(void 0, bridgeOpts)) {
     opts.onBridgeMiss(event);
   }
-  forwardTelemetryToBridge(event, mode);
+  forwardTelemetryToBridge(event, mode, void 0, {
+    allowedParentOrigins: opts?.allowedParentOrigins,
+    onBridgeError: opts?.onBridgeError
+  });
 }
 
 // src/runtime/telemetryPipeline.ts
@@ -183,17 +100,34 @@ function createLegacyPipeline(opts, extraSinks = []) {
     createTrackingPipelineSink("tracking", (event) => opts.tracking.track(event)),
     {
       id: "xapi",
-      emit(event) {
+      async emit(event) {
+        let statement;
         try {
-          const statement = telemetryEventToXAPIStatement(event);
-          if (statement) opts.xapi?.send(statement);
+          statement = telemetryEventToXAPIStatement(event);
         } catch (err) {
+          opts.onXapiMappingError?.(err);
           if (isDevEnvironment2()) {
             console.warn(
               "[lessonkit] xAPI mapping skipped:",
               err instanceof Error ? err.message : err
             );
           }
+          return;
+        }
+        if (!statement || !opts.xapi) return;
+        try {
+          opts.xapi.send(statement);
+          if (isLifecycleTelemetryEvent(event.name)) {
+            await opts.xapi.flush();
+          }
+        } catch (err) {
+          opts.onXapiTransportError?.(err);
+          if (isDevEnvironment2()) {
+            console.warn(
+              "[lessonkit] xAPI delivery failed:",
+              err instanceof Error ? err.message : err
+            );
+          }
         }
       }
     },
@@ -201,7 +135,9 @@ function createLegacyPipeline(opts, extraSinks = []) {
       id: "lxpack-bridge",
       emit(event) {
         forwardTelemetryToLxpack(event, opts.lxpackBridge, {
-          onBridgeMiss: opts.onLxpackBridgeMiss
+          onBridgeMiss: opts.onLxpackBridgeMiss,
+          onBridgeError: opts.onLxpackBridgeError,
+          allowedParentOrigins: opts.allowedParentOrigins
         });
       }
     },
@@ -209,7 +145,7 @@ function createLegacyPipeline(opts, extraSinks = []) {
   ]);
 }
 function emitThroughPipeline(event, opts, extraSinks) {
-  createLegacyPipeline(opts, extraSinks).emit(event);
+  return createLegacyPipeline(opts, extraSinks).emit(event);
 }
 
 // src/runtime/emitTelemetry.ts
@@ -230,9 +166,13 @@ function emitTelemetry(tracking, xapi, event, opts) {
     tracking,
     xapi,
     lxpackBridge: opts?.lxpackBridge ?? "auto",
-    onLxpackBridgeMiss: opts?.onLxpackBridgeMiss
+    allowedParentOrigins: opts?.allowedParentOrigins,
+    onLxpackBridgeMiss: opts?.onLxpackBridgeMiss,
+    onLxpackBridgeError: opts?.onLxpackBridgeError,
+    onXapiMappingError: opts?.onXapiMappingError,
+    onXapiTransportError: opts?.onXapiTransportError
   };
-  emitThroughPipeline(event, legacy, opts?.extraSinks);
+  return emitThroughPipeline(event, legacy, opts?.extraSinks);
 }
 
 // src/runtime/courseStartedPipeline.ts
@@ -273,16 +213,34 @@ async function emitExtraSinks(sinks, event, emitCtx) {
 async function emitCourseStartedNonTrackingPipeline(opts) {
   let xapiStatementSent = false;
   if (!opts.skipXapi && opts.xapi) {
-    const statement = telemetryEventToXAPIStatement2(opts.event);
+    let statement;
+    try {
+      statement = telemetryEventToXAPIStatement2(opts.event);
+    } catch (err) {
+      opts.onXapiMappingError?.(err);
+      if (isDevEnvironment4()) {
+        console.warn(
+          "[lessonkit] course_started xAPI mapping skipped:",
+          err instanceof Error ? err.message : err
+        );
+      }
+      statement = null;
+    }
     if (statement) {
       opts.xapi.send(statement);
       await opts.xapi.flush();
       xapiStatementSent = true;
+      opts.onXapiDelivered?.();
     }
   }
   forwardTelemetryToLxpack(opts.event, opts.lxpackBridge, {
-    onBridgeMiss: opts.onLxpackBridgeMiss
+    onBridgeMiss: opts.onLxpackBridgeMiss,
+    onBridgeError: opts.onLxpackBridgeError,
+    allowedParentOrigins: opts.allowedParentOrigins
   });
+  if (opts.onBeforeExtraSinks) {
+    await opts.onBeforeExtraSinks();
+  }
   const emitCtx = {
     courseId: opts.event.courseId,
     sessionId: opts.event.sessionId,
@@ -306,8 +264,12 @@ function emitTelemetryWithPlugins(opts) {
   if (next === null) return;
   emitTelemetry(opts.tracking, opts.xapi, next, {
     lxpackBridge: opts.lxpackBridge ?? "auto",
+    allowedParentOrigins: opts.allowedParentOrigins,
     extraSinks: opts.extraSinks,
-    onLxpackBridgeMiss: opts.onLxpackBridgeMiss
+    onLxpackBridgeMiss: opts.onLxpackBridgeMiss,
+    onLxpackBridgeError: opts.onLxpackBridgeError,
+    onXapiMappingError: opts.onXapiMappingError,
+    onXapiTransportError: opts.onXapiTransportError
   });
 }
 
@@ -322,34 +284,48 @@ import {
   markCourseStartedEmittedToTracking,
   hasCourseStartedPipelineDelivered,
   markCourseStartedPipelineDelivered,
+  hasCourseStartedXapiSent,
+  markCourseStartedXapiSent,
   migrateCourseStartedMark
 } from "@lessonkit/core";
 
 // src/provider/courseStarted/emit.ts
+function createCourseStartedFlightScope() {
+  return {
+    trackingFlights: /* @__PURE__ */ new Map(),
+    emitFlights: /* @__PURE__ */ new Map()
+  };
+}
 function resolveTrackingClient(source) {
   return typeof source === "function" ? source() : source;
 }
-var courseStartedTrackingFlights = /* @__PURE__ */ new Map();
-var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+var defaultFlightScope = createCourseStartedFlightScope();
 function resetCourseStartedTrackingFlightForTests() {
-  courseStartedTrackingFlights.clear();
-  courseStartedEmitFlights.clear();
+  defaultFlightScope.trackingFlights.clear();
+  defaultFlightScope.emitFlights.clear();
+}
+function resetCourseStartedTrackingFlights(scope) {
+  const target = scope ?? defaultFlightScope;
+  target.trackingFlights.clear();
+  target.emitFlights.clear();
+}
+function resolveFlightScope(scope) {
+  return scope ?? defaultFlightScope;
 }
 function isTrackingActive(tracking) {
   return tracking?.enabled !== false;
 }
 function isCourseStartedSinkSettled(result) {
-  return result === "emitted" || result === "filtered";
+  return result === "emitted";
 }
 async function deliverToTracking(client, event) {
   if (client.deliver) {
     return client.deliver(event);
   }
   client.track(event);
-  const flushed = await client.flush?.();
-  if (flushed === false) return false;
-  if (flushed === true) return true;
-  return false;
+  if (!client.flush) return true;
+  const flushed = await client.flush();
+  return flushed !== false;
 }
 function buildCourseStartedEvent(opts) {
   const pluginCtx = buildPluginContext({
@@ -365,14 +341,19 @@ function buildCourseStartedEvent(opts) {
     attemptId: opts.attemptId,
     user: opts.user
   });
-  return opts.pluginHost ? opts.pluginHost.runTelemetry(built, pluginCtx) : built;
+  const withId = {
+    ...built,
+    id: `${opts.sessionId}:${opts.courseId}:course_started`
+  };
+  return opts.pluginHost ? opts.pluginHost.runTelemetry(withId, pluginCtx) : withId;
 }
-async function emitCourseStartedToTracking(tracking, storage, sessionId, courseId, event, shouldCommit) {
+async function emitCourseStartedToTracking(tracking, storage, sessionId, courseId, event, shouldCommit, flightScope) {
+  const scope = resolveFlightScope(flightScope);
   const flightKey = `${sessionId}:${courseId}`;
   if (hasCourseStartedEmittedToTracking(storage, sessionId, courseId)) {
     return true;
   }
-  const existing = courseStartedTrackingFlights.get(flightKey);
+  const existing = scope.trackingFlights.get(flightKey);
   if (existing) {
     return existing;
   }
@@ -380,7 +361,7 @@ async function emitCourseStartedToTracking(tracking, storage, sessionId, courseI
   const flight = new Promise((resolve) => {
     resolveFlight = resolve;
   });
-  courseStartedTrackingFlights.set(flightKey, flight);
+  scope.trackingFlights.set(flightKey, flight);
   void (async () => {
     try {
       if (shouldCommit && !shouldCommit()) {
@@ -398,6 +379,10 @@ async function emitCourseStartedToTracking(tracking, storage, sessionId, courseI
         return;
       }
       if (markCourseStartedEmittedToTracking(storage, sessionId, courseId) === false) {
+        if (hasCourseStartedEmittedToTracking(storage, sessionId, courseId)) {
+          resolveFlight(true);
+          return;
+        }
         resolveFlight(false);
         return;
       }
@@ -405,30 +390,50 @@ async function emitCourseStartedToTracking(tracking, storage, sessionId, courseI
     } catch {
       resolveFlight(false);
     } finally {
-      if (courseStartedTrackingFlights.get(flightKey) === flight) {
-        courseStartedTrackingFlights.delete(flightKey);
+      if (scope.trackingFlights.get(flightKey) === flight) {
+        scope.trackingFlights.delete(flightKey);
       }
     }
   })();
   return flight;
 }
+function resolveSkipXapi(storage, sessionId, courseId, skipXapi) {
+  return Boolean(skipXapi || hasCourseStartedXapiSent(storage, sessionId, courseId));
+}
 async function emitCourseStartedPipelineOnly(opts) {
   try {
     if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    const skipXapi = resolveSkipXapi(opts.storage, opts.sessionId, opts.courseId, opts.skipXapi);
     const { xapiStatementSent } = await emitCourseStartedNonTrackingPipeline({
       event: opts.event,
       xapi: opts.xapi,
       lxpackBridge: opts.lxpackBridge,
+      allowedParentOrigins: opts.allowedParentOrigins,
       onLxpackBridgeMiss: opts.onLxpackBridgeMiss,
+      onLxpackBridgeError: opts.onLxpackBridgeError,
+      onXapiMappingError: opts.onXapiMappingError,
       extraSinks: opts.extraSinks,
-      skipXapi: opts.skipXapi
+      skipXapi,
+      onXapiDelivered: () => {
+        markCourseStartedXapiSent(opts.storage, opts.sessionId, opts.courseId);
+        opts.onXapiStatementSent?.();
+      },
+      onBeforeExtraSinks: async () => {
+        if (opts.shouldCommit && !opts.shouldCommit()) throw new Error("course_started commit aborted");
+        if (markCourseStarted(opts.storage, opts.sessionId, opts.courseId) === false && !hasCourseStarted(opts.storage, opts.sessionId, opts.courseId)) {
+          throw new Error("course_started mark failed");
+        }
+      }
     });
     if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
-    if (markCourseStarted(opts.storage, opts.sessionId, opts.courseId) === false) return "failed";
-    if (markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId) === false) {
+    if (markCourseStarted(opts.storage, opts.sessionId, opts.courseId) === false && !hasCourseStarted(opts.storage, opts.sessionId, opts.courseId)) {
+      return "failed";
+    }
+    if (markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId) === false && !hasCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId)) {
       return "failed";
     }
-    if (xapiStatementSent) {
+    if (xapiStatementSent && !hasCourseStartedXapiSent(opts.storage, opts.sessionId, opts.courseId)) {
+      markCourseStartedXapiSent(opts.storage, opts.sessionId, opts.courseId);
       opts.onXapiStatementSent?.();
     }
     return "emitted";
@@ -445,7 +450,8 @@ async function emitCourseStarted(opts) {
     opts.sessionId,
     opts.courseId,
     event,
-    opts.shouldCommit
+    opts.shouldCommit,
+    opts.flightScope
   );
   if (!tracked) return "failed";
   return emitCourseStartedPipelineOnly({
@@ -465,7 +471,8 @@ async function emitCourseStartedToTrackingOnly(opts) {
     opts.sessionId,
     opts.courseId,
     event,
-    opts.shouldCommit
+    opts.shouldCommit,
+    opts.flightScope
   );
   if (!tracked) return "failed";
   try {
@@ -474,7 +481,10 @@ async function emitCourseStartedToTrackingOnly(opts) {
       event,
       xapi: null,
       lxpackBridge: opts.lxpackBridge,
+      allowedParentOrigins: opts.allowedParentOrigins,
       onLxpackBridgeMiss: opts.onLxpackBridgeMiss,
+      onLxpackBridgeError: opts.onLxpackBridgeError,
+      onXapiMappingError: opts.onXapiMappingError,
       extraSinks: opts.extraSinks,
       skipXapi: true
     });
@@ -487,10 +497,11 @@ async function emitCourseStartedToTrackingOnly(opts) {
   }
 }
 async function emitPendingCourseStarted(opts) {
+  const scope = resolveFlightScope(opts.flightScope);
   const flightKey = `${opts.sessionId}:${opts.courseId}`;
   for (let attempt = 0; attempt < 2; attempt += 1) {
-    const existing = courseStartedEmitFlights.get(flightKey);
-    const flight = existing ?? startPendingCourseStartedFlight(opts, flightKey);
+    const existing = scope.emitFlights.get(flightKey);
+    const flight = existing ?? startPendingCourseStartedFlight(opts, flightKey, scope);
     const result = await flight;
     if (result !== "failed") return result;
     const sessionStarted = hasCourseStarted(opts.storage, opts.sessionId, opts.courseId);
@@ -511,12 +522,12 @@ async function emitPendingCourseStarted(opts) {
   }
   return "failed";
 }
-function startPendingCourseStartedFlight(opts, flightKey) {
+function startPendingCourseStartedFlight(opts, flightKey, scope) {
   const flight = emitPendingCourseStartedInner(opts);
-  courseStartedEmitFlights.set(flightKey, flight);
+  scope.emitFlights.set(flightKey, flight);
   void flight.finally(() => {
-    if (courseStartedEmitFlights.get(flightKey) === flight) {
-      courseStartedEmitFlights.delete(flightKey);
+    if (scope.emitFlights.get(flightKey) === flight) {
+      scope.emitFlights.delete(flightKey);
     }
   });
   return flight;
@@ -536,16 +547,17 @@ async function emitPendingCourseStartedInner(opts) {
   if (sessionStarted && trackingEmitted && pipelineDelivered) {
     return "emitted";
   }
+  const skipXapi = resolveSkipXapi(opts.storage, opts.sessionId, opts.courseId, opts.skipXapi);
   if (sessionStarted && !trackingEmitted) {
     return emitCourseStartedToTrackingOnly(opts);
   }
   if (trackingEmitted && !sessionStarted) {
     const event = buildCourseStartedEvent(opts);
     if (event === null) return "filtered";
-    return emitCourseStartedPipelineOnly({ ...opts, event });
+    return emitCourseStartedPipelineOnly({ ...opts, event, skipXapi });
   }
   if (!trackingEmitted && !sessionStarted) {
-    return emitCourseStarted(opts);
+    return emitCourseStarted({ ...opts, skipXapi });
   }
   if (sessionStarted && trackingEmitted && !pipelineDelivered) {
     const event = buildCourseStartedEvent(opts);
@@ -553,7 +565,7 @@ async function emitPendingCourseStartedInner(opts) {
     return emitCourseStartedPipelineOnly({
       ...opts,
       event,
-      skipXapi: opts.skipXapi,
+      skipXapi,
       onXapiStatementSent: opts.onXapiStatementSent
     });
   }
@@ -566,6 +578,124 @@ function assertTrackingSinkConfig(tracking) {
   );
 }
 
+// src/runtime/productionGuard.ts
+function isProductionEnvironment() {
+  try {
+    if (import.meta.env?.PROD === true) return true;
+  } catch {
+  }
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production";
+}
+function shouldEnforceProductionGuard() {
+  try {
+    if (import.meta.env?.MODE === "test") return false;
+  } catch {
+  }
+  return isProductionEnvironment();
+}
+function looksLikeConsoleSink(fn) {
+  if (typeof fn !== "function") return false;
+  const src = Function.prototype.toString.call(fn);
+  return /console\.(log|debug|info)\s*\(/.test(src);
+}
+function isTrackingDeliveryConfigured(tracking) {
+  if (!tracking || tracking.enabled === false) return false;
+  return Boolean(tracking.sink || tracking.batchSink || tracking.createClient);
+}
+function isXapiDeliveryConfigured(xapi) {
+  if (!xapi || xapi.enabled === false) return false;
+  if (xapi.client) return true;
+  return typeof xapi.transport === "function";
+}
+function trackingUsesConsole(config) {
+  const tracking = config.tracking;
+  if (!tracking || tracking.enabled === false) return false;
+  if (tracking.consoleSink === true) return true;
+  if (tracking.batchSink && looksLikeConsoleSink(tracking.batchSink)) return true;
+  if (tracking.sink && looksLikeConsoleSink(tracking.sink)) return true;
+  return false;
+}
+function xapiUsesConsole(config) {
+  const xapi = config.xapi;
+  if (!xapi || xapi.enabled === false || xapi.client) return false;
+  if (xapi.consoleTransport === true) return true;
+  return typeof xapi.transport === "function" && looksLikeConsoleSink(xapi.transport);
+}
+function observabilityIncomplete(observability, opts) {
+  if (!opts.trackingEnabled && !opts.xapiEnabled) return false;
+  const required = [observability?.onLxpackBridgeMiss];
+  if (opts.trackingEnabled) {
+    required.push(observability?.onTelemetrySinkError, observability?.onTelemetryBufferDrop);
+  }
+  if (opts.xapiEnabled) {
+    required.push(
+      observability?.onXapiQueueDepth,
+      observability?.onXapiQueueCap,
+      observability?.onXapiTransportError,
+      observability?.onXapiMappingError
+    );
+  }
+  return required.some((hook) => !hook);
+}
+function requiredObservabilityHookCount(opts) {
+  let count = 1;
+  if (opts.trackingEnabled) count += 2;
+  if (opts.xapiEnabled) count += 4;
+  return count;
+}
+function warnConsoleSinkHeuristic(config) {
+  if (!isDevEnvironment()) return;
+  if (config.preview?.allowConsoleTelemetry) return;
+  if (looksLikeConsoleSink(config.tracking?.sink) || looksLikeConsoleSink(config.tracking?.batchSink)) {
+    console.warn(
+      "[lessonkit] Telemetry sink looks like console.log; use preview.allowConsoleTelemetry for docs or wire a real sink."
+    );
+  }
+  if (looksLikeConsoleSink(config.xapi?.transport)) {
+    console.warn(
+      "[lessonkit] xAPI transport looks like console.log; use preview.allowConsoleTelemetry for docs or wire createFetchTransport."
+    );
+  }
+}
+function assertProductionCourseConfig(config) {
+  if (!isProductionEnvironment()) {
+    warnConsoleSinkHeuristic(config);
+    return;
+  }
+  assertTrackingSinkConfig(config.tracking);
+  const trackingImplicitlyEnabled = config.tracking === void 0 || config.tracking.enabled !== false;
+  if (trackingImplicitlyEnabled && !isTrackingDeliveryConfigured(config.tracking)) {
+    throw new Error(
+      "[lessonkit] Production build has tracking enabled but no sink or batchSink configured."
+    );
+  }
+  if (config.xapi?.enabled === true && !isXapiDeliveryConfigured(config.xapi)) {
+    throw new Error(
+      "[lessonkit] Production build has xAPI enabled but no transport or client configured."
+    );
+  }
+  const allowConsole = config.preview?.allowConsoleTelemetry === true;
+  const trackingEnabled = isTrackingDeliveryConfigured(config.tracking);
+  const xapiEnabled = isXapiDeliveryConfigured(config.xapi);
+  if (!allowConsole && trackingUsesConsole(config)) {
+    throw new Error(
+      "[lessonkit] Production build uses console telemetry sinks. Wire createFetchBatchSink or a real sink. See production checklist."
+    );
+  }
+  if (!allowConsole && xapiUsesConsole(config)) {
+    throw new Error(
+      "[lessonkit] Production build uses console xAPI transport. Wire createFetchTransport to your LRS proxy. See production checklist."
+    );
+  }
+  if (observabilityIncomplete(config.observability, { trackingEnabled, xapiEnabled })) {
+    const hookCount = requiredObservabilityHookCount({ trackingEnabled, xapiEnabled });
+    throw new Error(
+      `[lessonkit] Production build missing observability hooks. Wire all ${hookCount} config.observability callbacks before go-live.`
+    );
+  }
+}
+
 // src/provider/useLessonkitProviderRuntime.ts
 import {
   useCallback,
@@ -598,6 +728,39 @@ function wrapBatchSink(batchSink, observability) {
     }
   };
 }
+function warnMissingProductionObservability(observability, opts) {
+  let isProduction = false;
+  try {
+    const env = import.meta.env;
+    if (env?.MODE === "test") return;
+    isProduction = 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 required = [observability?.onLxpackBridgeMiss];
+  if (opts.trackingEnabled) {
+    required.push(observability?.onTelemetrySinkError, observability?.onTelemetryBufferDrop);
+  }
+  if (opts.xapiEnabled) {
+    required.push(
+      observability?.onXapiQueueDepth,
+      observability?.onXapiQueueCap,
+      observability?.onXapiTransportError,
+      observability?.onXapiMappingError
+    );
+  }
+  if (!required.some((hook) => !hook)) 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;
@@ -650,7 +813,8 @@ function createXapiClientFromConfig(config, queue, observability) {
     exitTransport: config.xapi?.exitTransport,
     abortInFlight: config.xapi?.abortInFlight,
     queue,
-    onTransportError: observability?.onXapiTransportError
+    onTransportError: observability?.onXapiTransportError,
+    onMappingError: observability?.onXapiMappingError
   });
 }
 
@@ -683,9 +847,12 @@ var useIsoLayoutEffect = (
   /* v8 ignore next -- SSR uses useEffect when window is unavailable */
   typeof window !== "undefined" ? useLayoutEffect : useEffect2
 );
-var defaultStorage = createSessionStoragePort();
+var providerStoragesForTests = /* @__PURE__ */ new Set();
 function resetLessonkitProviderStorageForTests() {
-  resetStoragePortForTests(defaultStorage);
+  for (const storage of providerStoragesForTests) {
+    resetStoragePortForTests(storage);
+  }
+  providerStoragesForTests.clear();
   resetSharedVolatileSessionIdForTests();
 }
 function useLessonkitProviderRuntime(config) {
@@ -699,6 +866,11 @@ function useLessonkitProviderRuntime(config) {
   );
   if (shouldEnforceProductionGuard()) {
     assertProductionCourseConfig(normalizedConfig);
+  } else {
+    warnMissingProductionObservability(normalizedConfig.observability, {
+      trackingEnabled: isTrackingDeliveryConfigured(normalizedConfig.tracking),
+      xapiEnabled: isXapiDeliveryConfigured(normalizedConfig.xapi)
+    });
   }
   const useV2Runtime = normalizedConfig.runtimeVersion !== "v1";
   useEffect2(() => {
@@ -712,13 +884,17 @@ function useLessonkitProviderRuntime(config) {
   const extraSinksRef = useRef(normalizedConfig.sinks);
   extraSinksRef.current = normalizedConfig.sinks;
   const headlessRef = useRef(null);
-  const sessionIdRef = useRef(resolveSessionId(defaultStorage, normalizedConfig.session?.sessionId));
-  const prevConfiguredSessionIdRef = useRef(normalizedConfig.session?.sessionId);
-  if (normalizedConfig.session?.sessionId) {
-    sessionIdRef.current = normalizedConfig.session.sessionId;
-  } else if (prevConfiguredSessionIdRef.current) {
-    sessionIdRef.current = resolveSessionId(defaultStorage, void 0);
+  const providerStorageRef = useRef(null);
+  if (!providerStorageRef.current) {
+    providerStorageRef.current = normalizedConfig.storage ?? createSessionStoragePort();
+    providerStoragesForTests.add(providerStorageRef.current);
   }
+  const providerStorage = providerStorageRef.current;
+  const sessionIdRef = useRef(
+    resolveSessionId(providerStorage, normalizedConfig.session?.sessionId)
+  );
+  const [sessionId, setSessionId] = useState(() => sessionIdRef.current);
+  const prevConfiguredSessionIdRef = useRef(normalizedConfig.session?.sessionId);
   const attemptIdRef = useRef(normalizedConfig.session?.attemptId);
   const userRef = useRef(normalizedConfig.session?.user);
   attemptIdRef.current = normalizedConfig.session?.attemptId;
@@ -727,11 +903,16 @@ function useLessonkitProviderRuntime(config) {
   courseIdRef.current = normalizedCourseId;
   const lxpackBridgeModeRef = useRef(normalizedConfig.lxpack?.bridge ?? "auto");
   lxpackBridgeModeRef.current = normalizedConfig.lxpack?.bridge ?? "auto";
+  const allowedParentOriginsRef = useRef(normalizedConfig.lxpack?.allowedParentOrigins);
+  allowedParentOriginsRef.current = normalizedConfig.lxpack?.allowedParentOrigins;
   const observabilityRef = useRef(normalizedConfig.observability);
   observabilityRef.current = normalizedConfig.observability;
   const onLxpackBridgeMiss = useCallback((event) => {
     observabilityRef.current?.onLxpackBridgeMiss?.(event);
   }, []);
+  const onLxpackBridgeError = useCallback((err) => {
+    observabilityRef.current?.onLxpackBridgeError?.(err);
+  }, []);
   const pluginsFingerprint = normalizedConfig.plugins?.map((p) => `${p.id}\0${p.version}`).join("|") ?? "";
   const pluginHost = useMemo(
     () => createReactPluginHost(normalizedConfig.plugins),
@@ -742,23 +923,38 @@ function useLessonkitProviderRuntime(config) {
   const progressRef = useRef(createProgressController());
   const courseStartedEmittedToSinkRef = useRef(false);
   const courseStartedEmitGenerationRef = useRef(0);
+  const courseStartedFlightScopeRef = useRef(createCourseStartedFlightScope());
+  const pendingSessionReEmitRef = useRef(false);
+  const prevPluginsFingerprintRef = useRef(pluginsFingerprint);
+  if (prevPluginsFingerprintRef.current !== pluginsFingerprint) {
+    prevPluginsFingerprintRef.current = pluginsFingerprint;
+    courseStartedEmitGenerationRef.current += 1;
+    courseStartedEmittedToSinkRef.current = false;
+    resetCourseStartedTrackingFlights(courseStartedFlightScopeRef.current);
+  }
   const prevCourseIdForProgressRef = useRef(normalizedCourseId);
   const pendingCourseIdResetRef = useRef(false);
   const prevUseV2RuntimeRef = useRef(useV2Runtime);
   const xapiCourseStartedSentOnClientRef = useRef(false);
   const xapiBootstrapSendRef = useRef(false);
+  const xapiBootstrapQueuedRef = useRef(false);
+  const xapiBootstrapInFlightRef = useRef(false);
   if (prevUseV2RuntimeRef.current !== useV2Runtime) {
     prevUseV2RuntimeRef.current = useV2Runtime;
     if (useV2Runtime) {
-      headlessRef.current = createLessonkitRuntime({
-        courseId: normalizedCourseId,
-        runtimeVersion: "v2",
-        session: normalizedConfig.session,
-        plugins: pluginHostRef.current ?? normalizedConfig.plugins,
-        deferPluginSetup: true
-      });
+      headlessRef.current = createLessonkitRuntime(
+        {
+          courseId: normalizedCourseId,
+          runtimeVersion: "v2",
+          session: normalizedConfig.session,
+          plugins: pluginHostRef.current ?? normalizedConfig.plugins,
+          deferPluginSetup: true
+        },
+        { storage: providerStorage }
+      );
       progressRef.current = headlessRef.current.progress;
     } else {
+      headlessRef.current?.dispose();
       headlessRef.current = null;
       progressRef.current = createProgressController();
     }
@@ -766,13 +962,16 @@ function useLessonkitProviderRuntime(config) {
     courseStartedEmittedToSinkRef.current = false;
     courseStartedEmitGenerationRef.current += 1;
   } else if (useV2Runtime && !headlessRef.current) {
-    headlessRef.current = createLessonkitRuntime({
-      courseId: normalizedCourseId,
-      runtimeVersion: "v2",
-      session: normalizedConfig.session,
-      plugins: pluginHostRef.current ?? normalizedConfig.plugins,
-      deferPluginSetup: true
-    });
+    headlessRef.current = createLessonkitRuntime(
+      {
+        courseId: normalizedCourseId,
+        runtimeVersion: "v2",
+        session: normalizedConfig.session,
+        plugins: pluginHostRef.current ?? normalizedConfig.plugins,
+        deferPluginSetup: true
+      },
+      { storage: providerStorage }
+    );
   }
   if (prevCourseIdForProgressRef.current !== normalizedCourseId) {
     prevCourseIdForProgressRef.current = normalizedCourseId;
@@ -820,6 +1019,8 @@ function useLessonkitProviderRuntime(config) {
       prevXapiCourseIdRef.current = courseId;
       xapiCourseStartedSentOnClientRef.current = false;
       xapiBootstrapSendRef.current = false;
+      xapiBootstrapQueuedRef.current = false;
+      xapiBootstrapInFlightRef.current = false;
     }
     const prev = xapiRef.current;
     const next = createXapiClientFromConfig(
@@ -832,32 +1033,36 @@ function useLessonkitProviderRuntime(config) {
     let bootstrapSent = false;
     let bootstrapAlreadyStarted = false;
     if (next) {
-      const sessionId = sessionIdRef.current;
+      const sessionId2 = sessionIdRef.current;
       const cid = courseIdRef.current;
       const trackingActive = isTrackingActive(normalizedConfig.tracking);
-      bootstrapAlreadyStarted = hasCourseStarted(defaultStorage, sessionId, cid);
+      bootstrapAlreadyStarted = hasCourseStarted(providerStorage, sessionId2, cid);
       const clientChanged = !prev || prev !== next;
       const skipBootstrap = trackingActive && !bootstrapAlreadyStarted;
-      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && !xapiBootstrapSendRef.current && (!bootstrapAlreadyStarted || clientChanged);
+      const xapiAlreadySentForSession = hasCourseStartedXapiSent(providerStorage, sessionId2, cid);
+      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && !xapiBootstrapQueuedRef.current && !xapiAlreadySentForSession && (!bootstrapAlreadyStarted || clientChanged);
       if (needsBootstrap) {
         try {
           const event = buildCourseStartedEvent({
             pluginHost: pluginHostRef.current,
             courseId: cid,
-            sessionId,
+            sessionId: sessionId2,
             attemptId: attemptIdRef.current,
             user: userRef.current,
-            lxpackBridge: lxpackBridgeModeRef.current
+            lxpackBridge: lxpackBridgeModeRef.current,
+            allowedParentOrigins: allowedParentOriginsRef.current
           });
           if (event !== null) {
             const statement = telemetryEventToXAPIStatement3(event);
             if (statement) {
               next.send(statement);
-              xapiBootstrapSendRef.current = true;
+              xapiBootstrapQueuedRef.current = true;
+              xapiBootstrapInFlightRef.current = true;
               bootstrapSent = true;
             }
           }
-        } catch {
+        } catch (err) {
+          observabilityRef.current?.onXapiMappingError?.(err);
         }
       }
     }
@@ -873,12 +1078,19 @@ function useLessonkitProviderRuntime(config) {
       try {
         await next?.flush();
         if (bootstrapSent && !cancelled) {
+          xapiBootstrapSendRef.current = true;
+          xapiBootstrapInFlightRef.current = false;
           if (!bootstrapAlreadyStarted) {
-            markCourseStarted(defaultStorage, sessionIdRef.current, courseIdRef.current);
+            markCourseStarted(providerStorage, sessionIdRef.current, courseIdRef.current);
           }
+          markCourseStartedXapiSent(providerStorage, sessionIdRef.current, courseIdRef.current);
           xapiCourseStartedSentOnClientRef.current = true;
         }
       } catch {
+        if (bootstrapSent && !cancelled) {
+          xapiBootstrapQueuedRef.current = false;
+          xapiBootstrapInFlightRef.current = false;
+        }
       }
     })();
     return () => {
@@ -908,6 +1120,39 @@ function useLessonkitProviderRuntime(config) {
     }),
     []
   );
+  const emitCourseStartedOnce = useCallback(
+    async (sid, cid) => {
+      if (courseStartedEmittedToSinkRef.current) return;
+      const generation = courseStartedEmitGenerationRef.current;
+      const shouldCommit = () => generation === courseStartedEmitGenerationRef.current;
+      if (generation !== courseStartedEmitGenerationRef.current) return;
+      const result = await emitPendingCourseStarted({
+        pluginHost: pluginHostRef.current,
+        tracking: () => trackingRef.current,
+        xapi: xapiRef.current,
+        storage: providerStorage,
+        sessionId: sid,
+        courseId: cid,
+        attemptId: attemptIdRef.current,
+        user: userRef.current,
+        lxpackBridge: lxpackBridgeModeRef.current,
+        allowedParentOrigins: allowedParentOriginsRef.current,
+        onLxpackBridgeMiss,
+        onLxpackBridgeError,
+        onXapiMappingError: observabilityRef.current?.onXapiMappingError,
+        extraSinks: extraSinksRef.current,
+        skipXapi: xapiCourseStartedSentOnClientRef.current || xapiBootstrapSendRef.current || xapiBootstrapInFlightRef.current,
+        onXapiStatementSent: () => {
+          xapiCourseStartedSentOnClientRef.current = true;
+        },
+        shouldCommit,
+        flightScope: courseStartedFlightScopeRef.current
+      });
+      if (generation !== courseStartedEmitGenerationRef.current) return;
+      courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
+    },
+    [onLxpackBridgeMiss, onLxpackBridgeError]
+  );
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
     const baseSink = wrapTrackingSink(normalizedConfig.tracking?.sink, observabilityRef.current);
@@ -943,45 +1188,19 @@ function useLessonkitProviderRuntime(config) {
     trackingRef.current = next;
     trackingClientForUnmountRef.current = next;
     setTracking(next);
-    const sessionId = sessionIdRef.current;
+    const sessionId2 = 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);
+    const courseStartedFullySettled = hasCourseStartedEmittedToTracking(providerStorage, sessionId2, cid) && hasCourseStarted(providerStorage, sessionId2, cid) && hasCourseStartedPipelineDelivered(providerStorage, sessionId2, cid);
     if (!trackingActive) {
       courseStartedEmittedToSinkRef.current = false;
     } 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: () => trackingRef.current,
-          xapi: xapiRef.current,
-          storage: defaultStorage,
-          sessionId,
-          courseId: cid,
-          attemptId: attemptIdRef.current,
-          user: userRef.current,
-          lxpackBridge: lxpackBridgeModeRef.current,
-          onLxpackBridgeMiss,
-          extraSinks: extraSinksRef.current,
-          skipXapi: xapiCourseStartedSentOnClientRef.current || xapiBootstrapSendRef.current,
-          onXapiStatementSent: () => {
-            xapiCourseStartedSentOnClientRef.current = true;
-          },
-          shouldCommit
-        });
-        if (generation !== courseStartedEmitGenerationRef.current) return;
-        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
-      })();
+    } else {
+      void emitCourseStartedOnce(sessionId2, cid);
     }
     return () => {
-      if (prev !== trackingRef.current) {
-        void disposeTrackingClient(prev);
-      }
+      void disposeTrackingClient(prev);
     };
   }, [
     trackingEnabled,
@@ -990,9 +1209,10 @@ function useLessonkitProviderRuntime(config) {
     batchEnabled,
     batchFlushIntervalMs,
     batchMaxBatchSize,
-    normalizedConfig.plugins,
+    pluginsFingerprint,
     normalizedCourseId,
-    buildCurrentPluginCtx
+    buildCurrentPluginCtx,
+    emitCourseStartedOnce
   ]);
   const emitWithBridge = useCallback((trackingClient, event) => {
     emitTelemetryWithPlugins({
@@ -1007,22 +1227,16 @@ function useLessonkitProviderRuntime(config) {
         user: userRef.current
       }),
       lxpackBridge: lxpackBridgeModeRef.current,
+      allowedParentOrigins: allowedParentOriginsRef.current,
       onLxpackBridgeMiss,
-      extraSinks: extraSinksRef.current
+      onLxpackBridgeError,
+      extraSinks: extraSinksRef.current,
+      onXapiMappingError: observabilityRef.current?.onXapiMappingError,
+      onXapiTransportError: observabilityRef.current?.onXapiTransportError
     });
-  }, [onLxpackBridgeMiss]);
+  }, [onLxpackBridgeMiss, onLxpackBridgeError]);
   const emitLifecycleEvent = useCallback(
-    (name, data, lessonId) => {
-      const event = tryBuildTelemetryEvent({
-        name,
-        courseId: courseIdRef.current,
-        lessonId: lessonId ?? activeLessonIdRef.current,
-        sessionId: sessionIdRef.current,
-        attemptId: attemptIdRef.current,
-        user: userRef.current,
-        data
-      });
-      if (!event) return;
+    (event) => {
       emitWithBridge(trackingRef.current, event);
     },
     [emitWithBridge]
@@ -1048,39 +1262,16 @@ function useLessonkitProviderRuntime(config) {
     pendingCourseIdResetRef.current = false;
     syncProgress();
     if (!isTrackingActive(normalizedConfig.tracking)) return;
-    const sessionId = sessionIdRef.current;
+    const sessionId2 = sessionIdRef.current;
     const cid = courseIdRef.current;
     void (async () => {
       try {
         await trackingRef.current?.flush?.();
       } catch {
       }
-      if (!courseStartedEmittedToSinkRef.current) {
-        const generation = courseStartedEmitGenerationRef.current;
-        const shouldCommit = () => generation === courseStartedEmitGenerationRef.current;
-        const result = await emitPendingCourseStarted({
-          pluginHost: pluginHostRef.current,
-          tracking: () => trackingRef.current,
-          xapi: xapiRef.current,
-          storage: defaultStorage,
-          sessionId,
-          courseId: cid,
-          attemptId: attemptIdRef.current,
-          user: userRef.current,
-          lxpackBridge: lxpackBridgeModeRef.current,
-          onLxpackBridgeMiss,
-          extraSinks: extraSinksRef.current,
-          skipXapi: xapiCourseStartedSentOnClientRef.current || xapiBootstrapSendRef.current,
-          onXapiStatementSent: () => {
-            xapiCourseStartedSentOnClientRef.current = true;
-          },
-          shouldCommit
-        });
-        if (generation !== courseStartedEmitGenerationRef.current) return;
-        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
-      }
+      await emitCourseStartedOnce(sessionId2, cid);
     })();
-  }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress, onLxpackBridgeMiss]);
+  }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress, emitCourseStartedOnce]);
   const emitLessonCompleted = useCallback(
     (lessonId, durationMs) => {
       track("lesson_completed", { lessonId, durationMs }, { lessonId });
@@ -1130,23 +1321,13 @@ function useLessonkitProviderRuntime(config) {
     };
   }, []);
   useEffect2(() => {
-    if (typeof document === "undefined") return;
+    if (typeof window === "undefined") return;
     const flushOnPageExit = () => {
-      try {
-        xapiRef.current?.flushOnExit?.();
-        trackingRef.current?.flushOnExit?.();
-      } finally {
-        void xapiRef.current?.flush();
-        void trackingRef.current?.flush?.();
-      }
-    };
-    const onVisibilityChange = () => {
-      if (document.visibilityState === "hidden") flushOnPageExit();
+      xapiRef.current?.flushOnExit?.();
+      trackingRef.current?.flushOnExit?.();
     };
-    document.addEventListener("visibilitychange", onVisibilityChange);
     window.addEventListener("pagehide", flushOnPageExit);
     return () => {
-      document.removeEventListener("visibilitychange", onVisibilityChange);
       window.removeEventListener("pagehide", flushOnPageExit);
     };
   }, []);
@@ -1241,36 +1422,56 @@ function useLessonkitProviderRuntime(config) {
       host.disposeAll();
     };
   }, [pluginHost, useV2Runtime, normalizedCourseId, sessionAttemptId, sessionConfiguredId, sessionUserKey]);
-  useEffect2(() => {
+  useIsoLayoutEffect(() => {
     const nextConfigured = normalizedConfig.session?.sessionId;
     const prevConfigured = prevConfiguredSessionIdRef.current;
     if (nextConfigured === prevConfigured) return;
     prevConfiguredSessionIdRef.current = nextConfigured;
     const cid = courseIdRef.current;
-    if (nextConfigured) {
-      const fromIds = /* @__PURE__ */ new Set();
-      if (prevConfigured) fromIds.add(prevConfigured);
-      const tabId = getTabSessionId(defaultStorage);
-      if (tabId) fromIds.add(tabId);
-      for (const fromId of fromIds) {
-        if (fromId !== nextConfigured) {
-          migrateCourseStartedMark(defaultStorage, fromId, nextConfigured, cid);
-        }
+    if (nextConfigured !== void 0) {
+      const resolved = resolveSessionId(providerStorage, nextConfigured);
+      const tabId = getTabSessionId(providerStorage);
+      const isExplicitLearnerSwap = prevConfigured !== void 0 && prevConfigured !== nextConfigured;
+      if (isExplicitLearnerSwap) {
+        courseStartedEmittedToSinkRef.current = false;
+        courseStartedEmitGenerationRef.current += 1;
+        pendingSessionReEmitRef.current = true;
+      } else if (tabId && tabId !== resolved) {
+        migrateCourseStartedMark(providerStorage, tabId, resolved, cid);
       }
-      sessionIdRef.current = nextConfigured;
+      sessionIdRef.current = resolved;
+      setSessionId(resolved);
     } else if (prevConfigured) {
-      const nextAuto = resolveSessionId(defaultStorage, void 0);
-      migrateCourseStartedMark(defaultStorage, prevConfigured, nextAuto, cid);
+      const nextAuto = resolveSessionId(providerStorage, void 0);
+      migrateCourseStartedMark(providerStorage, prevConfigured, nextAuto, cid);
       sessionIdRef.current = nextAuto;
+      setSessionId(nextAuto);
     }
   }, [sessionConfiguredId, normalizedCourseId]);
+  useEffect2(() => {
+    if (!pendingSessionReEmitRef.current) return;
+    pendingSessionReEmitRef.current = false;
+    if (!isTrackingActive(normalizedConfig.tracking)) return;
+    void emitCourseStartedOnce(sessionIdRef.current, courseIdRef.current);
+  }, [sessionConfiguredId, emitCourseStartedOnce, normalizedConfig.tracking]);
+  useLayoutEffect(() => {
+    if (sessionIdRef.current !== sessionId) {
+      setSessionId(sessionIdRef.current);
+    }
+  }, [sessionConfiguredId, sessionId]);
+  useEffect2(() => {
+    return () => {
+      headlessRef.current?.dispose();
+      headlessRef.current = null;
+    };
+  }, []);
   const runtime = useMemo(
     () => ({
       config: normalizedConfig,
       tracking,
       xapi,
-      storage: defaultStorage,
-      session: { sessionId: sessionIdRef.current, attemptId: attemptIdRef.current, user: userRef.current },
+      storage: providerStorage,
+      session: { sessionId, attemptId: attemptIdRef.current, user: userRef.current },
       progress,
       setActiveLesson,
       completeLesson,
@@ -1290,7 +1491,8 @@ function useLessonkitProviderRuntime(config) {
       pluginHost,
       sessionUser,
       sessionAttemptId,
-      sessionConfiguredId
+      sessionConfiguredId,
+      sessionId
     ]
   );
   return runtime;
@@ -1394,7 +1596,9 @@ var COMPOUND_CONTAINER_TYPES = /* @__PURE__ */ new Set([
   "SlideDeck",
   "TimedCue",
   "InteractiveVideo",
-  "AssessmentSequence"
+  "AssessmentSequence",
+  "BranchingScenario",
+  "BranchNode"
 ]);
 function warnOrThrow(msg, strict) {
   if (strict) throw new Error(msg);
@@ -1466,14 +1670,14 @@ function validateSubtreeForForbidden(node, forbidden, strict) {
   });
 }
 function validateAccordionSections(sections, strict) {
-  if (!isDevEnvironment() && !strict) return;
+  const enforceStrict = strict ?? !isDevEnvironment();
   for (const section of sections) {
-    validateSubtreeForForbidden(section.content, ACCORDION_FORBIDDEN_CHILD_TYPES, strict);
+    validateSubtreeForForbidden(section.content, ACCORDION_FORBIDDEN_CHILD_TYPES, enforceStrict);
   }
 }
 function validateCompoundChildren(parent, children, strict) {
-  if (!isDevEnvironment() && !strict) return;
-  validateNode(parent, children, 0, strict);
+  const enforceStrict = strict ?? !isDevEnvironment();
+  validateNode(parent, children, 0, enforceStrict);
 }
 function resetCompoundValidationWarningsForTests() {
   warnedPairs.clear();
@@ -1688,14 +1892,15 @@ function meetsPassingThreshold(score, maxScore, passingScore) {
 }
 function scoreFromCustom(custom, fallbackCorrect, fallbackMax = 1, passingScore) {
   const maxScore = custom?.maxScore ?? fallbackMax;
+  const hasNumericScore = custom?.score != null && Number.isFinite(custom.score);
+  if (hasNumericScore) {
+    const passed2 = custom.passed !== void 0 ? custom.passed : meetsPassingThreshold(custom.score, maxScore, passingScore);
+    return { score: custom.score, maxScore, passed: passed2 };
+  }
   if (custom?.passed !== void 0) {
-    const score2 = custom.passed ? custom.score ?? maxScore : custom.score ?? 0;
+    const score2 = custom.passed ? maxScore : 0;
     return { score: score2, maxScore, passed: custom.passed };
   }
-  if (custom?.maxScore != null && custom.maxScore > 0 && custom.score != null) {
-    const passed2 = meetsPassingThreshold(custom.score, custom.maxScore, passingScore);
-    return { score: custom.score, maxScore: custom.maxScore, passed: passed2 };
-  }
   const score = fallbackCorrect ? maxScore : 0;
   const passed = meetsPassingThreshold(score, maxScore, passingScore);
   return { score, maxScore, passed };
@@ -1747,6 +1952,7 @@ export {
   readStringField,
   readNumberField,
   readBooleanStateField,
+  aggregateAssessmentScores,
   useCompoundHydrationBridgeRef,
   CompoundPageIndexProvider,
   CompoundProvider,
@@ -1754,9 +1960,9 @@ export {
   useCompoundHandlesVersion,
   useCompoundHandleRef,
   useAssessmentHandleRegistration,
+  resetCourseStartedTrackingFlightForTests,
   shouldEnforceProductionGuard,
   assertProductionCourseConfig,
-  resetCourseStartedTrackingFlightForTests,
   resetLessonkitProviderStorageForTests,
   LessonkitContext,
   LessonkitProvider,
@@ -1769,6 +1975,7 @@ export {
   meetsPassingThreshold,
   usePluginScoring,
   setLessonkitBlockType,
+  getLessonkitBlockType,
   validateAccordionSections,
   validateCompoundChildren,
   resetCompoundValidationWarningsForTests