@lessonkit/react 0.1.1 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # `@lessonkit/react`
 
+[![CI](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml/badge.svg)](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml)
+[![npm](https://img.shields.io/npm/v/@lessonkit/react.svg)](https://www.npmjs.com/package/@lessonkit/react)
+[![License](https://img.shields.io/github/license/eddiethedean/lessonkit)](../../LICENSE)
+
 React components and hooks for building learning experiences in LessonKit.
 
 ## Install
@@ -11,11 +15,26 @@ npm install @lessonkit/react react react-dom
 ## Quick example
 
 ```tsx
+import { useMemo } from "react";
+import type { TelemetryEvent } from "@lessonkit/core";
 import { Course, Lesson, Quiz, Scenario, ProgressTracker } from "@lessonkit/react";
+import type { XAPIStatement } from "@lessonkit/xapi";
 
 export default function App() {
+  const config = useMemo(
+    () => ({
+      tracking: {
+        sink: (event: TelemetryEvent) => console.log(event),
+      },
+      xapi: {
+        transport: (statement: XAPIStatement) => console.log(statement),
+      },
+    }),
+    [],
+  );
+
   return (
-    <Course title="Cybersecurity Basics" courseId="cyber-basics">
+    <Course title="Cybersecurity Basics" courseId="cyber-basics" config={config}>
       <ProgressTracker />
 
       <Lesson title="Phishing Awareness" lessonId="phishing-101">
@@ -34,7 +53,7 @@ export default function App() {
 }
 ```
 
-## API (0.1.x)
+## API (0.3.0)
 
 ### Components
 
@@ -57,4 +76,12 @@ export default function App() {
 
 - `@lessonkit/react` ships **framework primitives**, not content. You bring your own layout/content
   and compose interactions as React components.
+- `Course` accepts a `config` prop that is passed through to `LessonkitProvider` (tracking sink,
+  optional `xapi.transport` or custom `xapi.client`, session metadata). Hoist `config` with `useMemo`
+  so tracking/xAPI clients are not recreated every render.
+- When a `<Lesson>` unmounts (for example, wizard navigation), it automatically calls `completeLesson`
+  for that lesson. Use stable `lessonId` values so completion and time-on-task telemetry stay consistent.
+- If you omit `session.sessionId`, the provider reuses a tab-scoped id via `sessionStorage` so React
+  Strict Mode remounts do not split analytics sessions in development.
+- Accessibility guidance lives in [`docs/ACCESSIBILITY.md`](../../docs/ACCESSIBILITY.md).
 

package/dist/index.cjs

@@ -38,6 +38,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/components.tsx
 var import_react3 = require("react");
+var import_accessibility = require("@lessonkit/accessibility");
 
 // src/context.tsx
 var import_react = require("react");
@@ -45,78 +46,226 @@ var import_core = require("@lessonkit/core");
 var import_xapi = require("@lessonkit/xapi");
 var import_jsx_runtime = require("react/jsx-runtime");
 var LessonkitContext = (0, import_react.createContext)(null);
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
+function disposeTrackingClient(client) {
+  client?.flush?.();
+  client?.dispose?.();
+}
+function safeSessionStorageGetItem(key) {
+  if (typeof sessionStorage === "undefined") return null;
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function safeSessionStorageSetItem(key, value) {
+  if (typeof sessionStorage === "undefined") return;
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+  }
+}
+function resolveSessionId(provided) {
+  if (provided) return provided;
+  const existing = safeSessionStorageGetItem(SESSION_STORAGE_KEY);
+  if (existing) return existing;
+  const id = (0, import_core.createSessionId)();
+  safeSessionStorageSetItem(SESSION_STORAGE_KEY, id);
+  return id;
+}
+function courseStartedStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
+}
+function hasCourseStarted(sessionId, courseId) {
+  if (!courseId) return false;
+  return safeSessionStorageGetItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStarted(sessionId, courseId) {
+  if (!courseId) return;
+  safeSessionStorageSetItem(courseStartedStorageKey(sessionId, courseId), "1");
+}
+function createTrackingClientFromConfig(config) {
+  if (config.tracking?.enabled === false) {
+    return (0, import_core.createTrackingClient)();
+  }
+  return (0, import_core.createTrackingClient)({
+    sink: config.tracking?.sink,
+    batchSink: config.tracking?.batchSink,
+    batch: config.tracking?.batch
+  });
+}
+function createXapiClientFromConfig(config, queue) {
+  if (config.xapi?.enabled === false) return null;
+  if (config.xapi?.client) return config.xapi.client;
+  const baseId = config.courseId ? `urn:lessonkit:course:${config.courseId}` : void 0;
+  return (0, import_xapi.createXAPIClient)({ baseId, transport: config.xapi?.transport, queue });
+}
 function LessonkitProvider(props) {
   const config = props.config ?? {};
-  const tracking = (0, import_react.useMemo)(() => {
-    if (config.tracking?.enabled === false) return (0, import_core.createTrackingClient)();
-    return (0, import_core.createTrackingClient)({ sink: config.tracking?.sink });
-  }, [config.tracking?.enabled, config.tracking?.sink]);
-  const xapi = (0, import_react.useMemo)(() => {
-    if (config.xapi?.enabled === false) return null;
-    const baseId = config.courseId ? `urn:lessonkit:course:${config.courseId}` : void 0;
-    return config.xapi?.client ?? (0, import_xapi.createXAPIClient)({ baseId });
-  }, [config.xapi?.enabled, config.xapi?.client, config.courseId]);
+  const sessionIdRef = (0, import_react.useRef)(resolveSessionId(config.session?.sessionId));
+  if (config.session?.sessionId) sessionIdRef.current = config.session.sessionId;
+  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 trackingRef = (0, import_react.useRef)((0, import_core.createTrackingClient)());
+  const [tracking, setTracking] = (0, import_react.useState)(() => trackingRef.current);
+  const courseStartedInProviderRef = (0, import_react.useRef)(false);
+  const trackingEnabled = config.tracking?.enabled;
+  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;
+  (0, import_react.useLayoutEffect)(() => {
+    const prev = trackingRef.current;
+    const next = createTrackingClientFromConfig(config);
+    trackingRef.current = next;
+    setTracking(next);
+    const sessionId = sessionIdRef.current;
+    const cid = courseIdRef.current;
+    const shouldEmitCourseStarted = cid ? !hasCourseStarted(sessionId, cid) : !courseStartedInProviderRef.current;
+    if (shouldEmitCourseStarted) {
+      if (cid) {
+        markCourseStarted(sessionId, cid);
+      } else {
+        courseStartedInProviderRef.current = true;
+      }
+      next.track({
+        name: "course_started",
+        timestamp: (0, import_core.nowIso)(),
+        courseId: cid,
+        sessionId,
+        attemptId: attemptIdRef.current,
+        user: userRef.current
+      });
+    }
+    return () => {
+      disposeTrackingClient(prev);
+    };
+  }, [
+    trackingEnabled,
+    trackingSink,
+    trackingBatchSink,
+    batchEnabled,
+    batchFlushIntervalMs,
+    batchMaxBatchSize
+  ]);
+  const xapiQueueRef = (0, import_react.useRef)((0, import_xapi.createInMemoryXAPIQueue)());
+  const xapiRef = (0, import_react.useRef)(null);
+  const [xapi, setXapi] = (0, import_react.useState)(null);
+  const xapiEnabled = config.xapi?.enabled;
+  const xapiClient = config.xapi?.client;
+  const xapiTransport = config.xapi?.transport;
+  const courseId = config.courseId;
+  (0, import_react.useLayoutEffect)(() => {
+    const prev = xapiRef.current;
+    const next = createXapiClientFromConfig(config, xapiQueueRef.current);
+    xapiRef.current = next;
+    setXapi(next);
+    void (async () => {
+      if (prev) {
+        try {
+          await prev.flush();
+        } catch {
+        }
+      }
+      try {
+        await next?.flush();
+      } catch {
+      }
+    })();
+    return () => {
+      void prev?.flush();
+    };
+  }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
   const [completedLessonIds, setCompletedLessonIds] = (0, import_react.useState)(() => /* @__PURE__ */ new Set());
+  const completedLessonIdsRef = (0, import_react.useRef)(completedLessonIds);
+  completedLessonIdsRef.current = completedLessonIds;
   const [activeLessonId, setActiveLessonId] = (0, import_react.useState)(void 0);
   const [courseCompleted, setCourseCompleted] = (0, import_react.useState)(false);
-  const courseIdRef = (0, import_react.useRef)(config.courseId);
-  courseIdRef.current = config.courseId;
+  const courseCompletedRef = (0, import_react.useRef)(false);
+  courseCompletedRef.current = courseCompleted;
+  const activeLessonIdRef = (0, import_react.useRef)(void 0);
+  activeLessonIdRef.current = activeLessonId;
+  const lessonStartTimesRef = (0, import_react.useRef)(/* @__PURE__ */ new Map());
   const track = (0, import_react.useCallback)(
     (name, data, opts) => {
-      tracking.track({
+      trackingRef.current?.track({
         name,
         timestamp: (0, import_core.nowIso)(),
         courseId: courseIdRef.current,
-        lessonId: opts?.lessonId ?? activeLessonId,
+        lessonId: opts?.lessonId ?? activeLessonIdRef.current,
+        sessionId: sessionIdRef.current,
+        attemptId: attemptIdRef.current,
+        user: userRef.current,
         data
       });
     },
-    [tracking, activeLessonId]
-  );
-  const setActiveLesson = (0, import_react.useCallback)(
-    (lessonId) => {
-      setActiveLessonId(lessonId);
-      track("lesson_started", { lessonId }, { lessonId });
-      xapi?.startedLesson({ lessonId });
-    },
-    [track, xapi]
+    []
   );
+  (0, import_react.useEffect)(() => {
+    return () => {
+      trackingRef.current?.flush?.();
+      void xapiRef.current?.flush();
+    };
+  }, []);
+  const setActiveLesson = (0, import_react.useCallback)((lessonId) => {
+    if (activeLessonIdRef.current === lessonId) return;
+    activeLessonIdRef.current = lessonId;
+    setActiveLessonId(lessonId);
+    lessonStartTimesRef.current.set(lessonId, Date.now());
+    track("lesson_started", { lessonId }, { lessonId });
+    xapiRef.current?.startedLesson({ lessonId });
+  }, [track]);
   const completeLesson = (0, import_react.useCallback)(
     (lessonId) => {
-      setCompletedLessonIds((prev) => new Set(prev).add(lessonId));
-      track("lesson_completed", { lessonId }, { lessonId });
-      xapi?.completeLesson({ lessonId });
+      if (completedLessonIdsRef.current.has(lessonId)) return;
+      completedLessonIdsRef.current = new Set(completedLessonIdsRef.current).add(lessonId);
+      setCompletedLessonIds(completedLessonIdsRef.current);
+      const startedAt = lessonStartTimesRef.current.get(lessonId);
+      lessonStartTimesRef.current.delete(lessonId);
+      const durationMs = typeof startedAt === "number" ? Math.max(0, Date.now() - startedAt) : void 0;
+      track("lesson_completed", { lessonId, durationMs }, { lessonId });
+      if (durationMs !== void 0) {
+        track("lesson_time_on_task", { lessonId, durationMs }, { lessonId });
+      }
+      xapiRef.current?.completeLesson({ lessonId, durationMs });
     },
-    [track, xapi]
+    [track]
   );
   const completeCourse = (0, import_react.useCallback)(() => {
+    if (courseCompletedRef.current) return;
+    courseCompletedRef.current = true;
     setCourseCompleted(true);
     track("course_completed");
-    xapi?.completeCourse({});
-  }, [track, xapi]);
+    xapiRef.current?.completeCourse();
+  }, [track]);
+  const progress = (0, import_react.useMemo)(
+    () => ({
+      activeLessonId,
+      completedLessonIds: new Set(completedLessonIds),
+      courseCompleted
+    }),
+    [activeLessonId, completedLessonIds, courseCompleted]
+  );
   const runtime = (0, import_react.useMemo)(
     () => ({
       config,
       tracking,
       xapi,
-      progress: { activeLessonId, completedLessonIds, courseCompleted },
+      session: { sessionId: sessionIdRef.current, attemptId: attemptIdRef.current, user: userRef.current },
+      progress,
       setActiveLesson,
       completeLesson,
       completeCourse,
       track
     }),
-    [
-      config,
-      tracking,
-      xapi,
-      activeLessonId,
-      completedLessonIds,
-      courseCompleted,
-      setActiveLesson,
-      completeLesson,
-      completeCourse,
-      track
-    ]
+    [config, tracking, xapi, progress, setActiveLesson, completeLesson, completeCourse, track]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(LessonkitContext.Provider, { value: runtime, children: props.children });
 }
@@ -158,7 +307,11 @@ function useQuizState() {
 // src/components.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 function Course(props) {
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(LessonkitProvider, { config: { courseId: props.courseId }, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": props.title, children: [
+  const providerConfig = (0, import_react3.useMemo)(
+    () => ({ ...props.config, courseId: props.courseId }),
+    [props.config, props.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 }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { children: props.children })
   ] }) });
@@ -166,7 +319,9 @@ function Course(props) {
 function Lesson(props) {
   const { setActiveLesson } = useLessonkit();
   const { completeLesson } = useCompletion();
-  const id = props.lessonId ?? (0, import_react3.useMemo)(() => `lesson-${cryptoRandomId()}`, []);
+  const reactId = (0, import_react3.useId)();
+  const generatedId = (0, import_react3.useMemo)(() => `lesson-${sanitizeLessonId(reactId)}`, [reactId]);
+  const id = props.lessonId ?? generatedId;
   (0, import_react3.useEffect)(() => {
     setActiveLesson(id);
     return () => {
@@ -186,7 +341,13 @@ function Reflection(props) {
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Reflection", children: [
     props.prompt ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { id: promptId, children: props.prompt }) : null,
     props.children,
-    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("textarea", { "aria-labelledby": props.prompt ? promptId : void 0 })
+    /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      "textarea",
+      {
+        "aria-labelledby": props.prompt ? promptId : void 0,
+        "aria-label": props.prompt ? void 0 : "Reflection response"
+      }
+    )
   ] });
 }
 function KnowledgeCheck(props) {
@@ -195,12 +356,13 @@ function KnowledgeCheck(props) {
 function Quiz(props) {
   const quiz = useQuizState();
   const [selected, setSelected] = (0, import_react3.useState)(null);
+  const completedRef = (0, import_react3.useRef)(false);
   const questionId = (0, import_react3.useId)();
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("section", { "aria-label": "Quiz", 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", { className: "sr-only", children: "Quiz choices" }),
-      props.choices.map((c) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("label", { style: { display: "block" }, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("legend", { style: import_accessibility.visuallyHiddenStyle, children: "Quiz choices" }),
+      props.choices.map((c, i) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("label", { style: { display: "block" }, children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
           "input",
           {
@@ -210,12 +372,17 @@ function Quiz(props) {
             checked: selected === c,
             onChange: () => {
               setSelected(c);
-              quiz.answer({ question: props.question, choice: c, correct: c === props.answer });
+              const correct = c === props.answer;
+              quiz.answer({ question: props.question, choice: c, correct });
+              if (correct && !completedRef.current) {
+                completedRef.current = true;
+                quiz.complete({ score: 1, maxScore: 1 });
+              }
             }
           }
         ),
         c
-      ] }, c))
+      ] }, `${questionId}-${i}`))
     ] }),
     selected ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { role: "status", "aria-live": "polite", children: selected === props.answer ? "Correct" : "Try again" }) : null
   ] });
@@ -228,10 +395,9 @@ function ProgressTracker() {
     completed
   ] }) });
 }
-function cryptoRandomId() {
-  const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
-  return Math.random().toString(16).slice(2);
+function sanitizeLessonId(id) {
+  const s = id.replace(/[^a-zA-Z0-9_-]/g, "");
+  return s.length ? s : "id";
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -1,52 +1,35 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { LessonId, CourseId, TelemetryEvent, TrackingClient } from '@lessonkit/core';
-import { XAPIClient } from '@lessonkit/xapi';
-
-declare function Course(props: {
-    title: string;
-    courseId?: string;
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function Lesson(props: {
-    title: string;
-    lessonId?: LessonId;
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function Scenario(props: {
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function Reflection(props: {
-    prompt?: string;
-    children?: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function KnowledgeCheck(props: {
-    question: string;
-    choices: string[];
-    answer: string;
-}): react_jsx_runtime.JSX.Element;
-declare function Quiz(props: {
-    question: string;
-    choices: string[];
-    answer: string;
-}): react_jsx_runtime.JSX.Element;
-declare function ProgressTracker(): react_jsx_runtime.JSX.Element;
+import { CourseId, TelemetryUser, TelemetryEvent, TrackingClient, LessonId } from '@lessonkit/core';
+import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
 
 type LessonkitConfig = {
     courseId?: CourseId;
+    session?: {
+        sessionId?: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
     tracking?: {
         enabled?: boolean;
         sink?: (event: TelemetryEvent) => void | Promise<void>;
+        batchSink?: (events: TelemetryEvent[]) => void | Promise<void>;
+        batch?: {
+            enabled?: boolean;
+            flushIntervalMs?: number;
+            maxBatchSize?: number;
+        };
     };
     xapi?: {
         enabled?: boolean;
+        transport?: XAPITransport;
         client?: XAPIClient;
     };
 };
 type ProgressState = {
     activeLessonId?: LessonId;
-    completedLessonIds: Set<LessonId>;
+    completedLessonIds: ReadonlySet<LessonId>;
     courseCompleted: boolean;
 };
 type LessonkitRuntime = {
@@ -54,6 +37,11 @@ type LessonkitRuntime = {
     tracking: TrackingClient;
     xapi: XAPIClient | null;
     progress: ProgressState;
+    session: {
+        sessionId: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
     setActiveLesson: (lessonId: LessonId) => void;
     completeLesson: (lessonId: LessonId) => void;
     completeCourse: () => void;
@@ -66,6 +54,36 @@ declare function LessonkitProvider(props: {
     children: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+declare function Course(props: {
+    title: string;
+    courseId?: CourseId;
+    config?: Omit<React.ComponentProps<typeof LessonkitProvider>["config"], "courseId">;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function Lesson(props: {
+    title: string;
+    lessonId?: LessonId;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function Scenario(props: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function Reflection(props: {
+    prompt?: string;
+    children?: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function KnowledgeCheck(props: {
+    question: string;
+    choices: string[];
+    answer: string;
+}): react_jsx_runtime.JSX.Element;
+declare function Quiz(props: {
+    question: string;
+    choices: string[];
+    answer: string;
+}): react_jsx_runtime.JSX.Element;
+declare function ProgressTracker(): react_jsx_runtime.JSX.Element;
+
 declare function useLessonkit(): LessonkitRuntime;
 declare function useProgress(): ProgressState;
 declare function useTracking(): {

package/dist/index.d.ts

@@ -1,52 +1,35 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { LessonId, CourseId, TelemetryEvent, TrackingClient } from '@lessonkit/core';
-import { XAPIClient } from '@lessonkit/xapi';
-
-declare function Course(props: {
-    title: string;
-    courseId?: string;
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function Lesson(props: {
-    title: string;
-    lessonId?: LessonId;
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function Scenario(props: {
-    children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function Reflection(props: {
-    prompt?: string;
-    children?: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
-declare function KnowledgeCheck(props: {
-    question: string;
-    choices: string[];
-    answer: string;
-}): react_jsx_runtime.JSX.Element;
-declare function Quiz(props: {
-    question: string;
-    choices: string[];
-    answer: string;
-}): react_jsx_runtime.JSX.Element;
-declare function ProgressTracker(): react_jsx_runtime.JSX.Element;
+import { CourseId, TelemetryUser, TelemetryEvent, TrackingClient, LessonId } from '@lessonkit/core';
+import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
 
 type LessonkitConfig = {
     courseId?: CourseId;
+    session?: {
+        sessionId?: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
     tracking?: {
         enabled?: boolean;
         sink?: (event: TelemetryEvent) => void | Promise<void>;
+        batchSink?: (events: TelemetryEvent[]) => void | Promise<void>;
+        batch?: {
+            enabled?: boolean;
+            flushIntervalMs?: number;
+            maxBatchSize?: number;
+        };
     };
     xapi?: {
         enabled?: boolean;
+        transport?: XAPITransport;
         client?: XAPIClient;
     };
 };
 type ProgressState = {
     activeLessonId?: LessonId;
-    completedLessonIds: Set<LessonId>;
+    completedLessonIds: ReadonlySet<LessonId>;
     courseCompleted: boolean;
 };
 type LessonkitRuntime = {
@@ -54,6 +37,11 @@ type LessonkitRuntime = {
     tracking: TrackingClient;
     xapi: XAPIClient | null;
     progress: ProgressState;
+    session: {
+        sessionId: string;
+        attemptId?: string;
+        user?: TelemetryUser;
+    };
     setActiveLesson: (lessonId: LessonId) => void;
     completeLesson: (lessonId: LessonId) => void;
     completeCourse: () => void;
@@ -66,6 +54,36 @@ declare function LessonkitProvider(props: {
     children: React.ReactNode;
 }): react_jsx_runtime.JSX.Element;
 
+declare function Course(props: {
+    title: string;
+    courseId?: CourseId;
+    config?: Omit<React.ComponentProps<typeof LessonkitProvider>["config"], "courseId">;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function Lesson(props: {
+    title: string;
+    lessonId?: LessonId;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function Scenario(props: {
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function Reflection(props: {
+    prompt?: string;
+    children?: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function KnowledgeCheck(props: {
+    question: string;
+    choices: string[];
+    answer: string;
+}): react_jsx_runtime.JSX.Element;
+declare function Quiz(props: {
+    question: string;
+    choices: string[];
+    answer: string;
+}): react_jsx_runtime.JSX.Element;
+declare function ProgressTracker(): react_jsx_runtime.JSX.Element;
+
 declare function useLessonkit(): LessonkitRuntime;
 declare function useProgress(): ProgressState;
 declare function useTracking(): {

package/dist/index.js

@@ -1,84 +1,241 @@
 // src/components.tsx
-import { useEffect, useId, useMemo as useMemo3, useState as useState2 } from "react";
+import { useEffect as useEffect2, useId, useMemo as useMemo3, useRef as useRef2, useState as useState2 } from "react";
+import { visuallyHiddenStyle } from "@lessonkit/accessibility";
 
 // src/context.tsx
-import { createContext, useCallback, useMemo, useRef, useState } from "react";
-import { createTrackingClient, nowIso } from "@lessonkit/core";
-import { createXAPIClient } from "@lessonkit/xapi";
+import {
+  createContext,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import { createSessionId, createTrackingClient, nowIso } from "@lessonkit/core";
+import { createInMemoryXAPIQueue, createXAPIClient } from "@lessonkit/xapi";
 import { jsx } from "react/jsx-runtime";
 var LessonkitContext = createContext(null);
+var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
+function disposeTrackingClient(client) {
+  client?.flush?.();
+  client?.dispose?.();
+}
+function safeSessionStorageGetItem(key) {
+  if (typeof sessionStorage === "undefined") return null;
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function safeSessionStorageSetItem(key, value) {
+  if (typeof sessionStorage === "undefined") return;
+  try {
+    sessionStorage.setItem(key, value);
+  } catch {
+  }
+}
+function resolveSessionId(provided) {
+  if (provided) return provided;
+  const existing = safeSessionStorageGetItem(SESSION_STORAGE_KEY);
+  if (existing) return existing;
+  const id = createSessionId();
+  safeSessionStorageSetItem(SESSION_STORAGE_KEY, id);
+  return id;
+}
+function courseStartedStorageKey(sessionId, courseId) {
+  return `${COURSE_STARTED_PREFIX}${sessionId}:${courseId ?? ""}`;
+}
+function hasCourseStarted(sessionId, courseId) {
+  if (!courseId) return false;
+  return safeSessionStorageGetItem(courseStartedStorageKey(sessionId, courseId)) === "1";
+}
+function markCourseStarted(sessionId, courseId) {
+  if (!courseId) return;
+  safeSessionStorageSetItem(courseStartedStorageKey(sessionId, courseId), "1");
+}
+function createTrackingClientFromConfig(config) {
+  if (config.tracking?.enabled === false) {
+    return createTrackingClient();
+  }
+  return createTrackingClient({
+    sink: config.tracking?.sink,
+    batchSink: config.tracking?.batchSink,
+    batch: config.tracking?.batch
+  });
+}
+function createXapiClientFromConfig(config, queue) {
+  if (config.xapi?.enabled === false) return null;
+  if (config.xapi?.client) return config.xapi.client;
+  const baseId = config.courseId ? `urn:lessonkit:course:${config.courseId}` : void 0;
+  return createXAPIClient({ baseId, transport: config.xapi?.transport, queue });
+}
 function LessonkitProvider(props) {
   const config = props.config ?? {};
-  const tracking = useMemo(() => {
-    if (config.tracking?.enabled === false) return createTrackingClient();
-    return createTrackingClient({ sink: config.tracking?.sink });
-  }, [config.tracking?.enabled, config.tracking?.sink]);
-  const xapi = useMemo(() => {
-    if (config.xapi?.enabled === false) return null;
-    const baseId = config.courseId ? `urn:lessonkit:course:${config.courseId}` : void 0;
-    return config.xapi?.client ?? createXAPIClient({ baseId });
-  }, [config.xapi?.enabled, config.xapi?.client, config.courseId]);
+  const sessionIdRef = useRef(resolveSessionId(config.session?.sessionId));
+  if (config.session?.sessionId) sessionIdRef.current = config.session.sessionId;
+  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 trackingRef = useRef(createTrackingClient());
+  const [tracking, setTracking] = useState(() => trackingRef.current);
+  const courseStartedInProviderRef = useRef(false);
+  const trackingEnabled = config.tracking?.enabled;
+  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;
+  useLayoutEffect(() => {
+    const prev = trackingRef.current;
+    const next = createTrackingClientFromConfig(config);
+    trackingRef.current = next;
+    setTracking(next);
+    const sessionId = sessionIdRef.current;
+    const cid = courseIdRef.current;
+    const shouldEmitCourseStarted = cid ? !hasCourseStarted(sessionId, cid) : !courseStartedInProviderRef.current;
+    if (shouldEmitCourseStarted) {
+      if (cid) {
+        markCourseStarted(sessionId, cid);
+      } else {
+        courseStartedInProviderRef.current = true;
+      }
+      next.track({
+        name: "course_started",
+        timestamp: nowIso(),
+        courseId: cid,
+        sessionId,
+        attemptId: attemptIdRef.current,
+        user: userRef.current
+      });
+    }
+    return () => {
+      disposeTrackingClient(prev);
+    };
+  }, [
+    trackingEnabled,
+    trackingSink,
+    trackingBatchSink,
+    batchEnabled,
+    batchFlushIntervalMs,
+    batchMaxBatchSize
+  ]);
+  const xapiQueueRef = useRef(createInMemoryXAPIQueue());
+  const xapiRef = useRef(null);
+  const [xapi, setXapi] = useState(null);
+  const xapiEnabled = config.xapi?.enabled;
+  const xapiClient = config.xapi?.client;
+  const xapiTransport = config.xapi?.transport;
+  const courseId = config.courseId;
+  useLayoutEffect(() => {
+    const prev = xapiRef.current;
+    const next = createXapiClientFromConfig(config, xapiQueueRef.current);
+    xapiRef.current = next;
+    setXapi(next);
+    void (async () => {
+      if (prev) {
+        try {
+          await prev.flush();
+        } catch {
+        }
+      }
+      try {
+        await next?.flush();
+      } catch {
+      }
+    })();
+    return () => {
+      void prev?.flush();
+    };
+  }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
   const [completedLessonIds, setCompletedLessonIds] = useState(() => /* @__PURE__ */ new Set());
+  const completedLessonIdsRef = useRef(completedLessonIds);
+  completedLessonIdsRef.current = completedLessonIds;
   const [activeLessonId, setActiveLessonId] = useState(void 0);
   const [courseCompleted, setCourseCompleted] = useState(false);
-  const courseIdRef = useRef(config.courseId);
-  courseIdRef.current = config.courseId;
+  const courseCompletedRef = useRef(false);
+  courseCompletedRef.current = courseCompleted;
+  const activeLessonIdRef = useRef(void 0);
+  activeLessonIdRef.current = activeLessonId;
+  const lessonStartTimesRef = useRef(/* @__PURE__ */ new Map());
   const track = useCallback(
     (name, data, opts) => {
-      tracking.track({
+      trackingRef.current?.track({
         name,
         timestamp: nowIso(),
         courseId: courseIdRef.current,
-        lessonId: opts?.lessonId ?? activeLessonId,
+        lessonId: opts?.lessonId ?? activeLessonIdRef.current,
+        sessionId: sessionIdRef.current,
+        attemptId: attemptIdRef.current,
+        user: userRef.current,
         data
       });
     },
-    [tracking, activeLessonId]
-  );
-  const setActiveLesson = useCallback(
-    (lessonId) => {
-      setActiveLessonId(lessonId);
-      track("lesson_started", { lessonId }, { lessonId });
-      xapi?.startedLesson({ lessonId });
-    },
-    [track, xapi]
+    []
   );
+  useEffect(() => {
+    return () => {
+      trackingRef.current?.flush?.();
+      void xapiRef.current?.flush();
+    };
+  }, []);
+  const setActiveLesson = useCallback((lessonId) => {
+    if (activeLessonIdRef.current === lessonId) return;
+    activeLessonIdRef.current = lessonId;
+    setActiveLessonId(lessonId);
+    lessonStartTimesRef.current.set(lessonId, Date.now());
+    track("lesson_started", { lessonId }, { lessonId });
+    xapiRef.current?.startedLesson({ lessonId });
+  }, [track]);
   const completeLesson = useCallback(
     (lessonId) => {
-      setCompletedLessonIds((prev) => new Set(prev).add(lessonId));
-      track("lesson_completed", { lessonId }, { lessonId });
-      xapi?.completeLesson({ lessonId });
+      if (completedLessonIdsRef.current.has(lessonId)) return;
+      completedLessonIdsRef.current = new Set(completedLessonIdsRef.current).add(lessonId);
+      setCompletedLessonIds(completedLessonIdsRef.current);
+      const startedAt = lessonStartTimesRef.current.get(lessonId);
+      lessonStartTimesRef.current.delete(lessonId);
+      const durationMs = typeof startedAt === "number" ? Math.max(0, Date.now() - startedAt) : void 0;
+      track("lesson_completed", { lessonId, durationMs }, { lessonId });
+      if (durationMs !== void 0) {
+        track("lesson_time_on_task", { lessonId, durationMs }, { lessonId });
+      }
+      xapiRef.current?.completeLesson({ lessonId, durationMs });
     },
-    [track, xapi]
+    [track]
   );
   const completeCourse = useCallback(() => {
+    if (courseCompletedRef.current) return;
+    courseCompletedRef.current = true;
     setCourseCompleted(true);
     track("course_completed");
-    xapi?.completeCourse({});
-  }, [track, xapi]);
+    xapiRef.current?.completeCourse();
+  }, [track]);
+  const progress = useMemo(
+    () => ({
+      activeLessonId,
+      completedLessonIds: new Set(completedLessonIds),
+      courseCompleted
+    }),
+    [activeLessonId, completedLessonIds, courseCompleted]
+  );
   const runtime = useMemo(
     () => ({
       config,
       tracking,
       xapi,
-      progress: { activeLessonId, completedLessonIds, courseCompleted },
+      session: { sessionId: sessionIdRef.current, attemptId: attemptIdRef.current, user: userRef.current },
+      progress,
       setActiveLesson,
       completeLesson,
       completeCourse,
       track
     }),
-    [
-      config,
-      tracking,
-      xapi,
-      activeLessonId,
-      completedLessonIds,
-      courseCompleted,
-      setActiveLesson,
-      completeLesson,
-      completeCourse,
-      track
-    ]
+    [config, tracking, xapi, progress, setActiveLesson, completeLesson, completeCourse, track]
   );
   return /* @__PURE__ */ jsx(LessonkitContext.Provider, { value: runtime, children: props.children });
 }
@@ -120,7 +277,11 @@ function useQuizState() {
 // src/components.tsx
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function Course(props) {
-  return /* @__PURE__ */ jsx2(LessonkitProvider, { config: { courseId: props.courseId }, children: /* @__PURE__ */ jsxs("section", { "aria-label": props.title, children: [
+  const providerConfig = useMemo3(
+    () => ({ ...props.config, courseId: props.courseId }),
+    [props.config, props.courseId]
+  );
+  return /* @__PURE__ */ jsx2(LessonkitProvider, { config: providerConfig, children: /* @__PURE__ */ jsxs("section", { "aria-label": props.title, children: [
     /* @__PURE__ */ jsx2("h1", { children: props.title }),
     /* @__PURE__ */ jsx2("div", { children: props.children })
   ] }) });
@@ -128,8 +289,10 @@ function Course(props) {
 function Lesson(props) {
   const { setActiveLesson } = useLessonkit();
   const { completeLesson } = useCompletion();
-  const id = props.lessonId ?? useMemo3(() => `lesson-${cryptoRandomId()}`, []);
-  useEffect(() => {
+  const reactId = useId();
+  const generatedId = useMemo3(() => `lesson-${sanitizeLessonId(reactId)}`, [reactId]);
+  const id = props.lessonId ?? generatedId;
+  useEffect2(() => {
     setActiveLesson(id);
     return () => {
       completeLesson(id);
@@ -148,7 +311,13 @@ function Reflection(props) {
   return /* @__PURE__ */ jsxs("section", { "aria-label": "Reflection", children: [
     props.prompt ? /* @__PURE__ */ jsx2("p", { id: promptId, children: props.prompt }) : null,
     props.children,
-    /* @__PURE__ */ jsx2("textarea", { "aria-labelledby": props.prompt ? promptId : void 0 })
+    /* @__PURE__ */ jsx2(
+      "textarea",
+      {
+        "aria-labelledby": props.prompt ? promptId : void 0,
+        "aria-label": props.prompt ? void 0 : "Reflection response"
+      }
+    )
   ] });
 }
 function KnowledgeCheck(props) {
@@ -157,12 +326,13 @@ function KnowledgeCheck(props) {
 function Quiz(props) {
   const quiz = useQuizState();
   const [selected, setSelected] = useState2(null);
+  const completedRef = useRef2(false);
   const questionId = useId();
   return /* @__PURE__ */ jsxs("section", { "aria-label": "Quiz", children: [
     /* @__PURE__ */ jsx2("p", { id: questionId, children: props.question }),
     /* @__PURE__ */ jsxs("fieldset", { "aria-labelledby": questionId, children: [
-      /* @__PURE__ */ jsx2("legend", { className: "sr-only", children: "Quiz choices" }),
-      props.choices.map((c) => /* @__PURE__ */ jsxs("label", { style: { display: "block" }, children: [
+      /* @__PURE__ */ jsx2("legend", { style: visuallyHiddenStyle, children: "Quiz choices" }),
+      props.choices.map((c, i) => /* @__PURE__ */ jsxs("label", { style: { display: "block" }, children: [
         /* @__PURE__ */ jsx2(
           "input",
           {
@@ -172,12 +342,17 @@ function Quiz(props) {
             checked: selected === c,
             onChange: () => {
               setSelected(c);
-              quiz.answer({ question: props.question, choice: c, correct: c === props.answer });
+              const correct = c === props.answer;
+              quiz.answer({ question: props.question, choice: c, correct });
+              if (correct && !completedRef.current) {
+                completedRef.current = true;
+                quiz.complete({ score: 1, maxScore: 1 });
+              }
             }
           }
         ),
         c
-      ] }, c))
+      ] }, `${questionId}-${i}`))
     ] }),
     selected ? /* @__PURE__ */ jsx2("p", { role: "status", "aria-live": "polite", children: selected === props.answer ? "Correct" : "Try again" }) : null
   ] });
@@ -190,10 +365,9 @@ function ProgressTracker() {
     completed
   ] }) });
 }
-function cryptoRandomId() {
-  const g = globalThis;
-  if (g.crypto?.randomUUID) return g.crypto.randomUUID();
-  return Math.random().toString(16).slice(2);
+function sanitizeLessonId(id) {
+  const s = id.replace(/[^a-zA-Z0-9_-]/g, "");
+  return s.length ? s : "id";
 }
 export {
   Course,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "private": false,
   "description": "React components and hooks for building learning experiences with LessonKit.",
   "license": "Apache-2.0",
@@ -37,11 +37,12 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.tsx --format esm,cjs --dts --external react --external react-dom",
-    "dev": "tsup src/index.tsx --format esm,cjs --dts --watch --external react --external react-dom",
+    "build": "tsup src/index.tsx --format esm,cjs --dts --external react --external react-dom --external @lessonkit/accessibility",
+    "dev": "tsup src/index.tsx --format esm,cjs --dts --watch --external react --external react-dom --external @lessonkit/accessibility",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests=false",
     "lint": "echo \"(no lint configured yet)\""
   },
   "peerDependencies": {
@@ -49,8 +50,9 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@lessonkit/core": "0.1.1",
-    "@lessonkit/xapi": "0.1.1"
+    "@lessonkit/accessibility": "0.3.0",
+    "@lessonkit/core": "0.3.0",
+    "@lessonkit/xapi": "0.3.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",