@lessonkit/react 0.9.2 → 1.0.0

package/dist/index.cjs

@@ -42,9 +42,15 @@ __export(index_exports, {
   ThemeProvider: () => ThemeProvider,
   blockCatalogVersion: () => blockCatalogVersion,
   buildBlockCatalog: () => buildBlockCatalog,
-  createPluginHost: () => import_core7.createPluginHost,
-  defineLessonkitPlugin: () => import_core7.defineLessonkitPlugin,
+  buildTelemetryEvent: () => import_core10.buildTelemetryEvent,
+  createLessonkitRuntime: () => import_core10.createLessonkitRuntime,
+  createPluginRegistry: () => import_core10.createPluginRegistry,
+  createTelemetryPipeline: () => import_core10.createTelemetryPipeline,
+  defineAssessmentPlugin: () => import_core10.defineAssessmentPlugin,
+  defineLifecyclePlugin: () => import_core10.defineLifecyclePlugin,
+  defineTelemetryPlugin: () => import_core10.defineTelemetryPlugin,
   getBlockCatalogEntry: () => getBlockCatalogEntry,
+  resetQuizWarningsForTests: () => resetQuizWarningsForTests,
   useCompletion: () => useCompletion,
   useLessonkit: () => useLessonkit,
   useProgress: () => useProgress,
@@ -55,240 +61,95 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/components.tsx
-var import_react3 = require("react");
+var import_react5 = require("react");
 var import_accessibility = require("@lessonkit/accessibility");
 
 // src/context.tsx
+var import_react2 = require("react");
+
+// src/provider/useLessonkitProviderRuntime.ts
 var import_react = require("react");
-var import_core5 = require("@lessonkit/core");
+var import_core8 = require("@lessonkit/core");
 var import_xapi3 = require("@lessonkit/xapi");
 var import_xapi4 = require("@lessonkit/xapi");
 
 // src/runtime/emitTelemetry.ts
+var import_core2 = require("@lessonkit/core");
+
+// src/runtime/telemetryPipeline.ts
 var import_core = require("@lessonkit/core");
 var import_xapi = require("@lessonkit/xapi");
 
 // src/runtime/lxpackBridge.ts
 var import_bridge = require("@lessonkit/lxpack/bridge");
-function getBridge() {
-  const fromSdk = (0, import_bridge.getLxpackBridge)();
-  if (fromSdk) return fromSdk;
-  if (typeof window === "undefined") return null;
-  const parent = window.parent;
-  if (!parent || parent === window) return null;
-  return parent.lxpack ?? null;
+function forwardTelemetryToLxpack(event, mode = "auto") {
+  (0, import_bridge.forwardTelemetryToBridge)(event, mode);
 }
-function applyBridgeAction(bridge, action) {
-  if (!action) return;
-  switch (action.kind) {
-    case "completeLesson":
-      bridge.completeLesson?.(action.lessonId);
-      return;
-    case "completeCourse":
-      bridge.completeCourse?.();
-      return;
-    case "submitAssessment": {
-      const scaled = (0, import_bridge.normalizeScore)({
-        score: action.score,
-        maxScore: action.maxScore
-      });
-      if (scaled === null) return;
-      bridge.submitAssessment?.({
-        id: action.id,
-        score: scaled,
-        passingScore: (0, import_bridge.normalizePassingThreshold)({
-          passingScore: action.passingScore,
-          maxScore: action.maxScore
-        }),
-        maxScore: action.maxScore
-      });
-      return;
-    }
-    case "track":
-      bridge.track?.(action.event);
-      return;
-    default:
-      return;
-  }
+
+// src/runtime/telemetryPipeline.ts
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
-function forwardTelemetryToLxpack(event, mode = "auto") {
-  if (mode === "off") return;
-  const bridge = getBridge();
-  if (!bridge) return;
-  const lessonkitEvent = (0, import_bridge.telemetryEventToLessonkit)(event);
-  if (!lessonkitEvent) return;
-  const action = (0, import_bridge.mapLessonkitTelemetryToBridgeAction)(lessonkitEvent);
-  applyBridgeAction(bridge, action);
+function createLegacyPipeline(opts, extraSinks = []) {
+  return (0, import_core.createTelemetryPipeline)([
+    (0, import_core.createTrackingPipelineSink)("tracking", (event) => opts.tracking.track(event)),
+    {
+      id: "xapi",
+      emit(event) {
+        try {
+          const statement = (0, import_xapi.telemetryEventToXAPIStatement)(event);
+          if (statement) opts.xapi?.send(statement);
+        } catch (err) {
+          if (isDevEnvironment()) {
+            console.warn(
+              "[lessonkit] xAPI mapping skipped:",
+              err instanceof Error ? err.message : err
+            );
+          }
+        }
+      }
+    },
+    {
+      id: "lxpack-bridge",
+      emit(event) {
+        forwardTelemetryToLxpack(event, opts.lxpackBridge);
+      }
+    },
+    ...extraSinks
+  ]);
+}
+function emitThroughPipeline(event, opts, extraSinks) {
+  createLegacyPipeline(opts, extraSinks).emit(event);
 }
 
 // src/runtime/emitTelemetry.ts
 var warnedMissingCourseId = false;
-var warnedMissingQuizLesson = false;
-function isDevEnvironment() {
+function isDevEnvironment2() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
 function emitTelemetry(tracking, xapi, event, opts) {
   if (!event.courseId) {
-    if (isDevEnvironment() && !warnedMissingCourseId) {
+    if (isDevEnvironment2() && !warnedMissingCourseId) {
       warnedMissingCourseId = true;
       console.warn("[lessonkit] telemetry event missing courseId");
     }
     return;
   }
-  tracking.track(event);
-  try {
-    const statement = (0, import_xapi.telemetryEventToXAPIStatement)(event);
-    if (statement) xapi?.send(statement);
-  } catch (err) {
-    if (isDevEnvironment()) {
-      console.warn("[lessonkit] xAPI mapping skipped:", err instanceof Error ? err.message : err);
-    }
-  }
-  forwardTelemetryToLxpack(event, opts?.lxpackBridge ?? "auto");
-}
-function buildTrackEvent(opts) {
-  const base = {
-    timestamp: (0, import_core.nowIso)(),
-    courseId: opts.courseId,
-    sessionId: opts.sessionId,
-    attemptId: opts.attemptId,
-    user: opts.user
+  const legacy = {
+    tracking,
+    xapi,
+    lxpackBridge: opts?.lxpackBridge ?? "auto"
   };
-  switch (opts.name) {
-    case "course_started":
-      return { name: "course_started", ...base };
-    case "course_completed":
-      return { name: "course_completed", ...base };
-    case "lesson_started": {
-      const data = opts.data;
-      const lessonId = opts.lessonId ?? data?.lessonId;
-      if (!lessonId) throw new Error("lesson_started requires lessonId");
-      return {
-        name: "lesson_started",
-        ...base,
-        lessonId,
-        data: { ...data, lessonId }
-      };
-    }
-    case "lesson_completed":
-    case "lesson_time_on_task": {
-      const data = opts.data;
-      const lessonId = opts.lessonId ?? data?.lessonId;
-      if (!lessonId) throw new Error(`${opts.name} requires lessonId`);
-      return {
-        name: opts.name,
-        ...base,
-        lessonId,
-        data: { ...data, lessonId }
-      };
-    }
-    case "quiz_answered": {
-      const data = opts.data;
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
-      return { name: "quiz_answered", ...base, lessonId, data };
-    }
-    case "quiz_completed": {
-      const data = opts.data;
-      const lessonId = opts.lessonId;
-      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
-      return { name: "quiz_completed", ...base, lessonId, data };
-    }
-    case "interaction":
-      return {
-        name: "interaction",
-        ...base,
-        lessonId: opts.lessonId,
-        data: opts.data
-      };
-    default:
-      return { name: opts.name, ...base };
-  }
-}
-function tryBuildTrackEvent(opts) {
-  const isQuiz = opts.name === "quiz_answered" || opts.name === "quiz_completed";
-  if (isQuiz && !opts.lessonId) {
-    if (isDevEnvironment() && !warnedMissingQuizLesson) {
-      warnedMissingQuizLesson = true;
-      console.warn(
-        `[lessonkit] ${opts.name} skipped: wrap <Quiz> in <Lesson> so an active lessonId is available`
-      );
-    }
-    return null;
-  }
-  return buildTrackEvent(opts);
+  emitThroughPipeline(event, legacy, opts?.extraSinks);
 }
 
 // src/runtime/ports.ts
-function createNoopStorage() {
-  return {
-    getItem: () => null,
-    setItem: () => {
-    }
-  };
-}
-function createSessionStoragePort() {
-  if (typeof sessionStorage === "undefined") return createNoopStorage();
-  return {
-    getItem: (key) => {
-      try {
-        return sessionStorage.getItem(key);
-      } catch {
-        return null;
-      }
-    },
-    setItem: (key, value) => {
-      try {
-        sessionStorage.setItem(key, value);
-      } catch {
-      }
-    },
-    removeItem: (key) => {
-      try {
-        sessionStorage.removeItem(key);
-      } catch {
-      }
-    }
-  };
-}
+var import_core3 = require("@lessonkit/core");
 
 // src/runtime/progress.ts
-function createProgressController() {
-  let activeLessonId;
-  let completedLessonIds = /* @__PURE__ */ new Set();
-  let courseCompleted = false;
-  const lessonStartTimes = /* @__PURE__ */ new Map();
-  return {
-    getState: () => ({
-      activeLessonId,
-      completedLessonIds: new Set(completedLessonIds),
-      courseCompleted
-    }),
-    setActiveLesson: (lessonId, startedAtMs) => {
-      const previousLessonId = activeLessonId;
-      activeLessonId = lessonId;
-      lessonStartTimes.set(lessonId, startedAtMs);
-      return { previousLessonId };
-    },
-    completeLesson: (lessonId, completedAtMs) => {
-      if (completedLessonIds.has(lessonId)) return { didComplete: false };
-      completedLessonIds = new Set(completedLessonIds).add(lessonId);
-      if (activeLessonId === lessonId) {
-        activeLessonId = void 0;
-      }
-      const startedAt = lessonStartTimes.get(lessonId);
-      lessonStartTimes.delete(lessonId);
-      const durationMs = typeof startedAt === "number" ? Math.max(0, completedAtMs - startedAt) : void 0;
-      return { durationMs, didComplete: true };
-    },
-    completeCourse: () => {
-      if (courseCompleted) return { didComplete: false };
-      courseCompleted = true;
-      return { didComplete: true };
-    }
-  };
-}
+var import_core4 = require("@lessonkit/core");
 
 // src/runtime/xapi.ts
 var import_xapi2 = require("@lessonkit/xapi");
@@ -306,64 +167,37 @@ function createXapiClientFromConfig(config, queue) {
 }
 
 // src/runtime/session.ts
-var import_core2 = require("@lessonkit/core");
-var SESSION_STORAGE_KEY = "lessonkit:sessionId";
-function getTabSessionId(storage) {
-  return storage.getItem(SESSION_STORAGE_KEY);
-}
-var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
-function resolveSessionId(storage, provided) {
-  if (provided) return provided;
-  const existing = storage.getItem(SESSION_STORAGE_KEY);
-  if (existing) return existing;
-  const id = (0, import_core2.createSessionId)();
-  storage.setItem(SESSION_STORAGE_KEY, id);
-  return id;
-}
-function courseStartedStorageKey(sessionId, courseId) {
-  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
-}
-function hasCourseStarted(storage, sessionId, courseId) {
-  if (!courseId) return false;
-  return storage.getItem(courseStartedStorageKey(sessionId, courseId)) === "1";
-}
-function markCourseStarted(storage, sessionId, courseId) {
-  if (!courseId) return;
-  storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
-}
-function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
-  if (!courseId || fromSessionId === toSessionId) return;
-  if (hasCourseStarted(storage, fromSessionId, courseId)) {
-    markCourseStarted(storage, toSessionId, courseId);
-    storage.removeItem?.(courseStartedStorageKey(fromSessionId, courseId));
-  }
-}
+var import_core5 = require("@lessonkit/core");
 
 // src/runtime/plugins.ts
-var import_core3 = require("@lessonkit/core");
+var import_core6 = require("@lessonkit/core");
 function createReactPluginHost(plugins) {
   if (!plugins?.length) return null;
-  return (0, import_core3.createPluginHost)(plugins);
+  return (0, import_core6.createPluginRegistry)(plugins);
 }
 function buildPluginContext(opts) {
   return {
     courseId: opts.courseId,
     sessionId: opts.sessionId,
-    attemptId: opts.attemptId
+    attemptId: opts.attemptId,
+    user: opts.user
   };
 }
 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" });
+  emitTelemetry(opts.tracking, opts.xapi, next, {
+    lxpackBridge: opts.lxpackBridge ?? "auto",
+    extraSinks: opts.extraSinks
+  });
 }
 
 // src/runtime/telemetry.ts
-var import_core4 = require("@lessonkit/core");
+var import_core7 = require("@lessonkit/core");
 function createTrackingClientFromConfig(config) {
-  if (config.tracking?.enabled === false) return (0, import_core4.createTrackingClient)();
+  if (config.tracking?.enabled === false) return (0, import_core7.createTrackingClient)();
   if (config.tracking?.createClient) return config.tracking.createClient();
-  return (0, import_core4.createTrackingClient)({
+  return (0, import_core7.createTrackingClient)({
     sink: config.tracking?.sink,
     batchSink: config.tracking?.batchSink,
     batch: config.tracking?.batch
@@ -380,70 +214,206 @@ async function disposeTrackingClient(client) {
   }
 }
 
-// src/context.tsx
-var import_jsx_runtime = require("react/jsx-runtime");
-var LessonkitContext = (0, import_react.createContext)(null);
+// src/provider/useLessonkitProviderRuntime.ts
 var useIsoLayoutEffect = typeof window !== "undefined" ? import_react.useLayoutEffect : import_react.useEffect;
-var defaultStorage = createSessionStoragePort();
+var defaultStorage = (0, import_core3.createSessionStoragePort)();
 function isTrackingActive(tracking) {
   return tracking?.enabled !== false;
 }
-function emitCourseStarted(opts) {
+var noopTrackingClient = { track: () => {
+} };
+function buildCourseStartedEvent(opts) {
+  const pluginCtx = buildPluginContext({
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  });
+  const built = (0, import_core2.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;
+}
+function emitCourseStartedPipelineOnly(opts) {
   const pluginCtx = buildPluginContext({
     courseId: opts.courseId,
     sessionId: opts.sessionId,
-    attemptId: opts.attemptId
+    attemptId: opts.attemptId,
+    user: opts.user
   });
   try {
     emitTelemetryWithPlugins({
-      pluginHost: opts.pluginHost,
-      tracking: opts.tracking,
+      pluginHost: null,
+      tracking: noopTrackingClient,
       xapi: opts.xapi,
-      event: buildTrackEvent({
-        name: "course_started",
-        courseId: opts.courseId,
-        sessionId: opts.sessionId,
-        attemptId: opts.attemptId,
-        user: opts.user
-      }),
+      event: opts.event,
       pluginCtx,
-      lxpackBridge: opts.lxpackBridge
+      lxpackBridge: opts.lxpackBridge,
+      extraSinks: opts.extraSinks
     });
-    markCourseStarted(opts.storage, opts.sessionId, opts.courseId);
+    (0, import_core5.markCourseStarted)(opts.storage, opts.sessionId, opts.courseId);
     return true;
   } catch {
     return false;
   }
 }
-function LessonkitProvider(props) {
-  const config = props.config;
-  const sessionIdRef = (0, import_react.useRef)(resolveSessionId(defaultStorage, config.session?.sessionId));
-  const prevConfiguredSessionIdRef = (0, import_react.useRef)(config.session?.sessionId);
-  if (config.session?.sessionId) {
-    sessionIdRef.current = config.session.sessionId;
+function emitCourseStarted(opts) {
+  const event = buildCourseStartedEvent(opts);
+  if (event === null) return true;
+  const trackingAlreadyEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (!trackingAlreadyEmitted) {
+    try {
+      opts.tracking.track(event);
+      (0, import_core5.markCourseStartedEmittedToTracking)(opts.storage, opts.sessionId, opts.courseId);
+    } catch {
+      return false;
+    }
+  }
+  return emitCourseStartedPipelineOnly({ ...opts, event });
+}
+function emitCourseStartedToTrackingOnly(opts) {
+  const event = buildCourseStartedEvent(opts);
+  if (event === null) return true;
+  const trackingAlreadyEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (!trackingAlreadyEmitted) {
+    try {
+      opts.tracking.track(event);
+      (0, import_core5.markCourseStartedEmittedToTracking)(opts.storage, opts.sessionId, opts.courseId);
+    } catch {
+      return false;
+    }
+  }
+  const pluginCtx = buildPluginContext({
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  });
+  try {
+    emitTelemetryWithPlugins({
+      pluginHost: null,
+      tracking: noopTrackingClient,
+      xapi: null,
+      event,
+      pluginCtx,
+      lxpackBridge: opts.lxpackBridge,
+      extraSinks: opts.extraSinks
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function emitPendingCourseStarted(opts) {
+  const trackingEmitted = (0, import_core5.hasCourseStartedEmittedToTracking)(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  const sessionStarted = (0, import_core5.hasCourseStarted)(opts.storage, opts.sessionId, opts.courseId);
+  if (sessionStarted && !trackingEmitted) {
+    return emitCourseStartedToTrackingOnly(opts);
+  }
+  if (trackingEmitted && !sessionStarted) {
+    const event = buildCourseStartedEvent(opts);
+    if (event === null) return true;
+    return emitCourseStartedPipelineOnly({ ...opts, event });
+  }
+  if (!trackingEmitted && !sessionStarted) {
+    return emitCourseStarted(opts);
+  }
+  return true;
+}
+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"
+  );
+}
+function useLessonkitProviderRuntime(config) {
+  const normalizedCourseId = (0, import_react.useMemo)(
+    () => (0, import_core8.assertValidId)(config.courseId, "courseId"),
+    [config.courseId]
+  );
+  const normalizedConfig = (0, import_react.useMemo)(
+    () => ({ ...config, courseId: normalizedCourseId }),
+    [config, normalizedCourseId]
+  );
+  const useV2Runtime = normalizedConfig.runtimeVersion !== "v1";
+  const extraSinksRef = (0, import_react.useRef)(normalizedConfig.sinks);
+  extraSinksRef.current = normalizedConfig.sinks;
+  const headlessRef = (0, import_react.useRef)(null);
+  const sessionIdRef = (0, import_react.useRef)((0, import_core5.resolveSessionId)(defaultStorage, normalizedConfig.session?.sessionId));
+  const prevConfiguredSessionIdRef = (0, import_react.useRef)(normalizedConfig.session?.sessionId);
+  if (normalizedConfig.session?.sessionId) {
+    sessionIdRef.current = normalizedConfig.session.sessionId;
   } else if (prevConfiguredSessionIdRef.current) {
-    sessionIdRef.current = resolveSessionId(defaultStorage, void 0);
+    sessionIdRef.current = (0, import_core5.resolveSessionId)(defaultStorage, void 0);
   }
-  const attemptIdRef = (0, import_react.useRef)(config.session?.attemptId);
-  const userRef = (0, import_react.useRef)(config.session?.user);
-  attemptIdRef.current = config.session?.attemptId;
-  userRef.current = config.session?.user;
-  const courseIdRef = (0, import_react.useRef)(config.courseId);
-  courseIdRef.current = config.courseId;
-  const lxpackBridgeModeRef = (0, import_react.useRef)(config.lxpack?.bridge ?? "auto");
-  lxpackBridgeModeRef.current = config.lxpack?.bridge ?? "auto";
-  const pluginHost = (0, import_react.useMemo)(() => createReactPluginHost(config.plugins), [config.plugins]);
+  const attemptIdRef = (0, import_react.useRef)(normalizedConfig.session?.attemptId);
+  const userRef = (0, import_react.useRef)(normalizedConfig.session?.user);
+  attemptIdRef.current = normalizedConfig.session?.attemptId;
+  userRef.current = normalizedConfig.session?.user;
+  const courseIdRef = (0, import_react.useRef)(normalizedCourseId);
+  courseIdRef.current = normalizedCourseId;
+  const lxpackBridgeModeRef = (0, import_react.useRef)(normalizedConfig.lxpack?.bridge ?? "auto");
+  lxpackBridgeModeRef.current = normalizedConfig.lxpack?.bridge ?? "auto";
+  const pluginHost = (0, import_react.useMemo)(() => createReactPluginHost(normalizedConfig.plugins), [normalizedConfig.plugins]);
   const pluginHostRef = (0, import_react.useRef)(pluginHost);
   pluginHostRef.current = pluginHost;
-  const progressRef = (0, import_react.useRef)(createProgressController());
+  const progressRef = (0, import_react.useRef)((0, import_core4.createProgressController)());
   const courseStartedEmittedToSinkRef = (0, import_react.useRef)(false);
-  const prevCourseIdForProgressRef = (0, import_react.useRef)(config.courseId);
+  const prevCourseIdForProgressRef = (0, import_react.useRef)(normalizedCourseId);
   const pendingCourseIdResetRef = (0, import_react.useRef)(false);
-  if (prevCourseIdForProgressRef.current !== config.courseId) {
-    prevCourseIdForProgressRef.current = config.courseId;
-    progressRef.current = createProgressController();
+  const prevUseV2RuntimeRef = (0, import_react.useRef)(useV2Runtime);
+  const xapiCourseStartedSentOnClientRef = (0, import_react.useRef)(false);
+  if (prevUseV2RuntimeRef.current !== useV2Runtime) {
+    prevUseV2RuntimeRef.current = useV2Runtime;
+    if (useV2Runtime) {
+      headlessRef.current = (0, import_core8.createLessonkitRuntime)({
+        courseId: normalizedCourseId,
+        runtimeVersion: "v2",
+        session: normalizedConfig.session
+      });
+      progressRef.current = headlessRef.current.progress;
+    } else {
+      headlessRef.current = null;
+      progressRef.current = (0, import_core4.createProgressController)();
+    }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
+  } else if (useV2Runtime && !headlessRef.current) {
+    headlessRef.current = (0, import_core8.createLessonkitRuntime)({
+      courseId: normalizedCourseId,
+      runtimeVersion: "v2",
+      session: normalizedConfig.session
+    });
+  }
+  if (prevCourseIdForProgressRef.current !== normalizedCourseId) {
+    prevCourseIdForProgressRef.current = normalizedCourseId;
+    if (useV2Runtime && headlessRef.current) {
+      headlessRef.current.resetForCourseChange(normalizedCourseId);
+      progressRef.current = headlessRef.current.progress;
+    } else {
+      progressRef.current = (0, import_core4.createProgressController)();
+    }
+    pendingCourseIdResetRef.current = true;
+    courseStartedEmittedToSinkRef.current = false;
+  }
+  if (useV2Runtime && headlessRef.current) {
+    progressRef.current = headlessRef.current.progress;
   }
   const [progress, setProgress] = (0, import_react.useState)(() => progressRef.current.getState());
   const syncProgress = (0, import_react.useCallback)(() => {
@@ -454,16 +424,16 @@ function LessonkitProvider(props) {
   const xapiQueueRef = (0, import_react.useRef)((0, import_xapi3.createInMemoryXAPIQueue)());
   const xapiRef = (0, import_react.useRef)(null);
   const [xapi, setXapi] = (0, import_react.useState)(null);
-  const prevXapiCourseIdRef = (0, import_react.useRef)(config.courseId);
-  const xapiEnabled = config.xapi?.enabled;
-  const xapiClient = config.xapi?.client;
-  const xapiTransport = config.xapi?.transport;
-  const courseId = config.courseId;
-  const trackingEnabled = config.tracking?.enabled;
+  const prevXapiCourseIdRef = (0, import_react.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 (config.xapi?.client) {
+      if (normalizedConfig.xapi?.client) {
         const g = globalThis;
         if (typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production") {
           console.warn(
@@ -474,20 +444,24 @@ function LessonkitProvider(props) {
       }
       xapiQueueRef.current = (0, import_xapi3.createInMemoryXAPIQueue)();
       prevXapiCourseIdRef.current = courseId;
+      xapiCourseStartedSentOnClientRef.current = false;
     }
     const prev = xapiRef.current;
-    const next = createXapiClientFromConfig(config, xapiQueueRef.current);
+    const next = createXapiClientFromConfig(normalizedConfig, xapiQueueRef.current);
     xapiRef.current = next;
     setXapi(next);
-    if (next && !prev) {
+    if (next) {
       const sessionId = sessionIdRef.current;
       const cid = courseIdRef.current;
-      const trackingActive = isTrackingActive(config.tracking);
-      const alreadyStarted = hasCourseStarted(defaultStorage, sessionId, cid);
-      if (!trackingActive || alreadyStarted) {
+      const trackingActive = isTrackingActive(normalizedConfig.tracking);
+      const alreadyStarted = (0, import_core5.hasCourseStarted)(defaultStorage, sessionId, cid);
+      const clientChanged = !prev || prev !== next;
+      const skipBootstrap = trackingActive && !alreadyStarted;
+      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && (!alreadyStarted || clientChanged);
+      if (needsBootstrap) {
         try {
           const statement = (0, import_xapi4.telemetryEventToXAPIStatement)(
-            buildTrackEvent({
+            (0, import_core2.buildTelemetryEvent)({
               name: "course_started",
               courseId: cid,
               sessionId,
@@ -497,7 +471,10 @@ function LessonkitProvider(props) {
           );
           if (statement) {
             next.send(statement);
-            markCourseStarted(defaultStorage, sessionId, cid);
+            if (!alreadyStarted) {
+              (0, import_core5.markCourseStarted)(defaultStorage, sessionId, cid);
+            }
+            xapiCourseStartedSentOnClientRef.current = true;
           }
         } catch {
         }
@@ -522,49 +499,56 @@ function LessonkitProvider(props) {
       void prev?.flush();
     };
   }, [xapiEnabled, xapiClient, xapiTransport, courseId, trackingEnabled]);
-  const trackingRef = (0, import_react.useRef)((0, import_core5.createTrackingClient)());
+  const trackingRef = (0, import_react.useRef)((0, import_core8.createTrackingClient)());
   const trackingClientForUnmountRef = (0, import_react.useRef)(trackingRef.current);
   const [tracking, setTracking] = (0, import_react.useState)(() => trackingRef.current);
-  const trackingSink = config.tracking?.sink;
-  const trackingBatchSink = config.tracking?.batchSink;
-  const batchEnabled = config.tracking?.batch?.enabled;
-  const batchFlushIntervalMs = config.tracking?.batch?.flushIntervalMs;
-  const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
+  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 = (0, import_react.useCallback)(
     () => buildPluginContext({
       courseId: courseIdRef.current,
       sessionId: sessionIdRef.current,
-      attemptId: attemptIdRef.current
+      attemptId: attemptIdRef.current,
+      user: userRef.current
     }),
     []
   );
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
-    const baseSink = config.tracking?.sink;
-    const sink = pluginHostRef.current && baseSink ? (event) => {
-      const composed = pluginHostRef.current.composeTrackingSink(baseSink, buildCurrentPluginCtx()) ?? baseSink;
-      return composed(event);
-    } : baseSink;
-    const batchSink = pluginHostRef.current && config.tracking?.batchSink ? (events) => {
-      const delivered = pluginHostRef.current.deliverTelemetryBatch(
-        events,
-        buildCurrentPluginCtx()
-      );
-      return config.tracking.batchSink(delivered);
-    } : config.tracking?.batchSink;
+    const baseSink = normalizedConfig.tracking?.sink;
+    const userBatchSink = normalizedConfig.tracking?.batchSink;
+    assertTrackingSinkConfig(normalizedConfig.tracking);
+    const sink = pluginHostRef.current && baseSink ? 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: { ...config.tracking, sink, batchSink }
+      tracking: { ...normalizedConfig.tracking, sink, batchSink }
     });
     trackingRef.current = next;
     trackingClientForUnmountRef.current = next;
     setTracking(next);
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
-    const trackingActive = isTrackingActive(config.tracking);
+    const trackingActive = isTrackingActive(normalizedConfig.tracking);
     if (!trackingActive) {
       courseStartedEmittedToSinkRef.current = false;
-    } else if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
-      const emitted = emitCourseStarted({
+    } else if (!courseStartedEmittedToSinkRef.current) {
+      const emitted = emitPendingCourseStarted({
         pluginHost: pluginHostRef.current,
         tracking: next,
         xapi: xapiRef.current,
@@ -573,8 +557,12 @@ function LessonkitProvider(props) {
         courseId: cid,
         attemptId: attemptIdRef.current,
         user: userRef.current,
-        lxpackBridge: lxpackBridgeModeRef.current
+        lxpackBridge: lxpackBridgeModeRef.current,
+        extraSinks: extraSinksRef.current
       });
+      if (emitted) {
+        (0, import_core5.markCourseStartedEmittedToTracking)(defaultStorage, sessionId, cid);
+      }
       courseStartedEmittedToSinkRef.current = emitted;
     } else if (trackingActive) {
       courseStartedEmittedToSinkRef.current = true;
@@ -591,8 +579,8 @@ function LessonkitProvider(props) {
     batchEnabled,
     batchFlushIntervalMs,
     batchMaxBatchSize,
-    config.plugins,
-    config.courseId,
+    normalizedConfig.plugins,
+    normalizedCourseId,
     buildCurrentPluginCtx
   ]);
   const emitWithBridge = (0, import_react.useCallback)((trackingClient, event) => {
@@ -604,14 +592,32 @@ function LessonkitProvider(props) {
       pluginCtx: buildPluginContext({
         courseId: courseIdRef.current,
         sessionId: sessionIdRef.current,
-        attemptId: attemptIdRef.current
+        attemptId: attemptIdRef.current,
+        user: userRef.current
       }),
-      lxpackBridge: lxpackBridgeModeRef.current
+      lxpackBridge: lxpackBridgeModeRef.current,
+      extraSinks: extraSinksRef.current
     });
   }, []);
+  const emitLifecycleEvent = (0, import_react.useCallback)(
+    (name, data, lessonId) => {
+      const event = (0, import_core2.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 = (0, import_react.useCallback)(
     (name, data, opts) => {
-      const event = tryBuildTrackEvent({
+      const event = (0, import_core2.tryBuildTelemetryEvent)({
         name,
         courseId: courseIdRef.current,
         lessonId: opts?.lessonId ?? activeLessonIdRef.current,
@@ -629,7 +635,7 @@ function LessonkitProvider(props) {
     if (!pendingCourseIdResetRef.current) return;
     pendingCourseIdResetRef.current = false;
     syncProgress();
-    if (!isTrackingActive(config.tracking)) return;
+    if (!isTrackingActive(normalizedConfig.tracking)) return;
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
     void (async () => {
@@ -637,8 +643,8 @@ function LessonkitProvider(props) {
         await trackingRef.current?.flush?.();
       } catch {
       }
-      if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
-        const emitted = emitCourseStarted({
+      if (!courseStartedEmittedToSinkRef.current) {
+        const emitted = emitPendingCourseStarted({
           pluginHost: pluginHostRef.current,
           tracking: trackingRef.current,
           xapi: xapiRef.current,
@@ -647,12 +653,13 @@ function LessonkitProvider(props) {
           courseId: cid,
           attemptId: attemptIdRef.current,
           user: userRef.current,
-          lxpackBridge: lxpackBridgeModeRef.current
+          lxpackBridge: lxpackBridgeModeRef.current,
+          extraSinks: extraSinksRef.current
         });
         courseStartedEmittedToSinkRef.current = emitted;
       }
     })();
-  }, [config.courseId, config.tracking?.enabled, syncProgress]);
+  }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress]);
   const emitLessonCompleted = (0, import_react.useCallback)(
     (lessonId, durationMs) => {
       track("lesson_completed", { lessonId, durationMs }, { lessonId });
@@ -664,20 +671,27 @@ function LessonkitProvider(props) {
   );
   const completeLesson = (0, import_react.useCallback)(
     (lessonId) => {
+      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]
+    [syncProgress, emitLessonCompleted, useV2Runtime, emitLifecycleEvent]
   );
   (0, import_react.useEffect)(() => {
     return () => {
       const client = trackingClientForUnmountRef.current;
+      const xapi2 = xapiRef.current;
       void (async () => {
         try {
-          await xapiRef.current?.flush();
+          await xapi2?.flush();
         } catch {
         }
         try {
@@ -693,8 +707,19 @@ function LessonkitProvider(props) {
   }, []);
   const setActiveLesson = (0, import_react.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());
@@ -707,32 +732,58 @@ function LessonkitProvider(props) {
       syncProgress();
       track("lesson_started", { lessonId }, { lessonId });
     },
-    [track, syncProgress, emitLessonCompleted]
+    [track, syncProgress, emitLessonCompleted, useV2Runtime, emitLifecycleEvent]
   );
   const completeCourse = (0, import_react.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]);
-  const sessionUser = config.session?.user;
-  const sessionAttemptId = config.session?.attemptId;
-  const sessionConfiguredId = config.session?.sessionId;
+  }, [track, syncProgress, emitLessonCompleted, useV2Runtime, emitLifecycleEvent]);
+  const sessionUser = normalizedConfig.session?.user;
+  const sessionUserKey = (0, import_react.useMemo)(
+    () => sessionUser ? JSON.stringify(sessionUser) : "",
+    [sessionUser]
+  );
+  const sessionAttemptId = normalizedConfig.session?.attemptId;
+  const sessionConfiguredId = normalizedConfig.session?.sessionId;
+  (0, import_react.useEffect)(() => {
+    if (useV2Runtime && headlessRef.current) {
+      headlessRef.current.updateConfig({
+        courseId: normalizedCourseId,
+        session: normalizedConfig.session
+      });
+    }
+  }, [useV2Runtime, normalizedCourseId, sessionAttemptId, sessionConfiguredId, sessionUserKey, normalizedConfig.session]);
   (0, import_react.useEffect)(() => {
     if (!pluginHost) return;
     const ctx = buildPluginContext({
       courseId: courseIdRef.current,
       sessionId: sessionIdRef.current,
-      attemptId: attemptIdRef.current
+      attemptId: attemptIdRef.current,
+      user: userRef.current
     });
     pluginHost.setupAll(ctx);
     return () => {
       pluginHost.disposeAll();
     };
-  }, [pluginHost, config.courseId, sessionAttemptId, sessionConfiguredId]);
+  }, [pluginHost, normalizedCourseId, sessionAttemptId, sessionConfiguredId, sessionUserKey]);
   (0, import_react.useEffect)(() => {
-    const nextConfigured = config.session?.sessionId;
+    const nextConfigured = normalizedConfig.session?.sessionId;
     const prevConfigured = prevConfiguredSessionIdRef.current;
     if (nextConfigured === prevConfigured) return;
     prevConfiguredSessionIdRef.current = nextConfigured;
@@ -740,23 +791,23 @@ function LessonkitProvider(props) {
     if (nextConfigured) {
       const fromIds = /* @__PURE__ */ new Set();
       if (prevConfigured) fromIds.add(prevConfigured);
-      const tabId = getTabSessionId(defaultStorage);
+      const tabId = (0, import_core5.getTabSessionId)(defaultStorage);
       if (tabId) fromIds.add(tabId);
       for (const fromId of fromIds) {
         if (fromId !== nextConfigured) {
-          migrateCourseStartedMark(defaultStorage, fromId, nextConfigured, cid);
+          (0, import_core5.migrateCourseStartedMark)(defaultStorage, fromId, nextConfigured, cid);
         }
       }
       sessionIdRef.current = nextConfigured;
     } else if (prevConfigured) {
-      const nextAuto = resolveSessionId(defaultStorage, void 0);
-      migrateCourseStartedMark(defaultStorage, prevConfigured, nextAuto, cid);
+      const nextAuto = (0, import_core5.resolveSessionId)(defaultStorage, void 0);
+      (0, import_core5.migrateCourseStartedMark)(defaultStorage, prevConfigured, nextAuto, cid);
       sessionIdRef.current = nextAuto;
     }
-  }, [sessionConfiguredId, config.courseId]);
+  }, [sessionConfiguredId, normalizedCourseId]);
   const runtime = (0, import_react.useMemo)(
     () => ({
-      config,
+      config: normalizedConfig,
       tracking,
       xapi,
       session: { sessionId: sessionIdRef.current, attemptId: attemptIdRef.current, user: userRef.current },
@@ -768,7 +819,7 @@ function LessonkitProvider(props) {
       plugins: pluginHost
     }),
     [
-      config,
+      normalizedConfig,
       tracking,
       xapi,
       progress,
@@ -782,13 +833,21 @@ function LessonkitProvider(props) {
       sessionConfiguredId
     ]
   );
+  return runtime;
+}
+
+// src/context.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var LessonkitContext = (0, import_react2.createContext)(null);
+function LessonkitProvider(props) {
+  const runtime = useLessonkitProviderRuntime(props.config);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LessonkitContext.Provider, { value: runtime, children: props.children });
 }
 
 // src/hooks.ts
-var import_react2 = require("react");
+var import_react3 = require("react");
 function useLessonkit() {
-  const ctx = (0, import_react2.useContext)(LessonkitContext);
+  const ctx = (0, import_react3.useContext)(LessonkitContext);
   if (!ctx) throw new Error("LessonKit: missing LessonkitProvider");
   return ctx;
 }
@@ -798,52 +857,80 @@ function useProgress() {
 }
 function useTracking() {
   const { track } = useLessonkit();
-  return (0, import_react2.useMemo)(() => ({ track }), [track]);
+  return (0, import_react3.useMemo)(() => ({ track }), [track]);
 }
 function useCompletion() {
   const { completeLesson, completeCourse } = useLessonkit();
-  return (0, import_react2.useMemo)(() => ({ completeLesson, completeCourse }), [completeLesson, completeCourse]);
+  return (0, import_react3.useMemo)(() => ({ completeLesson, completeCourse }), [completeLesson, completeCourse]);
 }
-function useQuizState() {
+function useQuizState(enclosingLessonId) {
   const { track } = useLessonkit();
-  return (0, import_react2.useMemo)(
+  const trackOpts = enclosingLessonId ? { lessonId: enclosingLessonId } : void 0;
+  return (0, import_react3.useMemo)(
     () => ({
       answer: (opts) => {
-        track("quiz_answered", opts);
+        track("quiz_answered", opts, trackOpts);
       },
       complete: (opts) => {
-        track("quiz_completed", opts);
+        track("quiz_completed", opts, trackOpts);
       }
     }),
-    [track]
+    [track, enclosingLessonId]
   );
 }
 
+// src/lessonContext.tsx
+var import_react4 = require("react");
+var LessonContext = (0, import_react4.createContext)(void 0);
+function useEnclosingLessonId() {
+  return (0, import_react4.useContext)(LessonContext);
+}
+
 // src/runtime/validateComponentId.ts
-var import_core6 = require("@lessonkit/core");
-var warnedPaths = /* @__PURE__ */ new Set();
-function isDevEnvironment2() {
+var import_core9 = require("@lessonkit/core");
+function isDevEnvironment3() {
   const g = globalThis;
   return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
 }
-function warnInvalidComponentId(id, path) {
-  if (!isDevEnvironment2()) return;
-  const key = `${path}:${String(id)}`;
-  if (warnedPaths.has(key)) return;
-  const result = (0, import_core6.validateId)(id, path);
-  if (result.ok) return;
-  warnedPaths.add(key);
-  const detail = result.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
-  console.warn(`[lessonkit] invalid ${path} \u2014 ${detail}`);
+function normalizeComponentId(id, path) {
+  return (0, import_core9.assertValidId)(id, path);
+}
+
+// src/runtime/lessonMountRegistry.ts
+var mountCounts = /* @__PURE__ */ new Map();
+var warnedConcurrentLessons = false;
+function registerLessonMount(lessonId) {
+  if (isDevEnvironment3() && mountCounts.size > 0 && !mountCounts.has(lessonId) && !warnedConcurrentLessons) {
+    warnedConcurrentLessons = true;
+    console.warn(
+      "[lessonkit] Multiple <Lesson> components are mounted; only one should be active at a time. Set autoCompleteOnUnmount={false} on routed lessons or unmount the previous lesson before showing the next."
+    );
+  }
+  mountCounts.set(lessonId, (mountCounts.get(lessonId) ?? 0) + 1);
+  return () => {
+    const next = (mountCounts.get(lessonId) ?? 1) - 1;
+    if (next <= 0) {
+      mountCounts.delete(lessonId);
+    } else {
+      mountCounts.set(lessonId, next);
+    }
+  };
+}
+function getLessonMountCount(lessonId) {
+  return mountCounts.get(lessonId) ?? 0;
 }
 
 // src/components.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
+var warnedQuizOutsideLesson = false;
+function resetQuizWarningsForTests() {
+  warnedQuizOutsideLesson = false;
+}
 function Course(props) {
-  warnInvalidComponentId(props.courseId, "courseId");
-  const providerConfig = (0, import_react3.useMemo)(
-    () => ({ ...props.config, courseId: props.courseId }),
-    [props.config, props.courseId]
+  const courseId = (0, import_react5.useMemo)(() => normalizeComponentId(props.courseId, "courseId"), [props.courseId]);
+  const providerConfig = (0, import_react5.useMemo)(
+    () => ({ ...props.config, courseId }),
+    [props.config, courseId]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LessonkitProvider, { config: providerConfig, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": props.title, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h1", { children: props.title }),
@@ -851,41 +938,64 @@ function Course(props) {
   ] }) });
 }
 function Lesson(props) {
-  warnInvalidComponentId(props.lessonId, "lessonId");
+  const lessonId = (0, import_react5.useMemo)(() => normalizeComponentId(props.lessonId, "lessonId"), [props.lessonId]);
+  const autoComplete = props.autoCompleteOnUnmount !== false;
   const { setActiveLesson, config } = useLessonkit();
   const { completeLesson } = useCompletion();
-  const id = props.lessonId;
-  const lessonMountGenerationRef = (0, import_react3.useRef)(0);
-  (0, import_react3.useEffect)(() => {
+  const lessonMountGenerationRef = (0, import_react5.useRef)(0);
+  (0, import_react5.useEffect)(() => {
+    const unregister = registerLessonMount(lessonId);
     const generation = ++lessonMountGenerationRef.current;
-    setActiveLesson(id);
+    setActiveLesson(lessonId);
     return () => {
-      const lessonId = id;
+      unregister();
+      if (getLessonMountCount(lessonId) > 0) {
+        return;
+      }
+      if (!autoComplete) return;
       queueMicrotask(() => {
         if (lessonMountGenerationRef.current !== generation) return;
         completeLesson(lessonId);
       });
     };
-  }, [id, config.courseId, setActiveLesson, completeLesson]);
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("article", { "aria-label": props.title, children: [
+  }, [lessonId, config.courseId, setActiveLesson, completeLesson, autoComplete]);
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LessonContext.Provider, { value: lessonId, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("article", { "aria-label": props.title, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("h2", { children: props.title }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { children: props.children })
-  ] });
+  ] }) });
 }
 function Scenario(props) {
-  if (props.blockId !== void 0) warnInvalidComponentId(props.blockId, "blockId");
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("section", { "aria-label": "Scenario", "data-lk-block-id": props.blockId, children: props.children });
+  const blockId = (0, import_react5.useMemo)(
+    () => props.blockId !== void 0 ? normalizeComponentId(props.blockId, "blockId") : void 0,
+    [props.blockId]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("section", { "aria-label": "Scenario", "data-lk-block-id": blockId, children: props.children });
 }
 function Reflection(props) {
-  if (props.blockId !== void 0) warnInvalidComponentId(props.blockId, "blockId");
-  const promptId = (0, import_react3.useId)();
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Reflection", "data-lk-block-id": props.blockId, children: [
+  const blockId = (0, import_react5.useMemo)(
+    () => props.blockId !== void 0 ? normalizeComponentId(props.blockId, "blockId") : void 0,
+    [props.blockId]
+  );
+  const promptId = (0, import_react5.useId)();
+  const hintId = (0, import_react5.useId)();
+  const [internalValue, setInternalValue] = (0, import_react5.useState)("");
+  const isControlled = props.value !== void 0;
+  const value = isControlled ? props.value : internalValue;
+  const handleChange = (event) => {
+    if (!isControlled) setInternalValue(event.target.value);
+    props.onChange?.(event.target.value);
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Reflection", "data-lk-block-id": blockId, children: [
     props.prompt ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: promptId, children: props.prompt }) : null,
+    props.hint ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: hintId, style: import_accessibility.visuallyHiddenStyle, children: props.hint }) : null,
     props.children,
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
       "textarea",
       {
+        value,
+        onChange: handleChange,
         "aria-labelledby": props.prompt ? promptId : void 0,
+        "aria-describedby": props.hint ? hintId : void 0,
         "aria-label": props.prompt ? void 0 : "Reflection response"
       }
     )
@@ -898,23 +1008,41 @@ function KnowledgeCheck(props) {
       checkId: props.checkId,
       question: props.question,
       choices: props.choices,
-      answer: props.answer
+      answer: props.answer,
+      passingScore: props.passingScore
     }
   );
 }
 function Quiz(props) {
-  warnInvalidComponentId(props.checkId, "checkId");
-  const quiz = useQuizState();
-  const { plugins, config, progress, session } = useLessonkit();
-  const [selected, setSelected] = (0, import_react3.useState)(null);
-  const [selectionCorrect, setSelectionCorrect] = (0, import_react3.useState)(null);
-  const completedRef = (0, import_react3.useRef)(false);
-  const questionId = (0, import_react3.useId)();
-  (0, import_react3.useEffect)(() => {
+  const checkId = (0, import_react5.useMemo)(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
+  const enclosingLessonId = useEnclosingLessonId();
+  const missingLesson = enclosingLessonId === void 0;
+  (0, import_react5.useEffect)(() => {
+    if (!missingLesson || isDevEnvironment3()) return;
+    if (!warnedQuizOutsideLesson) {
+      warnedQuizOutsideLesson = true;
+      console.error(
+        "[lessonkit] <Quiz> must be wrapped in <Lesson>; quiz telemetry will not be emitted."
+      );
+    }
+  }, [missingLesson]);
+  if (missingLesson && isDevEnvironment3()) {
+    throw new Error("[lessonkit] <Quiz> must be wrapped in <Lesson>");
+  }
+  const quiz = useQuizState(enclosingLessonId);
+  const { plugins, config, session } = useLessonkit();
+  const [selected, setSelected] = (0, import_react5.useState)(null);
+  const [selectionCorrect, setSelectionCorrect] = (0, import_react5.useState)(null);
+  const [quizPassed, setQuizPassed] = (0, import_react5.useState)(false);
+  const completedRef = (0, import_react5.useRef)(false);
+  const questionId = (0, import_react5.useId)();
+  const choicesKey = props.choices.join("\0");
+  (0, import_react5.useEffect)(() => {
     completedRef.current = false;
+    setQuizPassed(false);
     setSelected(null);
     setSelectionCorrect(null);
-  }, [props.checkId, props.answer, props.question]);
+  }, [checkId, props.answer, props.question, config.courseId, enclosingLessonId, choicesKey]);
   const isChoiceCorrect = (choice, custom) => {
     if (!custom) return choice === props.answer;
     if (custom.passed !== void 0) return custom.passed;
@@ -923,7 +1051,11 @@ function Quiz(props) {
     }
     return choice === props.answer;
   };
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Quiz", "data-lk-check-id": props.checkId, children: [
+  if (missingLesson) {
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("section", { role: "alert", "aria-label": "Quiz configuration error", "data-lk-check-id": checkId, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: "Quiz must be placed inside a Lesson." }) });
+  }
+  const passed = quizPassed;
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Quiz", "data-lk-check-id": checkId, children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: questionId, children: props.question }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("fieldset", { "aria-labelledby": questionId, children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("legend", { style: import_accessibility.visuallyHiddenStyle, children: "Quiz choices" }),
@@ -935,17 +1067,21 @@ function Quiz(props) {
             name: questionId,
             value: c,
             checked: selected === c,
+            disabled: passed,
+            "aria-invalid": selected === c && selectionCorrect === false ? true : void 0,
             onChange: () => {
+              if (passed) return;
               setSelected(c);
               const pluginCtx = buildPluginContext({
                 courseId: config.courseId,
                 sessionId: session.sessionId,
-                attemptId: session.attemptId
+                attemptId: session.attemptId,
+                user: session.user
               });
               const custom = plugins?.scoreAssessment(
                 {
-                  checkId: props.checkId,
-                  lessonId: progress.activeLessonId,
+                  checkId,
+                  lessonId: enclosingLessonId,
                   response: c
                 },
                 pluginCtx
@@ -953,18 +1089,20 @@ function Quiz(props) {
               const correct = isChoiceCorrect(c, custom);
               setSelectionCorrect(correct);
               quiz.answer({
-                checkId: props.checkId,
+                checkId,
                 question: props.question,
                 choice: c,
                 correct
               });
               if (correct && !completedRef.current) {
                 completedRef.current = true;
+                setQuizPassed(true);
+                const maxScore = custom?.maxScore ?? 1;
                 quiz.complete({
-                  checkId: props.checkId,
+                  checkId,
                   score: custom?.score ?? 1,
-                  maxScore: custom?.maxScore ?? 1,
-                  passingScore: 1
+                  maxScore,
+                  passingScore: props.passingScore ?? maxScore
                 });
               }
             }
@@ -976,20 +1114,40 @@ function Quiz(props) {
     selected && selectionCorrect !== null ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { role: "status", "aria-live": "polite", children: selectionCorrect ? "Correct" : "Try again" }) : null
   ] });
 }
-function ProgressTracker() {
+function ProgressTracker(props) {
   const { progress } = useLessonkit();
   const completed = progress.completedLessonIds.size;
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("aside", { "aria-label": "Progress", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { children: [
+  if (props.totalLessons != null) {
+    const total = props.totalLessons;
+    const displayed = Math.min(completed, total);
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("aside", { "aria-label": "Progress", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "div",
+      {
+        role: "progressbar",
+        "aria-valuemin": 0,
+        "aria-valuemax": total,
+        "aria-valuenow": displayed,
+        "aria-label": "Lessons completed",
+        children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { children: [
+          "Lessons completed: ",
+          displayed,
+          " of ",
+          total
+        ] })
+      }
+    ) });
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("aside", { "aria-label": "Progress", role: "status", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { children: [
     "Lessons completed: ",
     completed
   ] }) });
 }
 
 // src/index.tsx
-var import_core7 = require("@lessonkit/core");
+var import_core10 = require("@lessonkit/core");
 
 // src/theme/ThemeProvider.tsx
-var import_react4 = __toESM(require("react"), 1);
+var import_react6 = __toESM(require("react"), 1);
 var import_themes = require("@lessonkit/themes");
 
 // src/theme/applyCssVariables.ts
@@ -1009,8 +1167,8 @@ function applyCssVariables(target, vars, previousKeys) {
 
 // src/theme/ThemeProvider.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
-var ThemeContext = (0, import_react4.createContext)(null);
-var useIsoLayoutEffect2 = typeof window !== "undefined" ? import_react4.useLayoutEffect : import_react4.default.useEffect;
+var ThemeContext = (0, import_react6.createContext)(null);
+var useIsoLayoutEffect2 = typeof window !== "undefined" ? import_react6.useLayoutEffect : import_react6.default.useEffect;
 function getSystemMode() {
   if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
     return "light";
@@ -1028,7 +1186,7 @@ function ThemeProvider(props) {
   const preset = props.preset ?? "default";
   const mode = props.mode ?? "light";
   const targetKind = props.target ?? "document";
-  const [resolvedMode, setResolvedMode] = (0, import_react4.useState)(
+  const [resolvedMode, setResolvedMode] = (0, import_react6.useState)(
     () => mode === "system" ? getSystemMode() : mode
   );
   useIsoLayoutEffect2(() => {
@@ -1044,20 +1202,20 @@ function ThemeProvider(props) {
     return () => mq.removeEventListener("change", onChange);
   }, [mode]);
   const dataTheme = mode === "system" ? resolvedMode : mode === "dark" ? "dark" : "light";
-  const effectiveTheme = (0, import_react4.useMemo)(() => {
+  const effectiveTheme = (0, import_react6.useMemo)(() => {
     const modeBase = resolveModeBase(mode, dataTheme);
     const base = preset === "default" ? modeBase : preset === "brand" ? (0, import_themes.mergeThemes)(modeBase, import_themes.brandThemeOverrides) : (0, import_themes.mergeThemes)(modeBase, (0, import_themes.getPresetTheme)(preset));
     return (0, import_themes.mergeThemes)(base, props.theme ?? {});
   }, [preset, mode, dataTheme, props.theme]);
-  const hostRef = (0, import_react4.useRef)(null);
-  const appliedKeysRef = (0, import_react4.useRef)(/* @__PURE__ */ new Set());
+  const hostRef = (0, import_react6.useRef)(null);
+  const appliedKeysRef = (0, import_react6.useRef)(/* @__PURE__ */ new Set());
   useIsoLayoutEffect2(() => {
     if (targetKind === "document" && typeof document !== "undefined") {
       document.documentElement.setAttribute("data-lk-theme", dataTheme);
       return () => document.documentElement.removeAttribute("data-lk-theme");
     }
   }, [targetKind, dataTheme]);
-  const inject = (0, import_react4.useCallback)(() => {
+  const inject = (0, import_react6.useCallback)(() => {
     const vars = (0, import_themes.themeToCssVariables)(effectiveTheme);
     const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
     if (!el) return;
@@ -1074,7 +1232,7 @@ function ThemeProvider(props) {
       appliedKeysRef.current = /* @__PURE__ */ new Set();
     };
   }, [inject, targetKind]);
-  const value = (0, import_react4.useMemo)(
+  const value = (0, import_react6.useMemo)(
     () => ({
       theme: effectiveTheme,
       preset,
@@ -1089,7 +1247,7 @@ function ThemeProvider(props) {
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(ThemeContext.Provider, { value, children: /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("div", { ref: hostRef, "data-lk-theme": dataTheme, children: props.children }) });
 }
 function useTheme() {
-  const ctx = (0, import_react4.useContext)(ThemeContext);
+  const ctx = (0, import_react6.useContext)(ThemeContext);
   if (!ctx) {
     throw new Error("useTheme must be used within a ThemeProvider");
   }
@@ -1136,6 +1294,12 @@ var BLOCK_CATALOG = [
     props: [
       { name: "title", type: "string", required: true, description: "Lesson title shown in the h2." },
       { name: "lessonId", type: "LessonId", required: true, description: "Stable lesson identifier for telemetry and packaging." },
+      {
+        name: "autoCompleteOnUnmount",
+        type: "boolean",
+        required: false,
+        description: "When false, unmount does not emit lesson_completed (default true)."
+      },
       { name: "children", type: "ReactNode", required: true, description: "Scenario, Quiz, Reflection, and other blocks." }
     ],
     requiredIds: ["lessonId"],
@@ -1188,6 +1352,9 @@ var BLOCK_CATALOG = [
     props: [
       { name: "blockId", type: "BlockId", required: false, description: "Optional stable block id for interaction telemetry URNs." },
       { name: "prompt", type: "string", required: false, description: "Reflection question or instruction." },
+      { name: "hint", type: "string", required: false, description: "Optional hint linked via aria-describedby." },
+      { name: "value", type: "string", required: false, description: "Controlled textarea value." },
+      { name: "onChange", type: "(value: string) => void", required: false, description: "Called when the learner edits the textarea." },
       { name: "children", type: "ReactNode", required: false, description: "Optional content above the textarea." }
     ],
     requiredIds: [],
@@ -1206,6 +1373,7 @@ var BLOCK_CATALOG = [
     },
     telemetry: {
       emits: [],
+      requiresActiveLesson: true,
       manualTracking: "useTracking().track('interaction', { kind, blockId, payload }) on submit or blur"
     }
   },
@@ -1243,7 +1411,14 @@ var BLOCK_CATALOG = [
     type: "ProgressTracker",
     category: "chrome",
     description: "Displays count of completed lessons from runtime progress state.",
-    props: [],
+    props: [
+      {
+        name: "totalLessons",
+        type: "number",
+        required: false,
+        description: "When set, renders role=progressbar with aria-valuenow/max."
+      }
+    ],
     requiredIds: [],
     parentConstraints: ["Course"],
     a11y: {
@@ -1296,9 +1471,15 @@ function getBlockCatalogEntry(type) {
   ThemeProvider,
   blockCatalogVersion,
   buildBlockCatalog,
-  createPluginHost,
-  defineLessonkitPlugin,
+  buildTelemetryEvent,
+  createLessonkitRuntime,
+  createPluginRegistry,
+  createTelemetryPipeline,
+  defineAssessmentPlugin,
+  defineLifecyclePlugin,
+  defineTelemetryPlugin,
   getBlockCatalogEntry,
+  resetQuizWarningsForTests,
   useCompletion,
   useLessonkit,
   useProgress,