@lessonkit/react 0.9.3 → 1.0.1

package/dist/index.js

@@ -3,8 +3,10 @@ import { useEffect as useEffect2, useId, useMemo as useMemo3, useRef as useRef2,
 import { visuallyHiddenStyle } from "@lessonkit/accessibility";
 
 // src/context.tsx
+import { createContext } from "react";
+
+// src/provider/useLessonkitProviderRuntime.ts
 import {
-  createContext,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -12,241 +14,102 @@ import {
   useRef,
   useState
 } from "react";
-import { createTrackingClient as createTrackingClient2 } from "@lessonkit/core";
+import { createLessonkitRuntime, createTrackingClient as createTrackingClient2, assertValidId } from "@lessonkit/core";
 import { createInMemoryXAPIQueue } from "@lessonkit/xapi";
-import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
+import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement3 } from "@lessonkit/xapi";
 
 // src/runtime/emitTelemetry.ts
-import { nowIso } from "@lessonkit/core";
+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 {
-  getLxpackBridge as getLxpackBridgeFromSdk,
+  dispatchBridgeAction,
+  forwardTelemetryToBridge,
+  getLxpackBridge,
   mapLessonkitTelemetryToBridgeAction,
-  normalizePassingThreshold,
-  normalizeScore,
   telemetryEventToLessonkit
 } from "@lessonkit/lxpack/bridge";
-function getBridge() {
-  const fromSdk = getLxpackBridgeFromSdk();
-  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") {
+  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 = normalizeScore({
-        score: action.score,
-        maxScore: action.maxScore
-      });
-      if (scaled === null) return;
-      bridge.submitAssessment?.({
-        id: action.id,
-        score: scaled,
-        passingScore: 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 = telemetryEventToLessonkit(event);
-  if (!lessonkitEvent) return;
-  const action = mapLessonkitTelemetryToBridgeAction(lessonkitEvent);
-  applyBridgeAction(bridge, action);
+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 (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 = 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: 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 {
-      }
-    }
-  };
-}
+import {
+  createDefaultClock,
+  createGlobalTimer,
+  createNoopStorage,
+  createSessionStoragePort,
+  resetStoragePortForTests
+} from "@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 };
-    }
-  };
-}
+import { createProgressController } from "@lessonkit/core";
 
 // src/runtime/xapi.ts
 import { createXAPIClient } from "@lessonkit/xapi";
@@ -264,56 +127,63 @@ function createXapiClientFromConfig(config, queue) {
 }
 
 // src/runtime/session.ts
-import { createSessionId } from "@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 = 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));
+import {
+  SESSION_STORAGE_KEY,
+  getTabSessionId,
+  resolveSessionId,
+  hasCourseStarted,
+  markCourseStarted,
+  hasCourseStartedEmittedToTracking,
+  markCourseStartedEmittedToTracking,
+  hasCourseStartedPipelineDelivered,
+  markCourseStartedPipelineDelivered,
+  migrateCourseStartedMark
+} from "@lessonkit/core";
+
+// src/runtime/courseStartedPipeline.ts
+import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
+function emitCourseStartedNonTrackingPipeline(opts) {
+  let xapiStatementSent = false;
+  if (!opts.skipXapi && opts.xapi) {
+    const statement = telemetryEventToXAPIStatement2(opts.event);
+    if (statement) {
+      opts.xapi.send(statement);
+      xapiStatementSent = true;
+    }
+  }
+  forwardTelemetryToLxpack(opts.event, opts.lxpackBridge);
+  const emitCtx = {
+    courseId: opts.event.courseId,
+    sessionId: opts.event.sessionId,
+    attemptId: opts.event.attemptId
+  };
+  for (const sink of opts.extraSinks ?? []) {
+    sink.emit(opts.event, emitCtx);
   }
+  return { xapiStatementSent };
 }
 
 // src/runtime/plugins.ts
-import { createPluginHost } from "@lessonkit/core";
+import { createPluginRegistry } from "@lessonkit/core";
 function createReactPluginHost(plugins) {
   if (!plugins?.length) return null;
-  return createPluginHost(plugins);
+  return 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
@@ -338,71 +208,217 @@ async function disposeTrackingClient(client) {
   }
 }
 
-// src/context.tsx
-import { jsx } from "react/jsx-runtime";
-var LessonkitContext = createContext(null);
+// src/provider/useLessonkitProviderRuntime.ts
 var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
 var defaultStorage = createSessionStoragePort();
 function isTrackingActive(tracking) {
   return tracking?.enabled !== false;
 }
-function emitCourseStarted(opts) {
+function isCourseStartedSinkSettled(result) {
+  return result === "emitted";
+}
+function buildCourseStartedEvent(opts) {
   const pluginCtx = buildPluginContext({
     courseId: opts.courseId,
     sessionId: opts.sessionId,
-    attemptId: opts.attemptId
+    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;
+}
+function emitCourseStartedPipelineOnly(opts) {
   try {
-    emitTelemetryWithPlugins({
-      pluginHost: opts.pluginHost,
-      tracking: opts.tracking,
+    const { xapiStatementSent } = emitCourseStartedNonTrackingPipeline({
+      event: opts.event,
       xapi: opts.xapi,
-      event: buildTrackEvent({
-        name: "course_started",
-        courseId: opts.courseId,
-        sessionId: opts.sessionId,
-        attemptId: opts.attemptId,
-        user: opts.user
-      }),
-      pluginCtx,
-      lxpackBridge: opts.lxpackBridge
+      lxpackBridge: opts.lxpackBridge,
+      extraSinks: opts.extraSinks,
+      skipXapi: opts.skipXapi
     });
     markCourseStarted(opts.storage, opts.sessionId, opts.courseId);
-    return true;
+    markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId);
+    if (xapiStatementSent) {
+      opts.onXapiStatementSent?.();
+    }
+    return "emitted";
   } catch {
-    return false;
+    return "failed";
   }
 }
-function LessonkitProvider(props) {
-  const config = props.config;
-  const sessionIdRef = useRef(resolveSessionId(defaultStorage, config.session?.sessionId));
-  const prevConfiguredSessionIdRef = useRef(config.session?.sessionId);
-  if (config.session?.sessionId) {
-    sessionIdRef.current = config.session.sessionId;
+function emitCourseStarted(opts) {
+  const event = buildCourseStartedEvent(opts);
+  if (event === null) return "filtered";
+  const trackingAlreadyEmitted = hasCourseStartedEmittedToTracking(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (!trackingAlreadyEmitted) {
+    try {
+      opts.tracking.track(event);
+      markCourseStartedEmittedToTracking(opts.storage, opts.sessionId, opts.courseId);
+    } catch {
+      return "failed";
+    }
+  }
+  return emitCourseStartedPipelineOnly({
+    ...opts,
+    event,
+    skipXapi: opts.skipXapi,
+    onXapiStatementSent: opts.onXapiStatementSent
+  });
+}
+function emitCourseStartedToTrackingOnly(opts) {
+  const event = buildCourseStartedEvent(opts);
+  if (event === null) return "filtered";
+  const trackingAlreadyEmitted = hasCourseStartedEmittedToTracking(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (!trackingAlreadyEmitted) {
+    try {
+      opts.tracking.track(event);
+      markCourseStartedEmittedToTracking(opts.storage, opts.sessionId, opts.courseId);
+    } catch {
+      return "failed";
+    }
+  }
+  try {
+    emitCourseStartedNonTrackingPipeline({
+      event,
+      xapi: null,
+      lxpackBridge: opts.lxpackBridge,
+      extraSinks: opts.extraSinks,
+      skipXapi: true
+    });
+    markCourseStartedPipelineDelivered(opts.storage, opts.sessionId, opts.courseId);
+    return "emitted";
+  } catch {
+    return "failed";
+  }
+}
+function emitPendingCourseStarted(opts) {
+  const trackingEmitted = hasCourseStartedEmittedToTracking(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  const sessionStarted = hasCourseStarted(opts.storage, opts.sessionId, opts.courseId);
+  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);
+  }
+  const pipelineDelivered = hasCourseStartedPipelineDelivered(
+    opts.storage,
+    opts.sessionId,
+    opts.courseId
+  );
+  if (sessionStarted && trackingEmitted && !pipelineDelivered) {
+    const event = buildCourseStartedEvent(opts);
+    if (event === null) return "filtered";
+    return emitCourseStartedPipelineOnly({
+      ...opts,
+      event,
+      skipXapi: opts.skipXapi,
+      onXapiStatementSent: opts.onXapiStatementSent
+    });
+  }
+  return "emitted";
+}
+function assertTrackingSinkConfig(tracking) {
+  if (!tracking?.sink || !tracking?.batchSink) return;
+  throw new Error(
+    "[lessonkit] tracking.sink and tracking.batchSink cannot both be set; use batchSink alone for batched delivery"
+  );
+}
+function useLessonkitProviderRuntime(config) {
+  const normalizedCourseId = useMemo(
+    () => assertValidId(config.courseId, "courseId"),
+    [config.courseId]
+  );
+  const normalizedConfig = useMemo(
+    () => ({ ...config, courseId: normalizedCourseId }),
+    [config, normalizedCourseId]
+  );
+  const useV2Runtime = normalizedConfig.runtimeVersion !== "v1";
+  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(config.session?.attemptId);
-  const userRef = useRef(config.session?.user);
-  attemptIdRef.current = config.session?.attemptId;
-  userRef.current = config.session?.user;
-  const courseIdRef = useRef(config.courseId);
-  courseIdRef.current = config.courseId;
-  const lxpackBridgeModeRef = useRef(config.lxpack?.bridge ?? "auto");
-  lxpackBridgeModeRef.current = config.lxpack?.bridge ?? "auto";
-  const pluginHost = useMemo(() => createReactPluginHost(config.plugins), [config.plugins]);
+  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 pluginHost = useMemo(() => createReactPluginHost(normalizedConfig.plugins), [normalizedConfig.plugins]);
   const pluginHostRef = useRef(pluginHost);
   pluginHostRef.current = pluginHost;
   const progressRef = useRef(createProgressController());
   const courseStartedEmittedToSinkRef = useRef(false);
-  const prevCourseIdForProgressRef = useRef(config.courseId);
+  const prevCourseIdForProgressRef = useRef(normalizedCourseId);
   const pendingCourseIdResetRef = useRef(false);
-  if (prevCourseIdForProgressRef.current !== config.courseId) {
-    prevCourseIdForProgressRef.current = config.courseId;
-    progressRef.current = createProgressController();
+  const prevUseV2RuntimeRef = useRef(useV2Runtime);
+  const xapiCourseStartedSentOnClientRef = useRef(false);
+  if (prevUseV2RuntimeRef.current !== useV2Runtime) {
+    prevUseV2RuntimeRef.current = useV2Runtime;
+    if (useV2Runtime) {
+      headlessRef.current = createLessonkitRuntime({
+        courseId: normalizedCourseId,
+        runtimeVersion: "v2",
+        session: normalizedConfig.session
+      });
+      progressRef.current = headlessRef.current.progress;
+    } else {
+      headlessRef.current = null;
+      progressRef.current = createProgressController();
+    }
+    pendingCourseIdResetRef.current = true;
+    courseStartedEmittedToSinkRef.current = false;
+  } else if (useV2Runtime && !headlessRef.current) {
+    headlessRef.current = 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 = createProgressController();
+    }
     pendingCourseIdResetRef.current = true;
     courseStartedEmittedToSinkRef.current = false;
   }
+  if (useV2Runtime && headlessRef.current) {
+    progressRef.current = headlessRef.current.progress;
+  }
   const [progress, setProgress] = useState(() => progressRef.current.getState());
   const syncProgress = useCallback(() => {
     setProgress(progressRef.current.getState());
@@ -412,16 +428,16 @@ function LessonkitProvider(props) {
   const xapiQueueRef = useRef(createInMemoryXAPIQueue());
   const xapiRef = useRef(null);
   const [xapi, setXapi] = useState(null);
-  const prevXapiCourseIdRef = 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 = 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(
@@ -432,30 +448,40 @@ function LessonkitProvider(props) {
       }
       xapiQueueRef.current = 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 trackingActive = isTrackingActive(normalizedConfig.tracking);
       const alreadyStarted = hasCourseStarted(defaultStorage, sessionId, cid);
-      if (!trackingActive || alreadyStarted) {
+      const clientChanged = !prev || prev !== next;
+      const skipBootstrap = trackingActive && !alreadyStarted;
+      const needsBootstrap = !skipBootstrap && !xapiCourseStartedSentOnClientRef.current && (!alreadyStarted || clientChanged);
+      if (needsBootstrap) {
         try {
-          const statement = telemetryEventToXAPIStatement2(
-            buildTrackEvent({
-              name: "course_started",
-              courseId: cid,
-              sessionId,
-              attemptId: attemptIdRef.current,
-              user: userRef.current
-            })
-          );
-          if (statement) {
-            next.send(statement);
-            markCourseStarted(defaultStorage, sessionId, cid);
+          const event = buildCourseStartedEvent({
+            pluginHost: pluginHostRef.current,
+            courseId: cid,
+            sessionId,
+            attemptId: attemptIdRef.current,
+            user: userRef.current,
+            lxpackBridge: lxpackBridgeModeRef.current
+          });
+          if (event === null) {
+          } else {
+            const statement = telemetryEventToXAPIStatement3(event);
+            if (statement) {
+              next.send(statement);
+              if (!alreadyStarted) {
+                markCourseStarted(defaultStorage, sessionId, cid);
+              }
+              xapiCourseStartedSentOnClientRef.current = true;
+            }
           }
         } catch {
         }
@@ -483,43 +509,53 @@ function LessonkitProvider(props) {
   const trackingRef = useRef(createTrackingClient2());
   const trackingClientForUnmountRef = useRef(trackingRef.current);
   const [tracking, setTracking] = 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 = 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 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 && config.tracking?.batchSink ? (events) => {
-      const delivered = pluginHostRef.current.deliverTelemetryBatch(
-        events,
-        buildCurrentPluginCtx()
-      );
-      return config.tracking.batchSink(delivered);
-    } : config.tracking?.batchSink;
+    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 result = emitPendingCourseStarted({
         pluginHost: pluginHostRef.current,
         tracking: next,
         xapi: xapiRef.current,
@@ -528,9 +564,14 @@ function LessonkitProvider(props) {
         courseId: cid,
         attemptId: attemptIdRef.current,
         user: userRef.current,
-        lxpackBridge: lxpackBridgeModeRef.current
+        lxpackBridge: lxpackBridgeModeRef.current,
+        extraSinks: extraSinksRef.current,
+        skipXapi: xapiCourseStartedSentOnClientRef.current,
+        onXapiStatementSent: () => {
+          xapiCourseStartedSentOnClientRef.current = true;
+        }
       });
-      courseStartedEmittedToSinkRef.current = emitted;
+      courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
     } else if (trackingActive) {
       courseStartedEmittedToSinkRef.current = true;
     }
@@ -546,8 +587,8 @@ function LessonkitProvider(props) {
     batchEnabled,
     batchFlushIntervalMs,
     batchMaxBatchSize,
-    config.plugins,
-    config.courseId,
+    normalizedConfig.plugins,
+    normalizedCourseId,
     buildCurrentPluginCtx
   ]);
   const emitWithBridge = useCallback((trackingClient, event) => {
@@ -559,14 +600,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 = 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 = tryBuildTrackEvent({
+      const event = tryBuildTelemetryEvent({
         name,
         courseId: courseIdRef.current,
         lessonId: opts?.lessonId ?? activeLessonIdRef.current,
@@ -584,7 +643,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 () => {
@@ -592,8 +651,8 @@ function LessonkitProvider(props) {
         await trackingRef.current?.flush?.();
       } catch {
       }
-      if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
-        const emitted = emitCourseStarted({
+      if (!courseStartedEmittedToSinkRef.current) {
+        const result = emitPendingCourseStarted({
           pluginHost: pluginHostRef.current,
           tracking: trackingRef.current,
           xapi: xapiRef.current,
@@ -602,12 +661,13 @@ function LessonkitProvider(props) {
           courseId: cid,
           attemptId: attemptIdRef.current,
           user: userRef.current,
-          lxpackBridge: lxpackBridgeModeRef.current
+          lxpackBridge: lxpackBridgeModeRef.current,
+          extraSinks: extraSinksRef.current
         });
-        courseStartedEmittedToSinkRef.current = emitted;
+        courseStartedEmittedToSinkRef.current = isCourseStartedSinkSettled(result);
       }
     })();
-  }, [config.courseId, config.tracking?.enabled, syncProgress]);
+  }, [normalizedCourseId, normalizedConfig.tracking?.enabled, syncProgress]);
   const emitLessonCompleted = useCallback(
     (lessonId, durationMs) => {
       track("lesson_completed", { lessonId, durationMs }, { lessonId });
@@ -619,13 +679,19 @@ function LessonkitProvider(props) {
   );
   const completeLesson = 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]
   );
   useEffect(() => {
     return () => {
@@ -649,8 +715,19 @@ function LessonkitProvider(props) {
   }, []);
   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());
@@ -663,9 +740,15 @@ function LessonkitProvider(props) {
       syncProgress();
       track("lesson_started", { lessonId }, { lessonId });
     },
-    [track, syncProgress, emitLessonCompleted]
+    [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());
@@ -678,24 +761,37 @@ function LessonkitProvider(props) {
     syncProgress();
     track("course_completed");
     void trackingRef.current?.flush?.();
-  }, [track, syncProgress, emitLessonCompleted]);
-  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 = useMemo(
+    () => sessionUser ? JSON.stringify(sessionUser) : "",
+    [sessionUser]
+  );
+  const sessionAttemptId = normalizedConfig.session?.attemptId;
+  const sessionConfiguredId = normalizedConfig.session?.sessionId;
+  useEffect(() => {
+    if (useV2Runtime && headlessRef.current) {
+      headlessRef.current.updateConfig({
+        courseId: normalizedCourseId,
+        session: normalizedConfig.session
+      });
+    }
+  }, [useV2Runtime, normalizedCourseId, sessionAttemptId, sessionConfiguredId, sessionUserKey, normalizedConfig.session]);
   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]);
   useEffect(() => {
-    const nextConfigured = config.session?.sessionId;
+    const nextConfigured = normalizedConfig.session?.sessionId;
     const prevConfigured = prevConfiguredSessionIdRef.current;
     if (nextConfigured === prevConfigured) return;
     prevConfiguredSessionIdRef.current = nextConfigured;
@@ -716,10 +812,10 @@ function LessonkitProvider(props) {
       migrateCourseStartedMark(defaultStorage, prevConfigured, nextAuto, cid);
       sessionIdRef.current = nextAuto;
     }
-  }, [sessionConfiguredId, config.courseId]);
+  }, [sessionConfiguredId, normalizedCourseId]);
   const runtime = useMemo(
     () => ({
-      config,
+      config: normalizedConfig,
       tracking,
       xapi,
       session: { sessionId: sessionIdRef.current, attemptId: attemptIdRef.current, user: userRef.current },
@@ -731,7 +827,7 @@ function LessonkitProvider(props) {
       plugins: pluginHost
     }),
     [
-      config,
+      normalizedConfig,
       tracking,
       xapi,
       progress,
@@ -745,6 +841,14 @@ function LessonkitProvider(props) {
       sessionConfiguredId
     ]
   );
+  return runtime;
+}
+
+// src/context.tsx
+import { jsx } from "react/jsx-runtime";
+var LessonkitContext = createContext(null);
+function LessonkitProvider(props) {
+  const runtime = useLessonkitProviderRuntime(props.config);
   return /* @__PURE__ */ jsx(LessonkitContext.Provider, { value: runtime, children: props.children });
 }
 
@@ -767,46 +871,78 @@ function useCompletion() {
   const { completeLesson, completeCourse } = useLessonkit();
   return useMemo2(() => ({ completeLesson, completeCourse }), [completeLesson, completeCourse]);
 }
-function useQuizState() {
+function useQuizState(enclosingLessonId) {
   const { track } = useLessonkit();
+  const trackOpts = enclosingLessonId ? { lessonId: enclosingLessonId } : void 0;
   return useMemo2(
     () => ({
       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
+import { createContext as createContext2, useContext as useContext2 } from "react";
+var LessonContext = createContext2(void 0);
+function useEnclosingLessonId() {
+  return useContext2(LessonContext);
+}
+
 // src/runtime/validateComponentId.ts
-import { validateId } from "@lessonkit/core";
-var warnedPaths = /* @__PURE__ */ new Set();
-function isDevEnvironment2() {
+import { assertValidId as assertValidId2 } from "@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 = 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) {
+  if (path === "courseId") return assertValidId2(id, "courseId");
+  if (path === "lessonId") return assertValidId2(id, "lessonId");
+  if (path === "checkId") return assertValidId2(id, "checkId");
+  if (path === "blockId") return assertValidId2(id, "blockId");
+  return assertValidId2(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
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+var warnedQuizOutsideLesson = false;
+function resetQuizWarningsForTests() {
+  warnedQuizOutsideLesson = false;
+}
 function Course(props) {
-  warnInvalidComponentId(props.courseId, "courseId");
+  const courseId = useMemo3(() => normalizeComponentId(props.courseId, "courseId"), [props.courseId]);
   const providerConfig = useMemo3(
-    () => ({ ...props.config, courseId: props.courseId }),
-    [props.config, props.courseId]
+    () => ({ ...props.config, courseId }),
+    [props.config, courseId]
   );
   return /* @__PURE__ */ jsx2(LessonkitProvider, { config: providerConfig, children: /* @__PURE__ */ jsxs("section", { "aria-label": props.title, children: [
     /* @__PURE__ */ jsx2("h1", { children: props.title }),
@@ -814,41 +950,64 @@ function Course(props) {
   ] }) });
 }
 function Lesson(props) {
-  warnInvalidComponentId(props.lessonId, "lessonId");
+  const lessonId = useMemo3(() => normalizeComponentId(props.lessonId, "lessonId"), [props.lessonId]);
+  const autoComplete = props.autoCompleteOnUnmount !== false;
   const { setActiveLesson, config } = useLessonkit();
   const { completeLesson } = useCompletion();
-  const id = props.lessonId;
   const lessonMountGenerationRef = useRef2(0);
   useEffect2(() => {
+    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__ */ jsxs("article", { "aria-label": props.title, children: [
+  }, [lessonId, config.courseId, setActiveLesson, completeLesson, autoComplete]);
+  return /* @__PURE__ */ jsx2(LessonContext.Provider, { value: lessonId, children: /* @__PURE__ */ jsxs("article", { "aria-label": props.title, children: [
     /* @__PURE__ */ jsx2("h2", { children: props.title }),
     /* @__PURE__ */ jsx2("div", { children: props.children })
-  ] });
+  ] }) });
 }
 function Scenario(props) {
-  if (props.blockId !== void 0) warnInvalidComponentId(props.blockId, "blockId");
-  return /* @__PURE__ */ jsx2("section", { "aria-label": "Scenario", "data-lk-block-id": props.blockId, children: props.children });
+  const blockId = useMemo3(
+    () => props.blockId !== void 0 ? normalizeComponentId(props.blockId, "blockId") : void 0,
+    [props.blockId]
+  );
+  return /* @__PURE__ */ jsx2("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 blockId = useMemo3(
+    () => props.blockId !== void 0 ? normalizeComponentId(props.blockId, "blockId") : void 0,
+    [props.blockId]
+  );
   const promptId = useId();
-  return /* @__PURE__ */ jsxs("section", { "aria-label": "Reflection", "data-lk-block-id": props.blockId, children: [
+  const hintId = useId();
+  const [internalValue, setInternalValue] = useState2("");
+  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__ */ jsxs("section", { "aria-label": "Reflection", "data-lk-block-id": blockId, children: [
     props.prompt ? /* @__PURE__ */ jsx2("p", { id: promptId, children: props.prompt }) : null,
+    props.hint ? /* @__PURE__ */ jsx2("p", { id: hintId, style: visuallyHiddenStyle, children: props.hint }) : null,
     props.children,
     /* @__PURE__ */ jsx2(
       "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"
       }
     )
@@ -867,18 +1026,35 @@ function KnowledgeCheck(props) {
   );
 }
 function Quiz(props) {
-  warnInvalidComponentId(props.checkId, "checkId");
-  const quiz = useQuizState();
-  const { plugins, config, progress, session } = useLessonkit();
+  const checkId = useMemo3(() => normalizeComponentId(props.checkId, "checkId"), [props.checkId]);
+  const enclosingLessonId = useEnclosingLessonId();
+  const missingLesson = enclosingLessonId === void 0;
+  useEffect2(() => {
+    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] = useState2(null);
   const [selectionCorrect, setSelectionCorrect] = useState2(null);
+  const [quizPassed, setQuizPassed] = useState2(false);
   const completedRef = useRef2(false);
   const questionId = useId();
+  const choicesKey = props.choices.join("\0");
   useEffect2(() => {
     completedRef.current = false;
+    setQuizPassed(false);
     setSelected(null);
     setSelectionCorrect(null);
-  }, [props.checkId, props.answer, props.question, config.courseId]);
+  }, [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;
@@ -887,7 +1063,11 @@ function Quiz(props) {
     }
     return choice === props.answer;
   };
-  return /* @__PURE__ */ jsxs("section", { "aria-label": "Quiz", "data-lk-check-id": props.checkId, children: [
+  if (missingLesson) {
+    return /* @__PURE__ */ jsx2("section", { role: "alert", "aria-label": "Quiz configuration error", "data-lk-check-id": checkId, children: /* @__PURE__ */ jsx2("p", { children: "Quiz must be placed inside a Lesson." }) });
+  }
+  const passed = quizPassed;
+  return /* @__PURE__ */ jsxs("section", { "aria-label": "Quiz", "data-lk-check-id": checkId, children: [
     /* @__PURE__ */ jsx2("p", { id: questionId, children: props.question }),
     /* @__PURE__ */ jsxs("fieldset", { "aria-labelledby": questionId, children: [
       /* @__PURE__ */ jsx2("legend", { style: visuallyHiddenStyle, children: "Quiz choices" }),
@@ -899,17 +1079,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
@@ -917,18 +1101,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: props.passingScore ?? 1
+                  maxScore,
+                  passingScore: props.passingScore ?? maxScore
                 });
               }
             }
@@ -940,23 +1126,51 @@ function Quiz(props) {
     selected && selectionCorrect !== null ? /* @__PURE__ */ jsx2("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__ */ jsx2("aside", { "aria-label": "Progress", children: /* @__PURE__ */ jsxs("p", { children: [
+  if (props.totalLessons != null) {
+    const total = props.totalLessons;
+    const displayed = Math.min(completed, total);
+    return /* @__PURE__ */ jsx2("aside", { "aria-label": "Progress", children: /* @__PURE__ */ jsx2(
+      "div",
+      {
+        role: "progressbar",
+        "aria-valuemin": 0,
+        "aria-valuemax": total,
+        "aria-valuenow": displayed,
+        "aria-label": "Lessons completed",
+        children: /* @__PURE__ */ jsxs("p", { children: [
+          "Lessons completed: ",
+          displayed,
+          " of ",
+          total
+        ] })
+      }
+    ) });
+  }
+  return /* @__PURE__ */ jsx2("aside", { "aria-label": "Progress", role: "status", children: /* @__PURE__ */ jsxs("p", { children: [
     "Lessons completed: ",
     completed
   ] }) });
 }
 
 // src/index.tsx
-import { createPluginHost as createPluginHost2, defineLessonkitPlugin } from "@lessonkit/core";
+import {
+  buildTelemetryEvent as buildTelemetryEvent2,
+  createLessonkitRuntime as createLessonkitRuntime2,
+  createPluginRegistry as createPluginRegistry2,
+  createTelemetryPipeline as createTelemetryPipeline2,
+  defineAssessmentPlugin,
+  defineLifecyclePlugin,
+  defineTelemetryPlugin
+} from "@lessonkit/core";
 
 // src/theme/ThemeProvider.tsx
 import React3, {
-  createContext as createContext2,
+  createContext as createContext3,
   useCallback as useCallback2,
-  useContext as useContext2,
+  useContext as useContext3,
   useLayoutEffect as useLayoutEffect2,
   useMemo as useMemo4,
   useRef as useRef3,
@@ -988,7 +1202,7 @@ function applyCssVariables(target, vars, previousKeys) {
 
 // src/theme/ThemeProvider.tsx
 import { jsx as jsx3 } from "react/jsx-runtime";
-var ThemeContext = createContext2(null);
+var ThemeContext = createContext3(null);
 var useIsoLayoutEffect2 = typeof window !== "undefined" ? useLayoutEffect2 : React3.useEffect;
 function getSystemMode() {
   if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
@@ -1068,7 +1282,7 @@ function ThemeProvider(props) {
   return /* @__PURE__ */ jsx3(ThemeContext.Provider, { value, children: /* @__PURE__ */ jsx3("div", { ref: hostRef, "data-lk-theme": dataTheme, children: props.children }) });
 }
 function useTheme() {
-  const ctx = useContext2(ThemeContext);
+  const ctx = useContext3(ThemeContext);
   if (!ctx) {
     throw new Error("useTheme must be used within a ThemeProvider");
   }
@@ -1115,6 +1329,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"],
@@ -1167,6 +1387,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: [],
@@ -1185,6 +1408,7 @@ var BLOCK_CATALOG = [
     },
     telemetry: {
       emits: [],
+      requiresActiveLesson: true,
       manualTracking: "useTracking().track('interaction', { kind, blockId, payload }) on submit or blur"
     }
   },
@@ -1197,7 +1421,13 @@ var BLOCK_CATALOG = [
       { name: "checkId", type: "CheckId", required: true, description: "Stable check identifier for telemetry and LXPack assessments." },
       { name: "question", type: "string", required: true, description: "Question text shown above choices." },
       { name: "choices", type: "string[]", required: true, description: "Radio button choice labels." },
-      { name: "answer", type: "string", required: true, description: "Correct choice value (must match one choice)." }
+      { name: "answer", type: "string", required: true, description: "Correct choice value (must match one choice)." },
+      {
+        name: "passingScore",
+        type: "number",
+        required: false,
+        description: "Minimum score required to pass (defaults to maxScore when omitted)."
+      }
     ],
     requiredIds: ["checkId"],
     parentConstraints: ["Lesson"],
@@ -1222,7 +1452,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: {
@@ -1274,9 +1511,15 @@ export {
   ThemeProvider,
   blockCatalogVersion,
   buildBlockCatalog,
-  createPluginHost2 as createPluginHost,
-  defineLessonkitPlugin,
+  buildTelemetryEvent2 as buildTelemetryEvent,
+  createLessonkitRuntime2 as createLessonkitRuntime,
+  createPluginRegistry2 as createPluginRegistry,
+  createTelemetryPipeline2 as createTelemetryPipeline,
+  defineAssessmentPlugin,
+  defineLifecyclePlugin,
+  defineTelemetryPlugin,
   getBlockCatalogEntry,
+  resetQuizWarningsForTests,
   useCompletion,
   useLessonkit,
   useProgress,