@lessonkit/react 1.3.1 → 1.4.0

package/dist/chunk-TDM3ARE7.js

@@ -0,0 +1,1775 @@
+// src/assessment/AssessmentLessonGuard.tsx
+import { useEffect } from "react";
+
+// src/lessonContext.tsx
+import { createContext, useContext } from "react";
+var LessonContext = createContext(void 0);
+function useEnclosingLessonId() {
+  return useContext(LessonContext);
+}
+
+// src/runtime/validateComponentId.ts
+import { assertValidId } from "@lessonkit/core";
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function normalizeComponentId(id, path) {
+  if (path === "courseId") return assertValidId(id, "courseId");
+  if (path === "lessonId") return assertValidId(id, "lessonId");
+  if (path === "checkId") return assertValidId(id, "checkId");
+  if (path === "blockId") return assertValidId(id, "blockId");
+  return assertValidId(id, path);
+}
+
+// src/assessment/AssessmentLessonGuard.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var warnedAssessmentOutsideLesson = false;
+function resetAssessmentWarningsForTests() {
+  warnedAssessmentOutsideLesson = false;
+}
+function AssessmentLessonGuard(props) {
+  const enclosingLessonId = useEnclosingLessonId();
+  const missingLesson = enclosingLessonId === void 0;
+  useEffect(() => {
+    if (!missingLesson || isDevEnvironment()) return;
+    if (!warnedAssessmentOutsideLesson) {
+      warnedAssessmentOutsideLesson = true;
+      console.error(
+        `[lessonkit] <${props.blockLabel}> must be wrapped in <Lesson>; assessment telemetry will not be emitted.`
+      );
+    }
+  }, [missingLesson, props.blockLabel]);
+  if (missingLesson && isDevEnvironment()) {
+    throw new Error(`[lessonkit] <${props.blockLabel}> must be wrapped in <Lesson>`);
+  }
+  if (missingLesson) {
+    return /* @__PURE__ */ jsx("section", { role: "alert", "aria-label": `${props.blockLabel} configuration error`, "data-lk-check-id": props.checkId, children: /* @__PURE__ */ jsxs("p", { children: [
+      props.blockLabel,
+      " must be placed inside a Lesson."
+    ] }) });
+  }
+  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
+} from "@lessonkit/core";
+import { telemetryEventToXAPIStatement } from "@lessonkit/xapi";
+
+// src/runtime/lxpackBridge.ts
+import {
+  dispatchBridgeAction,
+  forwardTelemetryToBridge,
+  getLxpackBridge,
+  mapLessonkitTelemetryToBridgeAction,
+  telemetryEventToLessonkit
+} from "@lessonkit/lxpack/bridge";
+var BRIDGE_MISS_EVENT_NAMES = /* @__PURE__ */ new Set([
+  "course_completed",
+  "lesson_completed",
+  "assessment_completed",
+  "quiz_completed"
+]);
+function forwardTelemetryToLxpack(event, mode = "auto", opts) {
+  if (mode === "auto" && opts?.onBridgeMiss && BRIDGE_MISS_EVENT_NAMES.has(event.name) && !getLxpackBridge()) {
+    opts.onBridgeMiss(event);
+  }
+  forwardTelemetryToBridge(event, mode);
+}
+
+// src/runtime/telemetryPipeline.ts
+function isDevEnvironment2() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function createLegacyPipeline(opts, extraSinks = []) {
+  return createTelemetryPipeline([
+    createTrackingPipelineSink("tracking", (event) => opts.tracking.track(event)),
+    {
+      id: "xapi",
+      emit(event) {
+        try {
+          const statement = telemetryEventToXAPIStatement(event);
+          if (statement) opts.xapi?.send(statement);
+        } catch (err) {
+          if (isDevEnvironment2()) {
+            console.warn(
+              "[lessonkit] xAPI mapping skipped:",
+              err instanceof Error ? err.message : err
+            );
+          }
+        }
+      }
+    },
+    {
+      id: "lxpack-bridge",
+      emit(event) {
+        forwardTelemetryToLxpack(event, opts.lxpackBridge, {
+          onBridgeMiss: opts.onLxpackBridgeMiss
+        });
+      }
+    },
+    ...extraSinks
+  ]);
+}
+function emitThroughPipeline(event, opts, extraSinks) {
+  createLegacyPipeline(opts, extraSinks).emit(event);
+}
+
+// src/runtime/emitTelemetry.ts
+var warnedMissingCourseId = false;
+function isDevEnvironment3() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function emitTelemetry(tracking, xapi, event, opts) {
+  if (!event.courseId) {
+    if (isDevEnvironment3() && !warnedMissingCourseId) {
+      warnedMissingCourseId = true;
+      console.warn("[lessonkit] telemetry event missing courseId");
+    }
+    return;
+  }
+  const legacy = {
+    tracking,
+    xapi,
+    lxpackBridge: opts?.lxpackBridge ?? "auto",
+    onLxpackBridgeMiss: opts?.onLxpackBridgeMiss
+  };
+  emitThroughPipeline(event, legacy, opts?.extraSinks);
+}
+
+// src/runtime/courseStartedPipeline.ts
+import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
+function isDevEnvironment4() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnExtraSinkFailure(sinkId, err) {
+  if (isDevEnvironment4()) {
+    console.warn(
+      `[lessonkit] course_started extra sink "${sinkId}" failed:`,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+async function emitExtraSinks(sinks, event, emitCtx) {
+  await Promise.all(
+    sinks.map(async (sink) => {
+      let result;
+      try {
+        result = sink.emit(event, emitCtx);
+      } catch (err) {
+        warnExtraSinkFailure(sink.id, err);
+        throw err;
+      }
+      if (result != null && typeof result.then === "function") {
+        try {
+          await result;
+        } catch (err) {
+          warnExtraSinkFailure(sink.id, err);
+          throw err;
+        }
+      }
+    })
+  );
+}
+async function emitCourseStartedNonTrackingPipeline(opts) {
+  let xapiStatementSent = false;
+  if (!opts.skipXapi && opts.xapi) {
+    const statement = telemetryEventToXAPIStatement2(opts.event);
+    if (statement) {
+      opts.xapi.send(statement);
+      await opts.xapi.flush();
+      xapiStatementSent = true;
+    }
+  }
+  forwardTelemetryToLxpack(opts.event, opts.lxpackBridge, {
+    onBridgeMiss: opts.onLxpackBridgeMiss
+  });
+  const emitCtx = {
+    courseId: opts.event.courseId,
+    sessionId: opts.event.sessionId,
+    attemptId: opts.event.attemptId
+  };
+  await emitExtraSinks(opts.extraSinks ?? [], opts.event, emitCtx);
+  return { xapiStatementSent };
+}
+
+// src/runtime/plugins.ts
+import { buildPluginContext as buildPluginContextFromCore, createPluginRegistry } from "@lessonkit/core";
+function createReactPluginHost(plugins) {
+  if (!plugins?.length) return null;
+  return createPluginRegistry(plugins);
+}
+function buildPluginContext(opts) {
+  return buildPluginContextFromCore(opts);
+}
+function emitTelemetryWithPlugins(opts) {
+  const next = opts.pluginHost ? opts.pluginHost.runTelemetry(opts.event, opts.pluginCtx) : opts.event;
+  if (next === null) return;
+  emitTelemetry(opts.tracking, opts.xapi, next, {
+    lxpackBridge: opts.lxpackBridge ?? "auto",
+    extraSinks: opts.extraSinks,
+    onLxpackBridgeMiss: opts.onLxpackBridgeMiss
+  });
+}
+
+// src/runtime/session.ts
+import {
+  SESSION_STORAGE_KEY,
+  getTabSessionId,
+  resolveSessionId,
+  hasCourseStarted,
+  markCourseStarted,
+  hasCourseStartedEmittedToTracking,
+  markCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
+  markCourseStartedPipelineDelivered,
+  migrateCourseStartedMark
+} from "@lessonkit/core";
+
+// src/provider/courseStarted/emit.ts
+function resolveTrackingClient(source) {
+  return typeof source === "function" ? source() : source;
+}
+var courseStartedTrackingFlights = /* @__PURE__ */ new Map();
+var courseStartedEmitFlights = /* @__PURE__ */ new Map();
+function resetCourseStartedTrackingFlightForTests() {
+  courseStartedTrackingFlights.clear();
+  courseStartedEmitFlights.clear();
+}
+function isTrackingActive(tracking) {
+  return tracking?.enabled !== false;
+}
+function isCourseStartedSinkSettled(result) {
+  return result === "emitted" || result === "filtered";
+}
+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;
+}
+function buildCourseStartedEvent(opts) {
+  const pluginCtx = buildPluginContext({
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  });
+  const built = buildTelemetryEvent({
+    name: "course_started",
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  });
+  return opts.pluginHost ? opts.pluginHost.runTelemetry(built, pluginCtx) : built;
+}
+async function emitCourseStartedToTracking(tracking, storage, sessionId, courseId, event, shouldCommit) {
+  const flightKey = `${sessionId}:${courseId}`;
+  if (hasCourseStartedEmittedToTracking(storage, sessionId, courseId)) {
+    return true;
+  }
+  const existing = courseStartedTrackingFlights.get(flightKey);
+  if (existing) {
+    return existing;
+  }
+  let resolveFlight;
+  const flight = new Promise((resolve) => {
+    resolveFlight = resolve;
+  });
+  courseStartedTrackingFlights.set(flightKey, flight);
+  void (async () => {
+    try {
+      if (shouldCommit && !shouldCommit()) {
+        resolveFlight(false);
+        return;
+      }
+      const client = resolveTrackingClient(tracking);
+      const delivered = await deliverToTracking(client, event);
+      if (shouldCommit && !shouldCommit()) {
+        resolveFlight(false);
+        return;
+      }
+      if (!delivered) {
+        resolveFlight(false);
+        return;
+      }
+      if (markCourseStartedEmittedToTracking(storage, sessionId, courseId) === false) {
+        resolveFlight(false);
+        return;
+      }
+      resolveFlight(true);
+    } catch {
+      resolveFlight(false);
+    } finally {
+      if (courseStartedTrackingFlights.get(flightKey) === flight) {
+        courseStartedTrackingFlights.delete(flightKey);
+      }
+    }
+  })();
+  return flight;
+}
+async function emitCourseStartedPipelineOnly(opts) {
+  try {
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    const { xapiStatementSent } = await emitCourseStartedNonTrackingPipeline({
+      event: opts.event,
+      xapi: opts.xapi,
+      lxpackBridge: opts.lxpackBridge,
+      onLxpackBridgeMiss: opts.onLxpackBridgeMiss,
+      extraSinks: opts.extraSinks,
+      skipXapi: opts.skipXapi
+    });
+    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) {
+      return "failed";
+    }
+    if (xapiStatementSent) {
+      opts.onXapiStatementSent?.();
+    }
+    return "emitted";
+  } catch {
+    return "failed";
+  }
+}
+async function emitCourseStarted(opts) {
+  const event = buildCourseStartedEvent(opts);
+  if (event === null) return "filtered";
+  const tracked = await emitCourseStartedToTracking(
+    opts.tracking,
+    opts.storage,
+    opts.sessionId,
+    opts.courseId,
+    event,
+    opts.shouldCommit
+  );
+  if (!tracked) return "failed";
+  return emitCourseStartedPipelineOnly({
+    ...opts,
+    event,
+    skipXapi: opts.skipXapi,
+    onXapiStatementSent: opts.onXapiStatementSent,
+    shouldCommit: opts.shouldCommit
+  });
+}
+async function emitCourseStartedToTrackingOnly(opts) {
+  const event = buildCourseStartedEvent(opts);
+  if (event === null) return "filtered";
+  const tracked = await emitCourseStartedToTracking(
+    opts.tracking,
+    opts.storage,
+    opts.sessionId,
+    opts.courseId,
+    event,
+    opts.shouldCommit
+  );
+  if (!tracked) return "failed";
+  try {
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+    await emitCourseStartedNonTrackingPipeline({
+      event,
+      xapi: null,
+      lxpackBridge: opts.lxpackBridge,
+      onLxpackBridgeMiss: opts.onLxpackBridgeMiss,
+      extraSinks: opts.extraSinks,
+      skipXapi: true
+    });
+    if (markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId) === false) {
+      return "failed";
+    }
+    return "emitted";
+  } catch {
+    return "failed";
+  }
+}
+async function emitPendingCourseStarted(opts) {
+  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 result = await flight;
+    if (result !== "failed") return result;
+    const sessionStarted = hasCourseStarted(opts.storage, opts.sessionId, opts.courseId);
+    const trackingEmitted = hasCourseStartedEmittedToTracking(
+      opts.storage,
+      opts.sessionId,
+      opts.courseId
+    );
+    const pipelineDelivered = hasCourseStartedPipelineDelivered(
+      opts.storage,
+      opts.sessionId,
+      opts.courseId
+    );
+    if (sessionStarted && trackingEmitted && pipelineDelivered) {
+      return "emitted";
+    }
+    if (opts.shouldCommit && !opts.shouldCommit()) return "failed";
+  }
+  return "failed";
+}
+function startPendingCourseStartedFlight(opts, flightKey) {
+  const flight = emitPendingCourseStartedInner(opts);
+  courseStartedEmitFlights.set(flightKey, flight);
+  void flight.finally(() => {
+    if (courseStartedEmitFlights.get(flightKey) === flight) {
+      courseStartedEmitFlights.delete(flightKey);
+    }
+  });
+  return flight;
+}
+async function emitPendingCourseStartedInner(opts) {
+  const trackingEmitted = hasCourseStartedEmittedToTracking(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  const sessionStarted = hasCourseStarted(opts.storage, opts.sessionId, opts.courseId);
+  const pipelineDelivered = hasCourseStartedPipelineDelivered(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (sessionStarted && trackingEmitted && pipelineDelivered) {
+    return "emitted";
+  }
+  if (sessionStarted && !trackingEmitted) {
+    return emitCourseStartedToTrackingOnly(opts);
+  }
+  if (trackingEmitted && !sessionStarted) {
+    const event = buildCourseStartedEvent(opts);
+    if (event === null) return "filtered";
+    return emitCourseStartedPipelineOnly({ ...opts, event });
+  }
+  if (!trackingEmitted && !sessionStarted) {
+    return emitCourseStarted(opts);
+  }
+  if (sessionStarted && trackingEmitted && !pipelineDelivered) {
+    const event = buildCourseStartedEvent(opts);
+    if (event === null) return "filtered";
+    return emitCourseStartedPipelineOnly({
+      ...opts,
+      event,
+      skipXapi: opts.skipXapi,
+      onXapiStatementSent: opts.onXapiStatementSent
+    });
+  }
+  return "failed";
+}
+function assertTrackingSinkConfig(tracking) {
+  if (!tracking?.sink || !tracking?.batchSink) return;
+  throw new Error(
+    "[lessonkit] tracking.sink and tracking.batchSink cannot both be set; use batchSink alone for batched delivery"
+  );
+}
+
+// src/provider/useLessonkitProviderRuntime.ts
+import {
+  useCallback,
+  useEffect as useEffect2,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { createLessonkitRuntime, createTrackingClient as createTrackingClient2, assertValidId as assertValidId2 } from "@lessonkit/core";
+
+// src/runtime/observability.ts
+import { createInMemoryXAPIQueue } from "@lessonkit/xapi";
+function createXapiQueueFromObservability(getObservability) {
+  const opts = {
+    onDepth: (size) => getObservability?.()?.onXapiQueueDepth?.(size),
+    onCap: () => getObservability?.()?.onXapiQueueCap?.()
+  };
+  return 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 wrapTrackingSink(sink, observability) {
+  if (!sink || !observability?.onTelemetrySinkError) return sink;
+  const onError = observability.onTelemetrySinkError;
+  return ((event) => {
+    try {
+      const result = sink(event);
+      if (result != null && typeof result.catch === "function") {
+        return result.catch((err) => {
+          onError(err, { sinkId: "tracking" });
+          throw err;
+        });
+      }
+      return result;
+    } catch (err) {
+      onError(err, { sinkId: "tracking" });
+      throw err;
+    }
+  });
+}
+
+// src/provider/useLessonkitProviderRuntime.ts
+import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement3 } from "@lessonkit/xapi";
+
+// src/runtime/ports.ts
+import {
+  createDefaultClock,
+  createGlobalTimer,
+  createNoopStorage,
+  createSessionStoragePort,
+  resetStoragePortForTests
+} from "@lessonkit/core";
+
+// src/provider/useLessonkitProviderRuntime.ts
+import { resetSharedVolatileSessionIdForTests } from "@lessonkit/core";
+
+// src/runtime/progress.ts
+import { createProgressController } from "@lessonkit/core";
+
+// src/runtime/xapi.ts
+import { createXAPIClient } from "@lessonkit/xapi";
+function createXapiClientFromConfig(config, queue, observability) {
+  if (config.xapi?.enabled === false) return null;
+  if (config.xapi?.client) return config.xapi.client;
+  if (!config.courseId) return null;
+  const hasTransport = typeof config.xapi?.transport === "function";
+  if (!hasTransport && config.xapi?.enabled !== true) return null;
+  return createXAPIClient({
+    courseId: config.courseId,
+    transport: config.xapi?.transport,
+    exitTransport: config.xapi?.exitTransport,
+    abortInFlight: config.xapi?.abortInFlight,
+    queue,
+    onTransportError: observability?.onXapiTransportError
+  });
+}
+
+// src/runtime/telemetry.ts
+import { createTrackingClient } from "@lessonkit/core";
+function createTrackingClientFromConfig(config, observability) {
+  if (config.tracking?.enabled === false) return createTrackingClient();
+  if (config.tracking?.createClient) return config.tracking.createClient();
+  return createTrackingClient({
+    sink: config.tracking?.sink,
+    batchSink: config.tracking?.batchSink,
+    batch: config.tracking?.batch,
+    exitBatchSink: config.tracking?.exitBatchSink,
+    onBufferDrop: observability?.onTelemetryBufferDrop
+  });
+}
+async function disposeTrackingClient(client) {
+  try {
+    await client?.flush?.();
+  } catch {
+  }
+  try {
+    await client?.dispose?.();
+  } catch {
+  }
+}
+
+// src/provider/useLessonkitProviderRuntime.ts
+var useIsoLayoutEffect = (
+  /* v8 ignore next -- SSR uses useEffect when window is unavailable */
+  typeof window !== "undefined" ? useLayoutEffect : useEffect2
+);
+var defaultStorage = createSessionStoragePort();
+function resetLessonkitProviderStorageForTests() {
+  resetStoragePortForTests(defaultStorage);
+  resetSharedVolatileSessionIdForTests();
+}
+function useLessonkitProviderRuntime(config) {
+  const normalizedCourseId = useMemo(
+    () => assertValidId2(config.courseId, "courseId"),
+    [config.courseId]
+  );
+  const normalizedConfig = useMemo(
+    () => ({ ...config, courseId: normalizedCourseId }),
+    [config, normalizedCourseId]
+  );
+  if (shouldEnforceProductionGuard()) {
+    assertProductionCourseConfig(normalizedConfig);
+  }
+  const useV2Runtime = normalizedConfig.runtimeVersion !== "v1";
+  useEffect2(() => {
+    if (useV2Runtime) return;
+    const g = globalThis;
+    if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV === "production") return;
+    console.warn(
+      '[lessonkit] LessonkitProvider runtimeVersion "v1" is deprecated; omit or use "v2" (default). v1 will be removed in LessonKit 2.0.'
+    );
+  }, [useV2Runtime]);
+  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 attemptIdRef = useRef(normalizedConfig.session?.attemptId);
+  const userRef = useRef(normalizedConfig.session?.user);
+  attemptIdRef.current = normalizedConfig.session?.attemptId;
+  userRef.current = normalizedConfig.session?.user;
+  const courseIdRef = useRef(normalizedCourseId);
+  courseIdRef.current = normalizedCourseId;
+  const lxpackBridgeModeRef = useRef(normalizedConfig.lxpack?.bridge ?? "auto");
+  lxpackBridgeModeRef.current = normalizedConfig.lxpack?.bridge ?? "auto";
+  const observabilityRef = useRef(normalizedConfig.observability);
+  observabilityRef.current = normalizedConfig.observability;
+  const onLxpackBridgeMiss = useCallback((event) => {
+    observabilityRef.current?.onLxpackBridgeMiss?.(event);
+  }, []);
+  const pluginsFingerprint = normalizedConfig.plugins?.map((p) => `${p.id}\0${p.version}`).join("|") ?? "";
+  const pluginHost = useMemo(
+    () => createReactPluginHost(normalizedConfig.plugins),
+    [pluginsFingerprint]
+  );
+  const pluginHostRef = useRef(pluginHost);
+  pluginHostRef.current = pluginHost;
+  const progressRef = useRef(createProgressController());
+  const courseStartedEmittedToSinkRef = useRef(false);
+  const courseStartedEmitGenerationRef = useRef(0);
+  const prevCourseIdForProgressRef = useRef(normalizedCourseId);
+  const pendingCourseIdResetRef = useRef(false);
+  const prevUseV2RuntimeRef = useRef(useV2Runtime);
+  const xapiCourseStartedSentOnClientRef = useRef(false);
+  const xapiBootstrapSendRef = 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
+      });
+      progressRef.current = headlessRef.current.progress;
+    } else {
+      headlessRef.current = null;
+      progressRef.current = createProgressController();
+    }
+    pendingCourseIdResetRef.current = true;
+    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
+    });
+  }
+  if (prevCourseIdForProgressRef.current !== normalizedCourseId) {
+    prevCourseIdForProgressRef.current = normalizedCourseId;
+    if (useV2Runtime && headlessRef.current) {
+      headlessRef.current.resetForCourseChange(normalizedCourseId);
+      progressRef.current = headlessRef.current.progress;
+    } else {
+      progressRef.current = createProgressController();
+    }
+    pendingCourseIdResetRef.current = true;
+    courseStartedEmittedToSinkRef.current = false;
+    courseStartedEmitGenerationRef.current += 1;
+  }
+  if (useV2Runtime && headlessRef.current) {
+    progressRef.current = headlessRef.current.progress;
+  }
+  const [progress, setProgress] = useState(() => progressRef.current.getState());
+  const syncProgress = useCallback(() => {
+    setProgress(progressRef.current.getState());
+  }, []);
+  const activeLessonIdRef = useRef(progress.activeLessonId);
+  activeLessonIdRef.current = progress.activeLessonId;
+  const xapiQueueRef = useRef(createXapiQueueFromObservability(() => observabilityRef.current));
+  const xapiRef = useRef(null);
+  const [xapi, setXapi] = useState(null);
+  const prevXapiCourseIdRef = useRef(normalizedCourseId);
+  const xapiEnabled = normalizedConfig.xapi?.enabled;
+  const xapiClient = normalizedConfig.xapi?.client;
+  const xapiTransport = normalizedConfig.xapi?.transport;
+  const courseId = normalizedCourseId;
+  const trackingEnabled = normalizedConfig.tracking?.enabled;
+  useIsoLayoutEffect(() => {
+    const courseChanged = prevXapiCourseIdRef.current !== courseId;
+    if (courseChanged) {
+      if (normalizedConfig.xapi?.client) {
+        const g = globalThis;
+        if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production") {
+          console.warn(
+            "[lessonkit] courseId changed while using config.xapi.client; flush the client between courses or use config.xapi.transport so the provider can manage the queue."
+          );
+        }
+        void xapiRef.current?.flush();
+      }
+      xapiQueueRef.current = createXapiQueueFromObservability(() => observabilityRef.current);
+      prevXapiCourseIdRef.current = courseId;
+      xapiCourseStartedSentOnClientRef.current = false;
+      xapiBootstrapSendRef.current = false;
+    }
+    const prev = xapiRef.current;
+    const next = createXapiClientFromConfig(
+      normalizedConfig,
+      xapiQueueRef.current,
+      observabilityRef.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);
+      bootstrapAlreadyStarted = hasCourseStarted(defaultStorage, sessionId, cid);
+      const clientChanged = !prev || prev !== next;
+      const skipBootstrap = trackingActive && !bootstrapAlreadyStarted;
+      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && !xapiBootstrapSendRef.current && (!bootstrapAlreadyStarted || clientChanged);
+      if (needsBootstrap) {
+        try {
+          const event = buildCourseStartedEvent({
+            pluginHost: pluginHostRef.current,
+            courseId: cid,
+            sessionId,
+            attemptId: attemptIdRef.current,
+            user: userRef.current,
+            lxpackBridge: lxpackBridgeModeRef.current
+          });
+          if (event !== null) {
+            const statement = telemetryEventToXAPIStatement3(event);
+            if (statement) {
+              next.send(statement);
+              xapiBootstrapSendRef.current = true;
+              bootstrapSent = true;
+            }
+          }
+        } catch {
+        }
+      }
+    }
+    let cancelled = false;
+    void (async () => {
+      if (prev) {
+        try {
+          await prev.flush();
+        } catch {
+        }
+      }
+      if (cancelled) return;
+      try {
+        await next?.flush();
+        if (bootstrapSent && !cancelled) {
+          if (!bootstrapAlreadyStarted) {
+            markCourseStarted(defaultStorage, sessionIdRef.current, courseIdRef.current);
+          }
+          xapiCourseStartedSentOnClientRef.current = true;
+        }
+      } catch {
+      }
+    })();
+    return () => {
+      cancelled = true;
+      void (async () => {
+        try {
+          await prev?.flush();
+        } catch {
+        }
+      })();
+    };
+  }, [xapiEnabled, xapiClient, xapiTransport, courseId, trackingEnabled]);
+  const trackingRef = useRef(createTrackingClient2());
+  const trackingClientForUnmountRef = useRef(trackingRef.current);
+  const [tracking, setTracking] = useState(() => trackingRef.current);
+  const trackingSink = normalizedConfig.tracking?.sink;
+  const trackingBatchSink = normalizedConfig.tracking?.batchSink;
+  const batchEnabled = normalizedConfig.tracking?.batch?.enabled;
+  const batchFlushIntervalMs = normalizedConfig.tracking?.batch?.flushIntervalMs;
+  const batchMaxBatchSize = normalizedConfig.tracking?.batch?.maxBatchSize;
+  const buildCurrentPluginCtx = useCallback(
+    () => buildPluginContext({
+      courseId: courseIdRef.current,
+      sessionId: sessionIdRef.current,
+      attemptId: attemptIdRef.current,
+      user: userRef.current
+    }),
+    []
+  );
+  useIsoLayoutEffect(() => {
+    const prev = trackingRef.current;
+    const baseSink = wrapTrackingSink(normalizedConfig.tracking?.sink, observabilityRef.current);
+    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 */
+      pluginHostRef.current.composeTrackingSink(baseSink, buildCurrentPluginCtx) ?? baseSink
+    ) : baseSink;
+    const batchSink = pluginHostRef.current && userBatchSink ? async (events) => {
+      const host = pluginHostRef.current;
+      const ctx = buildCurrentPluginCtx();
+      const delivered = host.deliverTelemetryBatch(events, ctx);
+      const perEventForBatch = [];
+      const collector = (event) => {
+        perEventForBatch.push(event);
+      };
+      const composedPerEvent = host.composeTrackingSink(collector, buildCurrentPluginCtx) ?? collector;
+      for (const event of delivered) {
+        await Promise.resolve(composedPerEvent(event));
+      }
+      return userBatchSink(perEventForBatch);
+    } : userBatchSink;
+    const next = createTrackingClientFromConfig(
+      {
+        tracking: { ...normalizedConfig.tracking, sink, batchSink }
+      },
+      observabilityRef.current
+    );
+    trackingRef.current = next;
+    trackingClientForUnmountRef.current = next;
+    setTracking(next);
+    const sessionId = sessionIdRef.current;
+    const cid = courseIdRef.current;
+    const trackingActive = isTrackingActive(normalizedConfig.tracking);
+    const courseStartedFullySettled = hasCourseStartedEmittedToTracking(defaultStorage, sessionId, cid) && hasCourseStarted(defaultStorage, sessionId, cid) && hasCourseStartedPipelineDelivered(defaultStorage, sessionId, cid);
+    if (!trackingActive) {
+      courseStartedEmittedToSinkRef.current = false;
+    } else if (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);
+      })();
+    }
+    return () => {
+      if (prev !== trackingRef.current) {
+        void disposeTrackingClient(prev);
+      }
+    };
+  }, [
+    trackingEnabled,
+    trackingSink,
+    trackingBatchSink,
+    batchEnabled,
+    batchFlushIntervalMs,
+    batchMaxBatchSize,
+    normalizedConfig.plugins,
+    normalizedCourseId,
+    buildCurrentPluginCtx
+  ]);
+  const emitWithBridge = useCallback((trackingClient, event) => {
+    emitTelemetryWithPlugins({
+      pluginHost: pluginHostRef.current,
+      tracking: trackingClient,
+      xapi: xapiRef.current,
+      event,
+      pluginCtx: buildPluginContext({
+        courseId: courseIdRef.current,
+        sessionId: sessionIdRef.current,
+        attemptId: attemptIdRef.current,
+        user: userRef.current
+      }),
+      lxpackBridge: lxpackBridgeModeRef.current,
+      onLxpackBridgeMiss,
+      extraSinks: extraSinksRef.current
+    });
+  }, [onLxpackBridgeMiss]);
+  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;
+      emitWithBridge(trackingRef.current, event);
+    },
+    [emitWithBridge]
+  );
+  const track = useCallback(
+    (name, data, opts) => {
+      const event = tryBuildTelemetryEvent({
+        name,
+        courseId: courseIdRef.current,
+        lessonId: opts?.lessonId ?? activeLessonIdRef.current,
+        sessionId: sessionIdRef.current,
+        attemptId: attemptIdRef.current,
+        user: userRef.current,
+        data
+      });
+      if (!event) return;
+      emitWithBridge(trackingRef.current, event);
+    },
+    [emitWithBridge]
+  );
+  useLayoutEffect(() => {
+    if (!pendingCourseIdResetRef.current) return;
+    pendingCourseIdResetRef.current = false;
+    syncProgress();
+    if (!isTrackingActive(normalizedConfig.tracking)) return;
+    const sessionId = 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);
+      }
+    })();
+  }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress, onLxpackBridgeMiss]);
+  const emitLessonCompleted = useCallback(
+    (lessonId, durationMs) => {
+      track("lesson_completed", { lessonId, durationMs }, { lessonId });
+      if (durationMs !== void 0) {
+        track("lesson_time_on_task", { lessonId, durationMs }, { lessonId });
+      }
+    },
+    [track]
+  );
+  const completeLesson = useCallback(
+    (lessonId, opts) => {
+      if (opts?.courseId !== void 0 && opts.courseId !== courseIdRef.current) {
+        return;
+      }
+      if (useV2Runtime && headlessRef.current) {
+        headlessRef.current.completeLesson(lessonId, emitLifecycleEvent);
+        syncProgress();
+        void Promise.resolve(trackingRef.current?.flush?.());
+        return;
+      }
+      const result = progressRef.current.completeLesson(lessonId, Date.now());
+      if (!result.didComplete) return;
+      syncProgress();
+      emitLessonCompleted(lessonId, result.durationMs);
+      void Promise.resolve(trackingRef.current?.flush?.());
+    },
+    [syncProgress, emitLessonCompleted, useV2Runtime, emitLifecycleEvent]
+  );
+  useEffect2(() => {
+    return () => {
+      const client = trackingClientForUnmountRef.current;
+      const xapi2 = xapiRef.current;
+      void (async () => {
+        try {
+          await xapi2?.flush();
+        } catch {
+        }
+        try {
+          await client?.flush?.();
+        } catch {
+        }
+        try {
+          await client?.dispose?.();
+        } catch {
+        }
+      })();
+    };
+  }, []);
+  useEffect2(() => {
+    if (typeof document === "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();
+    };
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    window.addEventListener("pagehide", flushOnPageExit);
+    return () => {
+      document.removeEventListener("visibilitychange", onVisibilityChange);
+      window.removeEventListener("pagehide", flushOnPageExit);
+    };
+  }, []);
+  const setActiveLesson = useCallback(
+    (lessonId) => {
+      if (useV2Runtime && headlessRef.current) {
+        headlessRef.current.setActiveLesson(lessonId, emitLifecycleEvent);
+        syncProgress();
+        void Promise.resolve(trackingRef.current?.flush?.());
+        return;
+      }
+      const current = progressRef.current.getState();
+      if (current.activeLessonId === lessonId) return;
+      if (current.completedLessonIds.has(lessonId)) {
+        progressRef.current.setActiveLesson(lessonId, Date.now());
+        syncProgress();
+        return;
+      }
+      const previous = current.activeLessonId;
+      if (previous && previous !== lessonId) {
+        const completed = progressRef.current.completeLesson(previous, Date.now());
+        if (completed.didComplete) {
+          emitLessonCompleted(previous, completed.durationMs);
+          void Promise.resolve(trackingRef.current?.flush?.());
+        }
+      }
+      progressRef.current.setActiveLesson(lessonId, Date.now());
+      syncProgress();
+      track("lesson_started", { lessonId }, { lessonId });
+    },
+    [track, syncProgress, emitLessonCompleted, useV2Runtime, emitLifecycleEvent]
+  );
+  const completeCourse = useCallback(() => {
+    if (useV2Runtime && headlessRef.current) {
+      headlessRef.current.completeCourse(emitLifecycleEvent);
+      syncProgress();
+      void trackingRef.current?.flush?.();
+      return;
+    }
+    const current = progressRef.current.getState();
+    if (current.activeLessonId) {
+      const lessonResult = progressRef.current.completeLesson(current.activeLessonId, Date.now());
+      if (lessonResult.didComplete) {
+        emitLessonCompleted(current.activeLessonId, lessonResult.durationMs);
+      }
+    }
+    const result = progressRef.current.completeCourse();
+    if (!result.didComplete) return;
+    syncProgress();
+    track("course_completed");
+    void trackingRef.current?.flush?.();
+  }, [track, syncProgress, emitLessonCompleted, useV2Runtime, emitLifecycleEvent]);
+  const sessionUser = normalizedConfig.session?.user;
+  const sessionUserKey = useMemo(
+    () => sessionUser ? JSON.stringify(sessionUser) : "",
+    [sessionUser]
+  );
+  const sessionAttemptId = normalizedConfig.session?.attemptId;
+  const sessionConfiguredId = normalizedConfig.session?.sessionId;
+  useEffect2(() => {
+    if (useV2Runtime && headlessRef.current) {
+      headlessRef.current.updateConfig({
+        courseId: normalizedCourseId,
+        session: normalizedConfig.session
+      });
+    }
+  }, [
+    useV2Runtime,
+    normalizedCourseId,
+    sessionAttemptId,
+    sessionConfiguredId,
+    sessionUserKey,
+    normalizedConfig.session
+  ]);
+  useEffect2(() => {
+    if (!useV2Runtime || !headlessRef.current) return;
+    headlessRef.current.updateConfig({
+      plugins: pluginHostRef.current ?? normalizedConfig.plugins
+    });
+  }, [useV2Runtime, pluginHost]);
+  useEffect2(() => {
+    const host = useV2Runtime ? headlessRef.current?.pluginHost ?? null : pluginHost;
+    if (!host) return;
+    const ctx = buildPluginContext({
+      courseId: courseIdRef.current,
+      sessionId: sessionIdRef.current,
+      attemptId: attemptIdRef.current,
+      user: userRef.current
+    });
+    host.setupAll(ctx);
+    return () => {
+      host.disposeAll();
+    };
+  }, [pluginHost, useV2Runtime, normalizedCourseId, sessionAttemptId, sessionConfiguredId, sessionUserKey]);
+  useEffect2(() => {
+    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);
+        }
+      }
+      sessionIdRef.current = nextConfigured;
+    } else if (prevConfigured) {
+      const nextAuto = resolveSessionId(defaultStorage, void 0);
+      migrateCourseStartedMark(defaultStorage, prevConfigured, nextAuto, cid);
+      sessionIdRef.current = nextAuto;
+    }
+  }, [sessionConfiguredId, normalizedCourseId]);
+  const runtime = useMemo(
+    () => ({
+      config: normalizedConfig,
+      tracking,
+      xapi,
+      storage: defaultStorage,
+      session: { sessionId: sessionIdRef.current, attemptId: attemptIdRef.current, user: userRef.current },
+      progress,
+      setActiveLesson,
+      completeLesson,
+      completeCourse,
+      track,
+      plugins: pluginHost
+    }),
+    [
+      normalizedConfig,
+      tracking,
+      xapi,
+      progress,
+      setActiveLesson,
+      completeLesson,
+      completeCourse,
+      track,
+      pluginHost,
+      sessionUser,
+      sessionAttemptId,
+      sessionConfiguredId
+    ]
+  );
+  return runtime;
+}
+
+// src/context.tsx
+import { createContext as createContext2 } from "react";
+import { jsx as jsx2 } from "react/jsx-runtime";
+var LessonkitContext = createContext2(null);
+function LessonkitProvider(props) {
+  const runtime = useLessonkitProviderRuntime(props.config);
+  return /* @__PURE__ */ jsx2(LessonkitContext.Provider, { value: runtime, children: props.children });
+}
+
+// src/assessment/useAssessmentState.ts
+import { useMemo as useMemo3 } from "react";
+
+// src/hooks.ts
+import { useContext as useContext2, useMemo as useMemo2 } from "react";
+function useLessonkit() {
+  const ctx = useContext2(LessonkitContext);
+  if (!ctx) throw new Error("LessonKit: missing LessonkitProvider");
+  return ctx;
+}
+function useProgress() {
+  const { progress } = useLessonkit();
+  return progress;
+}
+function useTracking() {
+  const { track } = useLessonkit();
+  return useMemo2(() => ({ track }), [track]);
+}
+function useCompletion() {
+  const { completeLesson, completeCourse } = useLessonkit();
+  return useMemo2(() => ({ completeLesson, completeCourse }), [completeLesson, completeCourse]);
+}
+function useQuizState(enclosingLessonId) {
+  const { track } = useLessonkit();
+  const trackOpts = enclosingLessonId ? { lessonId: enclosingLessonId } : void 0;
+  return useMemo2(
+    () => ({
+      answer: (opts) => {
+        track("quiz_answered", opts, trackOpts);
+      },
+      complete: (opts) => {
+        track("quiz_completed", opts, trackOpts);
+      }
+    }),
+    [track, enclosingLessonId]
+  );
+}
+
+// src/assessment/useAssessmentState.ts
+function useAssessmentState(enclosingLessonId) {
+  const { track } = useLessonkit();
+  const trackOpts = enclosingLessonId ? { lessonId: enclosingLessonId } : void 0;
+  return useMemo3(
+    () => ({
+      answer: (data) => {
+        track("assessment_answered", data, trackOpts);
+      },
+      complete: (data) => {
+        track("assessment_completed", data, trackOpts);
+      }
+    }),
+    [track, enclosingLessonId]
+  );
+}
+
+// src/compound/validateChildren.ts
+import React3 from "react";
+import {
+  ACCORDION_FORBIDDEN_CHILD_TYPES,
+  COMPOUND_MAX_NESTING_DEPTH,
+  isChildTypeAllowed
+} from "@lessonkit/core";
+
+// src/compound/blockType.ts
+var LESSONKIT_BLOCK_TYPE = /* @__PURE__ */ Symbol.for("lessonkit.blockType");
+function setLessonkitBlockType(component, blockType) {
+  component[LESSONKIT_BLOCK_TYPE] = blockType;
+  if (!component.displayName) {
+    component.displayName = blockType;
+  }
+  return component;
+}
+function getLessonkitBlockType(component) {
+  if (!component || typeof component !== "object" && typeof component !== "function") {
+    return void 0;
+  }
+  const typed = component;
+  return typed[LESSONKIT_BLOCK_TYPE] ?? typed.displayName;
+}
+
+// src/compound/validateChildren.ts
+var warnedPairs = /* @__PURE__ */ new Set();
+var COMPOUND_CONTAINER_TYPES = /* @__PURE__ */ new Set([
+  "Page",
+  "InteractiveBook",
+  "Slide",
+  "SlideDeck",
+  "TimedCue",
+  "InteractiveVideo",
+  "AssessmentSequence"
+]);
+function warnOrThrow(msg, strict) {
+  if (strict) throw new Error(msg);
+  if (!warnedPairs.has(msg)) {
+    warnedPairs.add(msg);
+    console.warn(msg);
+  }
+}
+function validateNode(parent, node, depth, strict) {
+  React3.Children.forEach(node, (child) => {
+    if (!React3.isValidElement(child)) return;
+    const blockType = getLessonkitBlockType(child.type);
+    if (!blockType) {
+      if (child.props && typeof child.props === "object" && "children" in child.props) {
+        validateNode(parent, child.props.children, depth, strict);
+      }
+      return;
+    }
+    if (!isChildTypeAllowed(parent, blockType)) {
+      const key = `${parent}:${blockType}`;
+      if (!warnedPairs.has(key)) {
+        warnedPairs.add(key);
+        const msg = `[lessonkit] Block "${blockType}" is not in the allowlist for "${parent}"`;
+        if (strict) throw new Error(msg);
+        console.warn(msg);
+      }
+    }
+    if (COMPOUND_CONTAINER_TYPES.has(blockType)) {
+      const maxDepth = COMPOUND_MAX_NESTING_DEPTH[parent];
+      if (depth >= maxDepth) {
+        warnOrThrow(
+          `[lessonkit] Block "${blockType}" exceeds max nesting depth (${maxDepth}) for "${parent}"`,
+          strict
+        );
+      }
+      const nestedParent = blockType;
+      validateNode(nestedParent, child.props.children, depth + 1, strict);
+    } else if (blockType === "Accordion") {
+      const sections = child.props.sections;
+      if (sections) validateAccordionSections(sections, strict);
+    } else if (child.props && typeof child.props === "object" && "children" in child.props) {
+      validateSubtreeForForbidden(
+        child.props.children,
+        ACCORDION_FORBIDDEN_CHILD_TYPES,
+        strict
+      );
+    }
+  });
+}
+function validateSubtreeForForbidden(node, forbidden, strict) {
+  React3.Children.forEach(node, (child) => {
+    if (!React3.isValidElement(child)) return;
+    const blockType = getLessonkitBlockType(child.type);
+    if (blockType && forbidden.includes(blockType)) {
+      warnOrThrow(`[lessonkit] Block "${blockType}" must not nest inside Accordion`, strict);
+    }
+    if (blockType === "Accordion") {
+      const sections = child.props.sections;
+      if (sections) validateAccordionSections(sections, strict);
+      return;
+    }
+    if (child.props && typeof child.props === "object" && "children" in child.props) {
+      validateSubtreeForForbidden(
+        child.props.children,
+        forbidden,
+        strict
+      );
+    }
+  });
+}
+function validateAccordionSections(sections, strict) {
+  if (!isDevEnvironment() && !strict) return;
+  for (const section of sections) {
+    validateSubtreeForForbidden(section.content, ACCORDION_FORBIDDEN_CHILD_TYPES, strict);
+  }
+}
+function validateCompoundChildren(parent, children, strict) {
+  if (!isDevEnvironment() && !strict) return;
+  validateNode(parent, children, 0, strict);
+}
+function resetCompoundValidationWarningsForTests() {
+  warnedPairs.clear();
+}
+
+// src/assessment/internal/buildAssessmentHandle.ts
+function buildAssessmentHandle(opts) {
+  return {
+    getScore: opts.getScore,
+    getMaxScore: opts.getMaxScore,
+    getAnswerGiven: opts.getAnswerGiven,
+    resetTask: opts.resetTask,
+    showSolutions: opts.showSolutions,
+    getXAPIData: opts.getXAPIData,
+    ...opts.getCurrentState ? { getCurrentState: opts.getCurrentState } : {},
+    ...opts.resume ? { resume: opts.resume } : {}
+  };
+}
+
+// src/assessment/internal/resumeState.ts
+function readBooleanField(state, key) {
+  const value = state[key];
+  if (value === true || value === false || value === null) return value;
+  return void 0;
+}
+function readStringField(state, key) {
+  const value = state[key];
+  if (typeof value === "string" || value === null) return value;
+  return void 0;
+}
+function readNumberField(state, key) {
+  const value = state[key];
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (value === null) return null;
+  return void 0;
+}
+function readBooleanStateField(state, key, apply) {
+  const value = state[key];
+  if (typeof value === "boolean") apply(value);
+}
+
+// src/compound/CompoundPageIndexContext.tsx
+import { createContext as createContext3, useContext as useContext3 } from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var CompoundPageIndexContext = createContext3(void 0);
+function CompoundPageIndexProvider({
+  pageIndex,
+  children
+}) {
+  return /* @__PURE__ */ jsx3(CompoundPageIndexContext.Provider, { value: pageIndex, children });
+}
+function useCompoundPageIndex() {
+  return useContext3(CompoundPageIndexContext);
+}
+
+// src/compound/CompoundProvider.tsx
+import React6, { createContext as createContext5, useCallback as useCallback2, useContext as useContext5, useImperativeHandle, useMemo as useMemo4, useRef as useRef3, useState as useState2 } from "react";
+import { clampCompoundPageIndex, createCompoundResumeState } from "@lessonkit/core";
+
+// src/compound/aggregateScores.ts
+function aggregateAssessmentScores(handles, opts) {
+  let score = 0;
+  let maxScore = 0;
+  let allAnswered = true;
+  for (const entry of handles) {
+    const handle = "handle" in entry ? entry.handle : entry;
+    const pageIndex = "handle" in entry ? entry.pageIndex : void 0;
+    score += handle.getScore();
+    maxScore += handle.getMaxScore();
+    const countsForAnswerGiven = opts?.answerPageIndex === void 0 || pageIndex === void 0 || pageIndex === opts.answerPageIndex;
+    if (countsForAnswerGiven && !handle.getAnswerGiven()) allAnswered = false;
+  }
+  return { score, maxScore, allAnswered };
+}
+
+// src/compound/CompoundHydrationBridge.tsx
+import { createContext as createContext4, useContext as useContext4, useRef as useRef2 } from "react";
+import { jsx as jsx4 } from "react/jsx-runtime";
+var CompoundHydrationBridgeContext = createContext4(
+  null
+);
+function CompoundHydrationBridgeProvider({ children }) {
+  const bridgeRef = useRef2(null);
+  return /* @__PURE__ */ jsx4(CompoundHydrationBridgeContext.Provider, { value: bridgeRef, children });
+}
+function useCompoundHydrationBridgeRef() {
+  return useContext4(CompoundHydrationBridgeContext);
+}
+
+// src/compound/CompoundProvider.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+var CompoundRegistryContext = createContext5(null);
+var CompoundHandlesVersionContext = createContext5(0);
+function CompoundProvider({
+  children,
+  activePageIndex: _activePageIndex,
+  onActivePageIndexChange: _onActivePageIndexChange
+}) {
+  const registryRef = useRef3(/* @__PURE__ */ new Map());
+  const [handlesVersion, setHandlesVersion] = useState2(0);
+  const register = useCallback2((checkId, handle, pageIndex) => {
+    const prev = registryRef.current.get(checkId);
+    if (prev && prev.handle !== handle) {
+      const message = `[lessonkit] duplicate checkId "${checkId}" registered in the same compound container; the previous handle was replaced.`;
+      if (isDevEnvironment()) {
+        console.error(message);
+      } else {
+        console.warn(message);
+      }
+    }
+    registryRef.current.set(checkId, { handle, pageIndex });
+    if (prev?.handle !== handle || prev?.pageIndex !== pageIndex) {
+      setHandlesVersion((v) => v + 1);
+    }
+    return () => {
+      const current = registryRef.current.get(checkId);
+      if (current?.handle === handle) {
+        registryRef.current.delete(checkId);
+        setHandlesVersion((v) => v + 1);
+      }
+    };
+  }, []);
+  const registryValue = useMemo4(
+    () => ({
+      register,
+      getHandles: () => {
+        const handles = /* @__PURE__ */ new Map();
+        for (const [checkId, entry] of registryRef.current) {
+          handles.set(checkId, entry.handle);
+        }
+        return handles;
+      },
+      getRegisteredHandles: () => registryRef.current
+    }),
+    [register]
+  );
+  return /* @__PURE__ */ jsx5(CompoundHydrationBridgeProvider, { children: /* @__PURE__ */ jsx5(CompoundRegistryContext.Provider, { value: registryValue, children: /* @__PURE__ */ jsx5(CompoundHandlesVersionContext.Provider, { value: handlesVersion, children }) }) });
+}
+function useCompoundRegistry() {
+  const registry = useContext5(CompoundRegistryContext);
+  const handlesVersion = useContext5(CompoundHandlesVersionContext);
+  if (!registry) return null;
+  return { ...registry, handlesVersion };
+}
+function useCompoundHandlesVersion() {
+  return useContext5(CompoundHandlesVersionContext);
+}
+function useRegisterAssessmentHandle(checkId, handle) {
+  const registry = useContext5(CompoundRegistryContext);
+  const pageIndex = useCompoundPageIndex();
+  React6.useLayoutEffect(() => {
+    if (!registry || !handle) return;
+    return registry.register(checkId, handle, pageIndex);
+  }, [registry, checkId, handle, pageIndex]);
+}
+function useCompoundHandleRef(ref, opts) {
+  const { activePageIndex, setActivePageIndex, getHandles, getRegisteredHandles, pageCount } = opts;
+  const bridgeRef = useCompoundHydrationBridgeRef();
+  const setIndexClamped = useCallback2(
+    (index) => {
+      const next = pageCount !== void 0 ? clampCompoundPageIndex(index, pageCount) : Math.max(0, Math.floor(index));
+      setActivePageIndex(next);
+    },
+    [pageCount, setActivePageIndex]
+  );
+  useImperativeHandle(
+    ref,
+    () => ({
+      getScore: () => aggregateAssessmentScores(getRegisteredHandles().values()).score,
+      getMaxScore: () => aggregateAssessmentScores(getRegisteredHandles().values()).maxScore,
+      getAnswerGiven: () => aggregateAssessmentScores(getRegisteredHandles().values(), {
+        answerPageIndex: activePageIndex
+      }).allAnswered,
+      resetTask: () => {
+        for (const entry of getRegisteredHandles().values()) entry.handle.resetTask();
+      },
+      showSolutions: () => {
+        if (!opts.enableSolutionsButton) return;
+        for (const entry of getRegisteredHandles().values()) entry.handle.showSolutions();
+      },
+      getCurrentState: () => {
+        const childStates = {};
+        for (const [checkId, entry] of getRegisteredHandles()) {
+          if (entry.handle.getCurrentState) {
+            childStates[checkId] = entry.handle.getCurrentState();
+          }
+        }
+        return createCompoundResumeState({ activePageIndex, childStates });
+      },
+      resume: (state) => {
+        bridgeRef?.current?.notifyImperativeResume(state);
+      }
+    }),
+    [activePageIndex, setIndexClamped, getHandles, getRegisteredHandles, opts.enableSolutionsButton, bridgeRef]
+  );
+}
+
+// src/assessment/internal/useAssessmentHandleRegistration.ts
+import { useImperativeHandle as useImperativeHandle2 } from "react";
+function useAssessmentHandleRegistration(checkId, handle, ref) {
+  useImperativeHandle2(ref, () => handle, [handle]);
+  useRegisterAssessmentHandle(checkId, handle);
+}
+
+// src/assessment/scoring.ts
+function resolvePassingThreshold(passingScore, maxScore) {
+  return passingScore ?? maxScore;
+}
+function meetsPassingThreshold(score, maxScore, passingScore) {
+  const threshold = resolvePassingThreshold(passingScore, maxScore);
+  return score >= threshold;
+}
+function scoreFromCustom(custom, fallbackCorrect, fallbackMax = 1, passingScore) {
+  const maxScore = custom?.maxScore ?? fallbackMax;
+  if (custom?.passed !== void 0) {
+    const score2 = custom.passed ? custom.score ?? maxScore : custom.score ?? 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 };
+}
+
+// src/assessment/internal/usePluginScoring.ts
+import { useCallback as useCallback3 } from "react";
+function usePluginScoring(checkId, lessonId) {
+  const { plugins, config, session } = useLessonkit();
+  const getPluginScore = useCallback3(
+    (response) => {
+      const pluginCtx = buildPluginContext({
+        courseId: config.courseId,
+        sessionId: session.sessionId,
+        attemptId: session.attemptId,
+        user: session.user
+      });
+      return plugins?.scoreAssessment({ checkId, lessonId, response }, pluginCtx) ?? null;
+    },
+    [checkId, config.courseId, lessonId, plugins, session.attemptId, session.sessionId, session.user]
+  );
+  const scoreResponse = useCallback3(
+    (response, defaultCorrect, maxScore = 1, passingScore) => scoreFromCustom(getPluginScore(response), defaultCorrect, maxScore, passingScore),
+    [getPluginScore]
+  );
+  const isChoiceCorrect = useCallback3(
+    (choice, answer, custom, passingScore) => {
+      if (!custom) return choice === answer;
+      if (custom.passed !== void 0) return custom.passed;
+      if (custom.maxScore != null && custom.maxScore > 0 && custom.score != null) {
+        return meetsPassingThreshold(custom.score, custom.maxScore, passingScore);
+      }
+      return choice === answer;
+    },
+    []
+  );
+  return { getPluginScore, scoreResponse, isChoiceCorrect };
+}
+
+export {
+  LessonContext,
+  useEnclosingLessonId,
+  isDevEnvironment,
+  normalizeComponentId,
+  resetAssessmentWarningsForTests,
+  AssessmentLessonGuard,
+  buildAssessmentHandle,
+  readBooleanField,
+  readStringField,
+  readNumberField,
+  readBooleanStateField,
+  useCompoundHydrationBridgeRef,
+  CompoundPageIndexProvider,
+  CompoundProvider,
+  useCompoundRegistry,
+  useCompoundHandlesVersion,
+  useCompoundHandleRef,
+  useAssessmentHandleRegistration,
+  shouldEnforceProductionGuard,
+  assertProductionCourseConfig,
+  resetCourseStartedTrackingFlightForTests,
+  resetLessonkitProviderStorageForTests,
+  LessonkitContext,
+  LessonkitProvider,
+  useAssessmentState,
+  useLessonkit,
+  useProgress,
+  useTracking,
+  useCompletion,
+  useQuizState,
+  meetsPassingThreshold,
+  usePluginScoring,
+  setLessonkitBlockType,
+  validateAccordionSections,
+  validateCompoundChildren,
+  resetCompoundValidationWarningsForTests
+};